Torque 3D - Script Manual: GFX

TorqueScript

Main   Class List   Namespace List   Online

GFX
[Rendering]

The low level graphics interface to the engine. More...

Classes

class  CubemapData
 Used to create static or dynamic cubemaps. More...
class  DebugDrawer
 A debug helper for rendering debug primitives to the scene. More...
class  GFXCardProfiler
 Provides a device independent wrapper around both the capabilities reported by the card/drivers and the exceptions recorded in various scripts. More...
class  GFXCardProfilerAPI
 This class is the interface between TorqueScript and GFXCardProfiler. More...
class  GFXInit
 Functions for tracking GFX adapters and initializing them into devices. More...
class  GFXSamplerStateData
 A sampler state used by GFXStateBlockData. More...
class  GFXStateBlockData
 A state block description for rendering. More...
class  Material
 A material in Torque 3D is a data structure that describes a surface. More...
class  PfxVis
 Singleton class that exposes ConsoleStaticFunctions for debug visualizing PostEffects. More...
class  RenderFormatToken
 Used to change the render target format when rendering in AL. More...

Modules

 Materials
 

Classes, structures, functions, and variables related to Torque 3D's material system.


 Shaders
 

Classes, structures, functions, and variables related to Torque 3D's shader system.


Enumerations

enum  GFXAdapterType {
  OpenGL,
  D3D8,
  D3D9,
  NullDevice,
  Xenon
}
 

Back-end graphics API used by the GFX subsystem.

More...
enum  GFXBlend {
  GFXBlendZero,
  GFXBlendOne,
  GFXBlendSrcColor,
  GFXBlendInvSrcColor,
  GFXBlendSrcAlpha,
  GFXBlendInvSrcAlpha,
  GFXBlendDestAlpha,
  GFXBlendInvDestAlpha,
  GFXBlendDestColor,
  GFXBlendInvDestColor,
  GFXBlendSrcAlphaSat
}
 

The supported blend modes.

More...
enum  GFXBlendOp {
  GFXBlendOpAdd,
  GFXBlendOpSubtract,
  GFXBlendOpRevSubtract,
  GFXBlendOpMin,
  GFXBlendOpMax
}
 

The blend operators.

More...
enum  GFXCmpFunc {
  GFXCmpNever,
  GFXCmpLess,
  GFXCmpEqual,
  GFXCmpLessEqual,
  GFXCmpGreater,
  GFXCmpNotEqual,
  GFXCmpGreaterEqual,
  GFXCmpAlways
}
 

The supported comparison functions.

More...
enum  GFXCullMode {
  GFXCullNone,
  GFXCullCW,
  GFXCullCCW
}
 

The render cull modes.

More...
enum  GFXFormat {
  GFXFormatR8G8B8,
  GFXFormatR8G8B8A8,
  GFXFormatR8G8B8X8,
  GFXFormatR32F,
  GFXFormatR5G6B5,
  GFXFormatR5G5B5A1,
  GFXFormatR5G5B5X1,
  GFXFormatA4L4,
  GFXFormatA8L8,
  GFXFormatA8,
  GFXFormatL8,
  GFXFormatDXT1,
  GFXFormatDXT2,
  GFXFormatDXT3,
  GFXFormatDXT4,
  GFXFormatDXT5,
  GFXFormatD32,
  GFXFormatD24X8,
  GFXFormatD24S8,
  GFXFormatD24FS8,
  GFXFormatD16,
  GFXFormatR32G32B32A32F,
  GFXFormatR16G16B16A16F,
  GFXFormatL16,
  GFXFormatR16G16B16A16,
  GFXFormatR16G16,
  GFXFormatR16F,
  GFXFormatR16G16F,
  GFXFormatR10G10B10A2
}
 

The texture formats.

More...
enum  GFXStencilOp {
  GFXStencilOpKeep,
  GFXStencilOpZero,
  GFXStencilOpReplace,
  GFXStencilOpIncrSat,
  GFXStencilOpDecrSat,
  GFXStencilOpInvert,
  GFXStencilOpIncr,
  GFXStencilOpDecr
}
 

The stencil operators.

More...
enum  GFXTextureAddressMode {
  GFXAddressWrap,
  GFXAddressMirror,
  GFXAddressClamp,
  GFXAddressBorder,
  GFXAddressMirrorOnce
}
 

The texture address modes.

More...
enum  GFXTextureArgument {
  GFXTADiffuse,
  GFXTACurrent,
  GFXTATexture,
  GFXTATFactor,
  GFXTASpecular,
  GFXTATemp,
  GFXTAConstant,
  OneMinus,
  AlphaReplicate
}
 

The texture arguments.

More...
enum  GFXTextureFilterType {
  GFXTextureFilterNone,
  GFXTextureFilterPoint,
  GFXTextureFilterLinear,
  GFXTextureFilterAnisotropic,
  GFXTextureFilterPyramidalQuad,
  GFXTextureFilterGaussianQuad
}
 

The texture filter types.

More...
enum  GFXTextureOp {
  GFXTOPDisable,
  GFXTOPSelectARG1,
  GFXTOPSelectARG2,
  GFXTOPModulate,
  GFXTOPModulate2X,
  GFXTOPModulate4X,
  GFXTOPAdd,
  GFXTOPAddSigned,
  GFXTOPAddSigned2X,
  GFXTOPSubtract,
  GFXTOPAddSmooth,
  GFXTOPBlendDiffuseAlpha,
  GFXTOPBlendTextureAlpha,
  GFXTOPBlendFactorAlpha,
  GFXTOPBlendTextureAlphaPM,
  GFXTOPBlendCURRENTALPHA,
  GFXTOPPreModulate,
  GFXTOPModulateAlphaAddColor,
  GFXTOPModulateColorAddAlpha,
  GFXTOPModulateInvAlphaAddColor,
  GFXTOPModulateInvColorAddAlpha,
  GFXTOPBumpEnvMap,
  GFXTOPBumpEnvMapLuminance,
  GFXTOPDotProduct3,
  GFXTOPLERP
}
 

The texture operators.

More...
enum  GFXTextureTransformFlags {
  GFXTTFDisable,
  GFXTTFFCoord1D,
  GFXTTFFCoord2D,
  GFXTTFFCoord3D,
  GFXTTFFCoord4D,
  GFXTTFProjected
}
 

The texture transform state flags.

More...
enum  MaterialAnimType {
  Scroll,
  Rotate,
  Wave,
  Scale,
  Sequence
}
 

The type of animation effect to apply to this material.

More...
enum  MaterialBlendOp {
  None,
  Mul,
  Add,
  AddAlpha,
  Sub,
  LerpAlpha
}
 

The type of graphical blending operation to apply to this material.

More...
enum  MaterialWaveType {
  Sin,
  Triangle,
  Square
}
 

When using the Wave material animation, one of these Wave Types will be used to determine the type of wave to display.

More...

Functions

void cleanupTexturePool ()
 Release the unused pooled textures in texture manager freeing up video memory.
void clearGFXResourceFlags ()
 Clears the flagged state on all allocated GFX resources. See flagCurrentGFXResources for usage details.
void describeGFXResources (string resourceTypes, string filePath, bool unflaggedOnly=false)
 Dumps a description of GFX resources to a file or the console.
void describeGFXStateBlocks (string filePath)
 Dumps a description of all state blocks.
void dumpRandomNormalMap ()
 Creates a 64x64 normal map texture filled with noise. The texture is saved to randNormTex.png in the location of the game executable.
void dumpTextureObjects ()
 Dumps a list of all active texture objects to the console.
void flagCurrentGFXResources ()
 Flags all currently allocated GFX resources. Used for resource allocation and leak tracking by flagging current resources then dumping a list of unflagged resources at some later point in execution.
void flushTextureCache ()
 Releases all textures and resurrects the texture manager.
static int GFXInit::getAdapterCount ()
 Return the number of graphics adapters available.
GFXFormat getBestHDRFormat ()
 Returns the best texture format for storage of HDR data for the active device.
Point3F getDesktopResolution ()
 Returns the width, height, and bitdepth of the screen/desktop.
string getDisplayDeviceInformation ()
 Get the string describing the active GFX device.
String getDisplayDeviceList ()
 Returns a tab-seperated string of the detected devices across all adapters.
float getPixelShaderVersion ()
 Returns the pixel shader version for the active device.
String getTextureProfileStats ()
 Returns a list of texture profiles in the format: ProfileName TextureCount TextureMB.
void listGFXResources (bool unflaggedOnly=false)
 Returns a list of the unflagged GFX resources. See flagCurrentGFXResources for usage details.
void reloadTextures ()
 Reload all the textures from disk.
void screenShot (string file, string format, int tileCount=1, float tileOverlap=0)
 Takes a screenshot with optional tiling to produce huge screenshots.
void setPixelShaderVersion (float version)
 Sets the pixel shader version for the active device. This can be used to force a lower pixel shader version than is supported by the device for testing or performance optimization.
void setReflectFormat (GFXFormat format)
 Set the reflection texture format.

Variables

bool $gfx::disableOcclusionQuery
 Debug helper that disables all hardware occlusion queries causing them to return only the visibile state.
bool $pref::Video::disableVerticalSync
 Disables vertical sync on the active device.
bool $gfx::disassembleAllShaders
 On supported devices this will dump shader disassembly to the procedural shader folder.
float $pref::Video::forcedPixVersion
 Will force the shader model if the value is positive and less than the shader model supported by the active device. Use 0 for fixed function.
int $pref::Video::textureReductionLevel
 The number of mipmap levels to drop on loaded textures to reduce video memory usage. It will skip any textures that have been defined as not allowing down scaling.
bool $gfx::wireframe
 Used to toggle wireframe rendering at runtime.

Detailed Description

The low level graphics interface to the engine.

In Torque the GFX layer provides access to abstracted low level graphics concepts. From script you have limited access to graphics rendering as it is usually too slow to do individual draw calls thru the scripting interface. For drawing its usually better to use the higher level gameplay objects.

Note:
Detailed technical descriptions of when to use specific GFXStateBlockData fields, how GFXBlendOp works, or other interfaces of that nature are outside the scope of this manual. Since Torque is based on DirectX and OpenGL any reference documents for those APIs will provide the background needed to learn about rendering.

Enumeration Type Documentation

Back-end graphics API used by the GFX subsystem.

Enumerator:
OpenGL 

OpenGL.

D3D8 

Direct3D 8.

D3D9 

Direct3D 9.

NullDevice 

Null device for dedicated servers.

Xenon 

Direct3D 9 on Xbox 360.

enum GFXBlend

The supported blend modes.

Enumerator:
GFXBlendZero 

(0, 0, 0, 0)

GFXBlendOne 

(1, 1, 1, 1)

GFXBlendSrcColor 

(Rs, Gs, Bs, As)

GFXBlendInvSrcColor 

(1 - Rs, 1 - Gs, 1 - Bs, 1 - As)

GFXBlendSrcAlpha 

(As, As, As, As)

GFXBlendInvSrcAlpha 

( 1 - As, 1 - As, 1 - As, 1 - As)

GFXBlendDestAlpha 

(Ad Ad Ad Ad)

GFXBlendInvDestAlpha 

(1 - Ad 1 - Ad 1 - Ad 1 - Ad)

GFXBlendDestColor 

(Rd, Gd, Bd, Ad)

GFXBlendInvDestColor 

(1 - Rd, 1 - Gd, 1 - Bd, 1 - Ad)

GFXBlendSrcAlphaSat 

(f, f, f, 1) where f = min(As, 1 - Ad)

enum GFXBlendOp

The blend operators.

Enumerator:
GFXBlendOpAdd 
GFXBlendOpSubtract 
GFXBlendOpRevSubtract 
GFXBlendOpMin 
GFXBlendOpMax 
enum GFXCmpFunc

The supported comparison functions.

Enumerator:
GFXCmpNever 
GFXCmpLess 
GFXCmpEqual 
GFXCmpLessEqual 
GFXCmpGreater 
GFXCmpNotEqual 
GFXCmpGreaterEqual 
GFXCmpAlways 

The render cull modes.

Enumerator:
GFXCullNone 
GFXCullCW 
GFXCullCCW 
enum GFXFormat

The texture formats.

Note:
Not all formats are supported on all platforms.
Enumerator:
GFXFormatR8G8B8 
GFXFormatR8G8B8A8 
GFXFormatR8G8B8X8 
GFXFormatR32F 
GFXFormatR5G6B5 
GFXFormatR5G5B5A1 
GFXFormatR5G5B5X1 
GFXFormatA4L4 
GFXFormatA8L8 
GFXFormatA8 
GFXFormatL8 
GFXFormatDXT1 
GFXFormatDXT2 
GFXFormatDXT3 
GFXFormatDXT4 
GFXFormatDXT5 
GFXFormatD32 
GFXFormatD24X8 
GFXFormatD24S8 
GFXFormatD24FS8 
GFXFormatD16 
GFXFormatR32G32B32A32F 
GFXFormatR16G16B16A16F 
GFXFormatL16 
GFXFormatR16G16B16A16 
GFXFormatR16G16 
GFXFormatR16F 
GFXFormatR16G16F 
GFXFormatR10G10B10A2 

The stencil operators.

Enumerator:
GFXStencilOpKeep 
GFXStencilOpZero 
GFXStencilOpReplace 
GFXStencilOpIncrSat 
GFXStencilOpDecrSat 
GFXStencilOpInvert 
GFXStencilOpIncr 
GFXStencilOpDecr 

The texture address modes.

Enumerator:
GFXAddressWrap 
GFXAddressMirror 
GFXAddressClamp 
GFXAddressBorder 
GFXAddressMirrorOnce 

The texture arguments.

Enumerator:
GFXTADiffuse 
GFXTACurrent 
GFXTATexture 
GFXTATFactor 
GFXTASpecular 
GFXTATemp 
GFXTAConstant 
OneMinus 
AlphaReplicate 

The texture filter types.

Enumerator:
GFXTextureFilterNone 
GFXTextureFilterPoint 
GFXTextureFilterLinear 
GFXTextureFilterAnisotropic 
GFXTextureFilterPyramidalQuad 
GFXTextureFilterGaussianQuad 

The texture operators.

Enumerator:
GFXTOPDisable 
GFXTOPSelectARG1 
GFXTOPSelectARG2 
GFXTOPModulate 
GFXTOPModulate2X 
GFXTOPModulate4X 
GFXTOPAdd 
GFXTOPAddSigned 
GFXTOPAddSigned2X 
GFXTOPSubtract 
GFXTOPAddSmooth 
GFXTOPBlendDiffuseAlpha 
GFXTOPBlendTextureAlpha 
GFXTOPBlendFactorAlpha 
GFXTOPBlendTextureAlphaPM 
GFXTOPBlendCURRENTALPHA 
GFXTOPPreModulate 
GFXTOPModulateAlphaAddColor 
GFXTOPModulateColorAddAlpha 
GFXTOPModulateInvAlphaAddColor 
GFXTOPModulateInvColorAddAlpha 
GFXTOPBumpEnvMap 
GFXTOPBumpEnvMapLuminance 
GFXTOPDotProduct3 
GFXTOPLERP 

The texture transform state flags.

Enumerator:
GFXTTFDisable 
GFXTTFFCoord1D 
GFXTTFFCoord2D 
GFXTTFFCoord3D 
GFXTTFFCoord4D 
GFXTTFProjected 

The type of animation effect to apply to this material.

Enumerator:
Scroll 

Scroll the material along the X/Y axis.

Rotate 

Rotate the material around a point.

Wave 

Warps the material with an animation using Sin, Triangle or Square mathematics.

Scale 

Scales the material larger and smaller with a pulsing effect.

Sequence 

Enables the material to have multiple frames of animation in its imagemap.

The type of graphical blending operation to apply to this material.

Enumerator:
None 

Disable blending for this material.

Mul 

Multiplicative blending.

Add 

Adds the color of the material to the frame buffer with full alpha for each pixel.

AddAlpha 

The color is modulated by the alpha channel before being added to the frame buffer.

Sub 

Subtractive Blending. Reverses the color model, causing dark colors to have a stronger visual effect.

LerpAlpha 

Linearly interpolates between Material color and frame buffer color based on alpha.

When using the Wave material animation, one of these Wave Types will be used to determine the type of wave to display.

Enumerator:
Sin 

Warps the material along a curved Sin Wave.

Triangle 

Warps the material along a sharp Triangle Wave.

Square 

Warps the material along a wave which transitions between two oppposite states. As a Square Wave, the transition is quick and sudden.


Function Documentation

void cleanupTexturePool (  ) 

Release the unused pooled textures in texture manager freeing up video memory.

void clearGFXResourceFlags (  ) 

Clears the flagged state on all allocated GFX resources. See flagCurrentGFXResources for usage details.

See also:
flagCurrentGFXResources, listGFXResources, describeGFXResources
void describeGFXResources ( string  resourceTypes,
string  filePath,
bool  unflaggedOnly = false 
)

Dumps a description of GFX resources to a file or the console.

Parameters:
resourceTypes A space seperated list of resource types or an empty string for all resources.
filePath A file to dump the list to or an empty string to write to the console.
unflaggedOnly If true only unflagged resources are dumped. See flagCurrentGFXResources.
Note:
The resource types can be one or more of the following:
  • texture
  • texture target
  • window target
  • vertex buffers
  • primitive buffers
  • fences
  • cubemaps
  • shaders
  • stateblocks
void describeGFXStateBlocks ( string  filePath  ) 

Dumps a description of all state blocks.

Parameters:
filePath A file to dump the state blocks to or an empty string to write to the console.
void dumpRandomNormalMap (  ) 

Creates a 64x64 normal map texture filled with noise. The texture is saved to randNormTex.png in the location of the game executable.

void dumpTextureObjects (  ) 

Dumps a list of all active texture objects to the console.

Note:
This function is only available in debug builds.
void flagCurrentGFXResources (  ) 

Flags all currently allocated GFX resources. Used for resource allocation and leak tracking by flagging current resources then dumping a list of unflagged resources at some later point in execution.

See also:
listGFXResources, clearGFXResourceFlags, describeGFXResources
void flushTextureCache (  ) 

Releases all textures and resurrects the texture manager.

static int GFXInit::getAdapterCount (  )  [static, inherited]

Return the number of graphics adapters available.

GFXFormat getBestHDRFormat (  ) 

Returns the best texture format for storage of HDR data for the active device.

Point3F getDesktopResolution (  ) 

Returns the width, height, and bitdepth of the screen/desktop.

string getDisplayDeviceInformation (  ) 

Get the string describing the active GFX device.

String getDisplayDeviceList (  ) 

Returns a tab-seperated string of the detected devices across all adapters.

float getPixelShaderVersion (  ) 

Returns the pixel shader version for the active device.

String getTextureProfileStats (  ) 

Returns a list of texture profiles in the format: ProfileName TextureCount TextureMB.

void listGFXResources ( bool  unflaggedOnly = false  ) 

Returns a list of the unflagged GFX resources. See flagCurrentGFXResources for usage details.

See also:
flagCurrentGFXResources, clearGFXResourceFlags, describeGFXResources
void reloadTextures (  ) 

Reload all the textures from disk.

void screenShot ( string  file,
string  format,
int  tileCount = 1,
float  tileOverlap = 0 
)

Takes a screenshot with optional tiling to produce huge screenshots.

Parameters:
file The output image file path.
format Either JPEG or PNG.
tileCount If greater than 1 will tile the current screen size to take a large format screenshot.
tileOverlap The amount of horizontal and vertical overlap between the tiles used to remove tile edge artifacts from post effects.
void setPixelShaderVersion ( float  version  ) 

Sets the pixel shader version for the active device. This can be used to force a lower pixel shader version than is supported by the device for testing or performance optimization.

Parameters:
version The floating point shader version number.
Note:
This will only affect shaders/materials created after the call and should be used before the game begins.
See also:
$pref::Video::forcedPixVersion
void setReflectFormat ( GFXFormat  format  ) 

Set the reflection texture format.


Variable Documentation

bool $gfx::disableOcclusionQuery

Debug helper that disables all hardware occlusion queries causing them to return only the visibile state.

bool $pref::Video::disableVerticalSync

Disables vertical sync on the active device.

Note:
The video mode must be reset for the change to take affect.
bool $gfx::disassembleAllShaders

On supported devices this will dump shader disassembly to the procedural shader folder.

float $pref::Video::forcedPixVersion

Will force the shader model if the value is positive and less than the shader model supported by the active device. Use 0 for fixed function.

Note:
The graphics device must be reset for the change to take affect.
int $pref::Video::textureReductionLevel

The number of mipmap levels to drop on loaded textures to reduce video memory usage. It will skip any textures that have been defined as not allowing down scaling.

bool $gfx::wireframe

Used to toggle wireframe rendering at runtime.



Copyright © GarageGames, LLC. All Rights Reserved.