Class TAbstractGeometryNode

DescriptionHierarchyFieldsMethodsProperties

Unit

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

Overview

Methods

Public procedure CreateNode; override;
Public function BoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;
Public function LocalBoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;
Public function VerticesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;
Public function TrianglesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;
Public function Coord(State: TX3DGraphTraverseState; out ACoord: TMFVec3f): boolean; virtual;
Public function Coordinates(State: TX3DGraphTraverseState): TMFVec3f;
Public function CoordIndex: TMFLong; virtual;
Public function CoordRangesCounts(out RangeCount: TLongIntList; out SRanges, SRangeName: string; out RangeMinimumCount: Cardinal): boolean; virtual;
Public procedure MakeCoordRanges( State: TX3DGraphTraverseState; CoordRangeHandler: TCoordRangeHandler);
Public procedure CoordPolygons( State: TX3DGraphTraverseState; PolygonHandler: TIndexedPolygonHandler); virtual;
Public function TexCoord(State: TX3DGraphTraverseState; out ATexCoord: TX3DNode): boolean; virtual;
Public function TexCoordField: TSFNode; virtual;
Public function Proxy(var State: TX3DGraphTraverseState; const OverTriangulate: boolean): TAbstractGeometryNode; virtual;
Public function ProxyUsesOverTriangulate: boolean; virtual;
Public function Color: TMFVec3f;
Public function ColorRGBA: TMFColorRGBA;
Public function FogCoord: TMFFloat; virtual;
Public function Attrib: TMFNode; virtual;
Public function ColorField: TSFNode; virtual;
Public function SolidField: TSFBool; virtual;
Public function ConvexField: TSFBool; virtual;
Public function AutoGenerate3DTexCoords: boolean; virtual;
Public function TransformationChange: TNodeTransformationChange; override;
Public procedure GetTextureBounds2DST(const LocalBoxSizes: TVector3Single; out S, T: Integer);
Public function Lit(State: TX3DGraphTraverseState): boolean; virtual;
Public function FontTextureNode: TAbstractTexture2DNode; virtual;

Properties

Public property Convex: boolean read GetConvex write SetConvex;
Public property Solid: boolean read GetSolid write SetSolid;

Description

Methods

Public procedure CreateNode; override;

Constructor for node. Only sets DefaultContainerField to 'geometry', since this is valid for all X3D nodes descending from TAbstractGeometryNode.

Public 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.

  1. 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.

  2. 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).

  3. 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.

Public function LocalBoundingBox(State: TX3DGraphTraverseState; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): TBox3D; virtual;
 
Public 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.

Public function TrianglesCount(State: TX3DGraphTraverseState; OverTriangulate: boolean; ProxyGeometry: TAbstractGeometryNode; ProxyState: TX3DGraphTraverseState): Cardinal; virtual;
 
Public 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.

Public 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.
Public 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.

Public 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.

Public 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.

Public 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.

Public 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.

Public 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).

Public 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.

Public 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.

Public 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.

Public function ColorRGBA: TMFColorRGBA;
 
Public function FogCoord: TMFFloat; virtual;
 
Public function Attrib: TMFNode; virtual;
 
Public function ColorField: TSFNode; virtual;
 
Public function SolidField: TSFBool; virtual;

Is backface culling used. Nil if given geometry node doesn't have a field to control it.

Public function ConvexField: TSFBool; virtual;

Are faces guaranteed to be convex. Nil if given geometry node doesn't have a field to control it.

Public 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.

Public function TransformationChange: TNodeTransformationChange; override;
 
Public 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".

Public function Lit(State: TX3DGraphTraverseState): boolean; virtual;

Is this object lit, disregarding the material. Default implementation in TAbstractGeometryNode says True.

Public 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

Public property Convex: boolean read GetConvex write SetConvex;

Are faces convex. This knowledge is used when calculating normal vectors by CastleNormals.

Public property Solid: boolean read GetSolid write SetSolid;

Is backface culling used.


Generated by PasDoc 0.14.0.