Class T3DResource

Unit

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

  • TObject
  • T3DResource

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 ALevelProperties: TLevelProperties; 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;
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 ModelURL: string read FModelURL write FModelURL;

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 ALevelProperties: TLevelProperties; 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 TGameSceneManager.LoadLevel 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;
 
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/tutorial_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 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.


Generated by PasDoc 0.15.0.