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
- TObject
- TPersistent
- TComponent
- TCastleComponent
- TCastleUserInterface
- TCastleScreenEffects
- TCastleViewport
Overview
Fields
nested const DefaultScreenSpaceAmbientOcclusion = false; |
|
nested const DefaultScreenSpaceReflections = False; |
|
nested const DefaultScreenSpaceReflectionsSurfaceGlossiness = 0.5; |
|
nested const DefaultUseGlobalLights = true; |
|
nested const DefaultUseGlobalFog = true; |
|
nested const DefaultShadowVolumes = true; |
|
nested const DefaultBackgroundColor: TVector4 = (X: 0.1; Y: 0.1; Z: 0.1; W: 1); |
|
nested const Default2DProjectionFar = CastleTransform.Default2DProjectionFar deprecated 'this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display'; |
|
nested const Default2DProjectionNear = CastleTransform.Default2DProjectionNear deprecated 'this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display'; |
|
nested const Default2DCameraZ = CastleTransform.Default2DCameraZ; |
|
nested const DefaultPrepareOptions = [prRenderSelf, prRenderClones, prBackground, prBoundingBox, prScreenEffects]; |
|
nested const DefaultInternalGridAxis = false; |
|
var CustomRenderingPass: TUserRenderingPass; |
|
InternalDesignCamera: TCastleCamera; |
Methods
function CalculateProjection: TProjection; virtual; |
|
procedure InitializeGlobalLights(const GlobalLights: TLightInstancesList); virtual; |
|
procedure InitializeLights(const GlobalLights: TLightInstancesList); deprecated 'use InitializeGlobalLights'; |
|
procedure RenderFromViewEverything(const RenderingCamera: TRenderingCamera); virtual; |
|
procedure RenderFromView3D(const Params: TRenderParams); virtual; |
|
procedure RenderOnePass(const Params: TRenderParams; const PassParams: TRenderOnePassParams); virtual; |
|
procedure Notification(AComponent: TComponent; Operation: TOperation); override; |
|
function InternalExtraGetScreenEffects( const Index: Integer): TGLSLProgram; override; |
|
function InternalExtraScreenEffectsCount: Integer; override; |
|
function InternalExtraScreenEffectsNeedDepth: Boolean; override; |
|
procedure PointingDevicePressFailed; virtual; |
|
procedure BoundNavigationInfoChanged; virtual; |
|
procedure BoundViewpointChanged; virtual; |
|
procedure RenderWithoutScreenEffects; override; |
|
procedure Loaded; override; |
|
constructor Create(AOwner: TComponent); override; |
|
destructor Destroy; override; |
|
function AllowSuspendForInput: boolean; override; |
|
function Press(const Event: TInputPressRelease): boolean; override; |
|
function Release(const Event: TInputPressRelease): boolean; override; |
|
function Motion(const Event: TInputMotion): boolean; override; |
|
procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override; |
|
procedure BeforeRender; override; |
|
function PropertySections(const PropertyName: String): TPropertySections; override; |
|
procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override; |
|
function GetMainScene: TCastleScene; deprecated 'use Items.MainScene'; |
|
procedure AssignDefaultCamera; virtual; |
|
function ScreenSpaceAmbientOcclusionAvailable: boolean; |
|
function ScreenSpaceReflectionsAvailable: boolean; |
|
procedure GLContextOpen; override; |
|
procedure GLContextClose; override; |
|
function PrepareParams: TPrepareParams; deprecated 'use TCastleViewport.PrepareResources to prepare transforms'; |
|
function BaseLights: TLightInstancesList; deprecated 'this is internal info, you should not need this; use PrepareParams to get opaque information to pass to TCastleTransform.PrepareResources'; |
|
function Statistics: TRenderStatistics; |
|
function TriangleHit: PTriangle; |
|
procedure Setup2D; |
|
function PositionToCameraPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const Depth: Single; out PlanePosition: TVector3): Boolean; |
|
procedure PositionToRay(const Position: TVector2; const ContainerCoordinates: Boolean; out RayOrigin, RayDirection: TVector3); |
|
function PositionToWorldPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const PlaneConstCoord: T3DAxis; const PlaneConstValue: Single; out PlanePosition: TVector3): Boolean; overload; |
|
function PositionToWorldPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const PlaneConstValue: Single; out PlanePosition: TVector3): Boolean; overload; deprecated 'use PositionToWorldPlane overload with PlaneConstCoord parameter; this version assumes PlaneConstCoord = 2'; |
|
function PositionTo2DWorld(const Position: TVector2; const ContainerCoordinates: Boolean): TVector2; |
|
function PositionFrom2DWorld(const WorldPosition: TVector2; const ContainerCoordinates: Boolean): TVector2; |
|
function PositionFromWorld(const WorldPosition: TVector3): TVector2; |
|
procedure PrepareResources(const DisplayProgressTitle: string; const Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; deprecated 'use overload without DisplayProgressTitle: String'; |
|
procedure PrepareResources(const Item: TCastleTransform; const DisplayProgressTitle: string; Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; deprecated 'use overload without DisplayProgressTitle: String'; |
|
procedure PrepareResources( const Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; |
|
procedure PrepareResources(const Item: TCastleTransform; Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; virtual; |
|
function TransformUnderMouse: TCastleTransform; |
|
procedure SetupCamera; |
|
function InternalBuildNode(const SaveBaseUrl: String): TX3DRootNode; |
Properties
property Projection: TProjection read FProjection; deprecated 'in most cases, you can instead read Camera parameters, like Camera.Orthographic.EffectiveWidth, Camera.Orthographic.EffectiveHeight'; |
|
property BackgroundColor: TCastleColor
read FBackgroundColor write FBackgroundColor; |
|
property ScreenSpaceAmbientOcclusion: boolean
read FScreenSpaceAmbientOcclusion write SetScreenSpaceAmbientOcclusion
default DefaultScreenSpaceAmbientOcclusion; |
|
property ScreenSpaceReflections: Boolean
read FScreenSpaceReflections write SetScreenSpaceReflections
default DefaultScreenSpaceReflections; |
|
property ScreenSpaceReflectionsSurfaceGlossiness: Single
read FScreenSpaceReflectionsSurfaceGlossiness write SetScreenSpaceReflectionsSurfaceGlossiness; |
|
property OnCameraChanged: TNotifyEvent read FOnCameraChanged write FOnCameraChanged; |
|
property MouseRayHit: TRayCollision read GetMouseRayHit; |
|
property AvoidNavigationCollisions: TCastleTransform
read FAvoidNavigationCollisions
write SetAvoidNavigationCollisions; |
|
property Paused: boolean read GetPaused write SetPaused default false; deprecated 'use Items.Paused'; |
|
property SceneManager: TCastleSceneManager read FSceneManager write SetSceneManager; deprecated 'assign Items from one TCastleViewport to another to view the same world from multiple viewports'; |
|
property Navigation: TCastleNavigation read GetNavigation write SetNavigation
stored false; deprecated 'instead of this property: to get, just remember current navigation instance on your side; to set, add it like "MyViewport.InsertBack(MyNavigation)"'; |
|
property Items: TCastleRootTransform read FItems write SetItems; |
|
property Camera: TCastleCamera read FCamera write SetCamera; |
|
property ShadowVolumes: boolean
read FShadowVolumes write FShadowVolumes default DefaultShadowVolumes; |
|
property ShadowVolumesRender: boolean read FShadowVolumesRender write FShadowVolumesRender default false; |
|
property Background: TCastleBackground read FBackground write SetBackground; |
|
property Fog: TCastleFog read FFog write SetFog; |
|
property BackgroundWireframe: boolean
read FBackgroundWireframe write FBackgroundWireframe default false; |
|
property Transparent: boolean read FTransparent write FTransparent default false; |
|
property ClearDepth: boolean read FClearDepth write FClearDepth default true; |
|
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'; |
|
property UseGlobalFog: boolean
read FUseGlobalFog write FUseGlobalFog default DefaultUseGlobalFog; deprecated 'configure fog by assigning to TCastleViewport.Fog component; leave deprecated TCastleViewport.MainScene nil'; |
|
property ApproximateActivation: boolean
read FApproximateActivation write FApproximateActivation default false; |
|
property OnProjection: TProjectionEvent read FOnProjection write FOnProjection; deprecated 'adjust projection by changing Camera.ProjectionType and other projection parameters inside Camera'; |
|
property EnableParentDragging: boolean
read FEnableParentDragging write FEnableParentDragging default false; |
|
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'; |
|
property OnBoundViewpointChanged: TNotifyEvent read FOnBoundViewpointChanged write FOnBoundViewpointChanged; |
|
property OnBoundNavigationInfoChanged: TNotifyEvent read FOnBoundNavigationInfoChanged write FOnBoundNavigationInfoChanged; |
|
property PreventInfiniteFallingDown: Boolean
read FPreventInfiniteFallingDown write FPreventInfiniteFallingDown default false; |
|
property DynamicBatching: Boolean
read FDynamicBatching write SetDynamicBatching default false; |
|
property OcclusionCulling: boolean
read FOcclusionCulling write SetOcclusionCulling default false; |
|
property OcclusionSort: TShapeSort
read FOcclusionSort write FOcclusionSort default sortAuto; |
|
property BlendingSort: TShapeSort
read FBlendingSort write FBlendingSort default sortAuto; |
|
property OnCustomShapeSort: TShapeSortEvent
read FOnCustomShapeSort write FOnCustomShapeSort; |
|
property UpdateSoundListener: Boolean
read FUpdateSoundListener write FUpdateSoundListener default true; |
|
property BackgroundColorPersistent: TCastleColorPersistent read FBackgroundColorPersistent ; |
Description
Fields
nested const DefaultScreenSpaceAmbientOcclusion = false; |
|
This item has no description. |
nested const DefaultScreenSpaceReflections = False; |
|
This item has no description. |
nested const DefaultScreenSpaceReflectionsSurfaceGlossiness = 0.5; |
|
This item has no description. |
nested const DefaultUseGlobalLights = true; |
|
This item has no description. |
nested const DefaultUseGlobalFog = true; |
|
This item has no description. |
nested const DefaultShadowVolumes = true; |
|
This item has no description. |
nested const DefaultBackgroundColor: TVector4 = (X: 0.1; Y: 0.1; Z: 0.1; W: 1); |
|
This item has no description. |
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 |
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 This item has no description. |
nested const Default2DCameraZ = CastleTransform.Default2DCameraZ; |
|
This item has no description. |
nested const DefaultPrepareOptions = [prRenderSelf, prRenderClones, prBackground, prBoundingBox, prScreenEffects]; |
|
This item has no description. |
nested const DefaultInternalGridAxis = false; |
|
This item has no description. |
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. |
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
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. |
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. |
procedure InitializeLights(const GlobalLights: TLightInstancesList); deprecated 'use InitializeGlobalLights'; |
|
Warning: this symbol is deprecated: use InitializeGlobalLights This item has no description. |
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. |
procedure RenderOnePass(const Params: TRenderParams; const PassParams: TRenderOnePassParams); virtual; |
|
Render one pass, with current camera and parameters. All current camera settings are saved in RenderParams.RenderingCamera.
Parameters
|
procedure Notification(AComponent: TComponent; Operation: TOperation); override; |
|
This item has no description. |
function InternalExtraGetScreenEffects( const Index: Integer): TGLSLProgram; override; |
|
This item has no description. |
function InternalExtraScreenEffectsCount: Integer; override; |
|
This item has no description. |
function InternalExtraScreenEffectsNeedDepth: Boolean; override; |
|
This item has no description. |
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. |
procedure BoundNavigationInfoChanged; virtual; |
|
This item has no description. |
procedure BoundViewpointChanged; virtual; |
|
This item has no description. |
procedure RenderWithoutScreenEffects; override; |
|
This item has no description. Showing description inherited from TCastleScreenEffects.RenderWithoutScreenEffects. Descendants with special rendering code should override this, and never override Render or RenderOverChildren (as those two methods have special implementation in this class). This rendering method will be called regardless if we have or not some screen effects. When no screen effects are actually used (e.g. AddScreenEffect wasn't used, |
procedure Loaded; override; |
|
This item has no description. |
constructor Create(AOwner: TComponent); override; |
|
This item has no description. |
destructor Destroy; override; |
|
This item has no description. |
function AllowSuspendForInput: boolean; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.AllowSuspendForInput.
Allow window containing this control to suspend waiting for user input. Typically you want to override this to return In this class, this simply returns always |
function Press(const Event: TInputPressRelease): boolean; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.Press.
Override this method to react to user pressing a key, mouse button or mouse wheel. Return When implementing in descendants it is best to override it like this: function TMyControl.Press(const Event: TInputPressRelease): boolean; begin Result := inherited; if Result then Exit; // exit if ancestor already handled this event if Event.IsKey(keyEnter) then begin // do something in reaction to Enter key ... // let engine know that this input event was handled Exit(true); end; if Event.IsMouseButton(buttonLeft) then begin // do something in reaction to left mouse button press ... // let engine know that this input event was handled Exit(true); end; end;
These events are generated for all UI controls, whether they are considered "interactive" or not. These events are generated for non-interactive controls like TCastleRectangleControl or TCastleLabel as well. For example, these events ignore the TCastleButton.Enabled state, they are generated always (see https://github.com/castle-engine/castle-engine/issues/413 ). Use instead TCastleButton.OnClick to detect clicks on a button in a way that honors the TCastleButton.Enabled state. When a control returns The events Press and Release are passed to the parent only after the children had a chance to process this event. Overriding them makes sense if you draw something that "looks clickable" in TCastleUserInterface.Render, which is the standard place you should draw stuff. For example our TCastleButton draws there. In contrast, the events PreviewPress and PreviewRelease are passed first to the parent control, before children have a chance to process this event. In partcular, overriding them makes sense if you draw something that "looks clickable" in TCastleUserInterface.RenderOverChildren. |
function Release(const Event: TInputPressRelease): boolean; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.Release.
Override this method to react to user releasing a key, mouse button. Return This is counterpart to Press method. See Press for more details. Note: We'd like this method to also be called when user releases a mouse wheel. But currently releasing of the mouse wheel is not reported now by any backend. Only releasing of keys and mouse buttons is reported. |
function Motion(const Event: TInputMotion): boolean; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.Motion.
|
procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.Update. Control may do here anything that must be continuously repeated. E.g. camera handles here falling down due to gravity, rotating model in Examine mode, and many more.
This method may be used, among many other things, to continuously react to the fact that user pressed some key (or mouse button). For example, if holding some key should move some 3D object, you should do something like: if HandleInput then begin if Container.Pressed[keyArrowRight] then begin Transform.Position := Transform.Position + Vector3(SecondsPassed * 10, 0, 0); HandleInput := false; end; end;
Instead of directly using a key code, consider also using TInputShortcut that makes the input key nicely configurable. See engine tutorial about handling inputs. Multiplying movement by SecondsPassed makes your operation frame-rate independent. Object will move by 10 units in a second, regardless of how many FPS your game has. The code related to HandleInput is important if you write a generally-useful control that should nicely cooperate with all other controls, even when placed on top of them or under them. The correct approach is to only look at pressed keys/mouse buttons if HandleInput is Note that to handle a single press / release (like "switch light on when pressing a key") you should rather use Press and Release methods. Use this method only for continuous handling (like "holding this key makes the light brighter and brighter"). To understand why such HandleInput approach is needed, realize that the "Update" events are called differently than simple mouse and key events like "Press" and "Release". "Press" and "Release" events return whether the event was somehow "handled", and the container passes them only to the controls under the mouse (decided by TCastleUserInterface.CapturesEventsAtPosition). And as soon as some control says it "handled" the event, other controls (even if under the mouse) will not receive the event. This approach is not suitable for Update events. Some controls need to do the Update job all the time, regardless of whether the control is under the mouse and regardless of what other controls already did. So all controls (well, all controls that exist, in case of TCastleUserInterface, see TCastleUserInterface.Exists) receive Update calls. So the "handled" status is passed through HandleInput. If a control is not under the mouse, it will receive HandleInput = |
procedure BeforeRender; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.BeforeRender. Prepare your resources, right before drawing. Called only when Exists and GLInitialized. Do not explicitly call this method. Instead, render controls by adding them to the TCastleContainer.Controls list, or render them explicitly (for off-screen rendering) by TCastleContainer.RenderControl. |
function PropertySections(const PropertyName: String): TPropertySections; override; |
|
This item has no description. Showing description inherited from TCastleComponent.PropertySections. Section where to show property in the editor. |
procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override; |
|
This item has no description. Showing description inherited from TCastleComponent.CustomSerialization. Override this method to call various methods of SerializationProcess, which in turn allows to serialize/deserialize things that are not published. This allows to serialize/deserialize with more freedom, e.g. to serialize/deserialize some private field. |
function GetMainScene: TCastleScene; deprecated 'use Items.MainScene'; |
|
Warning: this symbol is deprecated: use Items.MainScene This item has no description. |
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. |
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. |
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. |
procedure GLContextOpen; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.GLContextOpen. Initialize your OpenGL resources. This is called when OpenGL context of the container is created, or when the control is added to the already existing context. In other words, this is the moment when you can initialize OpenGL resources, like display lists, VBOs, OpenGL texture names, etc. As an exception, this is called regardless of the Exists value. This way a control can prepare it's resources, regardless if it exists now. |
procedure GLContextClose; override; |
|
This item has no description. Showing description inherited from TCastleUserInterface.GLContextClose. Destroy your OpenGL resources. Called when OpenGL context of the container is destroyed. Also called when controls is removed from the container You should release here any resources that are tied to the OpenGL context. In particular, the ones created in GLContextOpen. As an exception, this is called regardless of the Exists value. This way a control can release it's resources, regardless if it exists now. |
function PrepareParams: TPrepareParams; deprecated 'use TCastleViewport.PrepareResources to prepare transforms'; |
|
Warning: this symbol is deprecated: use TCastleViewport.PrepareResources to prepare transforms 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. |
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 This item has no description. |
function Statistics: TRenderStatistics; |
|
Statistics about last rendering frame. See TRenderStatistics docs. |
function TriangleHit: PTriangle; |
|
Current 3D triangle under the mouse cursor. Updated in every mouse move. May be |
procedure Setup2D; |
|
Utility method to set camera to a suitable state for 2D games.
|
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:
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). |
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:
|
function PositionToWorldPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const PlaneConstCoord: T3DAxis; const PlaneConstValue: Single; out PlanePosition: TVector3): Boolean; overload; |
|
Convert 2D position on the viewport into 3D "world coordinates", by colliding camera ray with a plane at constant X, Y or Z. "World coordinates" are coordinates space seen by TCastleTransform / TCastleScene inside viewport Items. This works with any projection (perspective or orthographic). You can use it to pick a point on any plane with constant X (PlaneConstCoord = 0), constant Y (PlaneConstCoord = 1), constant Z (PlaneConstCoord = 2). This intersects the ray cast by Camera with a plane where given coordinate (PlaneConstCoord) has value equal to PlaneConstValue. The parameter names and interpretation is consistent e.g. with TrySimplePlaneRayIntersection. The interpretation of Position depends on ContainerCoordinates:
Returns true and sets 3D PlanePosition (the PlaneConstCoord component of this vector must always be equal to PlaneConstValue) if such intersection is found. Returns false if it's not possible to determine such point (when the camera looks in the other direction). |
function PositionToWorldPlane(const Position: TVector2; const ContainerCoordinates: Boolean; const PlaneConstValue: Single; out PlanePosition: TVector3): Boolean; overload; deprecated 'use PositionToWorldPlane overload with PlaneConstCoord parameter; this version assumes PlaneConstCoord = 2'; |
|
Warning: this symbol is deprecated: use PositionToWorldPlane overload with PlaneConstCoord parameter; this version assumes PlaneConstCoord = 2 This item has no description. |
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:
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. |
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. |
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 = |
procedure PrepareResources(const DisplayProgressTitle: string; const Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; deprecated 'use overload without DisplayProgressTitle: String'; |
|
Warning: this symbol is deprecated: use overload without DisplayProgressTitle: String This item has no description. |
procedure PrepareResources(const Item: TCastleTransform; const DisplayProgressTitle: string; Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; deprecated 'use overload without DisplayProgressTitle: String'; |
|
Warning: this symbol is deprecated: use overload without DisplayProgressTitle: String This item has no description. |
procedure PrepareResources( 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). |
procedure PrepareResources(const Item: TCastleTransform; Options: TPrepareResourcesOptions = DefaultPrepareOptions); overload; virtual; |
|
This item has no description. |
function TransformUnderMouse: TCastleTransform; |
|
Current TCastleTransform pointed by the mouse cursor position. This is the first object being hit by the ray from camera through the mouse cursor position. Automatically updated to always reflect the current mouse position. May be The "mouse cursor position" on touch devices is just the last touch point. When the navigation uses mouse look (like TCastleWalkNavigation.MouseLook), we automatically use viewport center as the "mouse cursor position".
See also
|
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 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. |
function InternalBuildNode(const SaveBaseUrl: String): TX3DRootNode; |
|
Export whole viewport contents to a node. This is useful to save viewport contents to X3D, STL or other files that we can save. This tries to export as much as we can express using nodes, which includes everything in Items (transformations, scenes, lights and more) and optional things like TCastleNavigation types (fly, walk, examine...), current Background, current Fog. Why is this an internal method?
|
Properties
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. |
property BackgroundColor: TCastleColor
read FBackgroundColor write FBackgroundColor; |
|
Background color. Displayed only if Background is Ignored if Transparent. Dark gray (DefaultBackgroundColor) by default. |
property ScreenSpaceAmbientOcclusion: boolean
read FScreenSpaceAmbientOcclusion write SetScreenSpaceAmbientOcclusion
default DefaultScreenSpaceAmbientOcclusion; |
|
Enable built-in SSAO screen effect in the world. |
property ScreenSpaceReflections: Boolean
read FScreenSpaceReflections write SetScreenSpaceReflections
default DefaultScreenSpaceReflections; |
|
Enable built-in SSR screen effect in the world. |
property ScreenSpaceReflectionsSurfaceGlossiness: Single
read FScreenSpaceReflectionsSurfaceGlossiness write SetScreenSpaceReflectionsSurfaceGlossiness; |
|
Adjust SSR default surface glossiness. |
property OnCameraChanged: TNotifyEvent read FOnCameraChanged write FOnCameraChanged; |
|
Called on any camera change. |
property MouseRayHit: TRayCollision read GetMouseRayHit; |
|
Current components (TCastleTransform hierarchy) pointed by the mouse cursor position. This is the first object being hit by the ray from camera through the mouse cursor position. Automatically updated to always reflect the current mouse position. May be The "mouse cursor position" on touch devices is just the last touch point. When the navigation uses mouse look (like TCastleWalkNavigation.MouseLook), we automatically use viewport center as the "mouse cursor position". See also
|
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. |
property Paused: boolean read GetPaused write SetPaused default false; deprecated 'use Items.Paused'; |
|
Warning: this symbol is deprecated: use Items.Paused |
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 This item has no description. |
property Navigation: TCastleNavigation read GetNavigation write SetNavigation
stored false; deprecated 'instead of this property: to get, just remember current navigation instance on your side; to set, add it like "MyViewport.InsertBack(MyNavigation)"'; |
|
Warning: this symbol is deprecated: instead of this property: to get, just remember current navigation instance on your side; to set, add it 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 |
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 Note that assigning here |
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 For convenience, there are however some moments when we set up this property and add camera to Items automatically:
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. |
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 ( |
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. |
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 |
property Fog: TCastleFog read FFog write SetFog; |
|
|
property BackgroundWireframe: boolean
read FBackgroundWireframe write FBackgroundWireframe default false; |
|
If Ignored if Transparent. |
property Transparent: boolean read FTransparent write FTransparent default false; |
|
If If |
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 Note: to disable clearning the color buffer, set Transparent to Note: if you use shadow volumes, we will still clear the stencil buffer at the beginning of rendering. |
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. |
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. |
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 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. |
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. |
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 |
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 Also, only if this property is By default it is |
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 castle-model-viewer), 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 = |
property DynamicBatching: Boolean
read FDynamicBatching write SetDynamicBatching default false; |
|
Combine (right before rendering) multiple shapes with a similar appearance into one. This can drastically reduce the number of "draw calls", making rendering much faster. To debug effectiveness of this, display TCastleViewport.Statistics. In CGE editor (at design-time), use menu item "Edit -> Show Statistics" (F8). When dynamic batching works, the number of rendered shapes and the number of "Draw Calls" should be much smaller. |
property OcclusionCulling: boolean
read FOcclusionCulling write SetOcclusionCulling default false; |
|
Use the occlusion culling to optimize the rendering. The shapes obscured by other shapes will not be rendered. This makes sense when in your view, many shapes are typically obscured by others. See the https://castle-engine.io/occlusion_culling for details how does this work. To debug effectiveness of this, display TCastleViewport.Statistics. In CGE editor (at design-time), use menu item "Edit -> Show Statistics" (F8). If you look closely at a wall that obscures many shapes behind it, you should see the number of rendered shapes drop significantly using occlusion culling. This is ignored if GPU doesn't support the necessary functionality (TGLFeatures.OcclusionQuery). |
property OcclusionSort: TShapeSort
read FOcclusionSort write FOcclusionSort default sortAuto; |
|
Sort the opaque shapes when rendering, from front to back. This may make a speedup when big shapes in front of camera obscure many shapes behind. This is only an optimization: regardless of the value of this, rendering opaque objects will be always correct. Different values of this properly may merely increase / decrease rendering performance (frames per second). In general this is an independent optimization from OcclusionCulling, albeit it makes sense in similar situations. When combined with OcclusionCulling, it makes occlusion culling even more effective. Occlusion culling can reject more shapes, because the things that obscure them are rendered earlier to the depth buffer. See https://castle-engine.io/occlusion_culling#occlusion_sort for more details. The default value, sortAuto, for now is equivalent to sortNone. It may change in the future to perform sorting esp. when OcclusionCulling is |
property BlendingSort: TShapeSort
read FBlendingSort write FBlendingSort default sortAuto; |
|
Sort the blending (partially-transparent) shapes when rendering, from back to front. This makes blending correct when there are multiple partially-transparent objects visible. See blending manual. Invalid value of this may cause rendering artifacts when rendering multiple partially-transparent objects. The default value, sortAuto, automatically detects if camera is 2D (orthographic, looking in -Z) and if yes, it behaves like sort2D. Otherwise it behaves like sort3D. |
property OnCustomShapeSort: TShapeSortEvent
read FOnCustomShapeSort write FOnCustomShapeSort; |
|
Used to sort shapes, if TCastleViewport.BlendingSort or TCastleViewport.OcclusionSort indicate sortCustom. See TShapeSortEvent for usage details and example. |
property UpdateSoundListener: Boolean
read FUpdateSoundListener write FUpdateSoundListener default true; |
|
Should the sound listener (that determines how the sounds are heard) be updated to reflect this viewport's active camera. This is Active camera comes from |
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
|
Generated by PasDoc 0.16.0-snapshot.