Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
VG(3)		       FreeBSD Library Functions Manual			 VG(3)

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 ob-
     jects) 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 handy "tool" registration interface which simpli-
     fies the development of editors.

     Note: While VG is general-purpose and designed for	simplicity, a more CAD
     oriented alternative, SK, is available in the FreeSG distribution
     (http://freesg.org/). SK is similar to VG,	but it provides	more advanced
     math and computational geometry features.	Unlike VG which	uses linear
     transformations to	represent relative entity positions, SK	uses systems
     of	geometrical constraints	(e.g., distances, angles, etc.).

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() re-
     leases 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() reinitial-
     izes only the node	trees.	VG_ClearColors() reinitializes the color ta-
     ble.

     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 docu-
     mented.  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 op-
     tional and	can be set to NULL.

     typedef struct vg_node_ops	{
	     const char		   *name;
	     struct ag_static_icon *icon;
	     size_t		    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 op-
     tional Agar icon resource for GUI purposes.  size is the full size	in
     bytes of the structure (derived from VG_Node) which describes node	in-
     stances.

     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) con-
     text, 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 abso-
     lute 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 de-
     scribed 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 in-
     stance.  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 refer-
     ence 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 posi-
     tion.  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 at-
     tached 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 ref-
     erence count of refNode.  This allows the referenced node to be automati-
     cally deleted when	no longer referenced.  Under multithreading, the re-
     turn 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-speci-
     fied 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 struc-
     ture.  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() op-
     erate 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 iden-
     tity 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 trans-
     formation 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 re-
     quired 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 an-
     other.  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	pro-
     vided, 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 val-
     ues.

     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 (de-
     scribed 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 (de-
     scribed by	p1 and p2) against a vertical line (described by x).  The re-
     turn 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.

SEE ALSO
     AG_Intro(3), VG_Arc(3), VG_Circle(3), VG_Line(3), VG_Point(3),
     VG_Polygon(3), VG_Text(3),	VG_View(3)

HISTORY
     The VG interface first appeared in	Agar 1.3.3.

FreeBSD	13.0			 July 9, 2008			  FreeBSD 13.0

NAME | SYNOPSIS | DESCRIPTION | BUILT-IN NODE CLASSES | VG INTERFACE | NODE CLASS REGISTRATION | NODE OPERATIONS | LINEAR TRANSFORMATIONS | SERIALIZATION | COLOR OPERATIONS | MATH ROUTINES | SEE ALSO | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=VG&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help