Class TCastleScene

Unit

Declaration

type TCastleScene = class(TCastleSceneCore)

Description

Complete loading, processing and rendering of a scene. This is a descendant of TCastleSceneCore that adds efficient rendering.

Hierarchy

Overview

Fields

Public InternalVisibilityTest: TTestShapeVisibility;

Methods

Protected function CreateShape(const AGeometry: TAbstractGeometryNode; const AState: TX3DGraphTraverseState; const ParentInfo: PTraversingInfo): TShape; override;
Protected procedure InternalInvalidateBackgroundRenderer; override;
Protected procedure LocalRender(const Params: TRenderParams); override;
Protected procedure LocalRenderShadowVolume(const Params: TRenderParams; const ShadowVolumeRenderer: TBaseShadowVolumeRenderer); override;
Protected procedure ChangeWorld(const Value: TCastleAbstractRootTransform); override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure GLContextClose; override;
Public procedure PrepareResources(const Options: TPrepareResourcesOptions; const Params: TPrepareParams); override;
Public procedure BeforeNodesFree(const InternalChangedAll: boolean = false); override;
Public procedure Setup2D;
Public procedure FreeResources(Resources: TSceneFreeResources); override;
Public function Attributes: TCastleRenderOptions; deprecated 'use RenderOptions';
Public procedure ViewChangedSuddenly; override;
Public procedure InternalCameraChanged; override;
Public function ScreenEffects(Index: Integer): TGLSLProgram;
Public function ScreenEffectsCount: Integer;
Public function ScreenEffectsNeedDepth: boolean;
Public function Clone(const AOwner: TComponent): TCastleScene;
Public function WasVisible: Boolean;

Properties

Public property FrustumCulling: TFrustumCulling read FFrustumCulling write SetFrustumCulling default fcBox; deprecated 'use simpler ShapeFrustumCulling';
Public property OctreeFrustumCulling: TFrustumCulling read FOctreeFrustumCulling write SetOctreeFrustumCulling default fcBox; deprecated 'use simpler ShapeFrustumCulling';
Published property ShapeFrustumCulling: Boolean read FShapeFrustumCulling write SetShapeFrustumCulling default true;
Published property SceneFrustumCulling: Boolean read FSceneFrustumCulling write FSceneFrustumCulling default true;
Published property ReceiveShadowVolumes: boolean read FReceiveShadowVolumes write FReceiveShadowVolumes default true;
Published property DistanceCulling: Single read FDistanceCulling write SetDistanceCulling default 0;
Published property RenderOptions: TCastleRenderOptions read GetRenderOptions;
Published property CastGlobalLights: Boolean read FCastGlobalLights write SetCastGlobalLights default false;

Description

Fields

Public InternalVisibilityTest: TTestShapeVisibility;

Internal override test visibility.

Methods

Protected function CreateShape(const AGeometry: TAbstractGeometryNode; const AState: TX3DGraphTraverseState; const ParentInfo: PTraversingInfo): TShape; override;

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.

Protected procedure InternalInvalidateBackgroundRenderer; override;

This item has no description.

Protected procedure LocalRender(const Params: TRenderParams); override;

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

Render with given Params (includes a full transformation of this scene).

This is mostly an internal method. You should not need to override it during normal engine usage. Instead, you should render everything using TCastleScene, which allows to load or build (by code) nodes to display meshes, light and everything else. But overriding this may be useful for special customized rendering.

Protected procedure LocalRenderShadowVolume(const Params: TRenderParams; const ShadowVolumeRenderer: TBaseShadowVolumeRenderer); override;

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 will calculate current bounding box (looking at ParentTransform, ParentTransformIsIdentity and LocalBoundingBox method).

It always uses silhouette optimization. This is the usual, fast method of rendering shadow volumes. Will not do anything (treat scene like not casting shadows, like CastShadows = false) if the model is not perfect 2-manifold, i.e. has some BorderEdges (although we could handle some BorderEdges for some points of view, this could leading to rendering artifacts).

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

Protected procedure ChangeWorld(const Value: TCastleAbstractRootTransform); override;

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.

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;

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

Public function PropertySections(const PropertyName: String): TPropertySections; override;

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

Section where to show property in the editor.

Public procedure GLContextClose; override;

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.

Public procedure PrepareResources(const Options: TPrepareResourcesOptions; const Params: TPrepareParams); override;

This item has no description.

Public procedure BeforeNodesFree(const InternalChangedAll: boolean = false); override;

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.

Public procedure Setup2D;

Adjust parameters for rendering 2D scenes. Sets BlendingSort := bs2D, which is good when your transparent objects have proper order along the Z axis (useful e.g. for Spine animations).

Public procedure FreeResources(Resources: TSceneFreeResources); override;

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

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

Public function Attributes: TCastleRenderOptions; deprecated 'use RenderOptions';

Warning: this symbol is deprecated: use RenderOptions

This item has no description.

Public procedure ViewChangedSuddenly; override;

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

Notify the scene that camera position/direction changed a lot. It may be called when you make a sudden change to the camera, like teleporting the player to a completely different scene part.

This may be used as a hint by some optimizations. It tells that what will be visible in the next rendered frame will be probably very different from what was visible in the last frame.

Current implementation notes:

Currently, this is used by TCastleScene if you use RenderOptions.OcclusionQuery. Normally, occlusion query tries to reuse results from previous frame, using the assumption that usually camera changes slowly and objects appear progressively in the view. When you make a sudden camera jump/change, this assumption breaks, so it's better to resign from occlusion query for the very next frame. This method will do exactly that.

Public procedure InternalCameraChanged; override;

This item has no description.

Public function ScreenEffects(Index: Integer): TGLSLProgram;

Screen effects information, used by TCastleViewport.ScreenEffects. ScreenEffectsCount may actually prepare screen effects.

Public function ScreenEffectsCount: Integer;

This item has no description.

Public function ScreenEffectsNeedDepth: boolean;

This item has no description.

Public function Clone(const AOwner: TComponent): TCastleScene;

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 attributes, like ProcessEvents or Spatial or rendering attributes in RenderOptions.

Public function WasVisible: Boolean;

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 and occlusion culling (see https://castle-engine.io/occlusion_query ) tests.

For this method it doesn't matter if the scene contains some lights that only make some other scenes brighter. Or if the scene contains some background that affects TCastleViewport skybox. Only the visibility of shapes 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.

Properties

Public property FrustumCulling: TFrustumCulling read FFrustumCulling write SetFrustumCulling default fcBox; deprecated 'use simpler ShapeFrustumCulling';

Warning: this symbol is deprecated: use simpler ShapeFrustumCulling

What kind of per-shape frustum culling do when ShapeFrustumCulling is True, and we don't have octree (ssRendering is not included in TCastleSceneCore.Spatial).

Public property OctreeFrustumCulling: TFrustumCulling read FOctreeFrustumCulling write SetOctreeFrustumCulling default fcBox; deprecated 'use simpler ShapeFrustumCulling';

Warning: this symbol is deprecated: use simpler ShapeFrustumCulling

What kind of per-shape frustum culling do when ShapeFrustumCulling is True, and we have octree (ssRendering is included in TCastleSceneCore.Spatial).

Published property ShapeFrustumCulling: Boolean read FShapeFrustumCulling write SetShapeFrustumCulling default true;

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.

Published property SceneFrustumCulling: Boolean read FSceneFrustumCulling write FSceneFrustumCulling default true;

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.

Published property ReceiveShadowVolumes: boolean read FReceiveShadowVolumes write FReceiveShadowVolumes default true;

Does this scene receive shadows by shadow volumes.

Published property DistanceCulling: Single read FDistanceCulling write SetDistanceCulling default 0;

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

Published property RenderOptions: TCastleRenderOptions read GetRenderOptions;

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

Published property CastGlobalLights: Boolean read FCastGlobalLights write SetCastGlobalLights default false;

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


Generated by PasDoc 0.16.0.