Castle Game Engine: X3DNodes: Class TAbstractGeometryNode

# Class TAbstractGeometryNode
Description | Hierarchy | Fields | Methods | Properties
## Unit X3DNodes ## Declaration `type TAbstractGeometryNode = class(TAbstractNode)` ## Description Geometry nodes are the only nodes that produces some visible results during rendering. Much of the VRML language is just a method of describing properties how geometry nodes are displayed (materials, transformations, lighting). A few things that make geometry node special : Only geometry nodes may have [Local]BoundingBox. Only geometry nodes define something visible "in usual way" during rendering (Some other nodes in VRML / X3D are visible but in an unusual way, like Background and Fog. These nodes must be rendered in a special way — they are not affected in any usual way by the current transformation matrix etc.) Geometry nodes are never "grouping nodes", in particular there's never a geometry node that is (direct or indirect) child of another geometry node. So there's no need to be concerned whether geometry nodes' children are included in things like [Local]BoundingBox or Triangles/VerticesCount. Geometry nodes don't affect anything in graph traverse state. (This is important mostly for VRML 1.0, since in newer VRML / X3D "graph traverse state" is not that important.) For X3D, this descends from TAbstractNode, and TAbstractX3DGeometryNode descends from us. This way in X3D TAbstractX3DGeometryNode descends from this, and also X3D hierarchy is preserved (X3DGeometryNode must descend from X3DNode). ## Hierarchy TPersistent TNonRefCountedInterfacedPersistent TX3DFileItem TX3DNode TAbstractNode TAbstractGeometryNode ## Overview ### Methods
| `procedure CreateNode; override;`
| `function BoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;`
| `function LocalBoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;`
| `function VerticesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;`
| `function TrianglesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;`
| `function Coord(State: TX3DGraphTraverseState; out ACoord: TMFVec3f): boolean; virtual;`
| `function Coordinates(State: TX3DGraphTraverseState): TMFVec3f;`
| `function CoordIndex: TMFLong; virtual;`
| `function CoordRangesCounts(out RangeCount: TLongIntList; out SRanges, SRangeName: string; out RangeMinimumCount: Cardinal): boolean; virtual;`
| `procedure MakeCoordRanges( State: TX3DGraphTraverseState; CoordRangeHandler: TCoordRangeHandler);`
| `procedure CoordPolygons( State: TX3DGraphTraverseState; PolygonHandler: TIndexedPolygonHandler); virtual;`
| `function TexCoord(State: TX3DGraphTraverseState; out ATexCoord: TX3DNode): boolean; virtual;`
| `function TexCoordField: TSFNode; virtual;`
| `function Proxy(var State: TX3DGraphTraverseState; const OverTriangulate: boolean): TAbstractGeometryNode; virtual;`
| `function ProxyUsesOverTriangulate: boolean; virtual;`
| `function Color: TMFVec3f;`
| `function ColorRGBA: TMFColorRGBA;`
| `function FogCoord: TMFFloat; virtual;`
| `function Attrib: TMFNode; virtual;`
| `function ColorField: TSFNode; virtual;`
| `function SolidField: TSFBool; virtual;`
| `function ConvexField: TSFBool; virtual;`
| `function AutoGenerate3DTexCoords: boolean; virtual;`
| `function TransformationChange: TNodeTransformationChange; override;`
| `procedure GetTextureBounds2DST(const LocalBoxSizes: TVector3Single; out S, T: Integer);`
| `function Lit(State: TX3DGraphTraverseState): boolean; virtual;`
| `function FontTextureNode: TAbstractTexture2DNode; virtual;`
### Properties
| `property Convex: boolean read GetConvex write SetConvex;`
| `property Solid: boolean read GetSolid write SetSolid;`
## Description ### Methods
| `procedure CreateNode; override;`
Constructor for node. Only sets DefaultContainerField to 'geometry', since this is valid for all X3D nodes descending from TAbstractGeometryNode.
| `function BoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;`
Calculate bounding box of this geometry node. They require State of this node during VRML traverse state — this is mainly for VRML 1.0 nodes, that depend on such state. LocalBoundingBox gives a bounding box ignoring current transformation (or, equivalently, assuming like Transform = IdentityMatrix). Normal `BoundingBox` gives a bounding box taking current transformation into account. Notes for descendants implementors: The default implementations of these methods in TAbstractGeometryNode try to be smart and cover all common bases, so that you have to do as little work as possible to implement working descendant. For nodes based on coordinates (when Coord returns `True`), LocalBoundingBox and `BoundingBox` already have optimal and correct implementation in this class. Using Coord and CoordIndex, no other information is needed. For other nodes, we first check ProxyGeometry and ProxyState. If ProxyGeometry is non-nil, we assume these came from Proxy call and we will use them to calculate bounding boxes, local and not local. So for nodes with Proxy overridden, you don't have to implement bounding box calculation, instead a ProxyGeometry will be created and provided here by the caller. This will work Ok if Proxy node will have bounding box calculation implemented. You can always override these methods, if you don't want to use proxy (for example, maybe there exists much faster method to calculate bounding box, or maybe tighter bounding box may be calculated directly). For other nodes (not coordinate-based and without a proxy): The default implementation of LocalBoundingBox just calls `BoundingBox` with a specially modified State, such that Transform is identity. The default implementation of `BoundingBox`, in turn, just calls LocalBoundingBox and transforms this bounding box. So the default implementations call each other, and will loop infinitely... But if you override any one of them (local or not local), the other one will magically work. Note that the default implementation of LocalBoundingBox may be non-optimal as far as time is concerned, as we'll do useless multiplications by identity matrix. And the default implementation of `BoundingBox` may generate non-optimal bounding box, more direct approach (transforming each vertex) may give much tightier bounding box. So you only have to override one method — although if you want the best implementation, fastest and with the best tight bounding boxes, you may need to override both of them for some nodes.
| `function LocalBoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;`
| `function VerticesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;`
Calculate vertex and triangles count of this node. They require State of this node during VRML traverse state — this is mainly for VRML 1.0 nodes, that depend on such state. OverTriangulate has the same meaning as for TShape.Triangulate. Vertices count calculates number of different vertexes in this node. That is, it doesn't eliminate doubles in cases like Coordinate node with multiple points the same. But if some face is known to use twice the same vertex index, then this counts like a single vertex. The idea is that this indicates rendering speed. For triangles count, the returned value may be different then actual if some faces were non-convex. Things like TriangulateFace may remove degenerate triangles, so actual number of triangles may be slightly less. So don't depend on TrianglesCount as a precise measure — but it's a good fast measure of complexity of given node, how fast it will be rendered, used with collision detection etc. Notes for descendants implementors: For coordinate-based nodes (when Coord returns `True`), `VerticesCount` is already implemented in this class. Using Coord method, no other information is needed. For other nodes, the default implementation of both `VerticesCount` and TrianglesCount in this TAbstractGeometryNode class will use ProxyGeometry and ProxyState to do the work. You should override these methods if Proxy is not available (so caller will always pass ProxyGeometry = `Nil`) or some faster approach is possible.
| `function TrianglesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;`
| `function Coord(State: TX3DGraphTraverseState; out ACoord: TMFVec3f): boolean; virtual;`
Return node's list of coordinates. Returns `False` if node is not based on coordinates. Returns `True` and sets ACoord if the node is based on coordinates. Even when returns `True`, it can set ACoord = `Nil`, which means that node is based on coordinates but they are empty right now (so for example bounding box may be considered empty). In base TAbstractGeometryNode class this always returns `False`. Override this for descendants that have some kind of "`coord`" field, then this should return `True` and set ACoord to coord.point field, assuming that `coord` is set and specifies Coordinate node. Override this even if coordinates affect the look indirectly, e.g. NURBS "controlPoint" fields also should be returned here. Otherwise should return `True` and set ACoord = `Nil`. For VRML 1.0, `coord` may be taken from State, that's why we have to pass current traverse state here.
| `function Coordinates(State: TX3DGraphTraverseState): TMFVec3f;`
Return node's list of coordinates, raising exception if node is not based on coordinates. This is just like the Coord method, except it simply returns the coordinates, not the boolean result. If virtual Coord returns `False` (indicating the node is not coordinate-based) this raises ENotCoordinateBasedNode. ###### Exceptions raised ENotCoordinateBasedNode If node is not coordinate-based, that is Coord returns false.
| `function CoordIndex: TMFLong; virtual;`
Node's list of coordinate indexes. In base TAbstractGeometryNode class this always returns `Nil`. Override this for descendants that have some kind of "`coordIndex`" or "index" field used to index Coord array.
| `function CoordRangesCounts(out RangeCount: TLongIntList; out SRanges, SRangeName: string; out RangeMinimumCount: Cardinal): boolean; virtual;`
Returns an information how to split Coord array into ranges. When CoordIndex = `Nil`, then if the node's Coord array can be divided into some "ranges", we will use this information. This is used (and should be overridden) for X3D non-indexed nodes, like fanCount or stripCount or vertexCount. What precisely is a "range of coordinates" is not specified here. It may be a line stip, or one triangle strip, etc. — depending on the descendant. Returns `True` if this is available. In this case, RangeCount must be set to something <> nil, and the rest of returned variables are mainly to generate proper warnings by MakeCoordRanges.
| `procedure MakeCoordRanges( State: TX3DGraphTraverseState; CoordRangeHandler: TCoordRangeHandler);`
Splits Coord array into ranges. If CoordIndex is assigned, then a "range of coordinates" is just a range of non-negative indexes within CoordIndex. Otherwise (when CoordIndex = `Nil`), CoordRangesCounts must return `True` and we will use RangeCount to split coordinates. Call this only for nodes with coordinates, that is only when Coord returns `True`.
| `procedure CoordPolygons( State: TX3DGraphTraverseState; PolygonHandler: TIndexedPolygonHandler); virtual;`
Splits coordinate-based node into polygons. Indexes in PolygonHandler point to CoordIndex, if assigned, or directly to Coord. The ordering of generated polygons is correct, so what pointed CCW in the node field, will still point CCW according to generated PolygonHandler indexes. In this class this does nothing. Some, but not all, coordinate-based nodes (the ones when Coord returns `True`) override this. So currently, whether this is implemented is coordinated with CastleNormals and such internal needs.
| `function TexCoord(State: TX3DGraphTraverseState; out ATexCoord: TX3DNode): boolean; virtual;`
Node's texture coordinates. Returns `False` if node cannot have texture coordinates. Returns `True` and sets ATexCoord to a node defining texture coords. ATexCoord may be set to TAbstractTextureCoordinateNode descendant or to TTextureCoordinate2Node_1 (latter one only for VRML <= 1.0). ATexCoord can also be set to `Nil` in this case, which means that this node has a field for `texCoord`, but it's empty right now. In base TAbstractGeometryNode class this looks at TexCoordField, eventually returns `False`.
| `function TexCoordField: TSFNode; virtual;`
Node's texCoord field, or `Nil` if not available. Various nodes may have different exact rules about what is allowed here, but everything allows TextureCoordinateGenerator and ProjectedTextureCoordinate instances. This gives you more possibilities than the TexCoord method (as you can assign texCoord using this), however it may be not available in all cases — for example VRML 1.0 nodes do not have texCoord field, but they may have a texture coordinate node (from the state).
| `function Proxy(var State: TX3DGraphTraverseState; const OverTriangulate: boolean): TAbstractGeometryNode; virtual;`
Converts this node to another node class that may be better supported. Typically, converts some complex geometry node (like Extrusion or Teapot) into more common node like IndexedFaceSet or IndexedTriangleSet. TShape class wraps this method into a more comfortable interface, that is TShape methods simply automatically convert geometry nodes to their proxy versions if needed. In the base TAbstractGeometryNode class, returns `Nil` indicating that no conversion is known. When returns non-nil, result's NodeName must be equal to our NodeName. Some Proxy implementations (especially for VRML 1.0) will have to create new State (TX3DGraphTraverseState) instance along with a new geometry node. You should do this by copying the State into a new TX3DGraphTraverseState instance, and modyfying the State reference. Simply speaking, do
      State := TX3DGraphTraverseState.CreateCopy(State)
#) You should not just modify the fields of the provided State instance. (Reasoning: some proxy methods rely on getting the original State, e.g. with original MaterialBinding, not the transformed state, to work correctly. And some proxy methods need to modify the state differently, depending on OverTriangulate value.) You can modify State variable only when returning non-nil geometry.
| `function ProxyUsesOverTriangulate: boolean; virtual;`
Does the Proxy method look at the OverTriangulate parameter at all. Default implementation in TAbstractGeometryNode returns safer `True`. Descendants may override and return `False`, to allow e.g. more caching in TShape.
| `function Color: TMFVec3f;`
Returns color.point field, assuming that "color" field is set and specifies Color (or ColorRGBA) node. Otherwise returns `Nil`. Note that only one of Color and ColorRGBA may return non-nil, since "color" field may contain only one of them.
| `function ColorRGBA: TMFColorRGBA;`
| `function FogCoord: TMFFloat; virtual;`
| `function Attrib: TMFNode; virtual;`
| `function ColorField: TSFNode; virtual;`
| `function SolidField: TSFBool; virtual;`
Is backface culling used. `Nil` if given geometry node doesn't have a field to control it.
| `function ConvexField: TSFBool; virtual;`
Are faces guaranteed to be convex. `Nil` if given geometry node doesn't have a field to control it.
| `function AutoGenerate3DTexCoords: boolean; virtual;`
Should renderer automatically generate 3D texture coordinates, in case we will apply 3D texture on this geometry. The generated coordinates will follow the X3D specification at "Texturing3D" component: "Texture coordinate generation for primitive objects". The 3D texture space will be mapped nicely to the shape bounding box. Implementation in this class (TAbstractGeometryNode) returns always `False`. Override it for primitives that have no texture coordinates to return `True`.
| `function TransformationChange: TNodeTransformationChange; override;`
| `procedure GetTextureBounds2DST(const LocalBoxSizes: TVector3Single; out S, T: Integer);`
Calculate texture S, T coordinates for BOUNDS2D texture mapping. This mapping is like the default IndexedFaceSet texture mapping, following X3D spec. We also use it for other geometry nodes, and even allow explicitly requesting it by TextureCoordinateGenerator.mode = "BOUNDS2D".
| `function Lit(State: TX3DGraphTraverseState): boolean; virtual;`
Is this object lit, disregarding the material. Default implementation in TAbstractGeometryNode says `True`.
| `function FontTextureNode: TAbstractTexture2DNode; virtual;`
Should renderer setup an extra texture slot with font texture when rendering this node. This is useful for rendering Text nodes, that want to cooperate with normal texturing and shading, and additionally they want to use extra texture determined by font (not by Appearance node).
### Properties
| `property Convex: boolean read GetConvex write SetConvex;`
Are faces convex. This knowledge is used when calculating normal vectors by CastleNormals.
| `property Solid: boolean read GetSolid write SetSolid;`
Is backface culling used.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:14