Strive README

$Header$


COPYRIGHT

Strive is Copyright (C) 2005, Daniel Fischer <dan@subsignal.org>.
That said, the strive library and tools are licensed under the GNU Lesser 
General Public License (LGPL) 2.1.


INTRODUCTION

"Strive" is a protocol, reference library and some utility applications for 
generating, transmitting and rendering two-dimensional vector graphics. It is 
at a very early stage of development and should be considered a research 
project, not a stable thing.

The idea for strive comes from the need (and wish) to be able to handle vector 
graphics in a "streaming" way, to integrate them into graph-based media 
processing systems (like GStreamer, puredata or Drone). After doing some 
research on the wealth of (open-source) stuff that is already available for 
"doing vectors" (cairo, SVG, Macromedia's Flash file format, etc), I decided to 
ignore all previous work and design a very simple protocol from scratch. Think 
about that whatever you want ;)

So, what've we got at the moment?

 * a very simplified, binary but not overly compact wire protocol/format to 
   express some very basic things about vector graphics (see below).
 * a support C library to read and write this protocol, and dump it to printf.
 * two very simple test/demo producers emitting strive data on stdout.
 * a basic OpenGL-based renderer that takes strive data from stdin and displays 
   the graphics in a GLX window.
 

GET IT RUNNING

To get the simple stuff that's going on running, 
 * download the latest strive tarball from
   http://iterative.org/strive/
 * unpack it, move inside the newly generated directory (strive-0.x), and do 
   the classic
   ./configure && make
   (there's currently not much point in doing "make install" unless you want to 
   clutter your /usr/local)
 * run a test
	demo/rects | gl/glrender
 * watch them moving vectors and rejoice.
 
 
PROTOCOL OVERVIEW

There's currently no formalized specification of the protocol, as it surely 
will change in the future. Nevertheless, eat the following (bon appetit):

The Strive Protocol is a set of 16 (or so) commands that can be thought of as a 
program for a renderer. Most commands are atomic (is that the proper word 
here?), but some are followed by a list of other commands. These lists end with 
the generic END command. For the purpose of this readme, I use an ad-hoc 
textual representation of the protocol that should be easy to understand. The 
actual protocol is binary (i.e. not human-readable).

Here's the (current) list of commands and their parameters:

	OBJECT oid
	SHOW oid
	REMOVE oid
	END
	RENDER

	FILL r g b a
	FONT face slant weight size
	
	PATH
	LINETO x y
	CURVETO ax ay bx by x y
	TEXT string
	
	TRANSLATE x y
	ROTATE angle
	SCALE x y 
	SKEW x y
	MATRIX xx yx xy yy x0 y0


Most parameters a floating-point values, except for (OBJECT's and SHOW's) oid, 
(FONT's) face, slant and weight, and (TEXT's) string, these are integer or 
string (yea, i know, i should do a proper spec).

The most important element is OBJECT which defines a new object (duh). Anything 
after the OBJECT command and before the respective END makes up the object. The 
defined object is invisible until it is SHOWn, but is cached on the renderer's 
side until it is REMOVEd or redefined by an OBJECT command with the same oid.

FILL and FONT manipulate the renderer's state to set the fill color/font spec.

PATH starts a shape description, it can only contain LINETOs and CURVETOs until 
it's END.

The transformation commands (TRANSLATE, ROTATE, SCALE, SKEW and MATRIX) also 
must END, at which point the transformation they specified is inverted.

The RENDER command triggers rendering of a frame. Any PATH, TEXT or SHOWn 
OBJECT that precedes RENDER (is on the root object) will be rendered on the 
frame, and cleared. To actually redisplay stuff, put them in an OBJECT and 
repeadedly call SHOW, RENDER.

Here's a sample minimal scene (actually the one from the "curve" demo):

 FILL 0 0 1 .5			# set fill color to semi-transparent blue.
 PATH					# start a path specification
	LINETO 0 .5
	CURVETO .2 .7 .4 .3 .6 .5
	LINETO .6 .0
	LINETO 0 0
 END					# end path specification
 RENDER					# render all that
 
It will render a single frame with some stupid graphic similar to this:

   /-----\
--/       \       /--|
|          \-----/   |
|                    |
|--------------------|


Note that the curve demo is actually inefficient because it redefines the shape 
on the "root scene" for every frame, even though it does not change. To get a 
stream of the same object, do something like:

 OBJECT 1
   <object definition, FILL and PATH stuff>
 SHOW 1
 RENDER
 SHOW 1
 RENDER
 ...
 

And note another thing, if you SHOW an OBJECT within another OBJECT, then 
RENDER, you can redefine the contained object after, and re-show the outer 
object, its content will be updated. Take a look at the "rects" sample for some 
object magic.


AFTERTHOUGHTS

That's all for now, please review and comment ;) And keep in mind things are 
still early and partially unimplemented (glrender doesnt do text for example, 
and uses a really stupid "synchronization mechanism" called "usleep(10000)"). 
There's many unresolved issues, no proper format header, and probably stupid 
stuff in there. You have been warned.

You might also want to have a look at TODO to get an idea of where i want to
go with this.