NAME

VG — agar vector graphics interface

SYNOPSIS

#include <agar/core.h>
#include <agar/gui.h>
#include <agar/vg.h>

DESCRIPTION

The VG interface allows applications to construct, display, export and import vector drawings, which are composed of entities (i.e., VG_Node objects) from simple primitives to more complex or application-specific items.

There is no notion of coordinates in VG. Entities are organized in a tree structure where elements are connected by linear transformations (such as translations or rotations). References between the entities are allowed. For example, a VG_Line(3) is fully described by references to two independent VG_Point(3) entities.

The VG_View(3) widget is almost always used to display VG drawings. VG_View also provides a simple tool registration interface which allows the editor to be extended.

BUILT-IN NODE CLASSES

A number of simple primitives entities are built into the library:

VG_Point(3): Single point
VG_Line(3): Line segment
VG_Circle(3): Circle
VG_Arc(3): Arc (centerpoint / angle)
VG_Polygon(3): Filled polygon
VG_Text(3): Text label

VG INTERFACE

void
VG_InitSubsystem(void);

void
VG_DestroySubsystem(void);

VG *
VG_New(Uint flags);

void
VG_Init(VG *vg, Uint flags);

void
VG_Destroy(VG *vg);

void
VG_Clear(VG *vg);

void
VG_ClearNodes(VG *vg);

void
VG_ClearColors(VG *vg);

void
VG_Lock(VG *vg);

void
VG_Unlock(VG *vg);

VG_Layer *
VG_PushLayer(VG *vg, const char *layer);

void
VG_PopLayer(VG *vg);

The VG_InitSubsystem() function initalizes the VG library and should be invoked before any other function is used. VG_DestroySubsystem() releases resources allocated by the VG library.

The VG_New() function allocates and initializes a new VG structure. VG_Init() initializes an existing one. Acceptable flags include:

VG_NO_ANTIALIAS: Disable anti-aliasing rendering methods.

VG_Destroy() releases all resources allocated by the given VG object. The structure itself is not freed.

VG_Clear() reinitializes the VG structures. VG_ClearNodes() reinitializes only the node trees. VG_ClearColors() reinitializes the color table.

VG_Lock() acquires the lock which protects a VG against modifications. VG_Unlock() releases the lock. The VG interface is thread-safe so it is not necessary for user applications to use these functions unless documented. For example, a VG_FindNode() immediately followed by a VG_NodeDetach() requires the use of VG_Lock()).

VG drawings are organized in layers, which are useful for determining the z-order of graphical entities. It is also possible to mask layers or blend layer-specific colors. VG_PushLayer() creates a new layer of the given name and returns a pointer to the newly created VG_Layer structure. VG_PopLayer() pops the highest layer off the stack.

NODE CLASS REGISTRATION

void
VG_RegisterClass(VG_NodeOps *class);

void
VG_UnregisterClass(VG_NodeOps *class);

VG_NodeOps *
VG_LookupClass(const char *className);

Applications and utilities are expected to register node classes using VG_RegisterClass(), which registers the class described by the given VG_NodeOps structure. VG_UnregisterClass() unregisters the given class.

VG_LookupClass() searches for a class of the specified name and return its description, or NULL if there is no such class. The VG_NodeOps structure fully describes a VG node class. All function pointers are optional and can be set to NULL.

typedef struct vg_node_ops {
	const char *_Nonnull name;              /* Display text */
	struct ag_static_icon *_Nullable icon;  /* Display icon */
	AG_Size size;

	void  (*init)(VG_Node *);
	void  (*destroy)(VG_Node *);
	int   (*load)(VG_Node *, AG_DataSource *, const AG_Version *);
	void  (*save)(VG_Node *, AG_DataSource *);
	void  (*draw)(VG_Node *, VG_View *);
	void  (*extent)(VG_Node *, VG_View *, VG_Vector *a,
	                VG_Vector *b);
	float (*pointProximity)(VG_Node *, VG_View *, VG_Vector *p);
	float (*lineProximity)(VG_Node *, VG_View *, VG_Vector *p1,
	                       VG_Vector *p2);
	void  (*deleteNode)(VG_Node *);
	void  (*moveNode)(VG_Node *, VG_Vector, VG_Vector);
	void *(*edit)(VG_Node *, VG_View *);
}

The name field is a string identifier for this class. icon is an optional Agar icon resource for GUI purposes. size is the full size in bytes of the structure (derived from VG_Node) which describes node instances.

The init() operation initializes a node instance structure. destroy() releases resources allocated by the node instance.

load() and save() are used to (de)serialize the node instance from/to the given AG_DataSource(3).

The draw() operation graphically renders the entity in a VG_View(3) context, typically using the standard AG_Widget(3) draw routines.

extent() computes the axis-aligned bounding box of the entity, returning the absolute VG coordinates of the upper-left corner in a and the lower right corner in b.

pointProximity() computes the shortest distance between p (given in absolute VG coordinates) and the entity. This operation is needed for GUI selection tools to be effective.

lineProximity() computes the shortest distance between the line (as described by endpoints p1 and p2) and the entity. This is an optimization which is optional to the operation of GUI selection tools.

The deleteNode() callback is invoked when the user deletes the node instance. It is used, for example, by VG_Line(3) to call VG_DelRef() on its two VG_Point(3) references (also calling VG_Delete() if their reference count reaches zero).

The moveNode() callback is invoked by VG_View(3) tools (usually "select" tools) to perform a translation on the entity. vAbs is the desired new position in absolute VG coordinates, vRel describes the change in position. It is recommended to only rely on vRel.

The edit() callback is invoked by the VG_EditNode() operation of VG_View(3). It is expected to return a container widget to which is attached a number of widgets bound to various VG_Node instance parameters.

NODE OPERATIONS

void
VG_NodeInit(VG_Node *node, VG_NodeOps *class);

int
VG_NodeIsClass(void *p, const char *name);

void
VG_NodeAttach(VG_Node *parent, VG_Node *node);

void
VG_NodeDetach(VG_Node *node);

int
VG_Delete(VG_Node *node);

void
VG_AddRef(VG_Node *node, VG_Node *refNode);

Uint
VG_DelRef(VG_Node *node, VG_Node *refNode);

void
VG_SetSym(VG_Node *node, const char *fmt, ...);

void
VG_SetLayer(VG_Node *node, int layerIndex);

void
VG_SetColorv(VG_Node *node, const VG_Color *cv);

void
VG_SetColorRGB(VG_Node *node, Uint8 r, Uint8 g, Uint8 b);

void
VG_SetColorRGBA(VG_Node *node, Uint8 r, Uint8 g, Uint8 b, Uint8 a);

void
VG_Select(VG_Node *node);

void
VG_Unselect(VG_Node *node);

void
VG_SelectAll(VG *vg);

void
VG_UnselectAll(VG *vg);

Uint32
VG_GenNodeName(VG *vg, const char *className);

VG_Node *
VG_FindNode(VG *vg, Uint32 handle, const char *type);

VG_Node *
VG_FindNodeSym(VG *vg, const char *sym);

The VG_NodeInit() function completely initializes a VG_Node structure as an instance of the specified node class.

VG_NodeIsClass() returns 1 if the specified node is an instance of the given class, 0 otherwise.

VG_NodeAttach() and VG_NodeDetach() are used to construct the hierarchy of entities in a drawing. The relationship between parent and child nodes defines the order of linear transformations (i.e., translations, rotations). VG_NodeAttach() attaches node to an existing node parent (which is either the root member of the VG structure, or any other entity in the drawing). VG_NodeDetach() detaches the specified node from its current parent.

The VG_Delete() function detaches and frees the specified node instance, along with any child nodes. The function can fail (returning -1) if the entity is in use.

VG_AddRef() creates a new reference (dependency), where node depends on refNode.

VG_DelRef() removes the dependency with refNode and returns the new reference count of refNode. This allows the referenced node to be automatically deleted when no longer referenced. Under multithreading, the return value of VG_DelRef() is only valid as long as VG_Lock() is used.

VG_SetSym() sets the symbolic name of the node, an arbitrary user-specified string which allows the node to be looked up using VG_FindNodeSym().

VG_SetLayer() assigns the node to the specified layer number (see VG_PushLayer() and VG_PopLayer()).

VG_SetColorv() sets the node color from a pointer to a VG_Color structure. VG_SetColorRGB() sets the node color from the given RGB triplet. VG_SetColorRGBA() sets the node color from the given RGBA components.

The VG_Select() and VG_Unselect() functions respectively set and unset the selection flag on the node. VG_SelectAll() and VG_UnselectAll() operate on all nodes in the drawing.

Nodes are named by their class name followed by a numerical handle (e.g., the first line created in a drawing will be named ‘Line0’). VG_GenNodeName() generates a new name, unique in the drawing, for use by a new instance of the specified class.

The VG_FindNode() function searches for a node by name, returning a pointer to the specified instance or NULL if not found. The VG_FindNodeSym() variant searches node by their symbolic names (see VG_SetSym()). Under multithreading, the return value of both VG_FindNode() and VG_FindNodeSym() only remains valid as long as VG_Lock() is used.

LINEAR TRANSFORMATIONS

VG_Vector
VG_Pos(VG_Node *node);

void
VG_LoadIdentity(VG_Node *node);

void
VG_Translate(VG_Node *node, VG_Vector v);

void
VG_SetPosition(VG_Node *node, VG_Vector v);

void
VG_SetPositionInParent(VG_Node *node, VG_Vector v);

void
VG_Scale(VG_Node *node, float s);

void
VG_Rotate(VG_Node *node, float radians);

void
VG_FlipVert(VG_Node *node);

void
VG_FlipHoriz(VG_Node *node);

void
VG_NodeTransform(VG_Node *node, VG_Matrix *T);

void
VG_PushMatrix(VG *vg);

void
VG_PopMatrix(VG *vg);

VG_Matrix
VG_MatrixInvert(VG_Matrix M);

Every node in a VG is associated with an invertible 3x3 matrix T, which defines a set of transformations on the coordinates.

The VG_Pos() function computes the current absolute VG coordinates of the node.

VG_LoadIdentity() sets the transformation matrix of the node to the identity matrix.

VG_Translate() translates the node by the amount specified in v.

VG_SetPosition() assigns the node an absolute position v, relative to the VG origin. VG_SetPositionInParent() assigns a position relative to the parent node.

VG_Scale() uniformly scales the node by a factor of s.

VG_Rotate() rotates the node by the specified amount, given in radians.

VG_FlipVert() mirrors the node vertically and VG_FlipHoriz() mirrors the node horizontally.

VG_NodeTransform() computes and returns into T the product of the transformation matrices of the given node and those of its parents.

VG_PushMatrix() and VG_PopMatrix() are called from the draw() operation of nodes to manipulate the global matrix stack associated with a drawing during rendering. VG_PushMatrix() grows the stack, duplicating the top matrix. VG_PopMatrix() discards the top matrix.

VG_MatrixInvert() computes the inverse of M. Since VG matrices are required to be non-singular, this operation cannot fail.

SERIALIZATION

void
VG_Save(VG *vg, AG_DataSource *ds);

int
VG_Load(VG *vg, AG_DataSource *ds);

VG_Vector
VG_ReadVector(AG_DataSource *ds);

void
VG_WriteVector(AG_DataSource *ds, const VG_Vector *v);

VG_Color
VG_ReadColor(AG_DataSource *ds);

void
VG_WriteColor(AG_DataSource *ds, const VG_Color *c);

void
VG_WriteRef(AG_DataSource *ds, VG_Node *node);

VG_Node *
VG_ReadRef(AG_DataSource *ds, VG_Node *node, const char *className);

The VG_Save() function archives the contents of vg into the specified data source. VG_Load() loads the drawing from a data source; see AG_DataSource(3).

VG_ReadVector() and VG_WriteVector() are used to (de)serialize vectors (see MATH ROUTINES section).

VG_ReadColor() and VG_WriteColor() are used to (de)serialize VG_Color structures.

VG_WriteRef() is useful for serializing a reference from one node to another. For example, the VG_Line(3) save() routine simply consists of VG_WriteRef() calls on its two VG_Point(3) references ) .

VG_ReadRef() deserializes a node->node reference. If className is provided, the function will fail and return NULL if the archived reference does not match the specified class name.

COLOR OPERATIONS

VG_Color
VG_GetColorRGB(Uint8 r, Uint8 g, Uint8 b);

VG_Color
VG_GetColorRGBA(Uint8 r, Uint8 g, Uint8 b, Uint8 a);

AG_Color
VG_MapColorRGB(VG_Color vc);

AG_Color
VG_MapColorRGBA(VG_Color vc);

void
VG_BlendColors(VG_Color *cDst, VG_Color cSrc);

void
VG_SetBackgroundColor(VG *vg, VG_Color c);

void
VG_SetSelectionColor(VG *vg, VG_Color c);

void
VG_SetMouseOverColor(VG *vg, VG_Color c);

VG_GetColorRGB() returns the VG_Color structure describing the specified RGB triplet, with the alpha component set to 1.0 (opaque). The VG_GetColorRGBA() variant includes the alpha component.

Functions VG_MapColorRGB() and VG_MapColorRGBA() convert the given color to AG_Color(3) format.

VG_BlendColors() blends the two specified colors, returning the results in cDst.

VG_SetBackgroundColor() configures the background color of the drawing. The VG_SetSelectionColor() and VG_SetMouseOverColor() functions configure the color which will be blended into the graphical rendering of entities which are selected or under the cursor, respectively.

MATH ROUTINES

VG_Vector
VG_GetVector(float x, float y);

VG_Matrix
VG_MatrixIdentity(void);

VG_Vector
VG_Add(VG_Vector v1, VG_Vector v2);

VG_Vector
VG_Sub(VG_Vector v1, VG_Vector v2);

VG_Vector
VG_ScaleVector(float c, VG_Vector v);

float
VG_DotProd(VG_Vector v1, VG_Vector v2);

float
VG_Length(VG_Vector v);

float
VG_Distance(VG_Vector v1, VG_Vector v2);

float
VG_PointLineDistance(VG_Vector A, VG_Vector B, VG_Vector *pt);

VG_Vector
VG_IntersectLineV(float x, VG_Vector p1, VG_Vector p2);

VG_Vector
VG_IntersectLineH(float x, VG_Vector p1, VG_Vector p2);

void
VG_MultMatrix(VG_Matrix *A, const VG_Matrix *B);

void
VG_MultMatrixByVector(VG_Vector *Mv, const VG_Vector *v, const VG_Matrix *M);

The VG_GetVector() function returns a VG_Vector structure given x, y values.

The VG_MatrixIdentity() function returns the identity matrix.

VG_Add() returns the sum of vectors v1 and v2.

VG_Sub() returns the difference of vectors v1 and v2.

VG_ScaleVector() multiplies vector v by a scalar c.

VG_DotProd() returns the dot product of two vectors.

VG_Length() returns the length of a vector.

VG_Distance() returns the unsigned distance between two vectors.

VG_PointLineDistance() computes the minimal distance from a line (described by two points A and B) and a point pt. The function returns the distance, and the closest point on the line is returned back into pt.

VG_IntersectLineV() computes the intersection of an infinite line (described by p1 and p2) against a vertical line (described by x). The return value is undefined if the two lines are parallel. VG_IntersectLineH() performs the same operation against a horizontal line (described by y).

VG_MultMatrix() computes the product of matrices A and B, returning the result into B.

VG_MultMatrixByVector() computes the product of matrix M and vector v, returning the result in Mv.

HISTORY

The VG interface first appeared in Agar 1.3.3.