Castle Game Engine: CastleResources: Class T3DResource

# 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 TObject T3DResource ## Overview ### Fields
| `internal const DefaultFallSpeed = 10.0;`
| `internal const DefaultGrowSpeed = 5.0;`
| `internal const DefaultReceiveShadowVolumes = true;`
| `internal const DefaultCastShadowVolumes = true;`
### Methods
| `procedure PrepareCore(const BaseLights: TAbstractLightInstancesList; const GravityUp: TVector3Single; const DoProgress: boolean); virtual;`
| `function PrepareCoreSteps: Cardinal; virtual;`
| `procedure ReleaseCore; virtual;`
| `constructor Create(const AName: string); virtual;`
| `destructor Destroy; override;`
| `procedure GLContextClose; virtual;`
| `procedure LoadFromFile(ResourceConfig: TCastleConfig); virtual;`
| `procedure RedoPrepare(const BaseLights: TAbstractLightInstancesList; const GravityUp: TVector3Single);`
| `procedure Prepare(const BaseLights: TAbstractLightInstancesList; const GravityUp: TVector3Single);`
| `procedure Release;`
| `procedure InstantiatePlaceholder(World: T3DWorld; const APosition, ADirection: TVector3Single; const NumberPresent: boolean; const Number: Int64); virtual; abstract;`
| `function AlwaysPrepared: boolean; virtual;`
### Properties
| `property Prepared: boolean read FPrepared;`
| `property Name: string read FName;`
| `property UsageCount: Cardinal read FUsageCount write FUsageCount default 0;`
| `property Animations: T3DResourceAnimationList read FAnimations;`
| `property ConfigAlwaysPrepared: boolean read FConfigAlwaysPrepared write FConfigAlwaysPrepared;`
| `property FallSpeed: Single read FFallSpeed write FFallSpeed default DefaultFallSpeed;`
| `property GrowSpeed: Single read FGrowSpeed write FGrowSpeed default DefaultGrowSpeed;`
| `property ReceiveShadowVolumes: boolean read FReceiveShadowVolumes write FReceiveShadowVolumes default DefaultReceiveShadowVolumes;`
| `property CastShadowVolumes: boolean read FCastShadowVolumes write FCastShadowVolumes default DefaultCastShadowVolumes;`
| `property ModelURL: string read FModelURL write FModelURL;`
## Description ### Fields
| `internal const DefaultFallSpeed = 10.0;`
| `internal const DefaultGrowSpeed = 5.0;`
| `internal const DefaultReceiveShadowVolumes = true;`
| `internal const DefaultCastShadowVolumes = true;`
### Methods
| `procedure PrepareCore(const BaseLights: TAbstractLightInstancesList; const GravityUp: TVector3Single; 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.
| `function PrepareCoreSteps: Cardinal; virtual;`
| `procedure ReleaseCore; virtual;`
| `constructor Create(const AName: string); virtual;`
| `destructor Destroy; override;`
| `procedure GLContextClose; virtual;`
Free any association with current OpenGL context.
| `procedure LoadFromFile(ResourceConfig: TCastleConfig); virtual;`
| `procedure RedoPrepare(const BaseLights: TAbstractLightInstancesList; const GravityUp: TVector3Single);`
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.
| `procedure Prepare(const BaseLights: TAbstractLightInstancesList; const GravityUp: TVector3Single);`
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.
| `procedure Release;`
| `procedure InstantiatePlaceholder(World: T3DWorld; const APosition, ADirection: TVector3Single; const NumberPresent: boolean; const Number: Int64); virtual; abstract;`
Place an instance of this resource on World, using information from the placeholder on the level.
| `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
| `property Prepared: boolean read FPrepared;`
Are we in a (fully) prepared state. That is after a (fully successfull) 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.
| `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.
| `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.
| `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.
| `property ConfigAlwaysPrepared: boolean read FConfigAlwaysPrepared write FConfigAlwaysPrepared;`
| `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 [http://castle-engine.sourceforge.net/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 T3D.FallSpeed for precise definition, this works the same, except our default value is non-zero, and by default T3D.Gravity and T3D.PreferredHeight are already sensible for creatures/items.
| `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 T3DCustomTransform.PreferredHeight) may temporarily "sink" into the ground. Then growing, controlled by this property, pushes the creature up. See T3D.GrowSpeed, this works the same, except the default value is non-zero, and by default T3D.Gravity and T3D.PreferredHeight are already sensible for creatures/items.
| `property ReceiveShadowVolumes: boolean read FReceiveShadowVolumes write FReceiveShadowVolumes default DefaultReceiveShadowVolumes;`
| `property CastShadowVolumes: boolean read FCastShadowVolumes write FCastShadowVolumes default DefaultCastShadowVolumes;`
| `property ModelURL: string read FModelURL write FModelURL;`
Model URL, only when you define multiple animations inside a single 3D file. See [http://castle-engine.sourceforge.net/creating_data_resources.php] for notes about <model> element in resource.xml files.
Generated by PasDoc 0.13.0 on 2015-06-15 04:43:11