Class TCastleBillboard

Unit

Declaration

type TCastleBillboard = class(TCastleBehavior)

Description

Behavior to make parent TCastleTransform a billboard, that always rotates to face the current camera.

The front of the parent, that always turns to the camera, is determined by the TCastleTransform.Orientation, which in turn by default is taken from TCastleTransform.DefaultOrientation, which by default just means "positive Z axis" (otUpYDirectionZ). The idea is that TCastleTransform.Direction is updated to point toward the camera.

The axis around which billboard rotates is determined by AxisOfRotation. When non-zero, this axis is set as TCastleTransform.Up.

Hierarchy

Overview

Methods

Protected function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; override;
Public constructor Create(AOwner: TComponent); override;
Public destructor Destroy; override;
Public procedure BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransform, ParentParentWorldInverseTransform, ParentWorldTransform, ParentWorldInverseTransform: TMatrix4); override;
Public function PropertySections(const PropertyName: String): TPropertySections; override;

Properties

Public property AxisOfRotation: TVector3 read FAxisOfRotation write FAxisOfRotation;
Published property MatchCameraDirection: Boolean read FMatchCameraDirection write FMatchCameraDirection default true;
Published property AxisOfRotationPersistent: TCastleVector3Persistent read FAxisOfRotationPersistent ;

Description

Methods

Protected function CanAttachToParent(const NewParent: TCastleTransform; out ReasonWhyCannot: String): Boolean; override;

This item has no description. Showing description inherited from TCastleBehavior.CanAttachToParent.

Check can this behavior be added to NewParent. When this returns False, it has to set also ReasonWhyCannot. When overriding this, you can use e.g. this code to make sure we are the only behavior of given class:

function TCastleBillboard.CanAttachToParent(const NewParent: TCastleTransform;
  out ReasonWhyCannot: String): Boolean;
begin
  Result := inherited;
  if not Result then Exit;

  if NewParent.FindBehavior(TCastleBillboard) <> nil then
  begin
    ReasonWhyCannot := 'Only one TCastleBillboard behavior can be added to a given TCastleTransform';
    Result := false;
  end;
end;

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Public destructor Destroy; override;

This item has no description.

Public procedure BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransform, ParentParentWorldInverseTransform, ParentWorldTransform, ParentWorldInverseTransform: TMatrix4); override;

This item has no description. Showing description inherited from TCastleBehavior.BeforeRender.

Event called right before rendering the parent TCastleTransform.

Override this is you have to adjust the parent transformation strictly before the rendering, and doing it in Update is not enough.

E.g. this makes sense to implement billboard, because user must never see artifacts caused by billboard not perfectly aligned with the camera (blending sort along camera direction in sort3D is not perfect if billboard doesn't exactly match camera direction).

Overriding this also allows to adjust transformation before rendering each occurrence of TCastleTransform in the viewport tree. This matters if given TCastleTransform may occur multiple times in the viewport tree, directly or through TCastleTransformReference. This also matters if given TCastleTransform may be present in multiple viewports (see https://castle-engine.io/multiple_viewports_to_display_one_world).

Public function PropertySections(const PropertyName: String): TPropertySections; override;

This item has no description. Showing description inherited from TCastleComponent.PropertySections.

Section where to show property in the editor.

Properties

Public property AxisOfRotation: TVector3 read FAxisOfRotation write FAxisOfRotation;

Axis around which the billboard rotates to face the camera. The rotation is free in 3D (with undefined up vector) when this is zero.

When non-zero, this axis is set as TCastleTransform.Up.

Similar to X3D TBillboardNode.AxisOfRotation. By default +Y (that is, (0, 1, 0)).

Note that this axis is expressed in the coordinate system of "parent of our parent" transform. That is, if you have instance X of a TCastleTransform, with TCastleBehavior attached, and it is a child of TCastleTransform instance Y, then you can rotate Y and it effectively rotates also the billboard's axis of rotation. The billboard still works correctly (it will rotate the X to look at camera as much as possible, though it cannot change rotation on Y).

See MatchCameraDirection for details how this axis affects object transformation.

Published property MatchCameraDirection: Boolean read FMatchCameraDirection write FMatchCameraDirection default true;

Whether the billboard direction should match the camera direction (True, default) or direction from camera to the billboard origin (False).

The difference between these 2 settings is subtle.

  • When True, all billboards in the scene have the same orientation (if they have the same AxisOfRotation). They just follow camera orientation. Billboard orientation is unrelated to billboard position, and unrelated to camera position.

    Strafing (moving camera) left/right doesn't change the billboard orientation. Moving billboard left/right doesn't change the billboard orientation.

    This may look better or worse – really depends on what you want to achieve.

    The major advantage of this approach (and the reason why it is the default) is that blending sorting for objects with thin layers, like on Spine models, can be made perfectly reliable, even in 3D.

  • When False, billboard orientation adjusts to the direction from camera to the origin of the billboard transformation. This means that the billboard position affects the billboard orientation, e.g. billboards on the edge of the field of view will have a different orientation than in the middle of the view.

    This is consistent with X3D Billboard, https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/navigation.html#Billboard .

Published property AxisOfRotationPersistent: TCastleVector3Persistent read FAxisOfRotationPersistent ;

AxisOfRotation 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 AxisOfRotation directly.

See also
AxisOfRotation
Axis around which the billboard rotates to face the camera.

Generated by PasDoc 0.16.0-snapshot.