Unit CastleSceneCore

These are various features that may be freed by TCastleSceneCore.FreeResources.

Warning: This is for experienced usage of TCastleSceneCore. Everything is explained in detail below, but still — if you have some doubts, or you just don't observe any memory shortage in your program, it's probably best to not use TCastleSceneCore.FreeResources.

• For frTextureDataInNodes, frBackgroundImageInNodes and TrianglesList, if you will free them unnecessarily (i.e. you will use it after you freed it), it will be automatically recreated on next use. So everything will work correctly, but you will experience unnecessary slowdown if we will need to recreate exactly the same resource over and over again.

• For frTextureDataInNodes and frBackgroundImageInNodes note that freeing these resources too eagerly may make texture cache (see TextureImages) less effective. In normal circumstances, if you will use the same cache instance throughout the program, loaded images are reused. If you free frTextureDataInNodes too early, you may remove them from the cache too early, and lose a chance to reuse them. So you may cause unnecessary slowdown of preparing models, e.g. inside PrepareResources.

Values

• frTextureDataInNodes: Unloads the texture images/videos allocated in texture nodes.

  It's useful if you know that you already prepared everything that needed the texture images, and you will not need texture images later. For TCastleScene this means that you use Optimization method other than roNone, and you already did PrepareResources (so textures are already loaded to OpenGL), and your code will not access TextureImage / TextureVideo anymore. This is commonly True for various games.

  Then you can call this to free some resources.

  Note that if you made an accident and you will use some TextureImage or TextureVideo after FreeResources, then you will get no crash, but texture image will be simply reloaded. So you may experience slowdown if you inappropriately use this feature.

• frBackgroundImageInNodes: Unloads the background images allocated in VRML/X3D Background nodes. The same comments as for frTextureDataInNodes apply.
• frShadowVolume: Free data created for shadow volumes processing. This frees some memory, but trying to render shadow volumes will need to recreate this data again (at least for all active shapes). So freeing this is useful only if you have used shadow volumes, but you will not need to render with shadow volumes anymore (for some time).

Callback for TCastleSceneCore.OnGeometryChanged.

SomeLocalGeometryChanged means that octree, triangles, bounding volumes local to some shape changed (not just e.g. shape transformation).

OnlyShapeChanged is meaningful when SomeLocalGeometryChanged = True. If nil, it indicates that only the given shape geometry changed. If not nil, assume that every shape's geometry potentially changed.

Possible spatial structures that may be managed by TCastleSceneCore, see TCastleSceneCore.Spatial.

Values

• ssRendering: Create and keep up-to-date a spatial structure containing all visible shapes. It's useful for "frustum culling", it will be automatically used by TCastleScene rendering to speed it up.

  This octree will be automatically updated on dynamic scenes (when e.g. animation moves some shape by changing it's transformation).

• ssDynamicCollisions: Create and keep up-to-date a spatial structure containing all collidable shapes (and then reaching into collidable triangles for a specifc shape). It is automatically used by the XxxCollision methods in this class.

  This is actually a hierarchy of octrees: scene is partitioned first into Shapes (each instance of VRML/X3D geometry node), and then each Shape has an octree of triangles inside.

  This octree is useful for all kinds of collision detection. Compared to ssStaticCollisions, it is (very slightly on typical scenes) less efficient, but it can also be updated very fast. For example, merely transforming some Shape means that only one item needs to be moved in the top-level shape tree. So this is the most important structure for collision detection on dynamic scenes.

• ssVisibleTriangles: Create a spatial structure containing all visible triangles, suitable only for scenes that stay static.

  It's primarily use is for ray-tracers, that make a lot of collision queries to the same scene in the same time. When rendering using OpenGL, this has no use currently.

  This structure is not updated on scene changes. In fact, the scene contents cannot change when this octree is created — as this octree keeps pointers to some states that may become invalid in dynamic scenes.

• ssStaticCollisions: Create a spatial structure containing all collidable triangles, only for scenes that never change.

  It may be useful if you're absolutely sure that you have a static scene (nothing changes, i.e. ProcessEvents = False and you never make any change to X3D nodes from code) and you want to have collision detection with the scene.

  For dynamic scenes, using this is a bad idea as this octree is not updated on scene changes. In fact, the scene contents cannot change when this octree is created — as this octree keeps pointers to some states that may become invalid in dynamic scenes. Use ssDynamicCollisions for dynamic scenes.

Values

• gcAll: Everything changed. All octrees must be rebuild, old State pointers may be invalid.

  Every ChangedAll call does this. ChangedAll must take into account that everything could change. Note that ChangedAll traverses the VRML/X3D graph again, recalculating State values... so the old States are not correct anymore. You have to rebuild the octree or your pointers will be bad.

  When DoGeometryChanged with gcAll is called, we know that ChangedAll called this, and every TShape will be (or already is) destroyed and created new.

• gcCollidableTransformChanged: Transformation of some shape changed.
• gcVisibleTransformChanged
• gcLocalGeometryChanged: Local geometry change happened (actual octree free is already done by TShape.LocalGeometryChanged, octree create will be done at next demand). We should update stuff at higher (TCastleSceneCore) level accordingly.

  gcLocalGeometryChangedCoord means that coordinates changed. Compared to gcLocalGeometryChanged, this means that model edges structure remains the same (this is helpful e.g. to avoid recalculating Manifold/BorderEdges).

  In this case, DoGeometryChanged parameter LocalGeometryShape is non-nil and indicated the (only) shape that changed.

• gcLocalGeometryChangedCoord
• gcActiveShapesChanged: What is considered "active" shapes changed. Like after Switch.whichChoice change.

Warning: this symbol is deprecated: use PlayAnimation with "Loop: boolean" parameter instead of TPlayAnimationLooping

Looping mode to use with TCastleSceneCore.PlayAnimation.

Values

• paDefault: Use current TimeSensor.Loop value to determine whether animation should loop. Suitable when X3D model already has sensible "TimeSensor.loop" values.
• paLooping: Set TimeSensor.Loop to be True, to force looping.
• paNotLooping: Set TimeSensor.Loop to be False, to force not looping.

Possible values for TCastleSceneCore.PrimitiveGeometry.

Values

• pgNone
• pgRectangle2D
• pgSphere
• pgBox

Possible options for TCastleSceneCore.Load.

Values

• slDisableResetTime

Old name for paLooping.

Old name for paNotLooping.

Warning: this symbol is deprecated: use ssStaticCollisions instead

Log changes to fields. This debugs what and why happens through TCastleSceneCore.InternalChangedField method and friends, which is central to VRML/X3D dynamic changes and events engine.

Meaningful only if you initialized log (see CastleLog unit) by InitializeLog first.

Set this to optimize animating transformations for scenes where you have many transformations (many Transform nodes), and many of them are animated at the same time. Often particularly effective for skeletal animations of characters, 3D and 2D (e.g. from Spine or glTF).

Experimental optimization of Transform animation. It assumes that Transform nodes affect only geometry, i.e. their only effect is moving/rotating etc. X3D shapes. This is *usually*, but not always, true. In X3D, Transform node can also affect lights, Background, Fog, cameras...

TODO: Extend it to include all cases, and use always.