Castle Game Engine: X3DNodes: Class TX3DGraphTraverseState

# Class TX3DGraphTraverseState
Description | Hierarchy | Fields | Methods | Properties
## Unit X3DNodes ## Declaration `type TX3DGraphTraverseState = class(TObject)` ## Description Current state (transformation and such) when traversing VRML/X3D graph. For VRML/X3D >= 2.0 this could be simpler, as VRML/X3D >= 2.0 doesn't need to keep track for example of the LastNodes. But we want to still handle VRML 1.0, 100% correctly, so here we are: this class contains whole state needed for any VRML/X3D version. ## Hierarchy TObject TX3DGraphTraverseState ## Overview ### Fields
| `Lights: TLightInstancesList;`
| `Transform: TMatrix4Single;`
| `InvertedTransform: TMatrix4Single;`
| `TransformScale: Single;`
| `TextureTransform: TMatrix4Single;`
| `ShapeNode: TAbstractShapeNode;`
| `InsideInline: Cardinal;`
| `InsidePrototype: Cardinal;`
| `InsideIgnoreCollision: Cardinal;`
| `InsideInvisible: Cardinal;`
| `PointingDeviceSensors: TPointingDeviceSensorList;`
| `HumanoidTransform: TMatrix4Single;`
| `HumanoidInvertedTransform: TMatrix4Single;`
| `Humanoid: THAnimHumanoidNode;`
| `ClipPlanes: TClipPlaneList;`
| `LocalFog: TLocalFogNode;`
| `Effects: TX3DNodeList;`
### Methods
| `procedure SetLastNodes(const StateNode: TVRML1StateNode; const Node: TX3DNode; const OwnNode: boolean);`
| `procedure AddLight(const Light: TLightInstance);`
| `procedure AssignTransform(Source: TX3DGraphTraverseState);`
| `constructor CreateCopy(Source: TX3DGraphTraverseState);`
| `constructor Create;`
| `destructor Destroy; override;`
| `procedure Assign(Source: TX3DGraphTraverseState);`
| `procedure Clear;`
| `function Equals(SecondValue: TX3DGraphTraverseState; const IgnoreTransform: boolean): boolean; reintroduce;`
| `function Texture: TAbstractTextureNode;`
| `function BlendMode: TBlendModeNode;`
| `function AddClipPlane: PClipPlane;`
| `function Emission(LightingCalculationOn: boolean): TVector3Single;`
### Properties
| `property LastNodes: TTraverseStateLastNodes read FLastNodes;`
## Description ### Fields
| `Lights: TLightInstancesList;`
Lights active in this state. May be `Nil` if empty. This way we optimize creation / assignment time, which happen very often with TX3DGraphTraverseState during VRML/X3D traversing. Note that VRML >= 2.0 "global" lights are added from TCastleSceneCore, not during the traverse pass.
| `Transform: TMatrix4Single;`
Current transformation.
| `InvertedTransform: TMatrix4Single;`
Inverted Transform matrix. This matrix is crucial for some special effects (for example, it's needed for calculating in tangent space for bump mapping). This is not calculated using any complex matrix inversion algorithms. Instead, this is calculated by updating this along the way, just like we calculate normal Transform. So it's simple, quick, and guaranteed to be correct assuming that user didn't use VRML 1.0 MatrixTransform along the way. That's why MatrixTransform node was removed from VRML 2.0, it breaks such things. Also, any scale with zero component along the way will make this partially invalid (we'll substitute identity in place of inverted scaling matrix). This is unavoidable, there's no reverse matrix for scaling with zero factor, since one resulting point may correpond to infinitely many source points (i.e., it's natural that such scaling function cannot be reversed).
| `TransformScale: Single;`
A uniform scale of the matrix Transform. If the matrix causes non-uniform scaling, this value represents an average scale. This is updated while traversing the VRML graph, just like the Transform matrix is updated. This way it's calculated fast and easy — we do not actually extract it from a matrix (as long as you don't use explicit MatrixTransform in the VRML/X3D file).
| `TextureTransform: TMatrix4Single;`
Current texture transformation. Usable only for VRML 1.0, in VRML 2.0 texture transformations don't accumulate like modelview transformations.
| `ShapeNode: TAbstractShapeNode;`
| `InsideInline: Cardinal;`
Information if you're within any inline node or expanded prototype. `InsideInline` = 0 means you're not inside any inline node, 1 means you're inside one inline, 2 means you're within content inlined from yet another inline node, and so on. Analogous for InsidePrototype. These are measured from the node where you started TX3DNode.Traverse call, that is they assume that the initial node from where you're traversing is at level 0 (not inside inline or expanded prototype). These are useful to establish "run-time name scope" of X3D, see X3D spec 4.4.7 (needed e.g. when handling Anchor node with "#Viewpoint" URL). Interpreting this for our implementation, specification says that if you traverse from node X, then all traversed nodes with `InsideInline` = InsidePrototype = 0 are within the same name scope. Also this is useful for searching for the first bindable node after loading the file. Specification says to ignore inline content in this case (although prototype content is Ok in this case). When scriping will be implemented, probably analogous InsideScriptCreatedNode will also be needed, as the spec says that bindable nodes should not be searched within things like "Browser.createX3DFromString()".
| `InsidePrototype: Cardinal;`
| `InsideIgnoreCollision: Cardinal;`
This is > 0 when traversing nodes that do not participate in collision detection. This counts how many times are we inside Collision node that prevents us from colliding. More precise, this is increased when we traverse inside Collision.children with Collision.enabled = FALSE or Collision.proxy <> NULL (since then Collision.children are not collidable).
| `InsideInvisible: Cardinal;`
This is > 0 when traversing nodes that are not visible. This counts how many times are we inside Collision.proxy (with Collision.enabled = TRUE). Collision.proxy is never visible.
| `PointingDeviceSensors: TPointingDeviceSensorList;`
Active pointing device sensors in this state. This can contain only nodes descending from X3DPointingDeviceSensorNode, and additionally an Anchor node. This list automatically honours VRML / X3D rules for what pointing device sensor is active: pointing device within some group node affects all children in this group node. (And when multiple pointing device sensors are within the same grouping node, they all work.)
| `HumanoidTransform: TMatrix4Single;`
For Humanoid skeleton, these contain cummulated joint transformation.
| `HumanoidInvertedTransform: TMatrix4Single;`
For Humanoid skeleton, these contain cummulated joint transformation.
| `Humanoid: THAnimHumanoidNode;`
Humanoid node containing us, or `Nil` if none.
| `ClipPlanes: TClipPlaneList;`
`ClipPlanes` affecting nodes within this state. They are collected here regardless of whether they are enabled or not. This allows efficient implementation of `ClipPlane.enabled` dynamic changes. Ordered from the most global to most local ones. So, following the X3D specification, we should consider the first clip planes on this list more important. Always `Nil` if empty. This allows us to optimize TX3DGraphTraverseState processing.
| `LocalFog: TLocalFogNode;`
Local fog settings. When `Nil`, it means use global fog (or no fog, if no global fog defined in file).
| `Effects: TX3DNodeList;`
Effects (TEffectNode) affecting this state.
### Methods
| `procedure SetLastNodes(const StateNode: TVRML1StateNode; const Node: TX3DNode; const OwnNode: boolean);`
| `procedure AddLight(const Light: TLightInstance);`
| `procedure AssignTransform(Source: TX3DGraphTraverseState);`
Copy transformation-related fields from Source. Copies Transform matrix, along with related information like InvertedTransform and TransformScale. Copies also the ClipPlanes list, as it contains the transformation information.
| `constructor CreateCopy(Source: TX3DGraphTraverseState);`
| `constructor Create;`
Standard constructor. Uses global StateDefaultNodes as default nodes for VRML 1.0 state. This makes it fast, and improves cache (more nodes have equal reference).
| `destructor Destroy; override;`
| `procedure Assign(Source: TX3DGraphTraverseState);`
| `procedure Clear;`
Clear the whole state, just like this TX3DGraphTraverseState instance would be just constructed.
| `function Equals(SecondValue: TX3DGraphTraverseState; const IgnoreTransform: boolean): boolean; reintroduce;`
Compare with other TX3DGraphTraverseState instance. True if these two states, when applied to the same geometry, result in the same TGeometryArrays output. If IgnoreTransform then we should ignore transformation during comparison (it means that renderer is absolutely sure that different transformation of geometry doesn't affect the generated arrays).
| `function Texture: TAbstractTextureNode;`
Returns texture node that should be used for nodes within this State. Regardless of VRML/X3D version. May return multi-texture (TMultiTextureNode), or normal 2D texture (TAbstractTexture2DNode), or some other TAbstractTextureNode descendant (cube map, 3d texture). Details: If ShapeNode <> nil, this returns texture node taken from ShapeNode.Texture (note that it may be nil, if Apperance of Appearance.Texture node is NULL in VRML). Otherwise it returns texture from LastNodes.Texture2.
| `function BlendMode: TBlendModeNode;`
Returns `BlendMode` for this state, or `Nil` if not present.
| `function AddClipPlane: PClipPlane;`
| `function Emission(LightingCalculationOn: boolean): TVector3Single;`
Calculate emission color of given shape. This can be used by software renderers (ray-tracers etc.) to calculate pixel color following VRML/X3D specifications. Emission should be added to TLightInstance.Contribution (for each light), and resulting color should be processed by TFogNode.ApplyFog. When LightingCalculationOn = `False` we actually take diffuseColor instead of emissiveColor. This is useful if you want to force the scene completely unlit, usually diffuseColor is more useful for this (since emissiveColor is often black on everything).
### Properties
| `property LastNodes: TTraverseStateLastNodes read FLastNodes;`
Nodes that are saved during VRML/X3D traversing. These nodes affect some following nodes in the graph, mostly for VRML 1.0. They are never `Nil` (traversing code must always take care to initialize them to default nodes at the beginning). Note that TX3DGraphTraverseState instance doesn't have to own these nodes (doesn't free them, and doesn't track of when they are freed). E.g. nodes' TX3DNode.ParentsCount doesn't take into account that they are owned by this state. Although for some tricks (but not during normal VRML/X3D traversing) some nodes are owned, by using SetLastNodes with OwnNode = `True`. For nodes that are within TraverseStateLastNodesClasses (and thus are stored inside `LastNodes`): it's guaranteed they don't affect the state (of this class) during traversing (that is, they don't do anything special in TX3DNode.BeforeTraverse / TX3DNode.MiddleTraverse / TX3DNode.AfterTraverse). So it's guaranteed that changing some field's value of a node within TraverseStateLastNodesClasses affects only the shapes that have given node inside State.LastNodes. TCastleSceneCore.ChangedField depends on that.
Generated by PasDoc 0.13.0 on 2013-08-17 21:27:15