FreeBSD Manual Pages
VG(3) 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 im- port 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 indepen- dent 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 in- voked 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 docu- mented. For example, a VG_FindNode() immediately followed by a VG_NodeDe- tach() 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() re- leases 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 ab- solute 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 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 po- sition 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 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 de- fines 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 refer- ence 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_Push- Layer() 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_Set- ColorRGBA() 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_GenNode- Name() generates a new name, unique in the drawing, for use by a new in- stance 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() vari- ant searches node by their symbolic names (see VG_SetSym()). Under multi- threading, 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 de- fines 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 transfor- mation 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 dur- ing rendering. VG_PushMatrix() grows the stack, duplicating the top ma- trix. 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 *class- Name) 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_Data- Source(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_GetCol- orRGBA() 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_Ma- trix *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 (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 (de- scribed by p1 and p2) against a vertical line (described by x). The return value is undefined if the two lines are parallel. VG_IntersectLineH() per- forms the same operation against a horizontal line (described by y). VG_MultMatrix() computes the product of matrices A and B, returning the re- sult into B. VG_MultMatrixByVector() computes the product of matrix M and vector v, re- turning the result in Mv. SEE ALSO AG_Intro(3), SK(3), SK_View(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. Agar 1.7 December 21, 2022 VG(3)
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://man.freebsd.org/cgi/man.cgi?query=VG&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>