Unit CastleTransform

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

An example:

{ TransformSave and TransformLoad example. }

{$apptype CONSOLE}

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

Warning: this symbol is deprecated: use TTransformation.Multiply

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

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

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

Warning: this symbol is deprecated: use OrientationFromDirectionUp

Warning: this symbol is deprecated: use OrientationFromDirectionUp

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

Warning: this symbol is deprecated: OrientationQuaternionFromDirectionUp

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.

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.Translation := NewPosition;).

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.

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

Values

• rtNone
• rtRemove
• rtRemoveAndFree

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.

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

TCastleBehavior.

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.

Values

• cdDiscrete
• cdContinuous

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.

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

Warning: this symbol is deprecated: use rfRenderedTexture

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

Warning: this symbol is 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; ProjectionNear in orthographic projection is now automatically adjusted to what you display

Default2DProjectionFar

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

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

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 castle-model-viewer.