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 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 refer- ences 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() 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 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 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) context, typically using the standard AG_Widget(3) draw routines. extent() computes the axis-aligned bounding box of the entity, return- ing 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 optimiza- tion 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 ref- erence count reaches zero). The moveNode() callback is invoked by VG_View(3) tools (usually "se- lect" tools) to perform a translation on the entity. vAbs is the de- sired 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 parame- ters. 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 en- tity in the drawing). VG_NodeDetach() detaches the specified node from its current parent. The VG_Delete() function detaches and frees the specified node in- stance, 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 au- tomatically 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-spec- ified 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() 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 draw- ing 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 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 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 speci- fied 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 config- ure the color which will be blended into the graphical rendering of en- tities 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 (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 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. 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+14.3.quarterly>