Castle Game Engine

Class T3DResource

Description
Hierarchy
Fields
Methods
Properties

Unit

CastleResources

Declaration

type T3DResource = class(TObject)

Description

Resource used for rendering and processing of 3D objects. By itself this doesn't render or do anything. But some 3D objects may need to have such resource prepared to work.

It can also load it's configuration from XML config file. For this purpose, it has a unique identifier in Name property.

Hierarchy

Overview

Fields

Public nested const DefaultFallSpeed = 10.0;
Public nested const DefaultGrowSpeed = 5.0;
Public nested const DefaultReceiveShadowVolumes = true;
Public nested const DefaultCastShadowVolumes = true;

Methods

Protected procedure PrepareCore(const Params: TPrepareParams; const DoProgress: boolean); virtual;
Protected function PrepareCoreSteps: Cardinal; virtual;
Protected procedure ReleaseCore; virtual;
Public constructor Create(const AName: string); virtual;
Public destructor Destroy; override;
Public procedure LoadFromFile(ResourceConfig: TCastleConfig); virtual;
Public procedure RedoPrepare(const Params: TPrepareParams);
Public procedure Prepare(const Params: TPrepareParams; const GravityUp: TVector3); deprecated 'use Prepare overload without the GravityUp parameter';
Public procedure Prepare(const Params: TPrepareParams);
Public procedure Release;
Public procedure InstantiatePlaceholder( const ALevel: TAbstractLevel; const APosition, ADirection: TVector3; const NumberPresent: boolean; const Number: Int64); virtual; abstract;
Public function AlwaysPrepared: boolean; virtual;

Properties

Public property Prepared: boolean read FPrepared;
Public property Name: string read FName;
Public property UsageCount: Cardinal read FUsageCount write FUsageCount default 0;
Public property Animations: T3DResourceAnimationList read FAnimations;
Public property ConfigAlwaysPrepared: boolean read FConfigAlwaysPrepared write FConfigAlwaysPrepared default false;
Public property FallSpeed: Single read FFallSpeed write FFallSpeed default DefaultFallSpeed;
Public property GrowSpeed: Single read FGrowSpeed write FGrowSpeed default DefaultGrowSpeed;
Public property ReceiveShadowVolumes: boolean read FReceiveShadowVolumes write FReceiveShadowVolumes default DefaultReceiveShadowVolumes;
Public property CastShadowVolumes: boolean read FCastShadowVolumes write FCastShadowVolumes default DefaultCastShadowVolumes;
Public property DefaultAnimationTransition: Single read FDefaultAnimationTransition write FDefaultAnimationTransition default 0.0;
Public property Orientation: TOrientationType read FOrientation write FOrientation;
Public property ModelURL: string read FModelURL write FModelURL;
Public property Pool: Cardinal read FPool write FPool default 0;

Description

Fields

Public nested const DefaultFallSpeed = 10.0;
 
Public nested const DefaultGrowSpeed = 5.0;
 
Public nested const DefaultReceiveShadowVolumes = true;
 
Public nested const DefaultCastShadowVolumes = true;
 

Methods

Protected procedure PrepareCore(const Params: TPrepareParams; const DoProgress: boolean); virtual;

Prepare or release everything needed to use this resource. PrepareCore and ReleaseCore should never be called directly, they are only to be overridden in descendants. These are used by actual Prepare and Release when the actual allocation / deallocation should take place (when UsageCount raises from zero or drops back to zero).

ReleaseCore is also called in destructor, regardless of UsageCount. This is done to free resources even if user forgot to call Release before destroying this resource instance.

PrepareCore must call Progress.Step exactly PrepareCoreSteps times, only if DoProgress. This allows to make nice progress bar in Prepare. In this class, PrepareCoreSteps returns 0.

Protected function PrepareCoreSteps: Cardinal; virtual;
 
Protected procedure ReleaseCore; virtual;
 
Public constructor Create(const AName: string); virtual;
 
Public destructor Destroy; override;
 
Public procedure LoadFromFile(ResourceConfig: TCastleConfig); virtual;
 
Public procedure RedoPrepare(const Params: TPrepareParams);

Release and then immediately prepare again this resource. Call only when UsageCount <> 0, that is when resource is prepared. Shows nice progress bar, using Progress.

Public procedure Prepare(const Params: TPrepareParams; const GravityUp: TVector3); deprecated 'use Prepare overload without the GravityUp parameter';

Warning: this symbol is deprecated: use Prepare overload without the GravityUp parameter

Prepare or release everything needed to use this resource.

There is an internal counter tracking how many times given resource was prepared and released. Which means that preparing and releasing resource multiple times is correct — but make sure that every single call to prepare is paired with exactly one call to release. Actual allocation / deallocation (when protected methods PrepareCore, ReleaseCore are called) happens only when UsageCount raises from zero or drops back to zero.

Show nice progress bar, using Progress.

Parameters
Params
World parameters to prepare for. See TCastleTransform.PrepareResources for more comments.
Public procedure Prepare(const Params: TPrepareParams);
 
Public procedure Release;
 
Public procedure InstantiatePlaceholder( const ALevel: TAbstractLevel; const APosition, ADirection: TVector3; const NumberPresent: boolean; const Number: Int64); virtual; abstract;

Place an instance of this resource on World, using information from the placeholder on the level.

Public function AlwaysPrepared: boolean; virtual;

Mechanics of given game may suggest that some 3D resources should always be prepared. For example, in typical 3D game when player has inventory and can drop items from inventory on the ground, then all items should be prepared for all levels, since you can in theory drop everything anywhere.

Return True if this is such resource.

Default implementation in T3DResource returns here the ConfigAlwaysPrepared value, which may be set in resource.xml and by default is false. This allows to configure this using resource.xml files. Descendants may choose to override this, to override value from resource.xml file.

Properties

Public property Prepared: boolean read FPrepared;

Are we in a (fully) prepared state. That is after a (fully successful) Prepare call and before Release. Note that this is slightly different than checking UsageCount <> 0: in some situations, UsageCount may be non-zero while the preparation is not finished yet. This property is guaranteed to be True only if preparation was fully successfully (no exceptions) finished.

Public property Name: string read FName;

Unique identifier of this resource. Used to refer to this resource from level placeholders (see TLevel.Load about placeholders), from other XML files (for example one creature may shoot another creature as a missile using TWalkAttackCreatureResource.FireMissileName), and in other places.

This can use only letters, use CamelCase. Reason: This must be a valid identifier in both VRML/X3D and ObjectPascal. Also digits and underscores are reserved, as we may use them to get other information from placeholder names.

Public property UsageCount: Cardinal read FUsageCount write FUsageCount default 0;

How many times this resource is used. Used by Prepare and Release: actual allocation / deallocation happens when this raises from zero or drops back to zero.

Public property Animations: T3DResourceAnimationList read FAnimations;

Animations of this resource.

The first animation, if exists, right now determines the default radius calculation. So the first animation should have the bounding box representative for all animations. Other than that, the order on this list doesn't matter.

The properties of these animations are automatically loaded from resource.xml file in LoadFromFile. The animations are automatically prepared / released by our Prepare / Release methods.

Public property ConfigAlwaysPrepared: boolean read FConfigAlwaysPrepared write FConfigAlwaysPrepared default false;
 
Public property FallSpeed: Single read FFallSpeed write FFallSpeed default DefaultFallSpeed;

The speed (in units per second) of falling down because of gravity. Note that the gravity direction is controlled by your level 3D model, see "Which way is up" section in the engine tutorial https://castle-engine.io/manual_up.php .

Currently, falling down of creatures and items just uses this constant speed. In the future, we plan to add properties to control mass and air friction and perform more physically-correct simulation of falling down.

This has no effect for creatures with TCreatureResource.Flying = True. This also has no effect for missile creatures (their TCreatureResource.Flying is ignored, they have special approach to gravity).

See TCastleTransform.FallSpeed for precise definition, this works the same, except our default value is non-zero, and by default TCastleTransform.Gravity and TCastleTransform.PreferredHeight are already sensible for creatures/items.

Public property GrowSpeed: Single read FGrowSpeed write FGrowSpeed default DefaultGrowSpeed;

The speed (in units per second) of growing.

"Growing" is used to allow non-flying creatures to climb stairs. The creature can move whenever a sphere (see TCreatureResource.MiddleHeight and TCreatureResource.Radius) can move. This means that part of the bounding box (part of the TCastleTransform.PreferredHeight) may temporarily "sink" into the ground. Then growing, controlled by this property, pushes the creature up.

See TCastleTransform.GrowSpeed, this works the same, except the default value is non-zero, and by default TCastleTransform.Gravity and TCastleTransform.PreferredHeight are already sensible for creatures/items.

Public property ReceiveShadowVolumes: boolean read FReceiveShadowVolumes write FReceiveShadowVolumes default DefaultReceiveShadowVolumes;
 
Public property CastShadowVolumes: boolean read FCastShadowVolumes write FCastShadowVolumes default DefaultCastShadowVolumes;
 
Public property DefaultAnimationTransition: Single read FDefaultAnimationTransition write FDefaultAnimationTransition default 0.0;

See TCastleSceneCore.DefaultAnimationTransition

Public property Orientation: TOrientationType read FOrientation write FOrientation;

See TCastleTransform.Orientation, by default this is TCastleTransform.DefaultOrientation.

In the resource.xml file, this value can be specified using following strings:

default

Use TCastleTransform.DefaultOrientation.

up:y,direction:-z

Use otUpYDirectionMinusZ.

up:y,direction:z

Use otUpYDirectionZ. Matches conventional glTF orientation.

up:z,direction:-y

Use otUpZDirectionMinusY.

up:z,direction:x

Use otUpZDirectionX.

Public property ModelURL: string read FModelURL write FModelURL;

Model URL, only when you define multiple animations inside a single 3D file. See [https://castle-engine.io/creating_data_resources.php] for notes about <model> element in resource.xml files.

Public property Pool: Cardinal read FPool write FPool default 0;

If non-zero, use a pool of TCastleScene to create resource instances.

To understand what this controls, some explanation is necessary: Multiple instances of the same creature / item may be visible. They all refer to the same "resource" holding one set of data. Our resources mechanism is prepared to handle it efficiently, in 2 ways:

  1. Without pool: We have a single TCastleScene, which is internally continuosly changed back-and-forth to show various animations (and various moment of these animations), to display all resource instances correctly.

    Advantages: Less loading time, less memory usage (no need to create pool).

    Disadvantages: Worse FPS (need to switch back-and-forth) and no animation blending support.

  2. With pool: Each resource instance gets a copy of TCastleScene. This avoids switching one scene back-and-forth. It's particularly beneficial for animations like from glTF or Spine JSON (in general: animations from formats other than castle-anim-frames).

    We keep a pool of TCastleScene that can be allocated for the needed instances.

    The "pool" attribute specifies the initial pool size. It should be large enough to cover practical needs. If it's not large enough then, when necessary, we will increase this pool at runtime, which works but causes one-time lag during game execution (as we need to make TCastleScene.Clone).

    This approach also allows for animation blending. (TODO: in the future)

    Disadvantages: More loading time and memory usage (for pool).

    Advantages: Better FPS and support for animation blending. In general, this uses TCastleScene in more standard way.

Note that Pool only matters if you use a single file for all resource animations. Using multiples files (separate file for each animation) is deprecated anyway, see https://castle-engine.io/creating_data_resources.php .

In the resource.xml, you can specify this value an explicit integer (0 means to not use pool), or you can write "auto" to automatically guess the best value. The best value means to use pool, unless the ModelURL indicates castle-anim-frames or MD3 formats.

Generated by PasDoc 0.16.0.