Decals

Decals are non-SimObject derived objects that are stored and loaded separately from the normal mission file.

More...

Classes:

class

DecalData

A datablock describing an individual decal.

class

DecalManager

The object that manages all of the decals in the active mission.

Functions

int

decalManagerAddDecal(Point3F position, Point3F normal, float rot, float scale, DecalData decalData, bool isImmortal)

Adds a new decal to the decal manager.

void

decalManagerClear()

Removes all decals currently loaded in the decal manager.

bool

decalManagerDirty()

Returns whether the decal manager has unsaved modifications.

bool

decalManagerLoad(string fileName)

Clears existing decals and replaces them with decals loaded from the specified file.

bool

decalManagerRemoveDecal(int decalID)

Remove specified decal from the scene.

void

decalManagerSave(String decalSaveFile)

Saves the decals for the active mission in the entered filename.

Variables

bool

debugRender

If true, the decal spheres will be visualized when in the editor.

bool

enabled

Controls whether decals are rendered.

float

lifeTimeScale

Lifetime that decals will last after being created in the world. Deprecated. Use DecalData::lifeSpan instead.

bool

poolBuffers

If true, will merge all PrimitiveBuffers and VertexBuffers into a pair of pools before clearing them at the end of a frame.

float

sphereDistanceTolerance

The distance at which the decal system will start breaking up decal spheres when adding new decals.

float

sphereRadiusTolerance

The radius beyond which the decal system will start breaking up decal spheres when adding new decals.

Detailed Description

Decals are non-SimObject derived objects that are stored and loaded separately from the normal mission file.

The DecalManager handles all aspects of decal management including loading, creation, saving, and automatically deleting decals that have exceeded their lifeSpan.

The static decals associated with a mission are normally loaded immediately after the mission itself has loaded as shown below.

// Load the static mission decals.
decalManagerLoad( %missionName @ ".decals" );

Functions

decalManagerAddDecal(Point3F position, Point3F normal, float rot, float scale, DecalData decalData, bool isImmortal)

Adds a new decal to the decal manager.

Parameters:

position	World position for the decal.
normal	Decal normal vector (if the decal was a tire lying flat on a surface, this is the vector pointing in the direction of the axle).
rot	Angle (in radians) to rotate this decal around its normal vector.
scale	Scale factor applied to the decal.
decalData	DecalData datablock to use for the new decal.
isImmortal	Whether or not this decal is immortal. If immortal, it does not expire automatically and must be removed explicitly.

return:

Returns the ID of the new Decal object or -1 on failure.

// Specify the decal position
%position = "1.0 1.0 1.0";

// Specify the up vector
%normal = "0.0 0.0 1.0";

// Add the new decal.
%decalObj = decalManagerAddDecal( %position, %normal, 0.5, 0.35, ScorchBigDecal, false );

decalManagerClear()

Removes all decals currently loaded in the decal manager.

// Tell the decal manager to remove all existing decals.
decalManagerClear();

decalManagerDirty()

Returns whether the decal manager has unsaved modifications.

return:

True if the decal manager has unsaved modifications, false if everything has been saved.

// Ask the decal manager if it has unsaved modifications.
%hasUnsavedModifications = decalManagerDirty();

decalManagerLoad(string fileName)

Clears existing decals and replaces them with decals loaded from the specified file.

Parameters:

fileName

Filename to load the decals from.

return:

True if the decal manager was able to load the requested file, false if it could not.

// Set the filename to load the decals from.
%fileName = "./missionDecals.mis.decals";
// Inform the decal manager to load the decals from the entered filename.
decalManagerLoad( %fileName );

decalManagerRemoveDecal(int decalID)

Remove specified decal from the scene.

Parameters:

decalID

ID of the decal to remove.

return:

Returns true if successful, false if decal ID not found.

// Specify a decal ID to be removed
%decalID = 1;

// Tell the decal manager to remove the specified decal ID.
decalManagerRemoveDecal( %decalId )

decalManagerSave(String decalSaveFile)

Saves the decals for the active mission in the entered filename.

Parameters:

decalSaveFile

Filename to save the decals to.

// Set the filename to save the decals in. If no filename is set, then the
// decals will default to <activeMissionName>.mis.decals
%fileName = "./missionDecals.mis.decals";
// Inform the decal manager to save the decals for the active mission.
decalManagerSave( %fileName );

Variables

bool debugRender

If true, the decal spheres will be visualized when in the editor.

bool enabled

Controls whether decals are rendered.

float lifeTimeScale

Lifetime that decals will last after being created in the world. Deprecated. Use DecalData::lifeSpan instead.

bool poolBuffers

If true, will merge all PrimitiveBuffers and VertexBuffers into a pair of pools before clearing them at the end of a frame.

If false, will just clear them at the end of a frame.

float sphereDistanceTolerance

The distance at which the decal system will start breaking up decal spheres when adding new decals.

float sphereRadiusTolerance

The radius beyond which the decal system will start breaking up decal spheres when adding new decals.