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

enum GFXAdapterType

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

enum GFXCullMode

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

enum GFXStencilOp

The stencil operators.

Enumerator:

GFXStencilOpKeep
GFXStencilOpZero
GFXStencilOpReplace
GFXStencilOpIncrSat
GFXStencilOpDecrSat
GFXStencilOpInvert
GFXStencilOpIncr
GFXStencilOpDecr

enum GFXTextureAddressMode

The texture address modes.

Enumerator:

GFXAddressWrap
GFXAddressMirror
GFXAddressClamp
GFXAddressBorder
GFXAddressMirrorOnce

enum GFXTextureArgument

The texture arguments.

Enumerator:

GFXTADiffuse
GFXTACurrent
GFXTATexture
GFXTATFactor
GFXTASpecular
GFXTATemp
GFXTAConstant
OneMinus
AlphaReplicate

enum GFXTextureFilterType

The texture filter types.

Enumerator:

GFXTextureFilterNone
GFXTextureFilterPoint
GFXTextureFilterLinear
GFXTextureFilterAnisotropic
GFXTextureFilterPyramidalQuad
GFXTextureFilterGaussianQuad

enum GFXTextureOp

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

enum GFXTextureTransformFlags

The texture transform state flags.

Enumerator:

GFXTTFDisable
GFXTTFFCoord1D
GFXTTFFCoord2D
GFXTTFFCoord3D
GFXTTFFCoord4D
GFXTTFProjected

enum MaterialAnimType

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.

enum MaterialBlendOp

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.

enum MaterialWaveType

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.