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

This item has no description.

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.

This item has no description.

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.

This item has no description.

Possible options for TCastleSceneCore.Load.

Values

• slDisableResetTime

This item has no description.

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

This is safe to enable, however in some cases (when you only animate a single / few transformations, and the whole scene is a big tree with many transformation) it may hurt performance more than it helps. But in many practical cases, with skeleton-based animations from Spine or glTF, it helps a lot.

See examples/animations/optimize_animations_test for a demo of this.

Experimental optimization of Transform animation. It assumes that Transform nodes affect only geometry, i.e. their only effect is moving/rotating/scaling 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.

See examples/animations/optimize_animations_test for a demo of this.

This item has no description.