Class TCastleBillboard

Description

Hierarchy

Methods

Properties

Unit

CastleBehaviors

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.

Source: transform/castlebehaviors_billboard.inc (line 32).

Hierarchy

TObject
TPersistent
TComponent
TCastleComponent
TCastleBehavior
TCastleBillboard

Show Additional Members: Inherited Protected

Overview

Methods

Protected	`function GetInternalText: String; virtual;`
Protected	`procedure SetInternalText(const Value: String); virtual;`
Protected	`procedure SetName(const Value: TComponentName); override;`
Protected	`procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual;`
Public	`procedure CustomSerialization(const SerializationProcess: TSerializationProcess); virtual;`
Public	`procedure SetTransient;`
Public	`procedure AddNonVisualComponent(const NonVisualComponent: TComponent);`
Public	`procedure InsertNonVisualComponent(const Index: Integer; const NonVisualComponent: TComponent);`
Public	`procedure RemoveNonVisualComponent(const NonVisualComponent: TComponent);`
Public	`function NonVisualComponentsIndexOf(const NonVisualComponent: TComponent): Integer;`
Public	`function NonVisualComponentsCount: Integer;`
Public	`function NonVisualComponentsEnumerate: TNonVisualComponentsEnumerator;`
Public	`function ValueIsStreamed: Boolean; virtual;`
Public	`procedure DesignerInfo(const SList: TStrings); virtual;`
Public	`procedure DesignerWarnings(const SList: TStrings); virtual;`
Protected	`procedure Update(const SecondsPassed: Single; var RemoveMe: TRemoveType); virtual;`
Protected	`procedure ParentChanged; virtual; deprecated 'Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach';`
Protected	`procedure ParentAfterAttach; virtual;`
Protected	`procedure ParentBeforeDetach; virtual;`
Protected	`procedure WorldAfterAttach; virtual;`
Protected	`procedure WorldBeforeDetach; virtual;`
Public	`procedure BeforeDestruction; override;`
Public	`function World: TCastleAbstractRootTransform;`
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 ParentParentWorldTransformation: TTransformation); override;`
Public	`function PropertySections(const PropertyName: String): TPropertySections; override;`

Properties

Public	`property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;`
Public	`property IsLoading: Boolean read FIsLoading;`
Public	`property Parent: TCastleTransform read FParent;`
Public	`property ListenWorldChange: Boolean read FListenWorldChange write SetListenWorldChange;`
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 GetInternalText: String; virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 575).

Protected procedure SetInternalText(const Value: String); virtual;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 576).

Protected procedure SetName(const Value: TComponentName); override;

This item is declared in ancestor TCastleComponent.

This item has no description.

Source: base/castleclassutils.pas (line 577).

Protected procedure TranslateProperties(const TranslatePropertyEvent: TTranslatePropertyEvent); virtual;

This item is declared in ancestor TCastleComponent.

Enumerate all properties that are possible to translate in this component. E.g. in TCastleLabel it will return TCastleLabel.Caption, in TCastleEdit it will return TCastleEdit.Text and TCastleEdit.Placeholder.

Returns only non-empty properties, thus assuming that if current (by convention, English) text is empty, then there is no point in translating it. Moreover descendants may define boolean properties to exclude particular text from translating, e.g. TCastleLabel.CaptionTranslate, TCastleEdit.TextTranslate, TCastleEdit.PlaceholderTranslate.

It is not recursive (it doesn't enumerate children properties). Use global TranslateProperties procedure to call this on a hierarchy of TComponent.

You usually don't want to call this method (it is called by other engine routines). But you may find it useful to override this, if you define new component.

Source: base/castleclassutils.pas (line 598).

Public procedure CustomSerialization(const SerializationProcess: TSerializationProcess); virtual;

This item is declared in ancestor TCastleComponent.

Override this method to call various methods of SerializationProcess, which in turn allows to serialize/deserialize things that are not published. This allows to serialize/deserialize with more freedom, e.g. to serialize/deserialize some private field.

Source: base/castleclassutils.pas (line 610).

Public procedure SetTransient;

This item is declared in ancestor TCastleComponent.

Ignore this component when serializing parent's TCastleUserInterface.Controls list or TCastleTransform.List, and do not show this component in CGE editor. This simply sets csTransient flag in ComponentStyle.

This is useful for children that are automatically managed by the parent, and should not be modified by user code. For example, TCastleCheckbox is internally composed from TCastleImageControl and TCastleLabel children, but we don't want to serialize or even show these children to user.

Note that if you want to prevent this component from serializing as part of TCastleUserInterface.Controls list or TCastleTransform.List, but you still want it to be visible in CGE editor, then make it a "subcomponent" instead, by SetSubComponent(true).

Note that both csSubComponent and csTransient only disable the component serialization as part of parent's lists enumerated by CustomSerialization (see internal TCastleUserInterface.SerializeChildrenEnumerate , TCastleTransform.SerializeChildrenEnumerate, TCastleTransform.SerializeBehaviorsEnumerate).

If you will make the component published in its own property (which is normal for "subcomponents") then it will be serialized anyway, just as part of it's own property (like TCastleScrollView.ScrollArea). So to really avoid serializing a children component make it csSubComponent and/or csTransient, and do not publish it.

Source: base/castleclassutils.pas (line 663).

Public procedure AddNonVisualComponent(const NonVisualComponent: TComponent);

This item is declared in ancestor TCastleComponent.

Add non-visual component to this component. This is used to organize non-visual components in a tree hierarchy, in CGE designs and editor.

Parameters

RemoveMe: Set this to rtRemove or rtRemoveAndFree to remove this component from Parent after this call finished. rtRemoveAndFree additionally will free this item. Initially it's rtNone when this method is called.

Source: transform/castletransform_behavior.inc (line 52).

Protected procedure ParentChanged; virtual; deprecated 'Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach';

This item is declared in ancestor TCastleBehavior.

Warning: this symbol is deprecated: Use ParentAfterAttach / ParentBeforeDetach or WorldAfterAttach / WorldBeforeDetach

Called after Parent changed, at the end of TCastleTransform.AddBehavior, TCastleTransform.RemoveBehavior.

Source: transform/castletransform_behavior.inc (line 109).

Protected procedure ParentAfterAttach; virtual;

This item is declared in ancestor TCastleBehavior.

Called after Parent changed, e.g. at the end of TCastleTransform.AddBehavior.

Source: transform/castletransform_behavior.inc (line 113).

Protected procedure ParentBeforeDetach; virtual;

This item is declared in ancestor TCastleBehavior.

Called before Parent changed, e.g. at the beginning of TCastleTransform.RemoveBehavior.

This is also called at the destruction of behavior (more precisely from BeforeDestruction now). Even in this case, we guarantee that Parent is still valid during this call, and not in half-destroyed state. Before the actual destructor of TCastleBehavior we do BeforeParentDetach and BeforeWorldDetach and set Parent to Nil.

Source: transform/castletransform_behavior.inc (line 122).

Protected procedure WorldAfterAttach; virtual;

This item is declared in ancestor TCastleBehavior.

Called after Parent became part of World. Called only if ListenWorldChange is True.

Source: transform/castletransform_behavior.inc (line 126).

Protected procedure WorldBeforeDetach; virtual;

This item is declared in ancestor TCastleBehavior.

Called before Parent stops being part of World. Called only if ListenWorldChange is True.

Source: transform/castletransform_behavior.inc (line 136).

Public procedure BeforeDestruction; override;

This item is declared in ancestor TCastleBehavior.

This item has no description.

Source: transform/castletransform_behavior.inc (line 161).

Public function World: TCastleAbstractRootTransform;

This item is declared in ancestor TCastleBehavior.

Reference to the root transformation (typically matching the TCastleViewport.Items value) corresponding to the parent of this behavior.

May be Nil if the behavior is not yet added to the parent TCastleTransform, or when the TCastleTransform is not yet part of the TCastleAbstractRootTransform (which means that TCastleTransform is not added to the viewport yet). You can use ListenWorldChange and override WorldBeforeDetach, WorldAfterAttach to be notified when this changes.

Source: transform/castletransform_behavior.inc (line 184).

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;

Source: transform/castlebehaviors_billboard.inc (line 37).

Public constructor Create(AOwner: TComponent); override;

This item has no description.

Source: transform/castlebehaviors_billboard.inc (line 40).

Public destructor Destroy; override;

This item has no description.

Source: transform/castlebehaviors_billboard.inc (line 41).

Public procedure BeforeRender( const CameraView: TViewVectors; const ParentParentWorldTransformation: TTransformation); override;

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

Event called right before rendering the parent TCastleTransform. Override this if you have to adjust the parent transformation strictly before the rendering.

Compared to adjusting the parent transformation in e.g. Update, adjusting the parent transformation here has advantages:

There's no 1-frame delay between moving the thing that causes the change (like camera) and updating the thing that reacts to it (like a transformation with a billboard).
We 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.
We adjust transformation before each render, so things are OK if given TCastleTransform is present in multiple viewports (see https://castle-engine.io/multiple_viewports_to_display_one_world).

For example, adjusting the TCastleTransform done by the TCastleBillboard is done using this method. The transformation in this case is determined by the camera and parent's parent transformation. The transformation has to be applied without any delay (even a 1-frame delay would be visible, as artifacts caused by billboard not perfectly aligned with the camera would be visible – blending sort along camera direction in sort3D is not perfect if billboard doesn't exactly match camera direction). And the transformation with billboard may be present in multiple viewports and/or multiple times in the same viewport tree.

Source: transform/castlebehaviors_billboard.inc (line 42).

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.

Source: transform/castlebehaviors_billboard.inc (line 45).

Properties

Public property NonVisualComponents [const Index: Integer]: TComponent read GetNonVisualComponents;

This item is declared in ancestor TCastleComponent.

Components added by AddNonVisualComponent.

Source: base/castleclassutils.pas (line 698).

Public property IsLoading: Boolean read FIsLoading;

This item is declared in ancestor TCastleComponent.

Is the component during deserialization now.

Note: We can't use csLoading in ComponentState because in Delphi it is not possible to control it from CastleComponentSerialize.

Source: base/castleclassutils.pas (line 711).

Public property Parent: TCastleTransform read FParent;

This item is declared in ancestor TCastleBehavior.

Parent TCastleTransform of this behavior. Change it by doing TCastleTransform.AddBehavior, TCastleTransform.RemoveBehavior.

Nil if this behavior is not yet added to a parent.

Source: transform/castletransform_behavior.inc (line 191).

Public property ListenWorldChange: Boolean read FListenWorldChange write SetListenWorldChange;

This item is declared in ancestor TCastleBehavior.

Set this to True to receive WorldBeforeDetach, WorldAfterAttach calls.

Source: transform/castletransform_behavior.inc (line 194).

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.

Source: transform/castlebehaviors_billboard.inc (line 65).

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 AxisOfRotation is zero (on all billboards) then TCastleViewport.BlendingSort set to sort3D will be perfect. It will work even if camera can make free rotations (downward and upward) in 3D.
  sort3D is also a good choice if AxisOfRotation is non-zero, but your camera "up" is locked (you don't let player to rotate downward or upward) to the same direction.
- When AxisOfRotation is +Y (0,1,0) (on all billboards) then TCastleViewport.BlendingSort set to sort3DVerticalBillboards will be perfect. It will work even if camera can make free rotations (downward and upward) in 3D.
- Many other possibilities can be accounted for using sortCustom and TCastleViewport.OnCustomShapeSort event. If only your AxisOfRotation is consistent for all billboards, you can implement something similar to sort3DVerticalBillboards to account for given up vector.
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 .

Source: transform/castlebehaviors_billboard.inc (line 131).

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.

Castle Game Engine

API Reference

Class TCastleBillboard

Unit

Declaration

Description

Hierarchy

Overview

Methods

Properties

Description

Methods

See also

See also

See also

See also

Parameters

Properties

See also