Class TCastleAbstractViewport

Unit

Declaration

type TCastleAbstractViewport = class(TCastleScreenEffects)

Description

Common abstract class for things that may act as a viewport: TCastleSceneManager and TCastleViewport.

Hierarchy

Overview

Fields

Public nested const DefaultScreenSpaceAmbientOcclusion = false;
Public nested const DefaultUseGlobalLights = true;
Public nested const DefaultUseGlobalFog = true;
Public nested const DefaultShadowVolumes = true;
Public var CustomRenderingPass: TUserRenderingPass;

Methods

Protected function CalculateProjection: TProjection; virtual;
Protected procedure Render3D(const Params: TRenderParams); virtual;
Protected procedure RenderShadowVolume; virtual;
Protected procedure RenderFromViewEverything(const RenderingCamera: TRenderingCamera); virtual;
Protected procedure InitializeLights(const Lights: TLightInstancesList); virtual;
Protected function Headlight: TAbstractLightNode; virtual; abstract;
Protected procedure RenderFromView3D(const Params: TRenderParams); virtual;
Protected function Background: TBackground; virtual;
Protected function MainLightForShadows( out AMainLightPosition: TVector4): boolean; virtual;
Protected procedure SetCamera(const Value: TCamera); virtual;
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
Protected procedure SetContainer(const Value: TUIContainer); override;
Protected function GetItems: TSceneManagerWorld; virtual; abstract;
Protected function GetMainScene: TCastleScene; virtual; abstract;
Protected function GetShadowVolumeRenderer: TGLShadowVolumeRenderer; virtual; abstract;
Protected function GetMouseRayHit: TRayCollision; virtual; abstract;
Protected function GetHeadlightCamera: TCamera; virtual; abstract;
Protected function GetPlayer: TPlayer; virtual; abstract;
Protected function GetTimeScale: Single; virtual; abstract;
Protected function PointingDeviceMove(const RayOrigin, RayDirection: TVector3): boolean; virtual; abstract;
Protected function PointingDeviceActivate(const Active: boolean): boolean; virtual; abstract;
Protected function CameraMoveAllowed(ACamera: TWalkCamera; const ProposedNewPos: TVector3; out NewPos: TVector3; const BecauseOfGravity: boolean): boolean; virtual; abstract;
Protected function CameraHeight(ACamera: TWalkCamera; const Position: TVector3; out AboveHeight: Single; out AboveGround: PTriangle): boolean; virtual; abstract;
Protected function CameraRayCollision(const RayOrigin, RayDirection: TVector3): TRayCollision; virtual; abstract;
Protected procedure CameraVisibleChange(const Sender: TInputListener; const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean); virtual; abstract;
Protected function GetScreenEffects(const Index: Integer): TGLSLProgram; virtual;
Protected procedure AssignDefaultCamera; virtual;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Resize; override;
Public function AllowSuspendForInput: boolean; override;
Public function Press(const Event: TInputPressRelease): boolean; override;
Public function Release(const Event: TInputPressRelease): boolean; override;
Public function Motion(const Event: TInputMotion): boolean; override;
Public function SensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; override;
Public function SensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; override;
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public procedure UpdateMouseRayHit;
Public function RequiredCamera: TCamera;
Public function WalkCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TWalkCamera;
Public function ExamineCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TExamineCamera;
Public procedure ClearCameras;
Public function InternalExamineCamera: TExamineCamera;
Public function InternalWalkCamera: TWalkCamera;
Public function ScreenEffectsCount: Integer; virtual;
Public function ScreenEffectsNeedDepth: boolean; virtual;
Public function ScreenSpaceAmbientOcclusionAvailable: boolean;
Public procedure GLContextClose; override;
Public function PrepareParams: TPrepareParams;
Public function BaseLights: TLightInstancesList; deprecated 'this is internal info, you should not need this; use PrepareParams to get opaque information to pass to TCastleTransform.PrepareResources';
Public function Statistics: TRenderStatistics;
Public function TriangleHit: PTriangle;
Public function HeadlightInstance(out Instance: TLightInstance): boolean; deprecated 'internal information, do not use this';

Properties

Public property Projection: TProjection read FProjection;
Public property NavigationType: TNavigationType read GetNavigationType write SetNavigationType;
Public property ScreenEffects [Index:Integer]: TGLSLProgram read GetScreenEffects;
Public property BackgroundColor: TCastleColor read FBackgroundColor write FBackgroundColor;
Public property Camera: TCamera read FCamera write SetCamera;
Published property Paused: boolean read FPaused write SetPaused default false;
Published property OnRender3D: TRender3DEvent read FOnRender3D write FOnRender3D;
Published property ShadowVolumes: boolean read FShadowVolumes write FShadowVolumes default DefaultShadowVolumes;
Published property ShadowVolumesRender: boolean read FShadowVolumesRender write FShadowVolumesRender default false;
Published property BackgroundWireframe: boolean read FBackgroundWireframe write FBackgroundWireframe default false;
Published property Transparent: boolean read FTransparent write FTransparent default false;
Published property ClearDepth: boolean read FClearDepth write FClearDepth default true;
Published property HeadlightFromViewport: boolean read FHeadlightFromViewport write FHeadlightFromViewport default false; deprecated;
Published property UseGlobalLights: boolean read FUseGlobalLights write FUseGlobalLights default DefaultUseGlobalLights;
Published property UseGlobalFog: boolean read FUseGlobalFog write FUseGlobalFog default DefaultUseGlobalFog;
Published property ApproximateActivation: boolean read FApproximateActivation write FApproximateActivation default false;
Published property DefaultVisibilityLimit: Single read FDefaultVisibilityLimit write FDefaultVisibilityLimit default 0.0;
Published property ScreenSpaceAmbientOcclusion: boolean read FScreenSpaceAmbientOcclusion write SetScreenSpaceAmbientOcclusion default DefaultScreenSpaceAmbientOcclusion;
Published property FullSize default true;
Published property OnProjection: TProjectionEvent read FOnProjection write FOnProjection;

Description

Fields

Public nested const DefaultScreenSpaceAmbientOcclusion = false;
 
Public nested const DefaultUseGlobalLights = true;
 
Public nested const DefaultUseGlobalFog = true;
 
Public nested const DefaultShadowVolumes = true;
 
Public var CustomRenderingPass: TUserRenderingPass;

Rendering pass, for user purposes. Useful to keep shaders cached when you render the same scene multiple times in the same frame (under different lighting conditions or other things that change shaders). By default this is always 0, the engine doesn't modify this. You can set this field manually.

Methods

Protected function CalculateProjection: TProjection; virtual;

The projection parameters. Determines if the view is perspective or orthogonal and exact field of view parameters. Used by our Render method.

The default implementation of this method in TCastleAbstractViewport calculates projection based on the Camera parameters, and based on the currently bound Viewpoint/OrthoViewpoint, NavigationInfo nodes in TCastleSceneManager.MainScene. If the scene manager's MainScene is not assigned, or it doesn't have a Viewpoint/OrthoViewpoint node, we use a default perspective projection.

Note that the TCastle2DSceneManager overrides this method to calculate always orthographic projection, using it's own properties like TCastle2DSceneManager.ProjectionAutoSize, TCastle2DSceneManager.ProjectionWidth, TCastle2DSceneManager.ProjectionHeight. It doesn't look at MainScene settings or Viewpoint/OrthoViewpoint nodes.

You can override this method, or assign the OnProjection event to adjust the projection settings.

Protected procedure Render3D(const Params: TRenderParams); virtual;

Render one pass, with current camera and parameters. All current camera settings are saved in RenderParams.RenderingCamera. If you want to write custom OpenGL rendering code, this is the simplest method to override. (Or you can use OnRender3D event, which is called at the end of this method.)

Parameters
Params
Rendering parameters, see TRenderParams.
Protected procedure RenderShadowVolume; virtual;

Render shadow quads for all the things rendered by Render3D. You can use here ShadowVolumeRenderer instance, which is guaranteed to be initialized with TGLShadowVolumeRenderer.InitFrustumAndLight, so you can do shadow volumes culling.

Protected procedure RenderFromViewEverything(const RenderingCamera: TRenderingCamera); virtual;

Render everything from given camera view (as TRenderingCamera). Given RenderingCamera.Target says to where we generate the image. Takes method must take care of making many rendering passes for shadow volumes, but doesn't take care of updating generated textures.

Protected procedure InitializeLights(const Lights: TLightInstancesList); virtual;

Prepare lights shining on everything. BaseLights contents should be initialized here.

The implementation in this class adds headlight determined by the Headlight method. By default, this looks at the MainScene, and follows NavigationInfo.headlight and KambiNavigationInfo.headlightNode properties.

Protected function Headlight: TAbstractLightNode; virtual; abstract;

Headlight used to light the scene.

Default implementation of this method in TCastleSceneManager returns non-nil headlight node if the algorithm described at UseHeadlight and TUseHeadlight indicates we should use a headlight. Otherwise returns Nil, to indicate we do not show a headlight now.

Default implementation of this method in TCastleViewport just refers to SceneManager.Headlight.

You can override this method to determine the headlight in any other way. Instead of overriding this method, you can often also change the UseHeadlight value, or MainScene.HeadlightOn value.

Protected procedure RenderFromView3D(const Params: TRenderParams); virtual;

Render the 3D part of scene. Called by RenderFromViewEverything at the end, when everything (clearing, background, headlight, loading camera matrix) is done and all that remains is to pass to OpenGL actual 3D world.

This will change Params.Transparent, Params.InShadow and Params.ShadowVolumesReceivers as needed. Their previous values do not matter.

Protected function Background: TBackground; virtual;

The background used during rendering. Nil if no background should be rendered.

The default implementation in this class does what is usually most natural: return MainScene.Background, if MainScene assigned.

Protected function MainLightForShadows( out AMainLightPosition: TVector4): boolean; virtual;

Detect position/direction of the main light that produces shadows. The default implementation in this class looks at MainScene.MainLightForShadows.

See also
TCastleSceneCore.MainLightForShadows
Detect position/direction of the main light that produces shadows.
Protected procedure SetCamera(const Value: TCamera); virtual;
 
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
 
Protected procedure SetContainer(const Value: TUIContainer); override;
 
Protected function GetItems: TSceneManagerWorld; virtual; abstract;

Information about the 3D world. For scene maager, these methods simply return it's own properties. For TCastleViewport, these methods refer to scene manager.

Protected function GetMainScene: TCastleScene; virtual; abstract;
 
Protected function GetShadowVolumeRenderer: TGLShadowVolumeRenderer; virtual; abstract;
 
Protected function GetMouseRayHit: TRayCollision; virtual; abstract;
 
Protected function GetHeadlightCamera: TCamera; virtual; abstract;
 
Protected function GetPlayer: TPlayer; virtual; abstract;
 
Protected function GetTimeScale: Single; virtual; abstract;
 
Protected function PointingDeviceMove(const RayOrigin, RayDirection: TVector3): boolean; virtual; abstract;

Pass pointing device (mouse) move event to 3D world.

Protected function PointingDeviceActivate(const Active: boolean): boolean; virtual; abstract;

Pass pointing device (mouse) activation/deactivation event to 3D world.

Protected function CameraMoveAllowed(ACamera: TWalkCamera; const ProposedNewPos: TVector3; out NewPos: TVector3; const BecauseOfGravity: boolean): boolean; virtual; abstract;

Handle camera events.

Scene manager implements collisions by looking at 3D scene, custom viewports implements collisions by calling their scene manager.

Protected function CameraHeight(ACamera: TWalkCamera; const Position: TVector3; out AboveHeight: Single; out AboveGround: PTriangle): boolean; virtual; abstract;
 
Protected function CameraRayCollision(const RayOrigin, RayDirection: TVector3): TRayCollision; virtual; abstract;
 
Protected procedure CameraVisibleChange(const Sender: TInputListener; const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean); virtual; abstract;
 
Protected function GetScreenEffects(const Index: Integer): TGLSLProgram; virtual;
 
Protected procedure AssignDefaultCamera; virtual;

Assign Camera to a default TCamera suitable for navigating in this scene. The newly created camera owned should be Self. This is automatically used when Camera is Nil at various places, and implementation may assume that Camera is Nil at entry.

The implementation in base TCastleAbstractViewport uses MainScene.NavigationTypeFromNavigationInfo (so it will follow your VRML/X3D scene Viewpoint, NavigationInfo and such). If MainScene is not assigned, we create a simple camera in Examine mode.

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Resize; override;
 
Public function AllowSuspendForInput: boolean; override;
 
Public function Press(const Event: TInputPressRelease): boolean; override;
 
Public function Release(const Event: TInputPressRelease): boolean; override;
 
Public function Motion(const Event: TInputMotion): boolean; override;
 
Public function SensorRotation(const X, Y, Z, Angle: Double; const SecondsPassed: Single): boolean; override;
 
Public function SensorTranslation(const X, Y, Z, Length: Double; const SecondsPassed: Single): boolean; override;
 
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
 
Public procedure UpdateMouseRayHit;

Update MouseHitRay and update Items (TCastleTransform hierarchy) knowledge about the current pointing device. You usually don't need to call this, as it is done at every mouse move.

Public function RequiredCamera: TCamera;

Return current camera. Automatically creates it if missing.

Public function WalkCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TWalkCamera;

Return the currently used camera as TWalkCamera, making sure that current NavigationType is something using TWalkCamera.

  • When SwitchNavigationTypeIfNeeded is True (the default), this method makes sure that the NavigationType corresponds to a type handled by TWalkCamera, creating and adjusting the camera if necessary.

    If the current NavigationType does not use TWalkCamera (see TNavigationType documentation for information which navigation types use which TCamera descendants), then it's switched to ntWalk.

  • When SwitchNavigationTypeIfNeeded is False, then we return Nil if the current camera is not already a TWalkCamera instance.

    We never create a new camera in this case (even if the NavigatinInfo node in MainScene would indicate that the new camera would be a TWalkCamera).

Public function ExamineCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TExamineCamera;

Return the currently used camera as TExamineCamera, making sure that current NavigationType is something using TExamineCamera.

  • When SwitchNavigationTypeIfNeeded is True (the default), this method makes sure that the NavigationType corresponds to a type handled by TExamineCamera, creating and adjusting the camera if necessary.

    If the current NavigationType does not use TExamineCamera (see TNavigationType documentation for information which navigation types use which TCamera descendants), then it's switched to ntExamine.

  • When SwitchNavigationTypeIfNeeded is False, then we return Nil if the current camera is not already a TExamineCamera instance.

    We never create a new camera in this case (even if the NavigatinInfo node in MainScene would indicate that the new camera would be a TExamineCamera).

Public procedure ClearCameras;

Make Camera Nil, and force creating a completely new camera instance when needed. The actual creation may be caused by calling ExamineCamera, WalkCamera, InternalExamineCamera, InternalWalkCamera, or by setting NavigationType.

In all cases, these methods will create a new camera instance after a ClearCameras call. No previous cached camera instance will be used.

Public function InternalExamineCamera: TExamineCamera;

Camera instances used by this scene manager. Using these methods automatically creates these instances (so they are never Nil).

Using these methods does not make these camera instances current (in contast to calling ExamineCamera, WalkCamera or setting NavigationType).

When you switch navigation types by calling ExamineCamera, WalkCamera or setting NavigationType the scene manager keeps using these instances of cameras, instead of creating new camera instances. This way all the camera properties (not only those copied by TCamera.Assign) are preserved when you switch e.g. NavigationType from ntWalk to ntExamine to ntWalk again.

Public function InternalWalkCamera: TWalkCamera;
 
Public function ScreenEffectsCount: Integer; virtual;
 
Public function ScreenEffectsNeedDepth: boolean; virtual;
 
Public function ScreenSpaceAmbientOcclusionAvailable: boolean;

Does the graphic card support our ScreenSpaceAmbientOcclusion shader. This does not depend on the current state of ScreenSpaceAmbientOcclusion property. You can use it e.g. to disable the menu item to switch SSAO in 3D viewer.

Public procedure GLContextClose; override;
 
Public function PrepareParams: TPrepareParams;

Parameters to prepare items that are to be rendered within this world. This should be passed to TCastleTransform.PrepareResources.

Note: Instead of using TCastleTransform.PrepareResources, and this method, it's usually easier to call TCastleSceneManager.PrepareResources. Then the appropriate TPrepareParams will be passed automatically.

Public function BaseLights: TLightInstancesList; deprecated 'this is internal info, you should not need this; use PrepareParams to get opaque information to pass to TCastleTransform.PrepareResources';

Warning: this symbol is deprecated: this is internal info, you should not need this; use PrepareParams to get opaque information to pass to TCastleTransform.PrepareResources

 
Public function Statistics: TRenderStatistics;

Statistics about last rendering frame. See TRenderStatistics docs.

Public function TriangleHit: PTriangle;

Current 3D triangle under the mouse cursor. Updated in every mouse move. May be Nil.

Public function HeadlightInstance(out Instance: TLightInstance): boolean; deprecated 'internal information, do not use this';

Warning: this symbol is deprecated: internal information, do not use this

Instance for headlight that should be used for this scene. Uses Headlight method, applies appropriate camera position/direction. Returns True only if Headlight method returned True and a suitable camera was present.

Instance should be considered undefined ("out" parameter) when we return False.

Properties

Public property Projection: TProjection read FProjection;

Current projection parameters, calculated by last CalculateProjection call, adjusted by OnProjection. This is read only. To change the projection parameters, override CalculateProjection or handle event OnProjection.

Public property NavigationType: TNavigationType read GetNavigationType write SetNavigationType;

Choose navigation method by creating and adjusting the camera, and various camera properies (like TWalkCamera.Gravity and so on). This is automatically determined from the currently bound NavigatinInfo X3D node in the GetMainScene. You can also set this manually, thus overriding the NavigatinInfo node.

This is a shortcut property for adjusting the camera class (by calling WalkCamera, ExamineCamera) and adjusting a couple of camera properties. Note that you can also affect the current NavigationType by directly changing the camera properties, e.g. you can directly change TWalkCamera.Gravity from False to True, and thus you effectively switch from ntFly to ntWalk navigation types. When you read the NavigationType property, we determine the current navigation type from current camera properties.

When the camera is created for the first time, it's parameters are determined from the current NavigationInfo and Viewpoint nodes in GetMainScene, and from bounding box of the world. When the camera class is switched later, the common camera properties (defined at TCamera, like TCamera.Radius and view vectors – position, direction, up) are copied, so they are preserved. The other camera properties (those defined only at TWalkCamera or TExamineCamera descendants, e.g. TWalkCamera.MouseLook and various inputs of cameras) are also preserved within InternalExamineCamera and InternalWalkCamera.

To reliably force recreating the camera from scratch, call ClearCameras. Simply freeing the current camera by SceneManager.Camera.Free is also valid operation, but it does not free both cameras (InternalExamineCamera and InternalWalkCamera) so it doesn't guarantee that all cameras will be recreated from a "clean" state. You can also explicitly assign your own camera descendant to SceneManager.Camera.

Setting this sets:

If you write to NavigationType, then you should not touch the above properties directly. That's because not every combination of above properties correspond to some sensible value of NavigationType. If you directly set some weird configuration, reading NavigationType will try it's best to determine the closest TNavigationType value that is similar to your configuration.

Public property ScreenEffects [Index:Integer]: TGLSLProgram read GetScreenEffects;

Screen effects are shaders that post-process the rendered screen. If any screen effects are active, we will automatically render screen to a temporary texture, processing it with each shader.

By default, screen effects come from GetMainScene.ScreenEffects, so the effects may be defined by VRML/X3D author using ScreenEffect nodes (see docs: [https://castle-engine.io/x3d_extensions_screen_effects.php]). Descendants may override GetScreenEffects, ScreenEffectsCount, and ScreenEffectsNeedDepth to add screen effects by code. Each viewport may have it's own, different screen effects.

Public property BackgroundColor: TCastleColor read FBackgroundColor write FBackgroundColor;

Background color, displayed behind the 3D world. Unless the MainScene has a Background node defined, in which case the Background (colored and/or textured) of the 3D scene is used.

Black by default.

Public property Camera: TCamera read FCamera write SetCamera;

Camera used to render this viewport.

Note this property may be Nil before rendering. If you don't assign anything here, we'll create a default camera when necessary (usually at the ApplyProjection which happens before the rendering). Use RequiredCamera instead of this property to get a camera that is never Nil. Or use ExamineCamera or WalkCamera to get a camera that is never Nil, and has particular type. Or set NavigationType first, this also sets the camera always.

For many purposes, you can directly operate on this camera, for example you can change it's Position. An exception to this is assigning events to the camera instance. The scene manager or viewport will "hijack" some Camera events: TCamera.OnVisibleChange, TWalkCamera.OnMoveAllowed, TWalkCamera.OnHeight. We will handle them in a proper way. Do not assign them yourself.

Comments for TCastleViewport only: The TCastleViewport's camera is slightly less important than TCastleSceneManager.Camera, because TCastleSceneManager.Camera may be treated as a "central" camera. Viewport's camera may not (because you may have many viewports and they all deserve fair treatment). So e.g. headlight is done only from TCastleSceneManager.Camera (for mirror textures, there must be one headlight for your 3D world). Also VRML/X3D ProximitySensors receive events only from TCastleSceneManager.Camera.

See also
TCastleSceneManager.OnCameraChanged
Called on any camera change.
Published property Paused: boolean read FPaused write SetPaused default false;

For scene manager: you can pause everything inside your 3D world, for viewport: you can make the camera of this viewpoint paused (not responsive).

For scene manager:

"Paused" means that no events (key, mouse, Update) are passed to any TCastleSceneManager.Items or the Camera. This is suitable if you really want to totally, unconditionally, make your 3D world view temporary still (for example, useful when entering some modal dialog box and you want 3D scene to behave as a still background).

You can of course still directly change some scene property, and then 3D world will change. But no change will be initialized automatically by scene manager events.

See also: For less drastic pausing methods, there are other methods of pausing / disabling some events processing for the 3D world:

  • You can set TCastleScene.TimePlaying to False. This is roughly equivalent to not running their Update methods. This means that time will "stand still" for them, so their animations will not play. Although they may still react and change in response to mouse clicks / key presses, if TCastleScene.ProcessEvents.

  • You can set TCastleScene.ProcessEvents to False. This means that scene will not receive and process any key / mouse and other events (through VRML/X3D sensors). Some animations (not depending on VRML/X3D events processing) may still run, for example MovieTexture will still animate, if only TCastleScene.TimePlaying.

  • For cameras, you can set TCamera.Input := [] to ignore key / mouse clicks.

Published property OnRender3D: TRender3DEvent read FOnRender3D write FOnRender3D;

See Render3D method.

Published property ShadowVolumes: boolean read FShadowVolumes write FShadowVolumes default DefaultShadowVolumes;

Should we render with shadow volumes. You can change this at any time, to switch rendering shadows on/off.

This works only if OpenGL context actually can render shadow volumes, checked by GLFeatures.ShadowVolumesPossible, which means that you have to initialize OpenGL context with stencil buffer.

The shadow volumes algorithm is used only if shadow caster is 2-manifold, that is has a correctly closed volume. Also you need a light source marked as the main shadow volumes light (shadowVolumes = shadowVolumesMain = TRUE). See [https://castle-engine.io/x3d_extensions.php#section_ext_shadows] for details.

Published property ShadowVolumesRender: boolean read FShadowVolumesRender write FShadowVolumesRender default false;

Actually draw the shadow volumes to the color buffer, for debugging. If shadows are rendered (see GLFeatures.ShadowVolumesPossible and ShadowVolumes), you can use this to actually see shadow volumes, for debug / demo purposes. Shadow volumes will be rendered on top of the scene, as yellow blended polygons.

Published property BackgroundWireframe: boolean read FBackgroundWireframe write FBackgroundWireframe default false;

If yes then the scene background will be rendered wireframe, over the background filled with BackgroundColor.

There's a catch here: this works only if the background is actually internally rendered as a geometry. If the background is rendered by clearing the screen (this is an optimized case of sky color being just one simple color, and no textures), then it will just cover the screen as normal, like without wireframe. This is uncertain situation anyway (what should the wireframe look like in this case anyway?), so I don't consider it a bug.

Useful especially for debugging when you want to see how your background geometry looks like.

Published property Transparent: boolean read FTransparent write FTransparent default false;

If yes then we will not draw any background, letting the window contents underneath be visible (in places where we do not draw our own 3D geometry, or where our own geometry is transparent, e.g. by Material.transparency). For this to make sense, make sure that you always place some other 2D control under this viewport, that actually draws something predictable underneath.

The normal background, derived from Background will be ignored. We will also not do any RenderContext.Clear on color buffer. Also BackgroundWireframe and BackgroundColor doesn't matter in this case.

Published property ClearDepth: boolean read FClearDepth write FClearDepth default true;

At the beginning of rendering, scene manager by default clears the depth buffer. This makes every scene manager draw everything on top of the previous 2D and 3D stuff (including on top of previous scene managers), like a layer.

You can disable this, which allows to combine together the 3D objects rendered by various scene managers (and by custom OpenGL rendering), such that the 3D positions determime what overlaps what. This only makes sense if all these scene managers (or custom renderers) use the same viewport, the same projection and the same camera.

It's your responsibility in such case to clear the depth buffer. E.g. place one scene manager in the back that has ClearDepth = True. Or place a TCastleUserInterface descendant in the back, that calls TRenderContent.Clear RenderContent.Clear in overridden TCastleUserInterface.Render.

Note: to disable clearning the color buffer, set Transparent to False.

Note: if you use shadow volumes, we will still clear the stencil buffer at the beginning of rendering.

Published property HeadlightFromViewport: boolean read FHeadlightFromViewport write FHeadlightFromViewport default false; deprecated;

Warning: this symbol is deprecated.

When True then headlight is always rendered from custom viewport's (TCastleViewport) camera, not from central camera (the one in scene manager). This is meaningless in TCastleSceneManager.

By default this is False, which means that when rendering custom viewport (TCastleViewport) we render headlight from TCastleViewport.SceneManager.Camera (not from current viewport's TCastleViewport.Camera). On one hand, this is sensible: there is exactly one headlight in your 3D world, and it shines from a central camera in SceneManager.Camera. When SceneManager.Camera is Nil (which may happen if you set SceneManager.DefaultViewport := false and you didn't assign SceneManager.Camera explicitly) headlight is never done. This means that when observing 3D world from other cameras, you will see a light shining from SceneManager.Camera. This is also the only way to make headlight lighting correctly reflected in mirror textures (like GeneratedCubeMapTexture) — since we render to one mirror texture, we need a knowledge of "cental" camera for this.

When this is True, then each viewport actually renders headlight from it's current camera. This means that actually each viewport has it's own, independent headlight (althoug they all follow VRML/X3D NavigationInfo.headlight and KambiNavigationInfo settings). This may allow you to light your view better (if you only use headlight to "just make the view brighter"), but it's not entirely correct (in particular, mirror reflections of the headlight are undefined then).

This is deprecated, since HeadlightFromViewport = True is not really nicely defined, and it's not practically that useful either.

Published property UseGlobalLights: boolean read FUseGlobalLights write FUseGlobalLights default DefaultUseGlobalLights;

Let MainScene.GlobalLights shine on every 3D object, not only MainScene. This is an easy way to lit your whole world with lights defined inside MainScene file. Be sure to set lights global=TRUE.

Note that for now this assumes that MainScene coordinates equal world coordinates. This means that you should not transform the MainScene, it should be placed inside TCastleSceneManager.Items and not transformed by TCastleTransform.

Published property UseGlobalFog: boolean read FUseGlobalFog write FUseGlobalFog default DefaultUseGlobalFog;

Let the fog defined in MainScene affect all objects, not only MainScene. This is consistent with UseGlobalLights, that allows lights from MainScene to shine on all objects.

Published property ApproximateActivation: boolean read FApproximateActivation write FApproximateActivation default false;

Help user to activate pointing device sensors and pick items. Every time you press or release Input_Interact (by default just left mouse button), we look if current mouse position hits 3D object that actually does something on activation. The objects may do various stuff inside TCastleTransform.PointingDeviceActivate, generally this causes various picking/interaction with the object (like pulling a level, opening a door), possibly dragging, possibly with the help of VRML/X3D pointing device and drag sensors.

When this is True, we try harder to hit some 3D object that handles PointingDeviceActivate. If there's nothing interesting under mouse, we will retry a couple of other positions arount the current mouse.

This should be usually used when you use TWalkCamera.MouseLook, or other navigation when mouse cursor is hidden. It allows user to only approximately look at interesting item and hit interaction button or key. Otherwise, activating a small 3D object is difficult, as you don't see the mouse cursor.

Published property DefaultVisibilityLimit: Single read FDefaultVisibilityLimit write FDefaultVisibilityLimit default 0.0;

Visibility limit of your 3D world. This is the distance the far projection clipping plane.

The default CalculateProjection implementation calculates the final visibility limit as follows:

  • First of all, if (GLFeatures.ShadowVolumesPossible and ShadowVolumes), then it's infinity.

  • Then we look NavigationInfo.visibilityLimit value inside MainScene. This allows your 3D data creators to set this inside VRML/X3D data.

    Only if MainScene is not set, or doesn't contain NavigationInfo node, or NavigationInfo.visibilityLimit is left at (default) zero, we look further.

  • We use this property, DefaultVisibilityLimit, if it's not zero.

  • Finally, as a last resort we calculate something suitable looking at the 3D bounding box of items inside our 3D world.

Published property ScreenSpaceAmbientOcclusion: boolean read FScreenSpaceAmbientOcclusion write SetScreenSpaceAmbientOcclusion default DefaultScreenSpaceAmbientOcclusion;

Enable built-in SSAO screen effect in the world.

Published property FullSize default true;

Viewports are by default full size (fill the parent control completely).

Published property OnProjection: TProjectionEvent read FOnProjection write FOnProjection;

Adjust the projection parameters. This event is called before every render. See the CalculateProjection for a description how to default projection parameters are calculated.


Generated by PasDoc 0.15.0.