Decals
[Special Effects]

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. More...
class	DecalManager
	The object that manages all of the decals in the active mission. More...
Functions
int	decalManagerAddDecal (Point3F position, Point3F normal, float rot, float scale, DecalData decalData, bool isImmortal=false)
	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	$Decals::debugRender
	If true, the decal spheres will be visualized when in the editor.
bool	$pref::Decals::enabled
	Controls whether decals are rendered.
float	$pref::Decals::lifeTimeScale
	Lifetime that decals will last after being created in the world. Deprecated. Use DecalData::lifeSpan instead.
bool	$Decals::poolBuffers
	If true, will merge all PrimitiveBuffers and VertexBuffers into a pair of pools before clearing them at the end of a frame.
float	$Decals::sphereDistanceTolerance
	The distance at which the decal system will start breaking up decal spheres when adding new decals.
float	$Decals::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.

Example:

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

---

Function Documentation

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

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.

Returns:

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

Example:

// 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 );

void decalManagerClear

(

)

Removes all decals currently loaded in the decal manager.

Example:

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

bool decalManagerDirty

(

)

Returns whether the decal manager has unsaved modifications.

Returns:

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

Example:

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

bool decalManagerLoad

(

string

fileName

)

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

Parameters:

fileName

Filename to load the decals from.

Returns:

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

Example:

// 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 );

bool decalManagerRemoveDecal

(

int

decalID

)

Remove specified decal from the scene.

Parameters:

decalID

ID of the decal to remove.

Returns:

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

Example:

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

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

void decalManagerSave

(

String

decalSaveFile = ""

)

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

Parameters:

decalSaveFile

Filename to save the decals to.

Example:

// 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 );

---

Variable Documentation

bool $Decals::debugRender

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

bool $pref::Decals::enabled

Controls whether decals are rendered.

float $pref::Decals::lifeTimeScale

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

bool $Decals::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 $Decals::sphereDistanceTolerance

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

float $Decals::sphereRadiusTolerance

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