Class TAbstractGeometryNode

Unit

Declaration

type TAbstractGeometryNode = class(TAbstractNode)

Description

Base node for a visible geometry in X3D.

Hierarchy

Overview

Methods

Protected function InternalCoordRangesCounts(out RangeCount: TLongIntList; out SRanges, SRangeName: string; out RangeMinimumCount: Cardinal): boolean; virtual;
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 InternalCoord(State: TX3DGraphTraverseState; out ACoord: TMFVec3f): boolean; virtual;
Public function InternalCoordinates(State: TX3DGraphTraverseState): TMFVec3f;
Public function CoordIndexField: TMFLong; virtual;
Public procedure InternalMakeCoordRanges( State: TX3DGraphTraverseState; CoordRangeHandler: TCoordRangeHandler);
Public procedure InternalCoordPolygons( State: TX3DGraphTraverseState; PolygonHandler: TIndexedPolygonHandler); virtual;
Public function InternalTexCoord(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 InternalColor: TMFVec3f;
Public function InternalColorRGBA: TMFColorRGBA;
Public function InternalFogCoord: TMFFloat; virtual;
Public function AttribField: 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: TVector3; out S, T: Integer);
Public function Lit(State: TX3DGraphTraverseState): boolean; virtual;
Public function FontTextureNode: TAbstractTexture2DNode; virtual;
Public constructor CreateWithShape(out Shape: TShapeNode);
Public constructor CreateShape(out Shape: TShapeNode); deprecated 'use CreateWithShape';
Public constructor CreateWithTransform(out Shape: TShapeNode; out Transform: TTransformNode);
Public constructor CreateTransform(out Shape: TShapeNode; out Transform: TTransformNode); deprecated 'use CreateWithTransform';

Properties

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

Description

Methods

Protected function InternalCoordRangesCounts(out RangeCount: TLongIntList; out SRanges, SRangeName: string; out RangeMinimumCount: Cardinal): boolean; virtual;

Returns an information how to split InternalCoord array into ranges.

When CoordIndex = Nil, then if the node's InternalCoord 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 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 InternalCoord 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 InternalCoord 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 InternalCoord(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 InternalCoordinates(State: TX3DGraphTraverseState): TMFVec3f;

Return node's list of coordinates, raising exception if node is not based on coordinates.

This is just like the InternalCoord method, except it simply returns the coordinates, not the boolean result. If virtual InternalCoord returns False (indicating the node is not coordinate-based) this raises ENotCoordinateBasedNode.

Exceptions raised
ENotCoordinateBasedNode
If node is not coordinate-based, that is InternalCoord returns false.
Public function CoordIndexField: 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 InternalCoord array.

Public procedure InternalMakeCoordRanges( State: TX3DGraphTraverseState; CoordRangeHandler: TCoordRangeHandler);

Splits InternalCoord 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), InternalCoordRangesCounts must return True and we will use RangeCount to split coordinates.

Call this only for nodes with coordinates, that is only when InternalCoord returns True.

Public procedure InternalCoordPolygons( 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 InternalCoord returns True) override this. So currently, whether this is implemented is coordinated with CastleInternalNormals and such internal needs.

Public function InternalTexCoord(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 InternalTexCoord 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.

The resulting node's Name (if the result is not Nil) must be equal to our Name.

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

@(longcode#
        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 InternalColor: 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 InternalColorRGBA: TMFColorRGBA;
 
Public function InternalFogCoord: TMFFloat; virtual;
 
Public function AttribField: 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: TVector3; 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).

Public constructor CreateWithShape(out Shape: TShapeNode);

Create an instance of this geometry node, and make it a child of a new shape node (TShapeNode). This way you get a ready shape that can be used inside the X3D scene graph to show this geometry.

You usually want to add the resulting Shape node to some scene, e.g. like this:

Box := TBoxNode.CreateWithShape(Shape);

Root := TX3DRootNode.Create;
Root.AddChildren(Shape);

Scene := TCastleScene.Create(nil);
Scene.Load(Root, true);

Remember that once the node is a children of another node, then this node will be automatically freed. So you should not free the resulting geometry node. Instead, free the resulting Shape node, or add it to some scene, as shown above.

Public constructor CreateShape(out Shape: TShapeNode); deprecated 'use CreateWithShape';

Warning: this symbol is deprecated: use CreateWithShape

 
Public constructor CreateWithTransform(out Shape: TShapeNode; out Transform: TTransformNode);

Create an instance of this geometry node, and make it a child of a new shape node (TShapeNode), and make it a child of a new transform node (TTransformNode). This way you get a ready transformation that can be used inside the X3D scene graph to show and transform this geometry.

You usually want to add the resulting Transform node to some scene, e.g. like this:

Box := TBoxNode.CreateWithTransform(Shape, Transform);

Root := TX3DRootNode.Create;
Root.AddChildren(Transform);

Scene := TCastleScene.Create(nil);
Scene.Load(Root, true);

Remember that once the node is a children of another node, then this node will be automatically freed. So you should not free the resulting geometry node or Shape node. Instead, free the resulting Transform node, or add it to some scene, as shown above.

Public constructor CreateTransform(out Shape: TShapeNode; out Transform: TTransformNode); deprecated 'use CreateWithTransform';

Warning: this symbol is deprecated: use CreateWithTransform

 

Properties

Public property Convex: boolean read GetConvex write SetConvex;

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

Public property Solid: boolean read GetSolid write SetSolid;

Is backface culling used.


Generated by PasDoc 0.15.0.