Class TCastleViewport

Unit

Declaration

type TCastleViewport = class(TCastleScreenEffects)

Description

Viewport displays a tree of scenes and transformations (TCastleTransform and descendants of it, like TCastleScene). Add the scenes and transformations to Items. See https://castle-engine.io/viewport_and_scenes .

Each viewport has a Camera with a position and orientation. Viewport may have multiple cameras.

Viewport may also have a navigation that allows to move camera by keyboard, mouse and other inputs. You can use any navigation method implemented in the engine (TCastleExamineNavigation, TCastleWalkNavigation, TCastleThirdPersonNavigation) or implement your own (you can create your own descendants of TCastleNavigation, or just move/rotate the camera by calling Viewport.Camera.SetWorldView from anywhere). Just add TCastleNavigation as a child of TCastleViewport.

Viewport may display a background. It may be a solid color, a 3D skybox or a gradient. See Background, BackgroundColor properties and https://castle-engine.io/background . Alternatively, viewport background may be transparent (so other TCastleUserInterface underneath will be visible) if Transparent.

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. See https://castle-engine.io/multiple_viewports_to_display_one_world .

Hierarchy

Overview

Fields

Public nested const DefaultScreenSpaceAmbientOcclusion = false;
Public nested const DefaultScreenSpaceReflections = False;
Public nested const DefaultScreenSpaceReflectionsSurfaceGlossiness = 0.5;
Public nested const DefaultUseGlobalLights = true;
Public nested const DefaultUseGlobalFog = true;
Public nested const DefaultShadowVolumes = true;
Public nested const DefaultBackgroundColor: TVector4 = (X: 0.1; Y: 0.1; Z: 0.1; W: 1);
Public nested const Default2DProjectionFar = CastleTransform.Default2DProjectionFar deprecated 'this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display';
Public nested const Default2DProjectionNear = CastleTransform.Default2DProjectionNear deprecated 'this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display';
Public nested const Default2DCameraZ = CastleTransform.Default2DCameraZ;
Public nested const DefaultPrepareOptions = [prRenderSelf, prRenderClones, prBackground, prBoundingBox, prScreenEffects];
Public var CustomRenderingPass: TUserRenderingPass;
Public InternalDesignCamera: TCastleCamera;

Methods

Protected function CalculateProjection: TProjection; virtual;
Protected procedure InitializeGlobalLights(const GlobalLights: TLightInstancesList); virtual;
Protected procedure InitializeLights(const GlobalLights: TLightInstancesList); deprecated 'use InitializeGlobalLights';
Protected procedure RenderFromViewEverything(const RenderingCamera: TRenderingCamera); virtual;
Protected procedure RenderFromView3D(const Params: TRenderParams); virtual;
Protected procedure RenderOnePass(const Params: TRenderParams); virtual;
Protected procedure Render3D(const Params: TRenderParams); virtual; deprecated 'use RenderOnePass';
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 PointingDevicePressFailed; virtual;
Protected procedure BoundNavigationInfoChanged; virtual;
Protected procedure BoundViewpointChanged; virtual;
Protected procedure RenderWithoutScreenEffects; override;
Protected procedure Loaded; 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 BeforeRender; override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
Public function GetMainScene: TCastleScene; deprecated 'use Items.MainScene';
Public procedure AssignDefaultCamera; virtual;
Public function ScreenEffectsCount: Integer; virtual;
Public function ScreenEffectsNeedDepth: boolean; virtual;
Public function ScreenSpaceAmbientOcclusionAvailable: boolean;
Public function ScreenSpaceReflectionsAvailable: 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 procedure Setup2D;
Public function PositionToCameraPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const Depth: Single; out PlanePosition: TVector3): Boolean;
Public procedure PositionToRay(const Position: TVector2; const ContainerCoordinates: Boolean; out RayOrigin, RayDirection: TVector3);
Public function PositionToWorldPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const PlaneZ: Single; out PlanePosition: TVector3): Boolean;
Public function PositionTo2DWorld(const Position: TVector2; const ContainerCoordinates: Boolean): TVector2;
Public function PositionFrom2DWorld(const WorldPosition: TVector2; const ContainerCoordinates: Boolean): TVector2;
Public function PositionFromWorld(const WorldPosition: TVector3): TVector2;
Public procedure PrepareResources(const DisplayProgressTitle: string = ''; const Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload;
Public procedure PrepareResources(const Item: TCastleTransform; const DisplayProgressTitle: string = ''; Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; virtual;
Public function TransformUnderMouse: TCastleTransform;
Public procedure SetupCamera;

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 [const 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 ScreenSpaceReflections: Boolean read FScreenSpaceReflections write SetScreenSpaceReflections default DefaultScreenSpaceReflections;
Public property ScreenSpaceReflectionsSurfaceGlossiness: Single read FScreenSpaceReflectionsSurfaceGlossiness write SetScreenSpaceReflectionsSurfaceGlossiness;
Public property OnCameraChanged: TNotifyEvent read FOnCameraChanged write FOnCameraChanged;
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';
Public property Navigation: TCastleNavigation read GetNavigation write SetNavigation stored false; deprecated 'no need to set this, instead add TCastleNavigation like "MyViewport.InsertBack(MyNavigation)"';
Published property Items: TCastleRootTransform read FItems write SetItems;
Published property Camera: TCastleCamera read FCamera write SetCamera;
Published property ShadowVolumes: boolean read FShadowVolumes write FShadowVolumes default DefaultShadowVolumes;
Published property ShadowVolumesRender: boolean read FShadowVolumesRender write FShadowVolumesRender default false;
Published property Background: TCastleBackground read FBackground write SetBackground;
Published property Fog: TCastleFog read FFog write SetFog;
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; deprecated 'if you need to tweak this, then do not use MainScene; use regular TCastleScene and set CastGlobalLights as needed';
Published property UseGlobalFog: boolean read FUseGlobalFog write FUseGlobalFog default DefaultUseGlobalFog; deprecated 'configure fog by assigning to TCastleViewport.Fog component; leave deprecated TCastleViewport.MainScene nil';
Published property ApproximateActivation: boolean read FApproximateActivation write FApproximateActivation default 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; deprecated 'it is simpler to set camera at design-time explicitly, or use CameraViewpointForWholeScene to auto-adjust camera; if you want to animate the camera, attach TCastleCamera to a bone transformation exposed by Scene.ExposeTransforms';
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 DefaultScreenSpaceReflections = False;
 
Public nested const DefaultScreenSpaceReflectionsSurfaceGlossiness = 0.5;
 
Public nested const DefaultUseGlobalLights = true;
 
Public nested const DefaultUseGlobalFog = true;
 
Public nested const DefaultShadowVolumes = true;
 
Public nested const DefaultBackgroundColor: TVector4 = (X: 0.1; Y: 0.1; Z: 0.1; W: 1);
 
Public nested const Default2DProjectionFar = CastleTransform.Default2DProjectionFar deprecated 'this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display';

Warning: this symbol is deprecated: this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display

referencing deprecated in deprecated

Public nested const Default2DProjectionNear = CastleTransform.Default2DProjectionNear deprecated 'this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display';

Warning: this symbol is deprecated: this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display

 
Public nested const Default2DCameraZ = CastleTransform.Default2DCameraZ;
 
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.

Public InternalDesignCamera: TCastleCamera;

At design-time (in CGE editor), this is the camera used by the editor. Usually use InternalCamera, to automatically pick either design-time camera or runtime Camera.

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 InitializeGlobalLights(const GlobalLights: TLightInstancesList); virtual;

Prepare lights shining on everything. GlobalLights contents should be initialized here. The implementation in this class adds headlight determined by the Items.UseHeadlight value.

Protected procedure InitializeLights(const GlobalLights: TLightInstancesList); deprecated 'use InitializeGlobalLights';

Warning: this symbol is deprecated: use InitializeGlobalLights

 
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 procedure RenderOnePass(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 Render3D(const Params: TRenderParams); virtual; deprecated 'use RenderOnePass';

Warning: this symbol is deprecated: use RenderOnePass

 
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 PointingDevicePressFailed; virtual;

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

Protected procedure BoundNavigationInfoChanged; virtual;
 
Protected procedure BoundViewpointChanged; virtual;
 
Protected procedure RenderWithoutScreenEffects; override;
 
Protected procedure Loaded; 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 BeforeRender; override;
 
Public function PropertySections(const PropertyName: String): TPropertySections; override;
 
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
 
Public function GetMainScene: TCastleScene; deprecated 'use Items.MainScene';

Warning: this symbol is deprecated: use Items.MainScene

 
Public procedure AssignDefaultCamera; virtual;

Assign current camera vectors and projection. This only fills existing Camera with contents, it doesn't change the Camera to new component.

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 function ScreenSpaceReflectionsAvailable: boolean;

Does the graphic card support our ScreenSpaceReflections shader. This does not depend on the current state of ScreenSpaceReflections property. You can use it e.g. to disable the menu item to switch SSR 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 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 viewport 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 viewport.

    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 PositionToCameraPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const Depth: Single; out PlanePosition: TVector3): Boolean;

Convert 2D position on the viewport into 3D "world coordinates", by colliding camera ray with a plane parallel to the viewport at given Depth. "World coordinates" are coordinates space seen by TCastleTransform / TCastleScene inside viewport Items. Use Depth > 0 for positions in front of the camera.

This is similar to "Unproject" GLU routine. It allows to map points from the 2D viewport back to the 3D space inside viewport.

The interpretation of Position depends on ContainerCoordinates:

  • When ContainerCoordinates = True, then Position is relative to the whole container (like TCastleWindow or TCastleControl).

    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 ContainerCoordinates = 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.

Returns true and sets 3D PlanePosition if such intersection is found. Returns false if it's not possible to determine such point (which should not be possible, unless camera field of view is larger than 180 degrees).

Public procedure PositionToRay(const Position: TVector2; const ContainerCoordinates: Boolean; out RayOrigin, RayDirection: TVector3);

Convert 2D position on the viewport into 3D ray.

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

  • When ContainerCoordinates = True, then Position is relative to the whole container (like TCastleWindow or TCastleControl).

    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 ContainerCoordinates = 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.

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

Convert 2D position on the viewport into 3D "world coordinates", by colliding camera ray with a plane at constant Z. "World coordinates" are coordinates space seen by TCastleTransform / TCastleScene inside viewport Items.

This is a more general version of PositionTo2DWorld, that works with any projection (perspective or orthographic). This is often useful if your game is "close to 2D", which means that you use 3D (and maybe even perspective camera), but most of the game world is placed around some plane with constant Z.

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

  • When ContainerCoordinates = True, then Position is relative to the whole container (like TCastleWindow or TCastleControl).

    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 ContainerCoordinates = 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 ContainerCoordinates: Boolean): TVector2;

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

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

  • When ContainerCoordinates = True, then Position is relative to the whole container (like TCastleWindow or TCastleControl).

    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 ContainerCoordinates = 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 function PositionFrom2DWorld(const WorldPosition: TVector2; const ContainerCoordinates: Boolean): TVector2;

Invert PositionTo2DWorld, converting the "world coordinates" (the coordinate space seen by TCastleTransform / TCastleScene inside viewport Items) into final screen position.

Just like PositionTo2DWorld, 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 function PositionFromWorld(const WorldPosition: TVector3): TVector2;

Project 3D coordinates (the coordinate space seen by TCastleTransform / TCastleScene inside viewport Items) into 2D position on the viewport UI.

The resulting position is relative to this viewport control and it is expressed in coordinates after UI scaling. IOW, if the size of this control is EffectiveWidth = 100, then Position.X between 0 and 100 reflects the visible range of this control. This is like using ContainerCoordinates = False with PositionToRay.

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

Prepare resources, to make various methods (like Render) execute fast. Call it only when rendering context is initialized (ApplicationProperties.IsGLContextOpen). If DisplayProgressTitle <> '', we will display progress bar during loading.

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

Current object (TCastleTransform instance) under the mouse cursor. Updated in every mouse move. May be Nil.

Public procedure SetupCamera;

Create new camera and make it used by this viewport. This creates new unnamed TCastleCamera, owned by this viewport, assigns it to Camera and adds it to Items.

Call this only when Camera is Nil.

This is done automatically when creating TCastleViewport (not in design-mode, not at deserialization) using the standard TCastleViewport.Create constructor. So you likely don't need to call this in typical applications.

Note: Even when used from CGE editor (CastleDesignMode), this creates non-design camera. This way viewports created with InternalCreateNonDesign have also non-design cameras. This is important, so that e.g. camera has no bounding box, and thus AssignDefaultCamera in sprite sheet editor doesn't put camera further and further away.

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 [const 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 only if Background is Nil and MainScene doesn't define any background either.

Ignored if Transparent.

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 ScreenSpaceReflections: Boolean read FScreenSpaceReflections write SetScreenSpaceReflections default DefaultScreenSpaceReflections;

Enable built-in SSR screen effect in the world.

Public property ScreenSpaceReflectionsSurfaceGlossiness: Single read FScreenSpaceReflectionsSurfaceGlossiness write SetScreenSpaceReflectionsSurfaceGlossiness;

Adjust SSR default surface glossiness.

Public property OnCameraChanged: TNotifyEvent read FOnCameraChanged write FOnCameraChanged;

Called on any camera change.

Public property MouseRayHit: TRayCollision read FMouseRayHit;

Current object (TCastleTransform hierarchy) under the mouse cursor. Updated in every mouse move. May be Nil.

The returned list (if not Nil) contains TCastleTransform instances that collided with the ray (from the deepest instance in the Items tree to the root), along with some additional information. See TRayCollision for details.

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

 
Public property Navigation: TCastleNavigation read GetNavigation write SetNavigation stored false; deprecated 'no need to set this, instead add TCastleNavigation like "MyViewport.InsertBack(MyNavigation)"';

Warning: this symbol is deprecated: no need to set this, instead add TCastleNavigation like "MyViewport.InsertBack(MyNavigation)"

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

This is a deprecated property. There's no point in assigning current navigation like this. Instead add the TCastleNavigation instance as a child of TCastleViewport and it will affect the viewport automatically. This property is now only a shortcut to

- get the current TCastleNavigation child (if multiple present, it is undefined which is returned)

- make the given set TCastleNavigation as the only child.

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

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.

Note that assigning here Nil is allowed, but under the hood it just creates an empty TCastleRootTransform instance. So this property is never Nil when reading. But try to not depend on it for the future, at some point this property may be allowed to be Nil, for consistency.

Published property Camera: TCastleCamera read FCamera write SetCamera;

Camera determines the viewer position and orientation.

You should create TCastleCamera, assign to this property, and add it somewhere to Items.

Note that camera can be placed anywhere within Items, not necessary as direct child of Items. For example it can be a children of some deeper TCastleTransform, this way you can attach camera e.g. to some bone or to a moving object.

Generally, TCastleCamera is a regular component that can be added and removed freely from Items, renamed, freed etc. And setting this property is an independent action that doesn't add/remove any camera from Items. This property can also be set to Nil.

For convenience, there are however some moments when we set up this property and add camera to Items automatically:

  1. When you create TCastleViewport from code (not by deserializing some xxx.castle-user-interface file, not in design-mode in editor) then we automatically add new (unnamed) camera and set Viewport.Camera and add it to Viewport.Items.

  2. Only at design-time (in editor): creating new viewport by editor menu also adds a default camera to it. In this case camera component is named and owned by the same owner as viewport. This is done right after TCastleViewport creation and only at design-time.

  3. For backward compatibility, after deserializing file from previous engine versions, we add the camera from it to Viewport.Items. This is made strictly for backward compatibility, only when deserializing, and it shouldn't occur when reading new design files.

It's important to note that when deserializing camera from new engine versions, there's no "magic". We just expect that Viewport.Camera and Viewport.Items are good. Trying to do something automatic/smart in this case turned out to be quite troublesome and breaking more than helping.

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 Background: TCastleBackground read FBackground write SetBackground;

Background (like a skybox) to display behind the Items. Displayed only when not Transparent. See https://castle-engine.io/background

Published property Fog: TCastleFog read FFog write SetFog;

Fog to use to display viewport contents in Items. See https://castle-engine.io/fog

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

If True then the background (from Background or MainScene) will be rendered wireframe, over the solid background filled with BackgroundColor. Useful for debugging when you want to see how your background geometry looks like.

Ignored if Transparent.

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

If True then the viewport will not draw a background and the UI underneath will be visible. The UI underneath is visible at pixels which are not covered by items on Items, and where items Items have partially-transparent materials.

If True, the Background, BackgroundColor, BackgroundWireframe, and any background defined inside MainScene will be ignored.

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

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

You can disable this, which allows to combine together the 3D objects rendered by various viewports (and by custom OpenGL rendering), such that the 3D positions determime what overlaps what. This only makes sense if you have a number of TCastleViewport instances, that share the same size and position on the screen, same projection and the same camera.

It's your responsibility in such case to clear the depth buffer. E.g. place one viewport 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; deprecated 'if you need to tweak this, then do not use MainScene; use regular TCastleScene and set CastGlobalLights as needed';

Warning: this symbol is deprecated: if you need to tweak this, then do not use MainScene; use regular TCastleScene and set CastGlobalLights as needed

Let lights in MainScene shine on every other TCastleScene, not only MainScene. This is an easy way to lit your whole world with lights defined inside MainScene file. Be sure to set X3D lights global=TRUE.

Published property UseGlobalFog: boolean read FUseGlobalFog write FUseGlobalFog default DefaultUseGlobalFog; deprecated 'configure fog by assigning to TCastleViewport.Fog component; leave deprecated TCastleViewport.MainScene nil';

Warning: this symbol is deprecated: configure fog by assigning to TCastleViewport.Fog component; leave deprecated TCastleViewport.MainScene nil

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 Input_Interact (by default just left mouse button), we look if current mouse/touch position hits an object (TCastleTransform) that actually does something on activation. The object may do various stuff inside TCastleTransform.PointingDevicePress, 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 PointingDevicePress. If there's nothing interesting under mouse/touch, we will retry a couple of other positions around the current mouse/touch.

This should be usually used when you use TCastleMouseLookNavigation.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 object is difficult, as you don't see the cursor.

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 TCastleViewport, 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, viewport 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; deprecated 'it is simpler to set camera at design-time explicitly, or use CameraViewpointForWholeScene to auto-adjust camera; if you want to animate the camera, attach TCastleCamera to a bone transformation exposed by Scene.ExposeTransforms';

Warning: this symbol is deprecated: it is simpler to set camera at design-time explicitly, or use CameraViewpointForWholeScene to auto-adjust camera; if you want to animate the camera, attach TCastleCamera to a bone transformation exposed by Scene.ExposeTransforms

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 automatically 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 False, which means you control Camera properties 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.

This is only used by navigations performing gravity internally, that is right now: TCastleWalkNavigation (when TCastleWalkNavigation.Gravity = True).

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.

Generated by PasDoc 0.16.0.