Modules

vgfx Request Format
[Vector Graphics Engine]


This is a description of the vector graphics engine request format. More...

Collaboration diagram for vgfx Request Format:

Modules

 Special vgfx meta tags
 


The vgfx engine is aware of some meta tags.



Detailed Description


This is a description of the vector graphics engine request format.

A request is a text stream passed into a vgfx::processRequest() call.

A request is intended to be easy for humans to read and write, as well as for programs to write and parse. The folium application (included in the folium package) is built on this vector graphics engine, and it constructs vgfx requests on the fly in response to user input. This is to do things like add new pages to the folio, add a path consisting of bezier curves for pen strokes, etc.

A request is a series of commands. The entire request is treated as a single transaction: either all of the commands succeed, or none do. If a request fails, the canvas (ObjectMap) remains in its clean pre-request state. (NOTE: applications can ask to run in non-transactional mode if they'd like).

The vector graphics engine deals with primitive vector graphics objects such as lines, curves, text, rectangles, etc. These are called Primitive objects. A group is a special Primitive : it contains child Primitive objects. Groups can contain other groups recursively.

The request acts on an ObjectMap. An ObjectMap is not a representation of a 2D canvas! Instead, an ObjectMap is a directory that contains all Primitives that have been created, indexed by ID. Many objects may not be visible to an end application. As the owner of the ObjectMap, you can decide what objects you want to draw.

Your vgfx::ObjectMap is like a big directory, containing all of the vgfx::Primitive objects you have defined. You can use the registered Primitives to construct rich hierarchical sets of vector graphic composite objects, using Groups.

What sorts of commands can you issue in a request?

Every Primitive you create must have an ID that is unique within that ObjectMap. An ID can be any string that meets these requirements:

A request must begin with a "request {" line, and end with a single closing curly bracket. Between the opening and closing you can list multiple commands.

Here are some sample requests:


This request asks that a line be created, with id "line001". The line starts at (x0, y0) = (0, 0) (the default), and ends at (x1, y1) = (4, 4).

 request {
        # note that any lines beginning with a hash mark are treated as comments

        # this request creates a line
        add line  id line001  x1 4  y1 4
 }


Here is a request that creates a different line, with id "line002".

 request {
        add line  id line002  x1 4  y1 -4
 }


You could decide to create a group that contained both of these objects within it:

 request {
        add group {
                id      g001

                object  tag first_line  id line001      x 1     y 1
                object  tag second_line id line002      x 1     y 5
        }
 }

That creates a single Primitive, of type group, with ID "g001". The group contains line001 starting at x=1, y=1 relative to the group origin, and line002 starting at x=1, y=-5 relative to the group origin.


If you wanted, you could do all of that (create both lines and the group) in a single transaction:

 request {

        add line  id line001  x1 4  y1 4

        add line  id line002  x1 4  y1 -4

        add group {
                id      g001

                object  tag first_line  id line001      x 1     y 1
                object  tag second_line id line002      x 1     y 5
        }
 }


Note that objects have to be created before they can be referenced. So a slightly re-ordered version of the above would fail:

 request {

        add group {
                id      g001

                object  tag first_line  id line001      x 1     y 1             # error here!
                object  tag second_line id line002      x 1     y 5
        }

        add line  id line001  x1 4  y1 4

        add line  id line002  x1 4  y1 -4

 }

That request would fail when parsing the group because the object with ID "line001" had not yet been defined.


Objects are referred to by their ID, and are NOT copied. You cannot remove a Primitive if there are other Primitives (groups) that refer to it.