FreeBSD Manual Pages
SG_OBJECT(3) Library Functions Manual SG_OBJECT(3) NAME SG_Object -- Agar-SG polyhedral object node SYNOPSIS #include <agar/core.h> #include <agar/sg.h> DESCRIPTION The SG_Object describes a geometrical object bounded by a polyhedral approximation. The data format used by SG_Object is based on Baum- gart's winged-edge data structure. The structure describes a set of facets (triangles or quads). Each facet references 3 or 4 halfedges, and each halfedge references the incident vertex (and incident facet). Facets and halfedges also contain pointers to their opposites. A mesh of two triangles: 1 4 ________ / \ / /______\/ 2 3 Would be described as follows: o---[ HalfEdge1 ]---[ Vertex1 ]---o | | [ Facet1 ]---+---[ HalfEdge2 ]---[ Vertex2 ] | | | | | o---[ HalfEdge3 ]---[ Vertex3 ] | | | | [ Facet2 ]---+--------o | | | |---[ HalfEdge4 ]---[ Vertex4 ] | | | +---[ HalfEdge5 ]-----------------o Surfaces as well as solid objects may be represented. The link between facets and halfedges expresses handedness (for surfaces this is the no- tion of "side", for closed solids this is the notion of being "inside" or "outside"). When SG_Object is used to describe closed solids, the convention is: if one looks at an object from the outside and an edge is pointing up, its HEAD halfedge references the facet at the LEFT. INHERITANCE HIERARCHY AG_Object(3) -> SG_Node(3) -> SG_Object. INITIALIZATION SG_Object * SG_ObjectNew(SG_Node *parent, const char *name) int SG_ObjectLoadPLY(SG_Object *so, const char *name, Uint flags) void SG_ObjectFreeGeometry(SG_Object *so) The SG_ObjectNew() function allocates, initializes, and attaches a SG_Object object. SG_ObjectLoadPLY() loads a mesh from a Stanford PLY file in either ASCII or binary format. Returns 0 on success or -1 if an error oc- curred. Acceptable flags options include: SG_PLY_LOAD_VTX_NORMALS Read vertex normals. SG_PLY_LOAD_VTX_COLORS Read vertex colors. SG_PLY_LOAD_TEXCOORDS Read texture coordinates. SG_PLY_DUP_VERTICES Check for, and eliminate duplicate vertices. The SG_ObjectFreeGeometry() function clears all vertices, edges and facets associated with an object. SPECIFYING VERTICES void SG_VertexInit(SG_Vertex *vtx) int SG_VertexNew(SG_Object *so, const M_Vector3 pos) int SG_VertexNewv(SG_Object *so, const M_Vector3 *pos) int SG_VertexNewvn(SG_Object *so, const M_Vector3 *pos, const M_Vector3 *normal) int SG_VertexNew2(SG_Object *so, M_Real x, M_Real y) int SG_VertexNew3(SG_Object *so, M_Real x, M_Real y, M_Real z) int SG_VertexNewCopy(SG_Object *so, const SG_Vertex *vtx) The SG_VertexInit() function initializes a vertex vtx that has already been allocated. The SG_VertexNew() function allocates, initializes and attaches a new vertex specified as a M_Vector(3), and returns an index to the new ver- tex (or to an existing vertex, if there is currently a vertex with the same coordinates, as compared up to machine precision). SG_VertexNewv() is a variant of SG_VertexNew() which accepts a pointer to a M_Vector3. M_VertexNewvn() is also a variant of SG_VertexNew(), which allows a normal vector norm to be specified. This normal vector will be used subsequently for lighting and physics calculations. The SG_VertexNew2() and SG_VertexNew3() variants of SG_VertexNew() ac- cept coordinates as individual M_Real(3) arguments. SG_VertexNewCopy() creates a vertex using the coordinates from an ex- isting vertex vtx. SPECIFYING EDGES SG_Edge * SG_Edge2(SG_Object *so, int vTail, int vHead) SG_Edge * SG_EdgeFindByVtx(SG_Object *so, int v1, int v2) Uint SG_HashEdge(SG_Object *so, int v1, int v2) int SG_EdgeRehash(SG_Object *so, Uint nBuckets) The SG_Edge2() function creates an edge (i.e., two halfedges) incident to the given vertices vTail and vHead. The function returns a pointer to the SG_Edge structure describing the HEAD halfedge. By convention, the HEAD halfedge points to the facet at the left of the edge. If the edge already exists, SG_Edge2() returns a pointer to (the HEAD halfedge of) the existing edge. The SG_EdgeFindByVtx() function searches for an (half)edge between ver- tices v1 and v2, returning a pointer to the SG_Edge structure on suc- cess, or NULL if no match was found. SG_EdgeFindByVtx() is an O(1) op- eration. The SG_HashEdge() function returns the index of the edgeTbl bucket cor- responding to the edge between vertices v1 and v2. SG_EdgeRehash() resizes an object's hash table of (half)edges to con- tain nBuckets buckets in total. If insufficient memory is available, the existing table is preserved and the function returns -1. SPECIFYING FACETS SG_Facet * SG_FacetNew(SG_Object *so, int n) SG_Facet * SG_Facet3(SG_Object *so) SG_Facet * SG_Facet4(SG_Object *so) SG_Facet * SG_FacetFromTri3(SG_Object *so, int v1, int v2, int v3) SG_Facet * SG_FacetFromQuad4(SG_Object *so, int v1, int v2, int v3, int v4) void SG_FacetDelete(SG_Facet *f) The SG_FacetNew() function allocates, initializes and attaches a new facet. The n must be either 3 for a triangle, or 4 for a quad facet. New facets don't have any associated edges / vertices. The SG_Facet3() and SG_Facet4() variants create triangle and quad facets, respectively. The SG_FacetFromTri3() and SG_FacetFromQuad4() functions create a tri- angular or quad facet from a contour of specified vertices, creating edges as necessary. Note that if the contour includes one or more ex- isting edges, the orientation of the facet may be reversed in order to remain consistent with the existing facets sharing those edges. The SG_FacetDelete() function deletes a facet, and removes any refer- ence to it. SG_FacetExtrude() creates, from an existing facet f, an extrusion along direction d. The function returns 0 on success or -1 if the feature could not be created. The mode argument may be one of: SG_EXTRUDE_REGION Create 2n edges and n+1 faces. SG_EXTRUDE_EDGES Create 2n edges and n faces. SG_EXTRUDE_VERTICES Create n edges and no faces. GEOMETRICAL QUERIES ON FACETS M_Vector3 SG_FacetNormal(SG_Object *so, SG_Facet *f) M_Real SG_FacetArea(SG_Object *so, SG_Facet *f) M_Real SG_FacetAreaSigned(SG_Object *so, SG_Facet *f) M_Vector3 SG_FacetCentroid(SG_Object *so, SG_Facet *f) The SG_FacetNormal() function computes the normal vector for a given facet f. Mathematically, this is the vector cross-product of three vertices of the facet (for quad facets, the 4th vertex is ignored), normalized. SG_FacetArea() computes the (unsigned) area covered by a facet SG_FacetAreaSigned() computes the signed area of a facet. SG_FacetCentroid() computes the center of mass (centroid) of a facet. MISCELLANEOUS OPERATIONS int SG_ObjectCheckConnectivity(SG_Object *so, AG_Console *console) int SG_ObjectNormalize(SG_Object *so) Uint SG_ObjectConvQuadsToTriangles(SG_Object *so) Uint8 * SG_ObjectEdgeMatrix(SG_Object *so, Uint *n) Uint8 * SG_ObjectFacetMatrix(SG_Object *so, Uint *n) The SG_ObjectCheckConnectivity() function performs (potentially very expensive) checks for inconsistencies in the edge/facet/vertex connec- tivity of an object. If any error is found, the function immediately returns -1 and sets the error message accordingly. If cons argument is non-NULL, errors are reported as AG_Console(3) messages, otherwise mes- sages are printed using AG_Verbose(3). SG_ObjectNormalize() calculates the normal vector for every facet of the object, using SG_FacetNormal() on the individual facets. The SG_ObjectConvQuadsToTriangles() converts all quad facets to trian- gular facets, returning the total number of facets that have been con- verted. The SG_ObjectEdgeMatrix() function generates a vertex/edge adjacency matrix for the object. SG_ObjectFacetMatrix() generates a vertex/facet adjacency matrix. Both functions will allocate the matrix and return the size into n. The functions may fail and return NULL. FLAGS The following public SG_Object flags are defined: SG_OBJECT_STATIC Advise to the scene-partitioning algorithms that the geometry of the object will not change once it is attached to the scene. This allows some important optimizations to be performed. SG_OBJECT_NODUPVERTEX In SG_VertexNew(), test for an existing vertex at the new vertex coordinates. If a match is found, return the existing vertex instead of creating a new one. The following public SG_Vertex flags are defined: SG_VERTEX_SELECTED Vertex is currently selected for edition. SG_VERTEX_HIGHLIGHTED Vertex is currently highlighted. STRUCTURE DATA For the SG_Object object: Uint flags Option flags, see "FLAGS" section for details. SG_Vertex *vtx Array of vertices; see below. Uint nvtx Vertex count. SG_EdgeEnt *edgeTbl Hash table of halfedges; see below. Uint nEdgeTbl Number of buckets in halfedge table. SLIST facets Facets (quads or triangles); see below. SG_Material *mat Associated material, see SG_Material(3). For the SG_EdgeEnt (halfedge bucket) structure: SLIST edges List of halfedges in bucket For the SG_Edge (halfedge) structure: int v Index of incident vertex SG_Facet *f Pointer to incident facet SG_Edge *oe Pointer to opposite halfedge For the SG_Vertex structure: M_Real s,t Texture coordinates (T2F) M_Color c Vertex color (C4F) M_Vector3 n Normal vector (N3F) M_Vector3 v Vertex position (V3F) Uint flags Vertex option flags (see "FLAGS" section for details). SEE ALSO AG_Queue(3), M_Real(3), M_Vector(3), SG(3), SG_Intro(3), SG_Material(3), SG_Node(3) HISTORY The SG_Object node class first appeared in Agar 1.6.0. Agar 1.7 December 21, 2022 SG_OBJECT(3)
NAME | SYNOPSIS | DESCRIPTION | INHERITANCE HIERARCHY | INITIALIZATION | SPECIFYING VERTICES | SPECIFYING EDGES | SPECIFYING FACETS | GEOMETRICAL QUERIES ON FACETS | MISCELLANEOUS OPERATIONS | FLAGS | STRUCTURE DATA | SEE ALSO | HISTORY
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=SG_Object&sektion=3&manpath=FreeBSD+Ports+14.3.quarterly>