The functions in this section provide simple, compatible facilities for inserting visible geometry into a pre-existing thing. They append the new geometry to whatever is already in the thing; thus, a series of calls to them may be used to build up a complex visual geometry in a single thing, which can then be efficiently rendered by a single :DRAW message. (It is MUCH more efficient to draw many polygons in one thing than to draw many things, each with -- in the extreme -- one polygon.)
(Note that XG.3D-MAKE-THING-OF-POINTS/LINES/TRIANGLES/RECTANGLES may be used to create appropriate things, and XG.3D-EMPTY-THING may be used to empty a thing of unwanted geometry.)
The functions in this section try very hard to do something reasonable in a wide variety of circumstances, defaulting missing optional parameters to reasonable values, and filling reasonable values into whatever arrays are present in the provided :THING.
For example, these functions will:
Insert points, lines, triangles or rectangles depending on the presence of :FACET-0/1/2/3 arrays. Insert facet normals if :FACET-NORMAL-X/Y/Z are present. Insert point normals if :POINT-NORMAL-X/Y/Z are present. Insert point colors if :POINT-RED/GREEN/BLUE are present. Insert facet colors if :FACET-RED/GREEN/BLUE are present. Insert point texture coordinates if :POINT-TEXTURE-U/V are present. Insert facet texture coordinates if :FACET-TEXTURE-U/V-0/1/2[/3] are present.
The specific values inserted in each case vary with the call, but are intended in each case to be reasonably useful.
In general, the objects inserted will default to about unit size centered on the origin, with the assumed viewpoint being toward positive Z with positive Y being up. In particular, texture coordinates are assigned on this assumption.
To facilitate free substitution of these functions for each other (say at runtime, as parameters to higher-level functions creating clusters of multiple geometric objects), these functions all have the same syntax in the sense that if a keyword parameter is legal for one of them, it is legal for all of them. (In fact, all use one common function to gather their keyword arguments.) Some functions ignore some arguments, however; Ignored arguments are omitted from the syntax diagram for the function.