Xors3d Engine
Shaders effects

Functions

void xClearEffectConstants (Entity *entity, int layer=-1)
 Clears all passed constansts.
void xClearFXConstants (Effect *effect)
 Deletes all the global values of the constants from an effect.
void xClearSurfaceConstants (Surface *surface, int layer=-1)
 Clears all passed constansts of surface.
void xDeleteEffectConstant (Entity *entity, const char *name, int layer=-1)
 Deletes a specified effect constant.
void xDeleteFXConstant (Effect *effect, const char *name)
 Deletes a global value of a constant from an effect.
void xDeleteSurfaceConstant (Surface *surface, const char *name, int layer=-1)
 Deletes a specified surface's effect constant.
void xFreeEffect (Effect *effect)
 Frees up an effect.
int xGetEntityShaderLayer (Entity *entity)
 Returns an active shader layer of an entity.
int xGetSurfaceShaderLayer (Surface *surface)
 Returns an active shader layer of a surface.
Effect * xLoadFXFile (const char *path)
 Loads an effect from file.
void xSetBonesArrayName (Entity *entity, const char *arrayName, int layer=-1)
 Sets a name of shader constant to pass bones for skinning computing.
void xSetEffectBool (Entity *entity, const char *name, bool value, int layer=-1)
 Sets a boolean constant value for entity shaders.
void xSetEffectEntityTexture (Entity *entity, const char *name, int index=0, int layer=-1)
 Sets shader texture constant by entity's texture.
void xSetEffectFloat (Entity *entity, const char *name, float value, int layer=-1)
 Sets a floating constant value for entity shaders.
void xSetEffectFloatArray (Entity *entity, const char *name, float *value, int count, int layer=-1)
 Sets a floating array constant for entity shaders.
void xSetEffectInt (Entity *entity, const char *name, int value, int layer=-1)
 Sets an integer constant value for entity shaders.
void xSetEffectIntArray (Entity *entity, const char *name, int *value, int count, int layer=-1)
 Sets an integer array constant for entity shaders.
void xSetEffectMatrix (Entity *entity, const char *name, float *matrix, int layer=-1)
 Sets a matrix constant value for entity shaders.
void xSetEffectMatrixArray (Entity *entity, const char *name, Matrix44 *value, int count, int layer=-1)
 Sets a matrices array constant for shaders.
void xSetEffectMatrixSemantic (Entity *entity, const char *name, int value, int layer=-1)
 Sets a matrix constant for entity shaders by matrix semantic.
void xSetEffectTechnique (Entity *entity, const char *name, int layer=-1)
 Sets active effect rendering technique.
void xSetEffectTexture (Entity *entity, const char *name, Texture *texture, int frame=0, int layer=-1, int isRecursive=1)
 Sets a texture constant for entity shader.
void xSetEffectVector (Entity *entity, const char *name, float x, float y, float z, float w=0.0f, int layer=-1)
 Sets a vector constant for entity shader.
void xSetEffectVectorArray (Entity *entity, const char *name, Vector4 *value, int count, int layer=-1)
 Sets a vectors array constant for entity shaders.
void xSetEntityEffect (Entity *entity, Effect *effect, int index=-1)
 Assings shader effect to entity.
void xSetEntityShaderLayer (Entity *entity, int layer)
 Sets an active shader layer for an entity.
void xSetFXBool (Effect *effect, const char *name, bool value)
 Sets a global value of a boolean constant for an effect.
void xSetFXEntityMatrix (Effect *effect, const char *name, Matrix44 *matrix)
 Sets a global value of a matrix constant for an effect.
void xSetFXFloat (Effect *effect, const char *name, float value)
 Sets a global value of a floating-point constant for an effect.
void xSetFXFloatArray (Effect *effect, const char *name, float *value, int count)
 Sets a global value of a floating-point array constant for an effect.
void xSetFXInt (Effect *effect, const char *name, int value)
 Sets a global value of a integer constant for an effect.
void xSetFXIntArray (Effect *effect, const char *name, int *value, int count)
 Sets a global value of an integer array constant for an effect.
void xSetFXMatrixArray (Effect *effect, const char *name, Matrix44 *value, int count)
 Sets a global value of a matrices array constant for an effect.
void xSetFXMatrixSemantic (Effect *effect, const char *name, int value)
 Sets an global value of a matrix semantic constant for an effect.
void xSetFXTechnique (Effect *effect, const char *name)
 Sets a global technique name for effect.
void xSetFXTexture (Effect *effect, const char *name, Texture *texture, int frame=0)
 Sets a global value of a texture constant for an effect.
void xSetFXVector (Effect *effect, const char *name, float x, float y, float z, float w=0.0f)
 Sets a global value of a vector constant for an effect.
void xSetFXVectorArray (Effect *effect, const char *name, Vector4 *value, int count)
 Sets a global value of a vectors array constant for an effect.
void xSetSurfaceEffect (Surface *surface, Effect *effect, int index=-1)
 Sets shader effect for surface.
void xSetSurfaceShaderLayer (Surface *surface, int layer)
 Sets an active shader layer for a surface.
void xSurfaceBonesArrayName (Surface *surface, const char *arrayName, int layer=-1)
 Sets shader constant name for passing bones for skinning computing.
void xSurfaceEffectBool (Surface *surface, const char *name, bool value, int layer=-1)
 Sets a boolean constant value for surface shaders.
void xSurfaceEffectFloat (Surface *surface, const char *name, float value, int layer=-1)
 Sets a floating constant value for surface shaders.
void xSurfaceEffectFloatArray (Surface *surface, const char *name, float *value, int count, int layer=-1)
 Sets a floating array constant for surface shaders.
void xSurfaceEffectInt (Surface *surface, const char *name, int value, int layer=-1)
 Sets shaders integer constant value.
void xSurfaceEffectIntArray (Surface *surface, const char *name, int *value, int count, int layer=-1)
 Sets an integer array constant for surface shaders.
void xSurfaceEffectMatrix (Surface *surface, const char *name, float *matrix, int layer=-1)
 Sets a matrix constant value for surface shaders.
void xSurfaceEffectMatrixArray (Surface *surface, const char *name, Matrix44 *value, int count, int layer=-1)
 Sets a matrices array constant for surface shaders.
void xSurfaceEffectMatrixSemantic (Surface *surface, const char *name, int value, int layer=-1)
 Sets a matrix constant for surface shaders by matrix semantic.
void xSurfaceEffectTexture (Surface *surface, const char *name, Texture *texture, int frame=0, int layer=-1)
 Sets a texture constant for surface shader.
void xSurfaceEffectVector (Surface *surface, const char *name, float x, float y, float z, float w=0.0f, int layer=-1)
 Sets a vector constant for surface shader.
void xSurfaceEffectVectorArray (Surface *surface, const char *name, Vector4 *value, int count, int layer=-1)
 Sets a vectors array constant for surface shaders.
void xSurfaceTechnique (Surface *surface, const char *name, int layer=-1)
 Sets active surface's effect rendering technique.
int xValidateEffectTechnique (Effect *effect, const char *name)
 Returns true if hardware supports specified technique.

Function Documentation

Effect* xLoadFXFile ( const char *  path)

Loads an effect from file.

Xors3D supports DirectX effects files (it uses HLSL as shaders language), it's more powerful and easy to use than regular shaders, you can change render states manually, make multi-pass effects and much more.

Parameters:
pathString containing filename of effect file
void xFreeEffect ( Effect *  effect)

Frees up an effect.

Parameters:
effectEffect handle
void xSetEntityEffect ( Entity *  entity,
Effect *  effect,
int  index = -1 
)

Assings shader effect to entity.

Parameters:
entityEntity handle
effectEffect handle
indexIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetSurfaceEffect ( Surface *  surface,
Effect *  effect,
int  index = -1 
)

Sets shader effect for surface.

Parameters:
surfaceSurafce handle
effectEffect handle
indexIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetBonesArrayName ( Entity *  entity,
const char *  arrayName,
int  layer = -1 
)

Sets a name of shader constant to pass bones for skinning computing.

If you use hardware skinning, you must pass bones transformation matrices in shader and transform vertices in it.

Parameters:
entityEntity handle
arrayNameName of shader constant for passing bones matrices
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceBonesArrayName ( Surface *  surface,
const char *  arrayName,
int  layer = -1 
)

Sets shader constant name for passing bones for skinning computing.

If you use hadrware skinning, you should pass bone transformation matrices to shader and transform vertices in it. This command specify constant name for each surface in mesh separatly.

Parameters:
surfaceSurface handle
arrayNameName of shader constant for passing bone matrices
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectInt ( Entity *  entity,
const char *  name,
int  value,
int  layer = -1 
)

Sets an integer constant value for entity shaders.

Parameters:
entityEntity handle
nameConstant name
valueConstant value
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectInt ( Surface *  surface,
const char *  name,
int  value,
int  layer = -1 
)

Sets shaders integer constant value.

Parameters:
surfaceSurface handle
nameConstant name
valueConstant value
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectFloat ( Entity *  entity,
const char *  name,
float  value,
int  layer = -1 
)

Sets a floating constant value for entity shaders.

Parameters:
entityEntity handle
nameConstant name
valueConstant value
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectFloat ( Surface *  surface,
const char *  name,
float  value,
int  layer = -1 
)

Sets a floating constant value for surface shaders.

Parameters:
surfaceSurface handle
nameConstant name
valueConstant value
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectBool ( Entity *  entity,
const char *  name,
bool  value,
int  layer = -1 
)

Sets a boolean constant value for entity shaders.

Parameters:
entityEntity handle
nameConstant name
valueConstant value
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectBool ( Surface *  surface,
const char *  name,
bool  value,
int  layer = -1 
)

Sets a boolean constant value for surface shaders.

Parameters:
surfaceSurface handle
nameConstant name
valueConstant value
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectVector ( Entity *  entity,
const char *  name,
float  x,
float  y,
float  z,
float  w = 0.0f,
int  layer = -1 
)

Sets a vector constant for entity shader.

Parameters:
entityEntity handle
nameConstant name
xVertor's x component
yVertor's y component
zVertor's z component
wVertor's w component
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectVector ( Surface *  surface,
const char *  name,
float  x,
float  y,
float  z,
float  w = 0.0f,
int  layer = -1 
)

Sets a vector constant for surface shader.

Parameters:
surfaceSurface handle
nameConstant name
xVertor's x component
yVertor's y component
zVertor's z component
wVertor's w component
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectVectorArray ( Entity *  entity,
const char *  name,
Vector4 *  value,
int  count,
int  layer = -1 
)

Sets a vectors array constant for entity shaders.

Parameters:
entityEntity handle
nameConstant name
valuePointer to vectors array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectVectorArray ( Surface *  surface,
const char *  name,
Vector4 *  value,
int  count,
int  layer = -1 
)

Sets a vectors array constant for surface shaders.

Parameters:
surfaceSurface handle
nameConstant name
valuePointer to vectors array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectMatrixArray ( Surface *  surface,
const char *  name,
Matrix44 *  value,
int  count,
int  layer = -1 
)

Sets a matrices array constant for surface shaders.

Parameters:
surfaceSurface handle
nameConstant name
valuePointer to matrices array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectFloatArray ( Surface *  surface,
const char *  name,
float *  value,
int  count,
int  layer = -1 
)

Sets a floating array constant for surface shaders.

Parameters:
surfaceSurface handle
nameConstant name
valuePointer to floating array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectIntArray ( Surface *  surface,
const char *  name,
int *  value,
int  count,
int  layer = -1 
)

Sets an integer array constant for surface shaders.

Parameters:
surfaceSurface handle
nameConstant name
valuePointer to integer array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectMatrixArray ( Entity *  entity,
const char *  name,
Matrix44 *  value,
int  count,
int  layer = -1 
)

Sets a matrices array constant for shaders.

Parameters:
entityEntity handle
nameConstant name
valuePointer to matrices array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectFloatArray ( Entity *  entity,
const char *  name,
float *  value,
int  count,
int  layer = -1 
)

Sets a floating array constant for entity shaders.

Parameters:
entityEntity handle
nameConstant name
valuePointer to floating array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectIntArray ( Entity *  entity,
const char *  name,
int *  value,
int  count,
int  layer = -1 
)

Sets an integer array constant for entity shaders.

Parameters:
entityEntity handle
nameConstant name
valuePointer to integer array
countNumber of elements in array
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectMatrix ( Entity *  entity,
const char *  name,
float *  matrix,
int  layer = -1 
)

Sets a matrix constant value for entity shaders.

Use with pointer to the matrix returned by xGetProjectionMatrix(), xGetViewMatrix(), xGetViewProjMatrix() and xGetEntityMatrix().

Parameters:
entityEntity handle
nameConstant name
matrixPointer to matrix
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectMatrix ( Surface *  surface,
const char *  name,
float *  matrix,
int  layer = -1 
)

Sets a matrix constant value for surface shaders.

Use with pointer to the matrix returned by xGetProjectionMatrix(), xGetViewMatrix(), xGetViewProjMatrix() and xGetEntityMatrix().

Parameters:
surfaceSurface handle
nameConstant name
matrixPointer to matrix
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectEntityTexture ( Entity *  entity,
const char *  name,
int  index = 0,
int  layer = -1 
)

Sets shader texture constant by entity's texture.

You can use it for automatic passing textures loaded with mesh or applied by xEntityTexture() to a shader.

Parameters:
entityEntity handle
nameConstant name
indexTextre layer index. Must be in range 0-7
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectTexture ( Entity *  entity,
const char *  name,
Texture *  texture,
int  frame = 0,
int  layer = -1,
int  isRecursive = 1 
)

Sets a texture constant for entity shader.

Parameters:
entityEntity handle
nameConstant name
textureTexture handle
frameTexture frame
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
isRecursiveIf 1 (true) then entity's children will receive the texture too.
void xSurfaceEffectTexture ( Surface *  surface,
const char *  name,
Texture *  texture,
int  frame = 0,
int  layer = -1 
)

Sets a texture constant for surface shader.

Parameters:
surfaceSurface handle
nameConstant name
textureTexture handle
frameTexture frame
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceEffectMatrixSemantic ( Surface *  surface,
const char *  name,
int  value,
int  layer = -1 
)

Sets a matrix constant for surface shaders by matrix semantic.

See 'Matrix semantics' for more infromation.

Parameters:
surfaceSurface handle
nameConstant name
valueMatrix semantic
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectMatrixSemantic ( Entity *  entity,
const char *  name,
int  value,
int  layer = -1 
)

Sets a matrix constant for entity shaders by matrix semantic.

See 'Matrix semantics' for more infromation.

Parameters:
entityEntity handle
nameConstant name
valueMatrix semantic
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xDeleteSurfaceConstant ( Surface *  surface,
const char *  name,
int  layer = -1 
)

Deletes a specified surface's effect constant.

Parameters:
surfaceSurface handle
nameConstant name
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xDeleteEffectConstant ( Entity *  entity,
const char *  name,
int  layer = -1 
)

Deletes a specified effect constant.

Parameters:
entityEntity handle
nameConstant name
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xClearSurfaceConstants ( Surface *  surface,
int  layer = -1 
)

Clears all passed constansts of surface.

This function deletes all constants passed into effect (by functions like xSurfaceEffectInt(), xSurfaceEffectTexture() etc).

Parameters:
surfaceSurface handle
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xClearEffectConstants ( Entity *  entity,
int  layer = -1 
)

Clears all passed constansts.

This function deletes all constants passed into effect (by functions like xSetEffectInt(), xSetEffectTexture() etc).

Parameters:
entityEntity handle
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSetEffectTechnique ( Entity *  entity,
const char *  name,
int  layer = -1 
)

Sets active effect rendering technique.

You may check support of technique by hardware using xValidateEffectTechnique()

Parameters:
entityEntity handle
nameTechnique name
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
void xSurfaceTechnique ( Surface *  surface,
const char *  name,
int  layer = -1 
)

Sets active surface's effect rendering technique.

You may check support technique on hadware by xValidateEffectTechnique()

Parameters:
surfaceSurface handle
nameTechnique name
layerIndex of the effect layer in range [0; 7]. If -1 is passed - active layer will be used (see xSetShaderLayer())
int xValidateEffectTechnique ( Effect *  effect,
const char *  name 
)

Returns true if hardware supports specified technique.

Parameters:
effectEffect handle
nameTechnique name
void xSetEntityShaderLayer ( Entity *  entity,
int  layer 
)

Sets an active shader layer for an entity.

This value overrides a global shader layer. If -1 is passed - a global value will be used

int xGetEntityShaderLayer ( Entity *  entity)

Returns an active shader layer of an entity.

void xSetSurfaceShaderLayer ( Surface *  surface,
int  layer 
)

Sets an active shader layer for a surface.

This value overrides a global shader layer. If -1 is passed - a global value will be used

int xGetSurfaceShaderLayer ( Surface *  surface)

Returns an active shader layer of a surface.

void xSetFXInt ( Effect *  effect,
const char *  name,
int  value 
)

Sets a global value of a integer constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
void xSetFXFloat ( Effect *  effect,
const char *  name,
float  value 
)

Sets a global value of a floating-point constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
void xSetFXBool ( Effect *  effect,
const char *  name,
bool  value 
)

Sets a global value of a boolean constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
void xSetFXVector ( Effect *  effect,
const char *  name,
float  x,
float  y,
float  z,
float  w = 0.0f 
)

Sets a global value of a vector constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
xX-component of the vector
yY-component of the vector
zZ-component of the vector
wW-component of the vector
void xSetFXVectorArray ( Effect *  effect,
const char *  name,
Vector4 *  value,
int  count 
)

Sets a global value of a vectors array constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
countArray size
void xSetFXMatrixArray ( Effect *  effect,
const char *  name,
Matrix44 *  value,
int  count 
)

Sets a global value of a matrices array constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
countArray size
void xSetFXFloatArray ( Effect *  effect,
const char *  name,
float *  value,
int  count 
)

Sets a global value of a floating-point array constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
countArray size
void xSetFXIntArray ( Effect *  effect,
const char *  name,
int *  value,
int  count 
)

Sets a global value of an integer array constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueConstant value
countArray size
void xSetFXEntityMatrix ( Effect *  effect,
const char *  name,
Matrix44 *  matrix 
)

Sets a global value of a matrix constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
matrixMatrix value
void xSetFXTexture ( Effect *  effect,
const char *  name,
Texture *  texture,
int  frame = 0 
)

Sets a global value of a texture constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
textureTexture handle
frameTexture's frame index
void xSetFXMatrixSemantic ( Effect *  effect,
const char *  name,
int  value 
)

Sets an global value of a matrix semantic constant for an effect.

This value will override all mesh or surface constants with same name.

Parameters:
effectEffect handle
nameConstant name
valueSemantic value
void xDeleteFXConstant ( Effect *  effect,
const char *  name 
)

Deletes a global value of a constant from an effect.

Parameters:
effectEffect handle
nameConstant name
void xClearFXConstants ( Effect *  effect)

Deletes all the global values of the constants from an effect.

Parameters:
effectEffect handle
void xSetFXTechnique ( Effect *  effect,
const char *  name 
)

Sets a global technique name for effect.

This value will override all mesh or surface techniques.

Parameters:
effectEffect handle
nameTechnique name