Class TCamera

Unit

Declaration

type TCamera = class(TInputListener)

Description

Handle user navigation in 3D scene. You control camera parameters and provide user input to this class by various methods and properties. You can investigate the current camera configuration by many methods, the most final is the Matrix method that generates a simple 4x4 camera matrix.

This class is not tied to any OpenGL specifics, any VRML specifics, and CastleWindow etc. — this class is fully flexible and may be used in any 3D program, whether using CastleWindow, OpenGL etc. or not.

Various TCamera descendants implement various navigation methods, for example TExamineCamera allows the user to rotate and scale the model (imagine that you're holding a 3D model in your hands and you look at it from various sides) and TWalkCamera implements typical navigation in the style of first-person shooter games.

The most comfortable way to use a camera is with a scene manager (TCastleSceneManager). You can create your camera instance, call it's Init method (this is initializes most important properties), and assign it to TCastleSceneManager.Camera property. This way SceneManager will pass all necessary window events to the camera, and when drawing SceneManager will load camera matrix like glLoadMatrix(Camera.Matrix);. In fact, if you do not assign anything to TCastleSceneManager.Camera property, then the default camera will be created for you. So when using TCastleSceneManager, you do not have to do anything to use a camera — default camera will be created and automatically used for you.

Hierarchy

Overview

Fields

Protected MouseDraggingStarted: Integer;
Protected MouseDraggingStart: TVector2;
Public nested const DefaultRadius = 0.25;
Public nested const DefaultInput = [ciNormal, ciMouseDragging, ci3dMouse];
Public nested const DefaultHeadBobbingTime = 0.5;
Public nested const DefaultHeadBobbing = 0.02;
Public nested const DefaultCrouchHeight = 0.5;

Methods

Protected procedure BeginVisibleChangeSchedule;
Protected procedure ScheduleVisibleChange;
Protected procedure EndVisibleChangeSchedule;
Protected procedure SetInput(const Value: TCameraInputs); virtual;
Protected procedure SetEnableDragging(const Value: boolean); virtual;
Protected function GetIgnoreAllInputs: boolean;
Protected procedure SetIgnoreAllInputs(const Value: boolean);
Protected procedure SetProjectionMatrix(const Value: TMatrix4); virtual;
Protected procedure SetRadius(const Value: Single); virtual;
Protected function GetPositionInternal: TVector3; virtual; abstract;
Protected procedure SetPosition(const Value: TVector3); virtual; abstract;
Protected function ReallyEnableMouseDragging: boolean; virtual;
Public constructor Create(AOwner: TComponent); override;
Public procedure Assign(Source: TPersistent); override;
Public procedure VisibleChange(const RectOrCursorChanged: boolean = false); override;
Public function Matrix: TMatrix4; virtual; abstract;
Public function RotationMatrix: TMatrix4; virtual; abstract;
Public procedure GetView(out APos, ADir, AUp: TVector3); overload; virtual; abstract;
Public procedure GetView(out APos, ADir, AUp, AGravityUp: TVector3); overload;
Public procedure SetView(const APos, ADir, AUp: TVector3; const AdjustUp: boolean = true); overload; virtual; abstract;
Public procedure SetView(const APos, ADir, AUp, AGravityUp: TVector3; const AdjustUp: boolean = true); overload;
Public function GetPosition: TVector3; deprecated 'use Position property';
Public procedure Ray(const WindowPosition: TVector2; const Projection: TProjection; out RayOrigin, RayDirection: TVector3); deprecated 'use CustomRay with proper viewport sizes, or use higher-level utilities like SceneManager.MouseRayHit instead';
Public procedure MouseRay( const Projection: TProjection; out RayOrigin, RayDirection: TVector3); deprecated 'use CustomRay with proper viewport sizes, or use higher-level utilities like SceneManager.MouseRayHit instead';
Public procedure CustomRay( const Viewport: TRectangle; const WindowPosition: TVector2; const Projection: TProjection; out RayOrigin, RayDirection: TVector3);
Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
Public function Press(const Event: TInputPressRelease): boolean; override;
Public function Release(const Event: TInputPressRelease): boolean; override;
Public procedure AnimateTo(OtherCamera: TCamera; const Time: TFloatTime);
Public procedure AnimateTo(const Pos, Dir, Up: TVector3; const Time: TFloatTime);
Public function Animation: boolean; virtual;
Public procedure SetInitialView( const AInitialPosition: TVector3; AInitialDirection, AInitialUp: TVector3; const TransformCurrentCamera: boolean); virtual;
Public procedure GoToInitial; virtual;
Public function GetNavigationType: TNavigationType; virtual; abstract;
Public procedure CorrectPreferredHeight;

Properties

Public property IgnoreAllInputs: boolean read GetIgnoreAllInputs write SetIgnoreAllInputs default false; deprecated;
Public property Frustum: TFrustum read FFrustum;
Public property ProjectionMatrix: TMatrix4 read FProjectionMatrix write SetProjectionMatrix;
Public property Radius: Single read FRadius write SetRadius default DefaultRadius;
Public property Position: TVector3 read GetPositionInternal write SetPosition;
Public property GravityUp: TVector3 read FGravityUp write SetGravityUp;
Public property InitialPosition : TVector3 read FInitialPosition;
Public property InitialDirection: TVector3 read FInitialDirection;
Public property InitialUp : TVector3 read FInitialUp;
Public property EnableDragging: boolean read FEnableDragging write SetEnableDragging;
Public property PreferredHeight: Single read FPreferredHeight write FPreferredHeight default 0.0;
Public property CrouchHeight: Single read FCrouchHeight write FCrouchHeight default DefaultCrouchHeight;
Public property HeadBobbing: Single read FHeadBobbing write FHeadBobbing default DefaultHeadBobbing;
Public property HeadBobbingTime: Single read FHeadBobbingTime write FHeadBobbingTime default DefaultHeadBobbingTime;
Public property MoveHorizontalSpeed: Single read FMoveHorizontalSpeed write FMoveHorizontalSpeed default 1.0;
Public property MoveVerticalSpeed: Single read FMoveVerticalSpeed write FMoveVerticalSpeed default 1.0;
Public property MoveSpeed: Single read FMoveSpeed write FMoveSpeed default 1.0;
Public property ClimbHeight: Single read FClimbHeight write FClimbHeight;
Public property ModelBox: TBox3D read FModelBox write FModelBox;
Published property Input: TCameraInputs read FInput write SetInput default DefaultInput;

Description

Fields

Protected MouseDraggingStarted: Integer;

Needed for ciMouseDragging navigation. Checking MouseDraggingStarted means that we handle only dragging that was initialized on viewport (since the viewport passed events to camera). MouseDraggingStarted -1 means none, otherwise it's the finder index (to support multitouch).

Protected MouseDraggingStart: TVector2;
 
Public nested const DefaultRadius = 0.25;

Default value for TCamera.Radius. Matches the default VRML/X3D NavigationInfo.avatarSize[0].

Public nested const DefaultInput = [ciNormal, ciMouseDragging, ci3dMouse];
 
Public nested const DefaultHeadBobbingTime = 0.5;
 
Public nested const DefaultHeadBobbing = 0.02;
 
Public nested const DefaultCrouchHeight = 0.5;
 

Methods

Protected procedure BeginVisibleChangeSchedule;

Mechanism to schedule VisibleChange calls.

This mechanism allows to defer calling VisibleChange. Idea: BeginVisibleChangeSchedule increases internal VisibleChangeSchedule counter, EndVisibleChangeSchedule decreases it and calls actual VisibleChange if counter is zero and some ScheduleVisibleChange was called in between.

When ScheduleVisibleChange is called when counter is zero, VisibleChange is called immediately, so it's safe to always use ScheduleVisibleChange instead of direct VisibleChange in this class.

Protected procedure ScheduleVisibleChange;
 
Protected procedure EndVisibleChangeSchedule;
 
Protected procedure SetInput(const Value: TCameraInputs); virtual;
 
Protected procedure SetEnableDragging(const Value: boolean); virtual;
 
Protected function GetIgnoreAllInputs: boolean;
 
Protected procedure SetIgnoreAllInputs(const Value: boolean);
 
Protected procedure SetProjectionMatrix(const Value: TMatrix4); virtual;

Setter of the ProjectionMatrix property. TCamera descendants may override this. In normal circumstances, you should not call it anywhere (it's automatically called by the scene manager).

Protected procedure SetRadius(const Value: Single); virtual;
 
Protected function GetPositionInternal: TVector3; virtual; abstract;
 
Protected procedure SetPosition(const Value: TVector3); virtual; abstract;
 
Protected function ReallyEnableMouseDragging: boolean; virtual;
 
Public constructor Create(AOwner: TComponent); override;
 
Public procedure Assign(Source: TPersistent); override;
 
Public procedure VisibleChange(const RectOrCursorChanged: boolean = false); override;

Called always when some visible part of this control changes. In the simplest case, this is used by the controls manager to know when we need to redraw the control.

In case of the TCamera class, we assume that changes to the TCamera.Matrix, and other properties (for example even changes to TWalkCamera.MoveSpeed), are "visible", and they also result in this event.

Public function Matrix: TMatrix4; virtual; abstract;

Current camera matrix. You should multiply every 3D point of your scene by this matrix, which usually simply means that you should do glLoadMatrix or glMultMatrix of this matrix.

Public function RotationMatrix: TMatrix4; virtual; abstract;

Extract only rotation from your current camera Matrix. This is useful for rendering skybox in 3D programs (e.g. for VRML/X3D Background node) and generally to transform directions between world and camera space.

It's guaranteed that this is actually only 3x3 matrix, the 4th row and 4th column are all zero except the lowest right item which is 1.0.

Public procedure GetView(out APos, ADir, AUp: TVector3); overload; virtual; abstract;

Express current view as camera vectors: position, direction, up.

Returned Dir and Up must be orthogonal. Returned Dir and Up and GravityUp are already normalized.

Public procedure GetView(out APos, ADir, AUp, AGravityUp: TVector3); overload;
 
Public procedure SetView(const APos, ADir, AUp: TVector3; const AdjustUp: boolean = true); overload; virtual; abstract;

Set camera view from vectors: position, direction, up.

Direction, Up and GravityUp do not have to be normalized, we will normalize them internally if necessary. But make sure they are non-zero.

We will automatically fix Direction and Up to be orthogonal, if necessary: when AdjustUp = True (the default) we will adjust the up vector (preserving the given direction value), otherwise we will adjust the direction (preserving the given up value).

Public procedure SetView(const APos, ADir, AUp, AGravityUp: TVector3; const AdjustUp: boolean = true); overload;
 
Public function GetPosition: TVector3; deprecated 'use Position property';

Warning: this symbol is deprecated: use Position property

 
Public procedure Ray(const WindowPosition: TVector2; const Projection: TProjection; out RayOrigin, RayDirection: TVector3); deprecated 'use CustomRay with proper viewport sizes, or use higher-level utilities like SceneManager.MouseRayHit instead';

Warning: this symbol is deprecated: use CustomRay with proper viewport sizes, or use higher-level utilities like SceneManager.MouseRayHit instead

Calculate a 3D ray picked by the WindowX, WindowY position on the window. Uses current Container, which means that you have to add this camera to TCastleWindowCustom.Controls or TCastleControlCustom.Controls before using this method.

Projection (read-only here) describe your projection, required for calculating the ray properly. Resulting RayDirection is always normalized.

WindowPosition is given in the same style as TUIContainer.MousePosition: (0, 0) is bottom-left.

Public procedure MouseRay( const Projection: TProjection; out RayOrigin, RayDirection: TVector3); deprecated 'use CustomRay with proper viewport sizes, or use higher-level utilities like SceneManager.MouseRayHit instead';

Warning: this symbol is deprecated: use CustomRay with proper viewport sizes, or use higher-level utilities like SceneManager.MouseRayHit instead

Calculate a ray picked by current mouse position on the window. Uses current Container (both to get it's size and to get current mouse position), which means that you have to add this camera to TCastleWindowCustom.Controls or TCastleControlCustom.Controls before using this method.

See also
Ray
Calculate a 3D ray picked by the WindowX, WindowY position on the window.
CustomRay
Calculate a ray picked by WindowPosition position on the viewport, assuming current viewport dimensions are as given.
Public procedure CustomRay( const Viewport: TRectangle; const WindowPosition: TVector2; const Projection: TProjection; out RayOrigin, RayDirection: TVector3);

Calculate a ray picked by WindowPosition position on the viewport, assuming current viewport dimensions are as given. This doesn't look at our container sizes at all.

Projection (read-only here) describe projection, required for calculating the ray properly.

Resulting RayDirection is always normalized.

WindowPosition is given in the same style as TUIContainer.MousePosition: (0, 0) is bottom-left.

Public procedure Update(const SecondsPassed: Single; var HandleInput: boolean); override;
 
Public function Press(const Event: TInputPressRelease): boolean; override;
 
Public function Release(const Event: TInputPressRelease): boolean; override;
 
Public procedure AnimateTo(OtherCamera: TCamera; const Time: TFloatTime);

Animate a camera smoothly into another camera settings. This will gradually change our settings (only the most important settings, that determine actual camera view, i.e. Matrix result) into another camera.

Current OtherCamera settings will be internally copied during this call. So you can even free OtherCamera instance immediately after calling this.

When we're during camera animation, Update doesn't do other stuff (e.g. gravity for TWalkCamera doesn't work, rotating for TExamineCamera doesn't work). This also means that the key/mouse controls of the camera do not work. Instead, we remember the source and target position (at the time AnimateTo was called) of the camera, and smoothly interpolate camera parameters to match the target.

Once the animation stops, Update goes back to normal: gravity in TWalkCamera works again, rotating in TExamineCamera works again etc.

Calling AnimateTo while the previous animation didn't finish yet is OK. This simply cancels the previous animation, and starts the new animation from the current position.

Descendants implementors notes: In this class, almost everything is handled (through GetView / SetView). In descendants you have to only ignore key/mouse/Update events when IsAnimation is True. (Although each Update would override the view anyway, but for stability it's best to explicitly ignore them — you never know how often Update will be called.)

Public procedure AnimateTo(const Pos, Dir, Up: TVector3; const Time: TFloatTime);
 
Public function Animation: boolean; virtual;
 
Public procedure SetInitialView( const AInitialPosition: TVector3; AInitialDirection, AInitialUp: TVector3; const TransformCurrentCamera: boolean); virtual;

Set three initial camera vectors.

AInitialDirection and AInitialUp will be automatically normalized. Corresponding properties (InitialDirection and InitialUp) will always contain normalized values.

AInitialUp will be also automatically corrected to be orthogonal to AInitialDirection. We will correct AInitialUp to make it orthogonal, but still preserving the plane they were indicating together with AInitialDirection. Do not ever give here AInitialUp that is parallel to AInitialDirection.

If TransformCurrentCamera = True, then they will also try to change current camera relative to the initial vectors changes. This implements VRML/X3D desired behavior that "viewer position/orientation is conceptually a child of viewpoint position/orientation, and when viewpoint position/orientation changes, viewer should also change".

Public procedure GoToInitial; virtual;

Jump to initial camera view (set by SetInitialView).

Public function GetNavigationType: TNavigationType; virtual; abstract;
 
Public procedure CorrectPreferredHeight;

Correct PreferredHeight based on your Radius and on current HeadBobbing.

Exactly what and why is done: if you do any kind of collision detection with some Radius, then you should make sure that RealPreferredHeight is always >= of your Radius, otherwise strange effects may happen when crouching or when head bobbing forces camera to go down.

Exactly, the required equation is

MinimumRealPreferredHeight :=
  PreferredHeight * CrouchHeight * (1 - HeadBobbing);

and always must be

MinimumRealPreferredHeight >= RealPreferredHeight

Reasoning: otherwise this class would "want camera to fall down" (because we will always be higher than RealPreferredHeight) but your OnMoveAllowed would not allow it (because Radius would not allow it). Note that this class doesn't keep value of your Radius, because collision detection is (by design) never done by this class — it's always delegated to OnHeight and OnMoveAllowed. Also, it's not exactly forced how you should force this condition to hold. Sometimes the good solution is to adjust Radius, not to adjust PreferredHeight.

Anyway, this method will make sure that this condition holds by eventually adjusting (making larger) PreferredHeight. Note that for Radius = 0.0 this will always leave PreferredHeight as it is.

Properties

Public property IgnoreAllInputs: boolean read GetIgnoreAllInputs write SetIgnoreAllInputs default false; deprecated;

Warning: this symbol is deprecated.

Deprecated, use more flexible Input instead. IgnoreAllInputs := true is equivalent to Input := [], IgnoreAllInputs := false is equivalent to Input := DefaultInput.

Public property Frustum: TFrustum read FFrustum;

The current camera (viewing frustum, based on ProjectionMatrix (set by you) and Matrix (calculated here). This is recalculated whenever one of these two properties change. Be sure to set ProjectionMatrix before using this.

Public property ProjectionMatrix: TMatrix4 read FProjectionMatrix write SetProjectionMatrix;

Projection matrix of the camera. Camera needs to know this to calculate Frustum, which in turn allows rendering code to use frustum culling.

In normal circumstances, if you use our scene manager and viewport (TCastleAbstractViewport) for rendering, this is automatically correctly set for you.

Public property Radius: Single read FRadius write SetRadius default DefaultRadius;

The radius of a sphere around the camera that makes collisions with the world.

  • Collision detection routines use this.

  • It determines the projection near plane (that must be slightly smaller than this radius) for 3D rendering.

  • Walk camera uses this for automatically correcting PreferredHeight, otherwise weird things could happen if your avatar height is too small compared to camera radius. See CorrectPreferredHeight.

    Especially useful if you let user change PreferredHeight at runtime by Input_IncreasePreferredHeight, Input_DecreasePreferredHeight.

    This is actually the whole use of Radius inside CastleCameras unit and classes. But the code all around the engine also looks for this Radius, and the camera is a natural place to keep this information.

Public property Position: TVector3 read GetPositionInternal write SetPosition;
 
Public property GravityUp: TVector3 read FGravityUp write SetGravityUp;

"Up" direction of the world in which player moves. Always normalized (when setting this property, we take care to normalize the provided vector).

This determines in which direction TWalkCamera.Gravity works.

This is also the "normal" value for both TWalkCamera.Up and InitialUp — one that means that player is looking straight foward. This is used for features like PreferGravityUpForRotations and/or PreferGravityUpForMoving.

The default value of this vector is (0, 1, 0) (same as the default TWalkCamera.Up and InitialUp vectors).

Public property InitialPosition : TVector3 read FInitialPosition;

Initial camera values.

InitialDirection and InitialUp must be always normalized, and orthogonal.

Default value of InitialPosition is (0, 0, 0), InitialDirection is DefaultCameraDirection = (0, -1, 0), InitialUp is DefaultCameraUp = (0, 1, 0).

Public property InitialDirection: TVector3 read FInitialDirection;
 
Public property InitialUp : TVector3 read FInitialUp;
 
Public property EnableDragging: boolean read FEnableDragging write SetEnableDragging;

Is mouse dragging allowed by scene manager. This is an additional condition to enable mouse dragging, above the existing ciMouseDragging in Input. It is set internally by scene manager, to prevent camera navigation by dragging when we already drag a 3D item (like X3D TouchSensor).

Public property PreferredHeight: Single read FPreferredHeight write FPreferredHeight default 0.0;

Height above the ground, only used by TWalkCamera descendant when TWalkCamera.Gravity is True. The Position tries to stay PreferredHeight above the ground. Temporarily it may still be lower (e.g. player can shortly "duck" when he falls from high).

This must always be >= 0. You should set this to something greater than zero to get sensible behavior of some things related to TWalkCamera.Gravity, and also you should set OnHeight.

See CorrectPreferredHeight for important property of PreferredHeight that you should keep.

Public property CrouchHeight: Single read FCrouchHeight write FCrouchHeight default DefaultCrouchHeight;

Preferred height when crouching. This is always mutiplied to PreferredHeight. This should always be <= 1 (CrouchHeight = 1 effectively disables crouching, although it's better to do this by calling MakeClear on Input_Crouch).

Public property HeadBobbing: Single read FHeadBobbing write FHeadBobbing default DefaultHeadBobbing;

When TWalkCamera moves, it may make a "head bobbing" effect, by moving the camera a bit up and down.

This property mutiplied by PreferredHeight says how much head bobbing can move you along GravityUp. Set this to 0 to disable head bobbing. This must always be < 1.0. For sensible effects, this should be rather close to 0.0, for example 0.02.

This is meaningfull only when TWalkCamera.Gravity works.

Public property HeadBobbingTime: Single read FHeadBobbingTime write FHeadBobbingTime default DefaultHeadBobbingTime;

Controls head bobbing frequency. In the time of HeadBobbingTime seconds, we do full head bobbing sequence (camera swing up, then down again).

Note that if you do a footsteps sound in your game (see stPlayerFootstepsDefault or TMaterialProperty.FootstepsSound) then you will want this property to match your footsteps sound length, things feel and sound natural then. Also, often it sounds better to record two footsteps inside a single sound file, in which case the footstep sound length should be twice as long as this property. For example, record 2 steps inside a 1-second long footstep sound, and set this property to 0.5 a second (which is a default in fact).

Public property MoveHorizontalSpeed: Single read FMoveHorizontalSpeed write FMoveHorizontalSpeed default 1.0;

Moving speeds, only used by TWalkCamera descendant. MoveHorizontalSpeed is only for horizontal movement, MoveVerticalSpeed is only for vertical, and MoveSpeed simply affects both types of movement. Effectively, we always scale the speed of movement by either MoveHorizontalSpeed * MoveSpeed or MoveVerticalSpeed * MoveSpeed.

We move by distance MoveSpeed * MoveHorizontalSpeed (or MoveVerticalSpeed) during one second. So if you leave MoveHorizontalSpeed = MoveVerticalSpeed = 1 (as default), MoveSpeed expresses the speed in nice units / per second.

Default values for all these speed properties is 1.0, so you simply move by 1 unit per second.

Public property MoveVerticalSpeed: Single read FMoveVerticalSpeed write FMoveVerticalSpeed default 1.0;
 
Public property MoveSpeed: Single read FMoveSpeed write FMoveSpeed default 1.0;
 
Public property ClimbHeight: Single read FClimbHeight write FClimbHeight;

The tallest height that you can climb, only used by TWalkCamera descendant when TWalkCamera.Gravity is True. This is checked in each single horizontal move when TWalkCamera.Gravity works. Must be >= 0. Value 0 means there is no limit (and makes a small speedup).

This is reliable to prevent user from climbing stairs and such, when vertical walls are really vertical (not just steep-almost-vertical).

It's not 100% reliable to prevent player from climbing steep hills. That's because, depending on how often an event processing occurs, you actually climb using less or more steps. So even a very steep hill can be always climbed on a computer with very fast speed, because with large FPS you effectively climb it using a lot of very small steps (assuming that FPS limit is not enabled, that is CastleWindow.TCastleApplication.LimitFPS or CastleControl.LimitFPS is zero).

Remember that user can still try jumping to climb on high obstactes. See TWalkCamera.JumpMaxHeight for a way to control jumping.

For a 100% reliable way to prevent user from reaching some point, that does not rely on specific camera/gravity settings, you should build actual walls in 3D (invisible walls can be created by Collision.proxy in VRML/X3D).

Public property ModelBox: TBox3D read FModelBox write FModelBox;

Approximate size of 3D world that is viewed, used by TExamineCamera descendant. It is crucial to set this to make TExamineCamera behave OK.

Initially this is TBox3D.Empty.

Published property Input: TCameraInputs read FInput write SetInput default DefaultInput;

Input methods available to user. See documentation of TCameraInput type for possible values and their meaning.

To disable any user interaction with camera (for example, to implement X3D "NONE" navigation type) you can simply set this to empty.


Generated by PasDoc 0.15.0.