Class TCastleViewport

Unit

Declaration

type TCastleViewport = class(TCastleScreenEffects)

Description

Viewport displays a tree of scenes and transformations (TCastleTransform and TCastleScene). Add the scenes and transformations to Items.

For some features, that require a notion of "main" scene, it is useful to set Items.MainScene. See the TCastleRootTransform.MainScene docs.

Each viewport has a Camera with a position and orientation. The initial camera may be auto-detected if AutoCamera.

Viewport may also have a Navigation that allows to move camera by keyboard, mouse and other inputs. You can use TCastleExamineNavigation or TCastleWalkNavigation instances. You can also implement your own navigation method (as a TCastleNavigation descendant, or just move/rotate the camera by calling TCastleCamera.SetView from anywhere). The inital navigation method may be auto-detected if AutoNavigation.

Viewport may clear the screen at the beginning, with a solid color or using a TAbstractBackgroundNode defined in Items.MainScene. This way you can use e.g. a skybox. You can control this using Transparent, BackgroundColor properties.

Viewport may also add headlight to the scene, see Items.UseHeadlight.

Multiple viewports can display the same world. To do this, simply copy Items reference from one TCastleViewport to another. You can also just create your own TCastleRootTransform instance and then assign it to multiple viewports. This allows e.g. to make a split-screen game (played by 2 people, with 2 viewports, on a single monitor). Or you can show in a 3D FPS game an additional view from some security camera, or from a flying rocket. For examples of using multiple viewports see:

Hierarchy

Overview

Fields

Public nested const DefaultScreenSpaceAmbientOcclusion = false;
Public nested const DefaultUseGlobalLights = true;
Public nested const DefaultUseGlobalFog = true;
Public nested const DefaultShadowVolumes = true;
Public nested const DefaultBackgroundColor: TVector4 = (Data: (0.1, 0.1, 0.1, 1));
Public nested const Default2DProjectionFar = 1000.0;
Public nested const Default2DCameraZ = Default2DProjectionFar / 2;
Public nested const DefaultPrepareOptions = [prRenderSelf, prRenderClones, prBackground, prBoundingBox, prScreenEffects];
Public var CustomRenderingPass: TUserRenderingPass;

Methods

Protected function CalculateProjection: TProjection; virtual;
Protected procedure InitializeLights(const Lights: TLightInstancesList); virtual;
Protected procedure RenderFromViewEverything(const RenderingCamera: TRenderingCamera); virtual;
Protected procedure RenderFromView3D(const Params: TRenderParams); virtual;
Protected function Background: TBackground; virtual;
Protected procedure Render3D(const Params: TRenderParams); virtual;
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
Protected function GetScreenEffects(const Index: Integer): TGLSLProgram; virtual;
Protected function InternalExtraGetScreenEffects(const Index: Integer): TGLSLProgram; override;
Protected function InternalExtraScreenEffectsCount: Integer; override;
Protected function InternalExtraScreenEffectsNeedDepth: Boolean; override;
Protected procedure PointingDeviceActivateFailed(const Active: boolean); virtual;
Protected function PointingDeviceActivate3D(const Item: TCastleTransform; const Active: boolean; const Distance: Single): boolean; virtual;
Protected procedure BoundNavigationInfoChanged; virtual;
Protected procedure BoundViewpointChanged; virtual;
Protected procedure RenderWithoutScreenEffects; override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; 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 procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public procedure VisibleChange(const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean = false); override;
Public procedure BeforeRender; override;
Public function GetMainScene: TCastleScene; deprecated 'use Items.MainScene';
Public procedure UpdateMouseRayHit;
Public function RequiredNavigation: TCastleNavigation; deprecated 'use Camera to set camera properties; if you require Navigation to be <> nil, just create own instance of TCastleWalkNavigation/TCastleExamineNavigation and assign it, or call AssignDefaultNavigation';
Public function RequiredCamera: TCastleNavigation; deprecated 'use Camera to set camera properties; if you require Navigation to be <> nil, just create own instance of TCastleWalkNavigation/TCastleExamineNavigation and assign it, or call AssignDefaultNavigation';
Public function WalkNavigation(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleWalkNavigation; deprecated 'create own instance of TCastleWalkNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';
Public function WalkCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleWalkNavigation; deprecated 'create own instance of TCastleWalkNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';
Public function ExamineNavigation(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleExamineNavigation; deprecated 'create own instance of TCastleExamineNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';
Public function ExamineCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleExamineNavigation; deprecated 'create own instance of TCastleExamineNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';
Public procedure ClearCameras; deprecated 'just set Navigation to nil instead of using this method; to avoid reusing previous instance, do not use WalkNavigation/ExamineNavigation methods, instead create and destroy your own TCastleWalkNavigation/TCastleExamineNavigation whenever you want';
Public function InternalExamineNavigation: TCastleExamineNavigation; deprecated 'create own instance of TCastleExamineNavigation instead of using this one, it results in more obvious code';
Public function InternalWalkNavigation: TCastleWalkNavigation; deprecated 'create own instance of TCastleWalkNavigation instead of using this one, it results in more obvious code';
Public function InternalExamineCamera: TCastleExamineNavigation; deprecated 'use InternalExamineNavigation';
Public function InternalWalkCamera: TCastleWalkNavigation; deprecated 'use InternalWalkNavigation';
Public procedure AssignDefaultNavigation; virtual;
Public procedure AssignDefaultCamera; virtual;
Public function ScreenEffectsCount: Integer; virtual;
Public function ScreenEffectsNeedDepth: boolean; virtual;
Public function ScreenSpaceAmbientOcclusionAvailable: boolean;
Public procedure GLContextOpen; override;
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';
Public procedure Setup2D;
Public function PositionToWorldPlane(const Position: TVector2; const ScreenCoordinates: Boolean; const PlaneZ: Single; out PlanePosition: TVector3): Boolean;
Public function PositionTo2DWorld(const Position: TVector2; const ScreenCoordinates: Boolean): TVector2;
Public procedure PrepareResources(const DisplayProgressTitle: string = ''; const Options: TPrepareResourcesOptions = DefaultPrepareOptions);
Public procedure PrepareResources(const Item: TCastleTransform; const DisplayProgressTitle: string = ''; Options: TPrepareResourcesOptions = DefaultPrepareOptions); virtual;

Properties

Public property Projection: TProjection read FProjection; deprecated 'in most cases, you can instead read Camera parameters, like Camera.Orthographic.EffectiveWidth, Camera.Orthographic.EffectiveHeight';
Public property ScreenEffects [Index:Integer]: TGLSLProgram read GetScreenEffects;
Public property BackgroundColor: TCastleColor read FBackgroundColor write FBackgroundColor;
Public property ScreenSpaceAmbientOcclusion: boolean read FScreenSpaceAmbientOcclusion write SetScreenSpaceAmbientOcclusion default DefaultScreenSpaceAmbientOcclusion;
Public property OnCameraChanged: TNotifyEvent read FOnCameraChanged write FOnCameraChanged;
Public property NavigationType: TNavigationType read GetNavigationType write SetNavigationType default ntNone;
Public property MouseRayHit: TRayCollision read FMouseRayHit;
Public property AvoidNavigationCollisions: TCastleTransform read FAvoidNavigationCollisions write SetAvoidNavigationCollisions;
Public property Paused: boolean read GetPaused write SetPaused default false; deprecated 'use Items.Paused';
Public property SceneManager: TCastleSceneManager read FSceneManager write SetSceneManager; deprecated 'assign Items from one TCastleViewport to another to view the same world from multiple viewports';
Published property Items: TCastleRootTransform read FItems write SetItems;
Published property Camera: TCastleCamera read FCamera;
Published property Navigation: TCastleNavigation read FNavigation write SetNavigation stored IsStoredNavigation;
Published property OnRender3D: TRender3DEvent read FOnRender3D write FOnRender3D; deprecated 'do not customize rendering with this; instead add TCastleUserInterface descendants where you can override TCastleUserInterface.Render to do custom rendering';
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 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; deprecated 'use Camera.ProjectionFar, and set AutoCamera to false';
Published property OnProjection: TProjectionEvent read FOnProjection write FOnProjection; deprecated 'adjust projection by changing Camera.ProjectionType and other projection parameters inside Camera';
Published property EnableParentDragging: boolean read FEnableParentDragging write FEnableParentDragging default false;
Published property AutoCamera: Boolean read FAutoCamera write SetAutoCamera default false;
Published property AutoNavigation: Boolean read FAutoNavigation write FAutoNavigation default false;
Published property OnBoundViewpointChanged: TNotifyEvent read FOnBoundViewpointChanged write FOnBoundViewpointChanged;
Published property OnBoundNavigationInfoChanged: TNotifyEvent read FOnBoundNavigationInfoChanged write FOnBoundNavigationInfoChanged;
Published property PreventInfiniteFallingDown: Boolean read FPreventInfiniteFallingDown write FPreventInfiniteFallingDown default false;
Published property BackgroundColorPersistent: TCastleColorPersistent read FBackgroundColorPersistent ;

Description

Fields

Public nested const DefaultScreenSpaceAmbientOcclusion = false;
 
Public nested const DefaultUseGlobalLights = true;
 
Public nested const DefaultUseGlobalFog = true;
 
Public nested const DefaultShadowVolumes = true;
 
Public nested const DefaultBackgroundColor: TVector4 = (Data: (0.1, 0.1, 0.1, 1));
 
Public nested const Default2DProjectionFar = 1000.0;
 
Public nested const Default2DCameraZ = Default2DProjectionFar / 2;
 
Public nested const DefaultPrepareOptions = [prRenderSelf, prRenderClones, prBackground, prBoundingBox, prScreenEffects];
 
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;

Calculate projection parameters. Determines if the view is perspective or orthogonal and exact field of view parameters. Called each time at the beginning of rendering.

The default implementation of this method in TCastleViewport calculates projection based on the Camera parameters.

In turn, the Camera parameters may be automatically calculated (if AutoCamera) based on the nodes in the TCastleRootTransform.MainScene. Nodes like TViewpointNode or TOrthoViewpointNode or TNavigationInfoNode determine the default camera and projection details.

You can override this method, or assign the OnProjection event to adjust the projection settings. But please note: instead of overriding this method, it's usually easier (and more advised) to simply change the Camera properties, like Camera.ProjectionType or Camera.Orthographic.Width or Camera.Perspective.FieldOfView.

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 procedure RenderFromViewEverything(const RenderingCamera: TRenderingCamera); virtual;

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

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

Render the scene, assuming that buffers were already cleared and background was rendered. Called by RenderFromViewEverything at the end. Lights are calculated in Params at this point.

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.InternalBackground, if MainScene assigned.

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

Render one pass, with current camera and parameters (e.g. only transparent or only opaque shapes). All current camera settings are saved in RenderParams.RenderingCamera.

Parameters
Params
Rendering parameters, see TRenderParams.
Protected procedure Notification(AComponent: TComponent; Operation: TOperation); override;
 
Protected function GetScreenEffects(const Index: Integer): TGLSLProgram; virtual;
 
Protected function InternalExtraGetScreenEffects(const Index: Integer): TGLSLProgram; override;
 
Protected function InternalExtraScreenEffectsCount: Integer; override;
 
Protected function InternalExtraScreenEffectsNeedDepth: Boolean; override;
 
Protected procedure PointingDeviceActivateFailed(const Active: boolean); virtual;

Called when PointingDeviceActivate was not handled by any 3D object. You can override this to make a message / sound signal to notify user that his Input_Interact click was not successful.

Protected function PointingDeviceActivate3D(const Item: TCastleTransform; const Active: boolean; const Distance: Single): boolean; virtual;

Handle pointing device (mouse) activation/deactivation event over a given 3D object. See TCastleTransform.PointingDeviceActivate method for description how it should be handled. Default implementation in TCastleViewport just calls TCastleTransform.PointingDeviceActivate.

Protected procedure BoundNavigationInfoChanged; virtual;
 
Protected procedure BoundViewpointChanged; virtual;
 
Protected procedure RenderWithoutScreenEffects; override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; 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 procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
 
Public procedure VisibleChange(const Changes: TCastleUserInterfaceChanges; const ChangeInitiatedByChildren: boolean = false); override;
 
Public procedure BeforeRender; override;
 
Public function GetMainScene: TCastleScene; deprecated 'use Items.MainScene';

Warning: this symbol is deprecated: use Items.MainScene

 
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 RequiredNavigation: TCastleNavigation; deprecated 'use Camera to set camera properties; if you require Navigation to be <> nil, just create own instance of TCastleWalkNavigation/TCastleExamineNavigation and assign it, or call AssignDefaultNavigation';

Warning: this symbol is deprecated: use Camera to set camera properties; if you require Navigation to be <> nil, just create own instance of TCastleWalkNavigation/TCastleExamineNavigation and assign it, or call AssignDefaultNavigation

Return current navigation. Automatically creates it if missing.

Public function RequiredCamera: TCastleNavigation; deprecated 'use Camera to set camera properties; if you require Navigation to be <> nil, just create own instance of TCastleWalkNavigation/TCastleExamineNavigation and assign it, or call AssignDefaultNavigation';

Warning: this symbol is deprecated: use Camera to set camera properties; if you require Navigation to be <> nil, just create own instance of TCastleWalkNavigation/TCastleExamineNavigation and assign it, or call AssignDefaultNavigation

 
Public function WalkNavigation(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleWalkNavigation; deprecated 'create own instance of TCastleWalkNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';

Warning: this symbol is deprecated: create own instance of TCastleWalkNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable

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

Public function WalkCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleWalkNavigation; deprecated 'create own instance of TCastleWalkNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';

Warning: this symbol is deprecated: create own instance of TCastleWalkNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable

 
Public function ExamineNavigation(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleExamineNavigation; deprecated 'create own instance of TCastleExamineNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';

Warning: this symbol is deprecated: create own instance of TCastleExamineNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable

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

Public function ExamineCamera(const SwitchNavigationTypeIfNeeded: boolean = true): TCastleExamineNavigation; deprecated 'create own instance of TCastleExamineNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable';

Warning: this symbol is deprecated: create own instance of TCastleExamineNavigation, and assign it to Viewport.Navigation, this is more flexible and predictable

 
Public procedure ClearCameras; deprecated 'just set Navigation to nil instead of using this method; to avoid reusing previous instance, do not use WalkNavigation/ExamineNavigation methods, instead create and destroy your own TCastleWalkNavigation/TCastleExamineNavigation whenever you want';

Warning: this symbol is deprecated: just set Navigation to nil instead of using this method; to avoid reusing previous instance, do not use WalkNavigation/ExamineNavigation methods, instead create and destroy your own TCastleWalkNavigation/TCastleExamineNavigation whenever you want

Make Navigation Nil. 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 InternalExamineNavigation: TCastleExamineNavigation; deprecated 'create own instance of TCastleExamineNavigation instead of using this one, it results in more obvious code';

Warning: this symbol is deprecated: create own instance of TCastleExamineNavigation instead of using this one, it results in more obvious code

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 TCastleNavigation.Assign) are preserved when you switch e.g. NavigationType from ntWalk to ntExamine to ntWalk again.

This is deprecated now, because it causes auto-detection of navigation parameters, which is (in general) more surprising than helpful. E.g. it adjusts camera radius, speed and more properties.

Public function InternalWalkNavigation: TCastleWalkNavigation; deprecated 'create own instance of TCastleWalkNavigation instead of using this one, it results in more obvious code';

Warning: this symbol is deprecated: create own instance of TCastleWalkNavigation instead of using this one, it results in more obvious code

 
Public function InternalExamineCamera: TCastleExamineNavigation; deprecated 'use InternalExamineNavigation';

Warning: this symbol is deprecated: use InternalExamineNavigation

 
Public function InternalWalkCamera: TCastleWalkNavigation; deprecated 'use InternalWalkNavigation';

Warning: this symbol is deprecated: use InternalWalkNavigation

 
Public procedure AssignDefaultNavigation; virtual;

Assign Navigation to a default TCastleNavigation suitable for navigating in this scene.

This is automatically used when Navigation is Nil and AutoNavigation. You can also use it explicitly.

The implementation in base TCastleViewport uses MainScene.NavigationTypeFromNavigationInfo and MainScene.InternalUpdateNavigation, thus it follows your X3D scene NavigationInfo. If MainScene is not assigned, we create a simple navigation in Examine mode.

Public procedure AssignDefaultCamera; virtual;

Assign initial and current camera vectors and projection.

This is automatically used at first rendering if AutoCamera. You can also use it explicitly.

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 GLContextOpen; override;
 
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 TCastleViewport.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.

Public procedure Setup2D;

Utility method to set camera to a suitable state for 2D games.

  • Sets both initial and current camera vectors like this:

    • Position camera at (0, 0, 500),

    • Looks along the -Z direction,

    • "Up" vector is in +Y.

    This way the 2D world spans horizontally in X and vertically in Y. The Z (depth) can be used to put things in front/behind each other.

    Since this initialized the camera sensibly, we also set AutoCamera to false.

  • Sets orthographic projection for the camera (TCastleCamera.ProjectionType set to ptOrthographic).

    By default our visible X range is [0..viewport width in pixels], visible Y range is [0..viewport height in pixels]. Use the properties of Camera.Orthographic to control the projection. For example set Camera.Orthographic.Width and/or Camera.Orthographic.Height to define visible projection size (horizontal or vertical) explicitly, regardless of the scene manager size.

    Setting Camera.Orthographic.Origin is also often useful, e.g. set it to (0.5,0.5) to make the things positioned at (0,0) in the world visible at the middle of the scene manager.

    By default our visible Z range is [-1500, 500], because this sets ProjectionNear to -1000, ProjectionFar to 1000, and camera default depth (Camera.Position.Z) is 500. This was chosen to be comfortable for all cases – you can keep camera Z unchanged and comfortably position things around [-500, 500], or set camera Z to zero and then comfortably position things around [-1000, 1000].

Public function PositionToWorldPlane(const Position: TVector2; const ScreenCoordinates: Boolean; const PlaneZ: Single; out PlanePosition: TVector3): Boolean;

Convert 2D position on the viewport into "world coordinates", which is the coordinate space seen by TCastleTransform / TCastleScene inside scene manager Items. This is a more general version of PositionTo2DWorld, that works with any projection (perspective or orthographic).

The interpretation of Position depends on ScreenCoordinates, and is similar to e.g. TCastleTiledMapControl.PositionToTile:

  • When ScreenCoordinates = True, then Position is relative to the whole container (like TCastleWindowBase or TCastleControlBase).

    And it is expressed in real device coordinates, just like TInputPressRelease.Position when mouse is being clicked, or like TInputMotion.Position when mouse is moved.

  • When ScreenCoordinates = False, then Position is relative to this UI control.

    And it is expressed in coordinates after UI scaling. IOW, if the size of this control is Width = 100, then Position.X between 0 and 100 reflects the visible range of this control.

This intersects the ray cast by Camera with a plane at Z = PlaneZ.

Returns true and sets 3D PlanePosition (the Z component of this vector must always be equal to PlaneZ) if such intersection is found. Returns false if it's not possible to determine such point (when the camera looks in the other direction).

Public function PositionTo2DWorld(const Position: TVector2; const ScreenCoordinates: Boolean): TVector2;

Convert 2D position into "world coordinates", which is the coordinate space seen by TCastleTransform / TCastleScene inside scene manager Items, assuming that we use orthographic projection in XY axes.

The interpretation of Position depends on ScreenCoordinates, and is similar to e.g. TCastleTiledMapControl.PositionToTile:

  • When ScreenCoordinates = True, then Position is relative to the whole container (like TCastleWindowBase or TCastleControlBase).

    And it is expressed in real device coordinates, just like TInputPressRelease.Position when mouse is being clicked, or like TInputMotion.Position when mouse is moved.

  • When ScreenCoordinates = False, then Position is relative to this UI control.

    And it is expressed in coordinates after UI scaling. IOW, if the size of this control is Width = 100, then Position.X between 0 and 100 reflects the visible range of this control.

This assumes that camera "up vector" is +Y, and it is looking along the negative Z axis. It also assumes orthographic projection (Camera.ProjectionType equal ptOrthographic). These are default camera direction, up and projection types set by Setup2D.

Public procedure PrepareResources(const DisplayProgressTitle: string = ''; const Options: TPrepareResourcesOptions = DefaultPrepareOptions);

Prepare resources, to make various methods (like Render) execute fast. If DisplayProgressTitle <> '', we will display progress bar during loading.

Public procedure PrepareResources(const Item: TCastleTransform; const DisplayProgressTitle: string = ''; Options: TPrepareResourcesOptions = DefaultPrepareOptions); virtual;
 

Properties

Public property Projection: TProjection read FProjection; deprecated 'in most cases, you can instead read Camera parameters, like Camera.Orthographic.EffectiveWidth, Camera.Orthographic.EffectiveHeight';

Warning: this symbol is deprecated: in most cases, you can instead read Camera parameters, like Camera.Orthographic.EffectiveWidth, Camera.Orthographic.EffectiveHeight

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

Dark gray (DefaultBackgroundColor) by default.

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

Enable built-in SSAO screen effect in the world.

Public property OnCameraChanged: TNotifyEvent read FOnCameraChanged write FOnCameraChanged;

Called on any camera change.

Public property NavigationType: TNavigationType read GetNavigationType write SetNavigationType default ntNone;

Set Navigation and some of its' parameters (like TCastleWalkNavigation.Gravity and so on).

If AutoNavigation, the initial Navigation as well as initial value of this property are automatically determined by the currently bound X3D NavigatinInfo node in the MainScene, and world bounding box. They are also automatically adjusted e.g. when current NavigatinInfo node changes.

But you can set Navigation, or this property, manually to override the detected navigation. You should set AutoNavigation to False to take control of Navigation and this property completely (no auto-detection based on MainScene will then take place).

Note that you can also affect the current NavigationType by directly changing the camera properties, e.g. you can directly change TCastleWalkNavigation.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.

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 MouseRayHit: TRayCollision read FMouseRayHit;

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

Public property AvoidNavigationCollisions: TCastleTransform read FAvoidNavigationCollisions write SetAvoidNavigationCollisions;

Do not collide with this object when moving by Navigation. It makes sense to put here player avatar (in 3rd person view) or player collision volume (in 1st person view) to allow player to move, not colliding with its own body.

In case of using TLevel, this is automatically set when you set TLevel.Player.

Public property Paused: boolean read GetPaused write SetPaused default false; deprecated 'use Items.Paused';

Warning: this symbol is deprecated: use Items.Paused

See TCastleRootTransform.Paused.

Public property SceneManager: TCastleSceneManager read FSceneManager write SetSceneManager; deprecated 'assign Items from one TCastleViewport to another to view the same world from multiple viewports';

Warning: this symbol is deprecated: assign Items from one TCastleViewport to another to view the same world from multiple viewports

 
Published property Items: TCastleRootTransform read FItems write SetItems;

Transformations and scenes visible in this viewport. You should add here your TCastleTransform and TCastleScene instances.

It is by default created (not nil), but you can also assign here your own TCastleRootTransform instance. You can also copy a TCastleRootTransform from one TCastleViewport to another, that is multiple TCastleViewport can refer to the same TCastleRootTransform instance.

Published property Camera: TCastleCamera read FCamera;

Camera determines the viewer position and orientation. The given camera instance is always available and connected with this viewport.

Published property Navigation: TCastleNavigation read FNavigation write SetNavigation stored IsStoredNavigation;

Navigation method is an optional component that handles the user input to control the camera.

You can assign here an instance of TCastleNavigation, like TCastleWalkNavigation or TCastleExamineNavigation. Or you can leave it as Nil.

Note that, if you leave it as Nil and have AutoNavigation as True (default) then a default navigation will be calculated right before the first rendering. It will take into account the 3D world initialized in Viewport.Items, e.g. the NavigatinInfo inside Viewport.Items.MainScene. Set AutoNavigation to false to avoid this automatic detection.

Note that assigning NavigationType also implicitly sets this property to an internal instance of TCastleWalkNavigation or TCastleExamineNavigation. Setting NavigationType to Nil sets this property to Nil.

See also
OnCameraChanged
Called on any camera change.
Published property OnRender3D: TRender3DEvent read FOnRender3D write FOnRender3D; deprecated 'do not customize rendering with this; instead add TCastleUserInterface descendants where you can override TCastleUserInterface.Render to do custom rendering';

Warning: this symbol is deprecated: do not customize rendering with this; instead add TCastleUserInterface descendants where you can override TCastleUserInterface.Render to do custom rendering

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 TRenderContext.Clear RenderContext.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 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 TCastleViewport.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 TCastleWalkNavigation.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; deprecated 'use Camera.ProjectionFar, and set AutoCamera to false';

Warning: this symbol is deprecated: use Camera.ProjectionFar, and set AutoCamera to false

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 OnProjection: TProjectionEvent read FOnProjection write FOnProjection; deprecated 'adjust projection by changing Camera.ProjectionType and other projection parameters inside Camera';

Warning: this symbol is deprecated: adjust projection by changing Camera.ProjectionType and other projection parameters inside Camera

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

Published property EnableParentDragging: boolean read FEnableParentDragging write FEnableParentDragging default false;

Enable to drag a parent control, for example to drag a TCastleScrollView that contains this scene manager, even when the scene inside contains clickable elements (using TouchSensor node).

To do this, you need to turn on TCastleScrollView.EnableDragging, and set EnableParentDragging=True here. In effect, scene manager will cancel the click operation once you start dragging, which allows the parent to handle all the motion events for dragging.

Published property AutoCamera: Boolean read FAutoCamera write SetAutoCamera default false;

Assign initial camera properties (initial position, direction, up, TCastleCamera.ProjectionNear) by looking at the initial world (Items) when rendering the first frame.

The AssignDefaultCamera is called only if this property is True.

Also, only if this property is True, we synchronize camera when X3D Viewpoint node changes, or a new X3D Viewpoint node is bound.

By default it is True. Setting it to False effectively means that you control Camera properties on your own.

Published property AutoNavigation: Boolean read FAutoNavigation write FAutoNavigation default false;

Assign sensible Navigation looking at the initial world (Items) if it is not assigned.

This also allows to later synchronize navigation properties when X3D NavigationInfo node changes, or a new NavigationInfo node is bound.

By default it is True. Setting it to False effectively means that you control Navigation on your own.

Published property OnBoundViewpointChanged: TNotifyEvent read FOnBoundViewpointChanged write FOnBoundViewpointChanged;

Called when bound Viewpoint node changes. Called exactly when TCastleSceneCore.ViewpointStack.OnBoundChanged is called.

Published property OnBoundNavigationInfoChanged: TNotifyEvent read FOnBoundNavigationInfoChanged write FOnBoundNavigationInfoChanged;

Called when bound NavigationInfo changes (to a different node, or just a field changes).

Published property PreventInfiniteFallingDown: Boolean read FPreventInfiniteFallingDown write FPreventInfiniteFallingDown default false;

Protect from falling down because of gravity when position is outside of world bounding box. This is a nice thing for general model viewers (like view3dscene), to prevent from accidentally falling down when using "Walk" mode.

For now, the only thing doing gravity on camera is TCastleWalkNavigation when TCastleWalkNavigation.Gravity = True, so this is the only case when this property is relevant.

Published property BackgroundColorPersistent: TCastleColorPersistent read FBackgroundColorPersistent ;

BackgroundColor that can be visually edited in Castle Game Engine Editor, Lazarus and Delphi. Normal user code does not need to deal with this, instead read or write BackgroundColor directly.

See also
BackgroundColor
Background color, displayed behind the 3D world.

Generated by PasDoc 0.15.0.