Castle Game Engine

Class TCastleCamera

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleTransform

Declaration

type TCastleCamera = class(TCastleTransform)

Description

Camera determines viewer position and orientation in the viewport.

You can create instances of this class yourself, and add them to TCastleViewport.Items, and set them as TCastleViewport.Camera.

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;
Public InternalOnCameraChanged: TNotifyEvent;

Methods

Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure Assign(Source: TPersistent); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;
Public procedure LocalRender(const Params: TRenderParams); override;
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
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); overload;
Public procedure AnimateTo(const APos, ADir, AUp: TVector3; const Time: TFloatTime); overload;
Public function Animation: boolean;
Public procedure Init(const AInitialPosition, AInitialDirection, AInitialUp, AGravityUp: TVector3); deprecated 'use SetWorldView, set GravityUp directly';
Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;
Public function EffectiveProjectionNear: Single;
Public function EffectiveProjectionFar: Single;
Public procedure VisibleChangeHere(const Changes: TVisibleChanges); override;

Properties

Public property GravityUp: TVector3 read FGravityUp write SetGravityUp;
Public property Frustum: TFrustum read FFrustum;
Public property ProjectionMatrix: TMatrix4 read FProjectionMatrix write SetProjectionMatrix;
Public property Orientation default TCastleTransform.DefaultCameraOrientation;
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 GravityUpPersistent: TCastleVector3Persistent read FGravityUpPersistent ;

Description

Fields

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

Methods

Public constructor Create(AOwner: TComponent); override;
 
Public destructor Destroy; override;
 
Public procedure Assign(Source: TPersistent); override;
 
Public function PropertySections(const PropertyName: String): TPropertySections; override;
 
Public procedure LocalRender(const Params: TRenderParams); override;
 
Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); override;
 
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 TCastleContainer.MousePosition: (0, 0) is bottom-left.

Public procedure AnimateTo(const OtherCamera: TCastleCamera; const Time: TFloatTime); overload;

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); overload;
 
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 Init(const AInitialPosition, AInitialDirection, AInitialUp, AGravityUp: TVector3); deprecated 'use SetWorldView, set GravityUp directly';

Warning: this symbol is deprecated: use SetWorldView, set GravityUp directly

 
Public procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); override;
 
Public function EffectiveProjectionNear: Single;

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

Public function EffectiveProjectionFar: Single;

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

Public procedure VisibleChangeHere(const Changes: TVisibleChanges); override;
 

Properties

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 "up" vector in world coordinates. Navigation uses it, e.g. features like PreferGravityUpForRotations and/or PreferGravityUpForMoving.

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

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 Orientation default TCastleTransform.DefaultCameraOrientation;
 
Published property ProjectionNear: Single read FProjectionNear write SetProjectionNear default 0;

Projection near plane distance.

0 (default) means to automatically calculate a correct value. Note that automatic calculation differs between perspective projection (uses DefaultCameraRadius, RadiusToProjectionNear for near, and infinity for far) and orthographic projection (adjusts to scene sizes and distance from camera).

For perspective projection, values <= 0 are invalid. So both value = 0 and value < 0 behave the same: they indicate we should automatically calculate the effective ProjectionNear.

For orthographic projection, all values are valid and reasonable. So value < 0 is just used literally, it doesn't cause the effective value to be autocalculated.

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

Projection far plane distance.

0 (default) means to automatically calculate a correct value. Note that automatic calculation differs between perspective projection (uses DefaultCameraRadius, RadiusToProjectionNear for near, and infinity for far) and orthographic projection (adjusts to scene sizes and distance from camera).

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