Unit CastleCameras

Description

Cameras to navigate in 3D space (TExamineCamera, TWalkCamera).

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class TCamera Handle user navigation in 3D scene.
Class TExamineCamera Navigate the 3D model in examine mode, like you would hold a box with the model inside.
Class TWalkCamera Navigation by walking (first-person-shooter-like moving) in 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 Register;

Types

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

Constants

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

Description

Functions and Procedures

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

See TWalkCamera.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 Register;
 

Types

TCameraInput = (...);

Possible navigation input types in cameras, set in TCamera.Input.

Values
  • ciNormal: Normal input types. This includes all inputs available as Input_Xxx properties in TCamera 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 WalkCamera.Input_Forward.MakeClear) to disable a specific shortcut. Excluding ciNormal from TCamera.Input is an easy way to disable all shortcuts.
  • ciMouseDragging: Mouse and touch dragging. Both TExamineCamera and TWalkCamera 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 TWalkCamera.MouseLook is used.

  • ci3dMouse: Navigation using 3D mouse devices, like the ones from 3dconnexion.
TCameraInputs = set of TCameraInput;
 
TNavigationType = (...);

Navigation type that determines various camera properties, used by TCastleAbstractViewport.NavigationType.

Values
  • ntExamine: Examine mode, comfortable to rotate the scene like an item held in your hand. Uses TExamineCamera.
  • ntTurntable: Turntable mode, similar to examine mode, but with a bit different interpretation of moves. Uses TExamineCamera.
  • ntWalk: Walk mode, comfortable to walk around the scene with gravity. Uses TWalkCamera.
  • ntFly: Fly mode, comfortable to move around around the scene without gravity. Uses TWalkCamera.
  • ntNone: Disable user navigation on the scene. Uses TWalkCamera.
TCameraClass = class of TCamera;
 
T3BoolInputs = array [0..2, boolean] of TInputShortcut;
 
TMouseDragMode = (...);

What mouse dragging does in TWalkCamera.

Values
  • mdWalk: Moves avatar continously in the direction of mouse drag (default for TWalkCamera.MouseDragMode).
  • mdRotate: Rotates the head when mouse is moved.
  • mdNone: Ignores the dragging.
TMoveAllowedFunc = function(Camera: TWalkCamera; const ProposedNewPos: TVector3; out NewPos: TVector3; const BecauseOfGravity: boolean): boolean of object;

See TWalkCamera.DoMoveAllowed and TWalkCamera.OnMoveAllowed

TFallNotifyFunc = procedure (Camera: TWalkCamera; const FallHeight: Single) of object;

See TWalkCamera.OnFall.

THeightEvent = function (Camera: TWalkCamera; const Position: TVector3; out AboveHeight: Single; out AboveGround: PTriangle): boolean of object;
 
TUniversalCamera = TCamera deprecated 'complicated TUniversalCamera class is removed; use TCamera as base class, or TWalkCamera or TExamineCamera for particular type, and SceneManager.NavigationType to switch type';

Warning: this symbol is deprecated: complicated TUniversalCamera class is removed; use TCamera as base class, or TWalkCamera or TExamineCamera for particular type, and SceneManager.NavigationType to switch type

 

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));
 

Generated by PasDoc 0.15.0.