# 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 Baumgart'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:
Would be described as follows:
Surfaces as well as solid objects may be represented.
The link between facets and halfedges expresses handedness (for
surfaces this is the notion 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.

1 4 ________ / \ / /______\/ 2 3

o---[ HalfEdge1 ]---[ Vertex1 ]---o | | [ Facet1 ]---+---[ HalfEdge2 ]---[ Vertex2 ] | | | | | o---[ HalfEdge3 ]---[ Vertex3 ] | | | | [ Facet2 ]---+--------o | | | |---[ HalfEdge4 ]---[ Vertex4 ] | | | +---[ HalfEdge5 ]-----------------o

# 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 occurred. 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 vertex (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() accept coordinates as individual M_Real(3) arguments.

SG_VertexNewCopy() creates a vertex using the coordinates from an existing 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 vertices

`v1`and

`v2`, returning a pointer to the

`SG_Edge`structure on success, or NULL if no match was found. SG_EdgeFindByVtx() is an O(1) operation.

The SG_HashEdge() function returns the index of the

`edgeTbl`bucket corresponding to the edge between vertices

`v1`and

`v2`.

SG_EdgeRehash() resizes an object's hash table of (half)edges to contain

`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 triangular or quad facet from a contour of specified vertices, creating edges as necessary. Note that if the contour includes one or more existing 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 reference 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 connectivity 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 messages 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 triangular facets, returning the total number of facets that have been converted.

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:

The following public

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:

For the

For the

For the

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

# HISTORY

The
SG_Object node class first appeared in
Agar 1.6.0.