Class TCastleCamera

Unit

Declaration

type TCastleCamera = class(TCastleComponent)

Description

Camera determines viewer position and orientation in a 3D or 2D world.

An instance of this class is automatically available in TCastleViewport.Camera. Do not instantiate this class yourself.

Note that this class does not handle any user input to modify the camera. For this, see TCastleNavigation descendants.

Hierarchy

Overview

Fields

Public InternalOnSceneBoundViewpointChanged: TNotifyEvent;
Public InternalOnSceneBoundViewpointVectorsChanged: TNotifyEvent;
Public InternalOnSceneBoundNavigationInfoChanged: TNotifyEvent;

Methods

Protected procedure Loaded; override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Assign(Source: TPersistent); override;
Public procedure GetView(out APos, ADir, AUp: TVector3); overload;
Public procedure GetView(out APos, ADir, AUp, AGravityUp: TVector3); overload;
Public procedure SetView(const ADir, AUp: TVector3; const AdjustUp: boolean = true);
Public procedure SetView(const APos, ADir, AUp: TVector3; const AdjustUp: boolean = true); overload;
Public procedure SetView(const APos, ADir, AUp, AGravityUp: TVector3; const AdjustUp: boolean = true); overload;
Public procedure UpPrefer(const AUp: TVector3);
Public function Matrix: TMatrix4;
Public function MatrixInverse: TMatrix4;
Public function RotationMatrix: TMatrix4;
Public procedure CustomRay( const ViewportRect: TFloatRectangle; const WindowPosition: TVector2; const Projection: TProjection; out RayOrigin, RayDirection: TVector3);
Public procedure AnimateTo(const OtherCamera: TCastleCamera; const Time: TFloatTime);
Public procedure AnimateTo(const APos, ADir, AUp: TVector3; const Time: TFloatTime);
Public function Animation: boolean;
Public procedure SetInitialView( const AInitialPosition: TVector3; AInitialDirection, AInitialUp: TVector3; const TransformCurrentCamera: boolean);
Public procedure GoToInitial;
Public procedure Init(const AInitialPosition, AInitialDirection, AInitialUp, AGravityUp: TVector3);
Public procedure Free; deprecated 'do not Free camera instance explicitly, only the TCastleViewport should create and destroy TCastleViewport.Camera; this method does nothing now';

Properties

Public property Position : TVector3 read FPosition write SetPosition;
Public property Direction: TVector3 read FDirection write SetDirection;
Public property Up : TVector3 read FUp write SetUp;
Public property GravityUp: TVector3 read FGravityUp write SetGravityUp;
Public property Frustum: TFrustum read FFrustum;
Public property ProjectionMatrix: TMatrix4 read FProjectionMatrix write SetProjectionMatrix;
Public property InitialPosition : TVector3 read FInitialPosition write SetInitialPosition;
Public property InitialDirection: TVector3 read FInitialDirection write SetInitialDirection;
Public property InitialUp : TVector3 read FInitialUp write SetInitialUp;
Public property EffectiveProjectionNear: Single read FEffectiveProjectionNear;
Public property EffectiveProjectionFar: Single read FEffectiveProjectionFar;
Published property ProjectionNear: Single read FProjectionNear write SetProjectionNear default 0;
Published property ProjectionFar: Single read FProjectionFar write SetProjectionFar default 0;
Published property ProjectionType: TProjectionType read FProjectionType write SetProjectionType default ptPerspective;
Published property Perspective: TCastlePerspective read FPerspective;
Published property Orthographic: TCastleOrthographic read FOrthographic;
Published property InitialPositionPersistent: TCastleVector3Persistent read FInitialPositionPersistent ;
Published property InitialDirectionPersistent: TCastleVector3Persistent read FInitialDirectionPersistent ;
Published property InitialUpPersistent: TCastleVector3Persistent read FInitialUpPersistent ;
Published property GravityUpPersistent: TCastleVector3Persistent read FGravityUpPersistent ;

Description

Fields

Public InternalOnSceneBoundViewpointChanged: TNotifyEvent;
 
Public InternalOnSceneBoundViewpointVectorsChanged: TNotifyEvent;
 
Public InternalOnSceneBoundNavigationInfoChanged: TNotifyEvent;
 

Methods

Protected procedure Loaded; override;
 
Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Assign(Source: TPersistent); override;
 
Public procedure GetView(out APos, ADir, AUp: TVector3); overload;

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 ADir, AUp: TVector3; const AdjustUp: boolean = true);

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: TVector3; const AdjustUp: boolean = true); overload;
 
Public procedure SetView(const APos, ADir, AUp, AGravityUp: TVector3; const AdjustUp: boolean = true); overload;
 
Public procedure UpPrefer(const AUp: TVector3);

Change up vector, keeping the direction unchanged. If necessary, the up vector provided here will be fixed to be orthogonal to direction. See TCastleTransform.UpPrefer for detailed documentation what this does.

Public function Matrix: TMatrix4;

Camera matrix, transforming from world space into camera space.

Public function MatrixInverse: TMatrix4;

Inverse of Matrix, transforming from camera space into world space.

Public function RotationMatrix: TMatrix4;

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 CustomRay( const ViewportRect: TFloatRectangle; 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 AnimateTo(const OtherCamera: TCastleCamera; 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.

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.

Public procedure AnimateTo(const APos, ADir, AUp: TVector3; const Time: TFloatTime);
 
Public function Animation: boolean;

Are we currently during animation (caused by AnimateTo).

TCastleNavigation descendants may use it to abort normal input handling. E.g. when camera is animating, then the gravity in TCastleWalkNavigation should not work, key/mouse handling in TCastleWalkNavigation shoult not work etc.

Public procedure SetInitialView( const AInitialPosition: TVector3; AInitialDirection, AInitialUp: TVector3; const TransformCurrentCamera: boolean);

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;

Jump to initial camera view (set by SetInitialView).

Public procedure Init(const AInitialPosition, AInitialDirection, AInitialUp, AGravityUp: TVector3);

Set the initial camera vectors (InitialPosition, InitialDirection...), and set current camera vectors (Position, Direction...) to the same values.

Given here AInitialDirection, AInitialUp, AGravityUp will be normalized, and AInitialUp will be adjusted to be orthogonal to AInitialDirection (see SetInitialView).

Public procedure Free; deprecated 'do not Free camera instance explicitly, only the TCastleViewport should create and destroy TCastleViewport.Camera; this method does nothing now';

Warning: this symbol is deprecated: do not Free camera instance explicitly, only the TCastleViewport should create and destroy TCastleViewport.Camera; this method does nothing now

 

Properties

Public property Position : TVector3 read FPosition write SetPosition;

Camera position, looking direction and up vector.

Call GoToInitial to set the current vectors to initial vectors, making them equal to InitialPosition, InitialDirection, InitialUp. You can also use Init method on some navigation descendants like TCastleExamineNavigation.Init and TCastleWalkNavigation.Init.

The Direction and Up vectors should always be normalized (have length 1). When setting them by these properties, we will normalize them automatically, so their given length is actually ignored.

When setting Direction, Up will always be automatically adjusted to be orthogonal to Direction. And vice versa — when setting Up, Direction will be adjusted.

Public property Direction: TVector3 read FDirection write SetDirection;
 
Public property Up : TVector3 read FUp write SetUp;
 
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 TCastleWalkNavigation.Gravity works.

This is also the "normal" value for both 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 Up and InitialUp vectors).

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 TCastleViewport for rendering, this is automatically correctly set for you.

Public property InitialPosition : TVector3 read FInitialPosition write SetInitialPosition;

Initial camera values. Can be set by SetInitialView. Camera vectors are reset to these values by GoToInitial. You can also use Init method on some navigation descendants like TCastleExamineNavigation.Init and TCastleWalkNavigation.Init to set initial vectors and current vectors at the same time.

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 write SetInitialDirection;
 
Public property InitialUp : TVector3 read FInitialUp write SetInitialUp;
 
Public property EffectiveProjectionNear: Single read FEffectiveProjectionNear;

Currently used projection near. Derived from ProjectionNear and possibly scene sizes.

Public property EffectiveProjectionFar: Single read FEffectiveProjectionFar;

Currently used projection far. Derived from ProjectionFar and possibly scene sizes. May be equal ZFarInfinity.

Published property ProjectionNear: Single read FProjectionNear write SetProjectionNear default 0;

Projection near plane distance.

For perspective projection, values <= 0 are invalid, and imply that a suitable value should actually be automatically calculated (looking at the world size).

For orthographic projection, all values are valid and reasonable, including 0 and < 0 values.

Published property ProjectionFar: Single read FProjectionFar write SetProjectionFar default 0;

Projection far plane distance. Use 0 to auto-calculate this each frame, based on world bounding box. If shadow volumes are used, this may be overridden to be infinite.

Published property ProjectionType: TProjectionType read FProjectionType write SetProjectionType default ptPerspective;

Perspective or orthographic projection. Depending on it, we either use Perspective or Orthographic settings.

Published property Perspective: TCastlePerspective read FPerspective;

Perspective projection properties, used only if ProjectionType is ptPerspective.

Published property Orthographic: TCastleOrthographic read FOrthographic;

Orthographic projection properties, used only if ProjectionType is ptOrthographic.

Published property InitialPositionPersistent: TCastleVector3Persistent read FInitialPositionPersistent ;

InitialPosition 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 InitialPosition directly.

See also
InitialPosition
Initial camera values.
Published property InitialDirectionPersistent: TCastleVector3Persistent read FInitialDirectionPersistent ;

InitialDirection 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 InitialDirection directly.

See also
InitialDirection
Published property InitialUpPersistent: TCastleVector3Persistent read FInitialUpPersistent ;

InitialUp 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 InitialUp directly.

See also
InitialUp
Published property GravityUpPersistent: TCastleVector3Persistent read FGravityUpPersistent ;

GravityUp 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 GravityUp directly.

See also
GravityUp
"Up" direction of the world in which player moves.

Generated by PasDoc 0.15.0.