Unit CastleTransform

Description

Group and transform scenes (TCastleTransform).

Uses

Overview

Classes, Interfaces, Objects and Records

Name Description
Class ECannotAddToAnotherWorld  
Class ETransformParentUndefined  
Class EMultipleReferencesInWorld  
Class ENotAddedToWorld  
Class EPhysicsError  
Class TBaseShadowVolumeRenderer Shadow volumes helper, not depending on OpenGL.
Record TRayCollisionNode Information about ray collision with a single 3D object.
Class TRayCollision Represents a ray collision with a 3D objects tree.
Record TCollisionDetailsItem Detailed information about collision with a single 3D object.
Class TCollisionDetails Represents a collision with a 3D objects tree.
Record TRenderStatistics Statistics about what was rendered during last frame.
Class TRenderParams Information that a TCastleTransform object needs to render.
Class TPrepareParams Information that a TCastleTransform object needs to prepare rendering.
Class TCastleBehavior Behaviors can be attached to TCastleTransform to perform specific logic, for example implement creature movement.
Class TCastleTransformList List of TCastleTransform instances.
Class TCastleTransform Group and transform (move, rotate, scale) children objects.
Class TCastleAbstractRootTransform Root of transformations and scenes (tree of TCastleTransform and TCastleScene).
Class TCastleTransformDesign Contents are loaded from an indicated castle-transform file (by the URL property).
Class TCastleTransformReference Reference another TCastleTransform instance, to render one TCastleTransform multiple times within the same viewport.
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 the viewport.
Record TPhysicsCollisionDetails Information send along with TCollisionEvent event, like TRigidBody.OnCollisionEnter, TRigidBody.OnCollisionExit.
Class TPhysicsProperties Configure physics simulation calculation.
Class TCollider Shape used for collision detection of a rigid body TRigidBody.
Class TPlaneCollider Collide as an infinite plane.
Class TBoxCollider Collide as a box.
Class TSphereCollider Collide as a sphere.
Class TCapsuleCollider Collide as a capsule.
Class TRigidBody Rigid body properties for the physics engine, see TCastleTransform.RigidBody.

Functions and Procedures

procedure TransformSave(const T: TCastleTransform; const Url: String);
function TransformLoad(const Url: String; const Owner: TComponent): TCastleTransform;
procedure TransformMatricesMult(var Transform, InverseTransform: TMatrix4; const Center: TVector3; const Rotation: TVector4; const Scale: TVector3; const ScaleOrientation: TVector4; const Translation: TVector3); deprecated 'use TTransformation.Multiply';
function StrToOrientationType(const S: String): TOrientationType;
function OrientationFromDirectionUp(const Direction, Up: TVector3): TVector4; overload;
procedure OrientationFromDirectionUp(const Direction, Up: TVector3; out Axis: TVector3; out Angle: Single); overload;
function OrientationFromDirectionUp(const Direction, Up: TVector3; const DefaultDirection, DefaultUp: TVector3): TVector4; overload;
function OrientationToDirection(const OrientationRotation: TVector4): TVector3;
function OrientationToUp(const OrientationRotation: TVector4): TVector3;
function CamDirUp2Orient(const Direction, Up: TVector3): TVector4; overload; deprecated 'use OrientationFromDirectionUp';
procedure CamDirUp2Orient(const Direction, Up: TVector3; out Axis: TVector3; out Angle: Single); overload; deprecated 'use OrientationFromDirectionUp';
function OrientationQuaternionFromDirectionUp(Direction, Up: TVector3; const DefaultDirection, DefaultUp: TVector3): TQuaternion; overload;
function OrientationQuaternionFromDirectionUp(const Direction, Up: TVector3): TQuaternion; overload;
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);

Types

TCastleTransformClass = class of TCastleTransform;
TRenderFromViewFunction = procedure (const RenderingCamera: TRenderingCamera) of object;
TVisibleChange = (...);
TVisibleChanges = set of TVisibleChange;
TVisibleChangeEvent = procedure (const Sender: TCastleTransform; const Changes: TVisibleChanges) of object;
TPrepareResourcesOption = (...);
TPrepareResourcesOptions = set of TPrepareResourcesOption;
PRayCollisionNode = ˆTRayCollisionNode;
PCollisionDetailsItem = ˆTCollisionDetailsItem;
TRemoveType = (...);
TOrientationType = (...);
TUserRenderingPass = 0..2;
TCastleBehaviorClass = class of TCastleBehavior;
TFieldOfViewAxis = (...);
T3DCoord = 0..2;
T3DCoords = set of T3DCoord;
TCollisionEvent = procedure (const CollisionDetails: TPhysicsCollisionDetails) of object;
TOnCollision = TCollisionEvent deprecated 'use TCollisionEvent';
TRigidBodyList = specialize TList<TRigidBody>;
TSceneManagerWorld = TCastleAbstractRootTransform deprecated 'use TCastleRootTransform';

Constants

rfOffScreen = rfRenderedTexture deprecated 'use rfRenderedTexture';
DefaultCameraDirection: TVector3 = (X: 0; Y: 0; Z: -1);
DefaultCameraUp : TVector3 = (X: 0; Y: 1; Z: 0);
Default2DProjectionFar = 1000.0 deprecated 'this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display';
Default2DProjectionNear = - 1000.0 deprecated 'this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display';
Default2DCameraZ = 1000.0 / 2;
RadiusToProjectionNear = 0.6;
DefaultCameraRadius = 0.1;
RadiusToPreferredHeightMin = 4.0;

Variables

InternalGizmoBoundingBox: Cardinal;

Description

Functions and Procedures

procedure TransformSave(const T: TCastleTransform; const Url: String);

Save / load TCastleTransform (or descendant) to a .castle-transform file.

An example:

{ TransformSave and TransformLoad example. }
uses SysUtils, Classes,
  CastleLog, CastleVectors, CastleTransform, CastleScene, CastleComponentSerialize;
var
  Scene: TCastleScene;
  Transform: TCastleTransform;
  TransformOwner: TComponent;
begin
  InitializeLog;

  { Create TCastleTransform instance, with a TCastleScene child. }
  Scene := TCastleScene.Create(nil);
  Scene.Name := 'MyScene'; // will enable to find it later with FindRequiredComponent
  Scene.Load('castle-data:/teapot.x3dv');
  Transform := TCastleTransform.Create(nil);
  Transform.Translation := Vector3(1, 2, 3);
  Transform.Add(Scene);

  { Save it to file. }
  TransformSave(Transform, 'aaa.castle-transform');

  { You can destroy the instances now. }
  FreeAndNil(Scene);
  FreeAndNil(Transform);

  { Create a component that will own all loaded instances,
    allowing to easily free them,
    and to use FindRequiredComponent. }
  TransformOwner := TComponent.Create(nil);

  { Now you can load them from file, and check that they are equal. }
  Transform := TransformLoad('aaa.castle-transform', TransformOwner);
  WritelnLog('Loaded transform, with translation %s, with %d children', [
    Transform.ToString,
    Transform.Count
  ]);
  Scene := TransformOwner.FindRequiredComponent('MyScene') as TCastleScene;
  WritelnLog('Found scene in loaded transform, with url %s', [
    Scene.Url
  ]);

  { Free loaded stuff. }
  FreeAndNil(TransformOwner);
end.

function TransformLoad(const Url: String; const Owner: TComponent): TCastleTransform;

This item has no description.

procedure TransformMatricesMult(var Transform, InverseTransform: TMatrix4; const Center: TVector3; const Rotation: TVector4; const Scale: TVector3; const ScaleOrientation: TVector4; const Translation: TVector3); deprecated 'use TTransformation.Multiply';

Warning: this symbol is deprecated: use TTransformation.Multiply

This item has no description.

function StrToOrientationType(const S: String): TOrientationType;

This item has no description.

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

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

This item has no description.

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

This item has no description.

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; overload; deprecated 'use OrientationFromDirectionUp';

Warning: this symbol is deprecated: use OrientationFromDirectionUp

This item has no description.

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

Warning: this symbol is deprecated: use OrientationFromDirectionUp

This item has no description.

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

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

This item has no description.

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

Warning: this symbol is deprecated: OrientationQuaternionFromDirectionUp

This item has no description.

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

Types

TCastleTransformClass = class of TCastleTransform;

This item has no description.

TRenderFromViewFunction = procedure (const RenderingCamera: TRenderingCamera) of object;

This item has no description.

TVisibleChange = (...);

Describe what visible thing changed for TCastleTransform.VisibleChangeHere.

Values
  • vcVisibleGeometry: Visible geometry (actual 3D shape) changed. It's not used when only light conditions, materials, textures and such changed.

    In practice, this means that the depth buffer from some point in space changed. Which means that shadow maps should be regenerated.

  • vcVisibleNonGeometry: Something visible, but not the geometry shape, changes. For example, material or texture on a visible surface changed.
TVisibleChanges = set of TVisibleChange;

This item has no description.

TVisibleChangeEvent = procedure (const Sender: TCastleTransform; const Changes: TVisibleChanges) of object;

This item has no description.

TPrepareResourcesOption = (...);

Various things that TCastleTransform.PrepareResources may prepare.

Values
  • prRenderSelf: Prepare resources for rendering *this* scene (on which TCastleTransform.PrepareResources is called).
  • prRenderClones: Prepare resources for rendering clones of the scene. E.g. textures, which are shared by clones using the cache.
  • prBackground
  • prBoundingBox
  • prShadowVolume
  • prSpatial: Prepare octrees (determined by things like TCastleSceneCore.Spatial).
  • prScreenEffects
TPrepareResourcesOptions = set of TPrepareResourcesOption;

This item has no description.

PRayCollisionNode = ˆTRayCollisionNode;

This item has no description.

PCollisionDetailsItem = ˆTCollisionDetailsItem;

This item has no description.

TRemoveType = (...);

This item has no description.

Values
  • rtNone
  • rtRemove
  • rtRemoveAndFree
TOrientationType = (...);

Orientation of the model is 3D world, determining where is the conceptual "up" direction of the model, and where is it facing.

This type is used by the TCastleTransform.Orientation and TCastleTransform.DefaultOrientation.

Orientation determines how TCastleTransform.Direction, TCastleTransform.Up work, i.e. what is TCastleTransform.Direction and TCastleTransform.Up relation to TCastleTransform.Rotation. The names of the enum values describe what is the direction/up when rotation is zero.

Values
  • otUpYDirectionMinusZ: Model up is +Y axis, direction is -Z which matches cameras of glTF, OpenGL, X3D.

    This also matches default export from Blender to X3D, with Blender "front" pointing toward -Z in the exported model. (But it mismatches default export from Blender to glTF in this regard.)

    Gravity pulls in -Y and GravityUp vector is +Y. Transformation makes -Z and +Y match (respectively) Direction and Up.

    For example, using this value for TCastleTransform.Orientation (or even TCastleTransform.DefaultOrientation) is sensible if you use default Blender X3D exporter, and you let the exporter to make a default transformation (to make +Z up into +Y up). Then you can follow the standard Blender view names ("front", "top" and such) when modelling, and Blender tools like "X-axis mirror" will work best.

  • otUpYDirectionZ: Model up is +Y axis, direction is +Z which matches export from Blender to glTF or Wavefront OBJ. This matches glTF specification that explicitly says "The front of a glTF asset faces +Z".

    Gravity pulls in -Y and GravityUp vector is +Y. Transformation makes +Z and +Y match (respectively) Direction and Up.

    This does not match default direction of OpenGL, X3D and glTF cameras. When viewed from the default direction of OpenGL, X3D and glTF cameras, you will see the front of the model, which means that the model's direction is the opposite of the camera direction.

    For example, using this value for TCastleTransform.Orientation (or even TCastleTransform.DefaultOrientation) is sensible if you use default Blender glTF or OBJ exporter, and you let the exporter to make a default transformation (to make +Z up into +Y up). This is the default setting. Then you can follow the standard Blender view names ("front", "top" and such) when modelling, and Blender tools like "X-axis mirror" will work best.

  • otUpZDirectionMinusY: Orientation sensible for models oriented around Z axis. Transformation makes -Y and +Z match (respectively) Direction and Up.

    Using this value for TCastleTransform.Orientation (or even TCastleTransform.DefaultOrientation) is sensible if you export your models from Blender to X3D without transforming them during export. Note that this is not the default Blender X3D exporter behavior. But you can configure the exporter to work like this (not transform), and then you can follow the standard Blender view names ("front", "top" and such) when modelling.

  • otUpZDirectionX:

    Warning: this symbol is deprecated.

    Up in +Z (like otUpZDirectionMinusY) and direction in +X. Should not be used in new models.
TUserRenderingPass = 0..2;

Rendering pass, for user purposes. Useful to keep shaders cached when you render the same scene multiple times in the same frame (under different lighting conditions or other things that change shaders).

TCastleBehaviorClass = class of TCastleBehavior;

TCastleBehavior.

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.
T3DCoord = 0..2;

This item has no description.

T3DCoords = set of T3DCoord;

This item has no description.

TCollisionEvent = procedure (const CollisionDetails: TPhysicsCollisionDetails) of object;

This item has no description.

TOnCollision = TCollisionEvent deprecated 'use TCollisionEvent';

Warning: this symbol is deprecated: use TCollisionEvent

This item has no description.

TRigidBodyList = specialize TList<TRigidBody>;

This item has no description.

TSceneManagerWorld = TCastleAbstractRootTransform deprecated 'use TCastleRootTransform';

Warning: this symbol is deprecated: use TCastleRootTransform

Copyright 2017-2022 Michalis Kamburelis.

This file is part of "Castle Game Engine".

"Castle Game Engine" is free software; see the file COPYING.txt, included in this distribution, for details about the copyright.

"Castle Game Engine" is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

—————————————————————————-

Constants

rfOffScreen = rfRenderedTexture deprecated 'use rfRenderedTexture';

Warning: this symbol is deprecated: use rfRenderedTexture

This item has no description.

DefaultCameraDirection: TVector3 = (X: 0; Y: 0; Z: -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 = (X: 0; Y: 1; Z: 0);

This item has no description.

Default2DProjectionFar = 1000.0 deprecated 'this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display';

Warning: this symbol is deprecated: this default is not used; ProjectionFar in orthographic projection is now automatically adjusted to what you display

This item has no description.

Default2DProjectionNear = - 1000.0 deprecated 'this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display';

Warning: this symbol is deprecated: this default is not used; ProjectionNear in orthographic projection is now automatically adjusted to what you display

This item has no description.

Default2DCameraZ = 1000.0 / 2;

Default2DProjectionFar

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

DefaultCameraRadius = 0.1;

Default Radius, determining also (with RadiusToProjectionNear) default TCastleCamera.EffectiveProjectionNear.

Note: *Do not* base automatic Radius (and, consistently, automatic ProjectionNear) on Box size.

- Major reason: It makes things go bad, as automatic ProjectionNear increases and clipping at near plane becomes visible, when you have some TCastleTransform in your world that travels forever (and thus increases the Viewport.ItemsBoundingBox into infinity).

E.g. a missile that flies into infinity. Or a box that falls down due to gravity into infinity. While such things in general should not happen (you should prevent things from traveling to infinity), but they may happen esp. in development, and it's bad when one problem (flying to infinity) causes another (sudden clipping at near plane).

- Minor reason: It avoids the need to calculate Viewport.ItemsBoundingBox at each frame, at least for the purpose of automatic projection for ProjectionNear. It was never observed in profiler, but in theory Viewport.ItemsBoundingBox may be costly when you have a lot of scenes.

Note: This is smaller, so even safer, than X3D default Navigation.avatarSize[0] (0.25).

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_navigation/data/level/level-dungeon.gltf open with view3dscene.

Variables

InternalGizmoBoundingBox: Cardinal;

This item has no description.


Generated by PasDoc 0.16.0.