Castle Game Engine: CastleOctree: Class TOctree

# Class TOctree
Description | Hierarchy | Fields | Methods | Properties
## Unit CastleOctree ## Declaration `type TOctree = class(TObject)` ## Description Base abstract octree class. Holds some settings common for the whole octree (like MaxDepth) and a reference to the root octree node (of TOctreeNode class) in the protected property InternalTreeRoot. ## Hierarchy TObject TOctree ## Overview ### Methods
| `function StatisticsBonus( const LeavesCount, ItemsCount, NonLeafNodesCount: Int64): string; virtual;`
| `constructor Create(AMaxDepth, ALeafCapacity: integer; const ARootBox: TBox3D; AOctreeNodeFinalClass: TOctreeNodeClass; AItemsInNonLeafNodes: boolean);`
| `constructor Create(const Limits: TOctreeLimits; const ARootBox: TBox3D; AOctreeNodeFinalClass: TOctreeNodeClass; AItemsInNonLeafNodes: boolean);`
| `destructor Destroy; override;`
| `procedure EnumerateCollidingOctreeItems( const Frustum: TFrustum; EnumerateOctreeItemsFunc: TEnumerateOctreeItemsFunc);`
| `function Statistics: string;`
### Properties
| `property InternalTreeRoot: TOctreeNode read FTreeRoot;`
| `property MaxDepth: integer read FMaxDepth write FMaxDepth;`
| `property LeafCapacity: Integer read FLeafCapacity write FLeafCapacity;`
| `property ItemsInNonLeafNodes: boolean read FItemsInNonLeafNodes;`
| `property OctreeNodeFinalClass: TOctreeNodeClass read FOctreeNodeFinalClass;`
## Description ### Methods
| `function StatisticsBonus( const LeavesCount, ItemsCount, NonLeafNodesCount: Int64): string; virtual;`
This will be appended to output of Statistics. In this class this returns ''. You can override this if you want, and you can use there LeavesCount, ItemsCount, NonLeafNodesCount counts (they are already calculated for the sake of Statistics anyway). Every line, including the last one, must be terminated by nl.
| `constructor Create(AMaxDepth, ALeafCapacity: integer; const ARootBox: TBox3D; AOctreeNodeFinalClass: TOctreeNodeClass; AItemsInNonLeafNodes: boolean);`
| `constructor Create(const Limits: TOctreeLimits; const ARootBox: TBox3D; AOctreeNodeFinalClass: TOctreeNodeClass; AItemsInNonLeafNodes: boolean);`
| `destructor Destroy; override;`
| `procedure EnumerateCollidingOctreeItems( const Frustum: TFrustum; EnumerateOctreeItemsFunc: TEnumerateOctreeItemsFunc);`
Traverse octree seeking for nodes that (possibly) collide with given Frustum. For every such item calls given EnumerateOctreeItemsFunc. Requires that ParentTree.ItemsInNonLeafNodes = true (checked by assertion here, so only if you have assertions on). May be implemented one day to work with ParentTree.ItemsInNonLeafNodes = false too, but it will be (usually) much slower on such tree. It gives to EnumerateOctreeItemsFunc an ItemIndex, an index to octrees items. This is just taken from ItemIndices array. May call EnumerateOctreeItemsFunc with the same ItemIndex multiple times. It also gives to EnumerateOctreeItemsFunc parameter CollidesForSure: If CollidesForSure = true then octree node that had this item was found to be entirely in the frustum. This means that (assuming that octree item that is in some octree node always collides with Box of this node, and it should always be true) given octree item for sure collides with frustum. If CollidesForSure = false then given octree item was found inside some octree leaf that may only partially (or not at all) collide with frustum. And this function doesn't check whether your octree item possibly collides with Frustum (since in this generic octree unit, CastleOctree, we have no knowledge about geometry of your octree items). So you may want to check inside EnumerateOctreeItemsFunc handler your octree items versus Frustum, if you want to have greatest possibility of eliminating octree items that are not within your frustum (but beware that too many checks for visibility can also cost you too much time...). That why CollidesForSure may be useful: if it's true then you already know for sure that frustum collides with this octree item, so you don't have to waste your time on additional checks. Notes for implementing descendants of this class: This method simply calls TreeRoot.EnumerateCollidingOctreeItems.
| `function Statistics: string;`
Multi-line description of how the octree levels look like. Describes how many leaves / non-leaves we have, how many items in leaves we have and on each level and in summary. Every line, including the last one, is terminated by newline. Notes for implementing descendants of this class: You can override StatisticsBonus, it's appended to the result of this method.
### Properties
| `property InternalTreeRoot: TOctreeNode read FTreeRoot;`
| `property MaxDepth: integer read FMaxDepth write FMaxDepth;`
Maximum tree depth. Set this to zero to force RootNode to be a leaf (useful to test whether octree vs a flat list is actually useful). Currently, you should not change `MaxDepth` and LeafCapacity after creating the octree, as they will not rebuild the octree to obey the given limits.
| `property LeafCapacity: Integer read FLeafCapacity write FLeafCapacity;`
Maximum number of items inside a leaf, unless this leaf is already at maximum depth (MaxDepth). When you add an item to a leaf, to keep `LeafCapacity` correct. Must be >= 1.
| `property ItemsInNonLeafNodes: boolean read FItemsInNonLeafNodes;`
Does this octree keep items also in internal nodes. Leaf nodes always store items (have ItemIndices). If you set this property to `True` when constructing this object then all created TOctreeNode will have ItemIndices property that keeps the items inside. Advantages: e.g. consider frustum culling using octree. In some situations you know that some OctreeNode is completely inside frustum. Then you want to mark all items inside this OctreeNode as "visible". If you would have to traverse all children of this OctreeNode, you could have horribly slow algorithm (especially since one item is often stored in many leafs, since it collides with many leafs BoundingBoxes). So you can set `ItemsInNonLeafNodes` and simply use ItemIndices list of your OctreeNode. And you don't have to traverse children of this OctreeNode. Disadvantages: if you have many items in your octree (as is typical with e.g. TTriangleOctree) then this property can cost you a lot of memory.
| `property OctreeNodeFinalClass: TOctreeNodeClass read FOctreeNodeFinalClass;`
The actual (non-abstact) TOctreeNode descendant class for this octree. Set when constructing this octree. This tells what class should have FTreeRoot. Since inside TOctreeNode, each children node (in TreeSubNodes) always has the same class as it's parent, so class `OctreeNodeFinalClass` determines the TOctreeNode descendant that will be used to construct your whole octree.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:10