Castle Game Engine

Unit CastleCameras

Description
Uses
Classes, Interfaces, Objects and Records
Functions and Procedures
Types
Constants
Variables

Description

Camera and navigation (TCastleCamera, TCastleExamineNavigation, TCastleWalkNavigation).

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class EViewportNotAssigned  
Class TCastlePerspective Subcomponent used in TCastleCamera.Perspective to set perspective projection parameters.
Class TCastleOrthographic Subcomponent used in TCastleCamera.Orthographic to set orthographic projection parameters.
Class TCastleCamera Camera determines viewer position and orientation in a 3D or 2D world.
Class TCastleNavigation Handle user input to modify viewport's camera.
Class TCastleExamineNavigation Navigate the 3D model in examine mode, like you would hold a box with the model inside.
Class TCastleMouseLookNavigation Abstract navigation class that can utilize mouse look, during which mouse cursor is hidden and we look at MouseLookDelta every frame.
Class TCastleWalkNavigation Navigation by walking or flying (classic first-person shooter navigation) in a 3D scene.

Functions and Procedures

procedure CorrectPreferredHeight(var PreferredHeight: Single; const Radius: Single; const CrouchHeight, HeadBobbing: Single);
function OrientationFromDirectionUp(const Direction, Up: TVector3): TVector4;
procedure OrientationFromDirectionUp(const Direction, Up: TVector3; out Axis: TVector3; out Angle: Single);
function OrientationFromDirectionUp(const Direction, Up: TVector3; const DefaultDirection, DefaultUp: TVector3): TVector4;
function OrientationToDirection(const OrientationRotation: TVector4): TVector3;
function OrientationToUp(const OrientationRotation: TVector4): TVector3;
function CamDirUp2Orient(const Direction, Up: TVector3): TVector4; deprecated 'use OrientationFromDirectionUp';
procedure CamDirUp2Orient(const Direction, Up: TVector3; out Axis: TVector3; out Angle: Single); deprecated 'use OrientationFromDirectionUp';
function OrientationQuaternionFromDirectionUp(Direction, Up: TVector3; const DefaultDirection, DefaultUp: TVector3): TQuaternion;
function OrientationQuaternionFromDirectionUp(const Direction, Up: TVector3): TQuaternion;
function CamDirUp2OrientQuat(const Direction, Up: TVector3): TQuaternion; deprecated 'OrientationQuaternionFromDirectionUp';
procedure CameraViewpointForWholeScene(const Box: TBox3D; const WantedDirection, WantedUp: Integer; const WantedDirectionPositive, WantedUpPositive: boolean; out Position, Direction, Up, GravityUp: TVector3);
procedure CameraOrthoViewpointForWholeScene(const Box: TBox3D; const ViewportWidth, ViewportHeight: Single; const Origin: TVector2; out Position: TVector3; out AProjectionWidth, AProjectionHeight, AProjectionFar: Single);
procedure Register;

Types

TNavigationInput = (...);
TNavigationInputs = set of TNavigationInput;
TCameraInput = TNavigationInput deprecated 'use TNavigationInput';
TCameraInputs = TNavigationInputs deprecated 'use TNavigationInputs';
TNavigationType = (...);
TFieldOfViewAxis = (...);
TCameraClass = class of TCamera;
T3BoolInputs = array [0..2, boolean] of TInputShortcut;
TMoveAllowedFunc = function (const Sender: TCastleNavigation; const OldPos, ProposedNewPos: TVector3; out NewPos: TVector3; const Radius: Single; const BecauseOfGravity: Boolean): boolean of object;
TFallNotifyFunc = procedure (const Sender: TCastleNavigation; const FallHeight: Single) of object;
THeightEvent = function (const Sender: TCastleNavigation; const Position: TVector3; out AboveHeight: Single; out AboveGround: PTriangle): Boolean of object;
TMouseDragMode = (...);
TUniversalCamera = TCastleNavigation deprecated 'complicated TUniversalCamera class is removed; use TCastleNavigation as base class, or TCastleWalkNavigation or TCastleExamineNavigation for particular type, and Viewport.NavigationType to switch type';
TCamera = TCastleNavigation deprecated 'use TCastleNavigation';
TExamineCamera = TCastleExamineNavigation deprecated 'use TCastleExamineNavigation';
TWalkCamera = TCastleWalkNavigation deprecated 'use TCastleWalkNavigation';

Constants

DefaultCameraDirection: TVector3 = (Data: (0, 0, -1));
DefaultCameraUp: TVector3 = (Data: (0, 1, 0));
ciNormal = niNormal deprecated 'use niNormal';
ciMouseDragging = niMouseDragging deprecated 'use niMouseDragging';
ciGesture = niGesture deprecated 'use niGesture';
ci3dMouse = ni3dMouse deprecated 'use ni3dMouse';
RadiusToProjectionNear = 0.6;
WorldBoxSizeToProjectionFar = 20.0;
RadiusToPreferredHeightMin = 4.0;
WorldBoxSizeToRadius = 0.005;

Description

Functions and Procedures

procedure CorrectPreferredHeight(var PreferredHeight: Single; const Radius: Single; const CrouchHeight, HeadBobbing: Single);

See TCastleWalkNavigation.CorrectPreferredHeight. This is a global version, sometimes may be useful.

function OrientationFromDirectionUp(const Direction, Up: TVector3): TVector4;

Convert camera direction and up vectors into a rotation (X3D "orientation" vector).

Orientation vector expresses Direction and Up as a rotation. First three components of the resulting vector are the Axis (normalized) and the 4th component is the Angle (in radians). If you would rotate the standard direction and up (see DefaultCameraDirection, DefaultCameraUp) around Axis by the Angle, then you would get Direction and Up back.

There is an overloaded version where you can pass your custom DefaultDirection, DefaultUp to be used instead of default DefaultCameraDirection, DefaultCameraUp.

Given here Direction and Up must be orthogonal and non-zero. Their lengths are not relevant (that is, you don't need to normalize them before passing here).

procedure OrientationFromDirectionUp(const Direction, Up: TVector3; out Axis: TVector3; out Angle: Single);
 
function OrientationFromDirectionUp(const Direction, Up: TVector3; const DefaultDirection, DefaultUp: TVector3): TVector4;
 
function OrientationToDirection(const OrientationRotation: TVector4): TVector3;

Convert rotation (X3D orientation) to a direction vector, reversing the OrientationFromDirectionUp.

function OrientationToUp(const OrientationRotation: TVector4): TVector3;

Convert rotation (X3D orientation) to an up vector, reversing the OrientationFromDirectionUp.

function CamDirUp2Orient(const Direction, Up: TVector3): TVector4; deprecated 'use OrientationFromDirectionUp';

Warning: this symbol is deprecated: use OrientationFromDirectionUp

 
procedure CamDirUp2Orient(const Direction, Up: TVector3; out Axis: TVector3; out Angle: Single); deprecated 'use OrientationFromDirectionUp';

Warning: this symbol is deprecated: use OrientationFromDirectionUp

 
function OrientationQuaternionFromDirectionUp(Direction, Up: TVector3; const DefaultDirection, DefaultUp: TVector3): TQuaternion;

Convert camera direction and up vectors into a "rotation quaternion". Just like OrientationFromDirectionUp, but the result is a quaternion, not an axis-angle vector.

function OrientationQuaternionFromDirectionUp(const Direction, Up: TVector3): TQuaternion;
 
function CamDirUp2OrientQuat(const Direction, Up: TVector3): TQuaternion; deprecated 'OrientationQuaternionFromDirectionUp';

Warning: this symbol is deprecated: OrientationQuaternionFromDirectionUp

 
procedure CameraViewpointForWholeScene(const Box: TBox3D; const WantedDirection, WantedUp: Integer; const WantedDirectionPositive, WantedUpPositive: boolean; out Position, Direction, Up, GravityUp: TVector3);

Calculate sensible camera configuration to see the whole Box.

WantedDirection and WantedUp indicate desired look direction/up axis (0, 1 or 2 for X, Y or Z). WantedDirectionPositive and WantedUpPositive indicate if we want the positive axis. Obviously look direction and up cannot be parallel, so WantedDirection must be different than WantedUp.

Returned Direction, Up, GravityUp are normalized.

procedure CameraOrthoViewpointForWholeScene(const Box: TBox3D; const ViewportWidth, ViewportHeight: Single; const Origin: TVector2; out Position: TVector3; out AProjectionWidth, AProjectionHeight, AProjectionFar: Single);

Calculate suitable camera to see everything using an orthographic projection.

Assumes that the camera direction is -Z, and camera up is +Y. So the horizontal axis of the world is X, vertical axis is Y. These are default values of camera set by TCastleViewport.Setup2D.

The meaning of Origin is the same as TCastleOrthographic.Origin.

Returns new correct values of TCastleOrthographic.Width, TCastleOrthographic.Height, TCastleCamera.ProjectionFar and camera position (set it like Viewport.Camera.Position := NewPosition;).

procedure Register;
 

Types

TNavigationInput = (...);

Possible navigation input types for TCastleNavigation.Input.

Values
  • niNormal: Normal input types. This includes all inputs available as Input_Xxx properties in TCastleNavigation descendants. They are all fully configurable (as TInputShortcut class), they may be mouse button presses, mouse wheel clicks, or key presses. You can always clear some shortcut (like TCastleWalkNavigation.Input_Forward.MakeClear) to disable a specific shortcut. Excluding niNormal from TCastleNavigation.Input is an easy way to disable all shortcuts.
  • niMouseDragging: Mouse and touch dragging. Both TCastleExamineNavigation and TCastleWalkNavigation implement their own, special reactions to mouse dragging, that allows to navigate / rotate while pressing specific mouse buttons.

    Note that mouse dragging is automatically disabled when TCastleWalkNavigation.MouseLook is used.

  • niGesture: Touch gestures, like multi-touch pinch or pan gesture.
  • ni3dMouse: Navigation using 3D mouse devices, like the ones from 3dconnexion.
TNavigationInputs = set of TNavigationInput;
 
TCameraInput = TNavigationInput deprecated 'use TNavigationInput';

Warning: this symbol is deprecated: use TNavigationInput

 
TCameraInputs = TNavigationInputs deprecated 'use TNavigationInputs';

Warning: this symbol is deprecated: use TNavigationInputs

 
TNavigationType = (...);

Navigation type that determines various navigation properties, used by TCastleViewport.NavigationType.

Values
TFieldOfViewAxis = (...);

Value of TCastlePerspective.FieldOfViewAxis.

Values
  • faSmallest: TCastlePerspective.FieldOfView specifies the angle along the smaller viewport axis.

    E.g. on a full-screen viewport, on a typical desktop screen, with a typical panoramic window (wide, not tall), this will determine the vertical axis angle. The horizontal axis will be adjusted following the aspect ratio.

  • faLargest: TCastlePerspective.FieldOfView specifies the angle along the larger viewport axis. The other axis will be adjusted, following the aspect ratio.
  • faHorizontal: TCastlePerspective.FieldOfView specifies the angle along the horizontal axis. The vertical axis will be adjusted, following the aspect ratio.
  • faVertical: TCastlePerspective.FieldOfView specifies the angle along the vertical axis. The horizontal axis will be adjusted, following the aspect ratio.
TCameraClass = class of TCamera;
 
T3BoolInputs = array [0..2, boolean] of TInputShortcut;
 
TMoveAllowedFunc = function (const Sender: TCastleNavigation; const OldPos, ProposedNewPos: TVector3; out NewPos: TVector3; const Radius: Single; const BecauseOfGravity: Boolean): boolean of object;

See TCastleNavigation.MoveAllowed and TCastleNavigation.OnMoveAllowed

TFallNotifyFunc = procedure (const Sender: TCastleNavigation; const FallHeight: Single) of object;

See TCastleNavigation.OnFall.

THeightEvent = function (const Sender: TCastleNavigation; const Position: TVector3; out AboveHeight: Single; out AboveGround: PTriangle): Boolean of object;

See TCastleNavigation.OnInternalHeight.

TMouseDragMode = (...);

What mouse dragging does in TCastleWalkNavigation.

Values
  • mdWalk: Moves avatar continuously in the direction of mouse drag (default for TCastleWalkNavigation.MouseDragMode).
  • mdRotate: Rotates the head when mouse is moved.
  • mdNone: Ignores the dragging.
TUniversalCamera = TCastleNavigation deprecated 'complicated TUniversalCamera class is removed; use TCastleNavigation as base class, or TCastleWalkNavigation or TCastleExamineNavigation for particular type, and Viewport.NavigationType to switch type';

Warning: this symbol is deprecated: complicated TUniversalCamera class is removed; use TCastleNavigation as base class, or TCastleWalkNavigation or TCastleExamineNavigation for particular type, and Viewport.NavigationType to switch type

 
TCamera = TCastleNavigation deprecated 'use TCastleNavigation';

Warning: this symbol is deprecated: use TCastleNavigation

 
TExamineCamera = TCastleExamineNavigation deprecated 'use TCastleExamineNavigation';

Warning: this symbol is deprecated: use TCastleExamineNavigation

 
TWalkCamera = TCastleWalkNavigation deprecated 'use TCastleWalkNavigation';

Warning: this symbol is deprecated: use TCastleWalkNavigation

 

Constants

DefaultCameraDirection: TVector3 = (Data: (0, 0, -1));

Default camera direction and up vectors, used to define the meaning of "camera orientation" for OrientationFromDirectionUp, OrientationToDirection, OrientationToUp. These match X3D default camera values.

DefaultCameraUp: TVector3 = (Data: (0, 1, 0));
 
ciNormal = niNormal deprecated 'use niNormal';

Warning: this symbol is deprecated: use niNormal

 
ciMouseDragging = niMouseDragging deprecated 'use niMouseDragging';

Warning: this symbol is deprecated: use niMouseDragging

 
ciGesture = niGesture deprecated 'use niGesture';

Warning: this symbol is deprecated: use niGesture

 
ci3dMouse = ni3dMouse deprecated 'use ni3dMouse';

Warning: this symbol is deprecated: use ni3dMouse

 
RadiusToProjectionNear = 0.6;

Following X3D spec of NavigationType: "It is recommended that the near clipping plane be set to one-half of the collision radius as specified in the avatarSize field."

WorldBoxSizeToProjectionFar = 20.0;

Used when it is necessary to calculate projection far based on world size.

RadiusToPreferredHeightMin = 4.0;

Multiply radius by this to get sensible "preferred height".

We need to make "preferred height" much larger than Radius * 2, to allow some space to decrease (e.g. by Input_DecreasePreferredHeight). Remember that CorrectPreferredHeight adds a limit to PreferredHeight, around Radius * 2.

This determines minimal PreferredHeight, it should be used always like Max(DefaultPreferredHeight, Radius * RadiusToPreferredHeightMin) This way, in case of models that are small, but still follow the standard "1 unit = 1 meter", the PreferredHeight will not get weirdly small, it will be DefaultPreferredHeight. Testcase: examples/third_person_camera/data/level/level-dungeon.gltf open with view3dscene.

WorldBoxSizeToRadius = 0.005;

Multiply world bounding box AverageSize by this to get sensible radius.

Generated by PasDoc 0.16.0.