Class TCastleScene

Internal override test visibility.

This item has no description. Showing description inherited from TCastleSceneCore.CreateShape.

Create TShape (or descendant) instance suitable for this TCastleSceneCore descendant. In this class, this simply creates new TShape instance. If you make a descendant of TCastleSceneCore, you may need to store some per-shape information, and then it may be useful to have your own TShape descendant to carry this information. So you can override this to create your own descendant, and then you're sure that all leafs within Shapes tree are created using this.

Example: TCastleScene uses this to create TGLShape.

This item has no description.

This item has no description. Showing description inherited from TCastleTransform.LocalRender.

Collect the things to be rendered now.

Override this method if you need to perform custom rendering, by direct OpenGL(ES) calls. Never call this method yourself – the rendering of TCastleViewport will call it when needed.

Warning: It is an advanced topic how to make such rendering work, and make it work in a cross-platform way. You will need to understand how OpenGL(ES) works, and you will need to account for how the engine renders things too, to not conflict with the engine – e.g. you will have to use RenderContext for some things. If you're not ready for this, then you're better off not overriding this method, instead just rely on the engine built-in rendering, done by TCastleScene and other components.

This method gets parameters (Params) including a full transformation of this scene.

In return, it should add the things to be rendered in this frame using Params.AddRenderEvent.

Internally: TCastleScene also adds X3D shapes to be rendered to TRenderParams.Collector. But you should not need to deal with TRenderParams.Collector in your own code.

TODO: The names LocalRender, TRenderParams are now confusing. LocalRender is not a method where one should "render" anymore. It's a "collection phase". Think of it as "TCastleTranssform.CollectThingsToRender(const Params: ...)" and bear with us as we figure out a non-confusing naming around this.

Render shadow volume (sides and caps) of this scene, for shadow volume algorithm.

Uses ShadowVolumeRenderer for rendering, and to detect if rendering is necessary at all.

It always uses silhouette optimization. This is the usual, fast method of rendering shadow volumes.

All shadow quads are generated from scene triangles transformed by ParentTransform. We must be able to correctly detect front and back facing triangles with respect to light position, so ShadowVolumeRenderer.LightPosition and "this scene transformed by ParentTransform" must be in the same coordinate system. If ParentTransformIsIdentity then ParentTransform value is ignored and everything works like ParentTransform = identity matrix (and is a little faster in this special case).

Uses TrianglesListShadowCasters and ManifoldEdges and BorderEdges (so you may prefer to prepare it before, e.g. by calling PrepareResources with prShadowVolume included).

We look at some RenderOptions, like RenderOptions.Blending, because transparent triangles have to be handled a little differently, and when RenderOptions.Blending = false then all triangles are forced to be opaque. In other words, this takes RenderOptions into account, to cooperate with our Render method.

ShadowVolumeRenderer.LightPosition is the light position. ShadowVolumeRenderer.LightPosition[3] must be 1 (to indicate positional light) or 0 (a directional light). It's expected that ShadowVolumeRenderer is already initialized by ShadowVolumeRenderer.InitFrustumAndLight.

Faces (both shadow quads and caps) are rendered such that CCW <=> you're looking at it from outside (i.e. it's considered front face of this shadow volume).

This item has no description. Showing description inherited from TCastleTransform.ChangeWorld.

Called when the current World that contains this object changes. In the usual case, World corresponds to a TCastleViewport.Items instance, and when this method is called it means that object is added/removed from a viewport.

You can ignore this when called with Value equal to current World.

Note that each TCastleTransform instance can only be part of one world (TCastleAbstractRootTransform) at a time. Although we may be present many times within the same world. Always remove the TCastleTransform from previous world before adding it to a new one.

This item has no description.

This item has no description.

This item has no description. Showing description inherited from TCastleTransform.Update.

Continuously occuring event, for various tasks.

Executed only on instances that have Exists (no need to check this in overridden Update implementation).

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Destroy any associations of this object with current OpenGL context. For example, release any allocated texture names.

Generally speaking, destroys everything that is allocated by PrepareResources call. It's harmless to call this method when there are already no associations with current OpenGL context. This is called automatically from the destructor.

Warning: this symbol is deprecated: this is internal; use TCastleViewport.PrepareResources to prepare transformations

This item has no description. Showing description inherited from TCastleTransform.PrepareResources.

Prepare resources, making various methods (like rendering and such) to execute fast.

It is usually simpler to call TCastleViewport.PrepareResources then this method. Calling Viewport.PrepareResources(MyScene) will automatically call MyScene.PrepareResources(...) underneath, with proper parameters.

It is best to call this when the rendering context is initailized, e.g. at Application.OnInitialize or later. Calling this method before the rendering context is initialized (e.g. from initializaton section of some unit) will have to skip some preparations, thus reducing the effectiveness of this method. But it is allowed to call this at any time, regardless of the context being initialized, just like e.g. TCastleContainer.LoadSettings (which may call this, to warmup cache).

This makes sure that appropriate methods execute as fast as possible. It's never required to call this method — everything will be prepared "as needed" anyway. But if you allow everything to be prepared "as needed", then e.g. the first Render call may take a long time because it may have to prepare resources that will be reused in next Render calls. This may make your program seem slow at the beginning (when rendering resources are being prepared, so at the first frame, or a couple of first animation frames). To avoid this, call this method, showing the user something like "now we're preparing the resources — please wait".

TODO: It is not possible to call this now without TPrepareParams, and to get params you need to access deprecated TCastleViewport.PrepareParams. We advise to call TCastleViewport.PrepareResources instead. We'd like to get rid of TPrepareParams eventually.

This item has no description. Showing description inherited from TCastleSceneCore.BeforeNodesFree.

Release all internal associations with your VRML/X3D nodes. In particular, this will release OpenGL resources connected to your nodes. You should always call this before you (may) free some nodes in RootNode.

You have to call ChangedAll or Load at sometime after BeforeNodesFree, and before you try actual rendering, events etc. Otherwise some stuff may not get recalculated.

The InternalChangedAll parameter is for internal use. It is set to True when ChangedAll calls this method at the beginning of it's work, and means that nothing is freed, and we only require necessary cleanup at the beginning of ChangedAll. This way ChangedAll (when it wasn't preceeded by explicit BeforeNodesFree(false)) produces events from stacks CheckForDeletedNodes.

Does this transform have a collision mesh that TCastleMeshCollider can use.

Enumerate triangles for a collision mesh that TCastleMeshCollider can use.

This item has no description. Showing description inherited from TCastleSceneCore.FreeResources.

Frees some scene resources, to conserve memory. See TSceneFreeResources documentation.

Warning: this symbol is deprecated: use RenderOptions

This item has no description.

This item has no description.

This item has no description.

This item has no description.

Create a scene with the same contents (X3D scene graph) as this one. The created scene has exactly the same class as this one (we use ClassType.Create to call a virtual constructor).

Note that this does not copy other scene properties, like ProcessEvents or RenderOptions contents.

Whether the scene was (potentially, at least partially) visible in the last rendering event.

The "was visible" means that "some shape was visible", that is: some shape passed frustum culling, distance culling and occlusion culling (see https://castle-engine.io/occlusion_culling ) tests.

The result of this method is not affected by:

• Lights.

  That is, it doesn't matter whether this scene contains some lights (X3D light nodes in RootNode) that possibly make some other scenes brighter.

• Background.

  It doesn't matter whether the scene contains some background that affects TCastleViewport skybox.

• Children scenes.

  It doesn't matter if you have any children scenes (TCastleScene instances that are children of this) and whether they are visible. This follows the general rule that TCastleScene-specific features do not look/affect children scenes, including children TCastleScene. Only TCastleTransform features, like TCastleTransform.Exists, are applied recursively, i.e. they generally affect the children transformations.

To summarize and emphasize: for this method, only the visibility of shapes within this scene matters.

If this scene instance is used multiple times within some viewport, or when multiple viewports render the same scene, then it is enough that at least one shape in one of the scene instances was visible last frame.

TODO: For now, occlusion culling doesn't affect this, i.e. if the scene is not visible because occlusion culling.

Improve performance of rendering by checking for each shape whether it is inside frustum (camera pyramid of view) before rendering.

This is almost always a good idea. Exception may be when, in the most common scene position, all the shapes are inside the frustum, or all the shapes are outside the frustum. In this case this check is wasting time, and it matters if you have a lot of shapes. In such case, SceneFrustumCulling will be enough.

Improve performance of rendering by checking for the whole scene whether it is inside frustum (camera pyramid of view) before rendering.

This is almost always a good idea. Exception may be when the scene is almost always within the frustum, and you have a lot of scenes. In such case, this check may be a waste of time.

Does this scene receive shadows by shadow volumes.

Cull shapes farther than this distance. Ignored if <= 0.

Rendering options. You are free to change them at any time.

Lights defines by given scene shine on everything in the viewport, including all other TCastleScene.