Xors3d Engine
Shadows

Functions

BBDECL void BBCALL xCameraDisableShadows (Camera *camera)
 Disables shadow rendering for the specified camera.
BBDECL void BBCALL xCameraEnableShadows (Camera *camera)
 Enables shadow rendering for the specified camera.
BBDECL void BBCALL xEntityCastShadows (Entity *entity, Light *light, bool state)
 Enables or disables shadow casting for an entity.
BBDECL int BBCALL xEntityIsCaster (Entity *entity, Light *light)
 Checks if an entity casts shadows from the light source.
BBDECL int BBCALL xEntityIsReceiver (Entity *entity, Light *light)
 Checks if entity receive shadows from the light source.
BBDECL void BBCALL xEntityReceiveShadows (Entity *entity, Light *light, bool state)
 Enables or disables shadow receiving for an entity.
BBDECL Effect *BBCALL xInitShadows (int dirSize, int spotSize, int pointSize)
 Initializes the shadow system and returns the handle of the shadow shader.
BBDECL void BBCALL xLightEnableShadows (Light *light, int state)
 Enables or disables shadow casting for light.
BBDECL void BBCALL xLightShadowEpsilons (Light *light, float epsilon1, float epsilon2)
 Sets epsilon values of light source.
BBDECL int BBCALL xLightShadowsEnabled (Light *light)
 Checks if light source has shadows.
BBDECL void BBCALL xSetShadowParams (int splitPlanes=4, float splitLambda=0.95f, bool useOrtho=true, float lightDist=300.0f)
 Sets parameters of the shadow system.
BBDECL void BBCALL xSetShadowsBlur (int blurLevel)
 Sets the level of Gaussian blur for the shadows.
BBDECL void BBCALL xSetShadowShader (const char *path)
 Sets a path to the shadow shader (e.g. "shaders\mySmartShadows.hlsl").
BBDECL void BBCALL xShadowPriority (int priority)
 Sets the minimum priority of the shadow casting.

Function Documentation

BBDECL void BBCALL xLightShadowEpsilons ( Light *  light,
float  epsilon1,
float  epsilon2 
)

Sets epsilon values of light source.

Every light sources has 2 epsilon values for shadows rendering. First value is a depth bias (it's needed to compensate inaccuracy of floating-point values), second value is to prevent shadowing of angularly triangles. Epsilons delete some noise from shadows, but can lead to incorrect rejection of a part of shadow. Default values are optimal, but you may need to adjust them for best results.

Parameters:
lightLight source handle
epsilon1First epsilon value (compensates inaccuracy of floating-point values)
epsilon2Second epsilon value (prevents shadowing of angularly triangles), actually it is a cosine of maximum angle of shadowed triangle.
BBDECL void BBCALL xLightEnableShadows ( Light *  light,
int  state 
)

Enables or disables shadow casting for light.

You should set casting priority for light source greater than zero to enable shadow casting from it. Priority allows you to change shadows quality in your game, for more information see xShadowPriority()

Parameters:
lightLight source handle
stateLight casting priority
See also:
xShadowPriority()
BBDECL int BBCALL xLightShadowsEnabled ( Light *  light)

Checks if light source has shadows.

Parameters:
lightLight source to be checked
BBDECL void BBCALL xSetShadowsBlur ( int  blurLevel)

Sets the level of Gaussian blur for the shadows.

Parameters:
blurLevelThe level of blur. See 'The levels of blur for the shadows.' for more information about the constants.
BBDECL void BBCALL xSetShadowShader ( const char *  path)

Sets a path to the shadow shader (e.g. "shaders\mySmartShadows.hlsl").

Specified shader must contain code for rendring shadow maps (writing depth textures), final scene rendering with shadows, and mixing the result from all light sources. If no shader is specified in this function - default built-in shader is used.

Parameters:
pathShader file name.
BBDECL Effect* BBCALL xInitShadows ( int  dirSize,
int  spotSize,
int  pointSize 
)

Initializes the shadow system and returns the handle of the shadow shader.

You should call this function to use shadows. You can specify the size of the shadow maps for all types of lights separately. If you set 0 the shadow map will not be created for this type of light, you can't cast shadows from this light, but you will save some video memory.

Parameters:
dirSizeSize of the shadow map for directional light.
spotSizeSize of the shadow map for spot light.
pointSizeSize of the shadow map for point light (uses cube map, and requires 6 renders of the scene per shadow map)
Returns:
The shadow shader handle.
BBDECL void BBCALL xSetShadowParams ( int  splitPlanes = 4,
float  splitLambda = 0.95f,
bool  useOrtho = true,
float  lightDist = 300.0f 
)

Sets parameters of the shadow system.

You can change number of PSSM split planes (PSSM technique splits visible scene in some parts, each part will be rendered separately to its own shadow map. It increases quality of shadows near camera, but may cause loss of quality in large distance from camera), and split lambda. We set optimal values, but you may change them for better quality or better perfomance. Also you can change projection type for shadow map rendering, and set the distance of light source from the camera view point (larger distance causes larger part of scene which casts shadows, but quality of the shadows is poorer).

Parameters:
splitPlanesNumber of split planes for PSSM rendering. The number of split planes is equal to the number of shadow maps for the directional light.
splitLambdaThe ratio of the scene splitting in range (0.0; 1.0).
useOrthoTrue to use orthographical projection, false - for perspective projection.
lightDistDistance from light source to the view point.
BBDECL void BBCALL xShadowPriority ( int  priority)

Sets the minimum priority of the shadow casting.

All light sources have the shadow casting priority. If priority is greater than zero - light source will cast shadows. But you can set the global priority and shadow casting will be disabled for all light sources, which priority is less than the global one. You can use it for changing shadow quality in your game (enable more light for powerful machines, and disable it for old hardware) using one command.

Parameters:
priorityGlobal shadow casting priority.
BBDECL void BBCALL xCameraDisableShadows ( Camera *  camera)

Disables shadow rendering for the specified camera.

Parameters:
cameraCamera handle.
See also:
xCameraEnableShadows()
BBDECL void BBCALL xCameraEnableShadows ( Camera *  camera)

Enables shadow rendering for the specified camera.

Parameters:
cameraCamera handle.
See also:
xCameraDisableShadows()
BBDECL void BBCALL xEntityCastShadows ( Entity *  entity,
Light *  light,
bool  state 
)

Enables or disables shadow casting for an entity.

In some cases you need some entity not casting the shadows from a specified light source (e.g. light bulb). This function excludes the entity from the list of shadow casters. By default entity casts shadows from all light sources.

Note: Any transparent or ordered entity is automtically excluded from the list of casters.

Parameters:
entityEntity to be excluded from the list of casters.
lightLight source from which the entity will not cast shadows. Set 1 to affect all the lights.
stateTrue to make the entity cast shadows, false for otherwise.
See also:
xEntityIsCaster()
BBDECL void BBCALL xEntityReceiveShadows ( Entity *  entity,
Light *  light,
bool  state 
)

Enables or disables shadow receiving for an entity.

In some cases you need some entity not receiving the shadows from a specified light source (e.g. fullbrighted entity). This function excludes the entity from the list of shadow receivers. By default entity receives shadows from all light sources.

Note: Any transparent or ordered entity is automtically excluded from the list of receivers.

Parameters:
entityEntity to be excluded from the list of receivers.
lightLight source from which the entity will not receive shadows. Set 1 to affect all the lights.
stateTrue to make the entity receive shadows, false for otherwise.
See also:
xEntityIsReceiver()
BBDECL int BBCALL xEntityIsCaster ( Entity *  entity,
Light *  light 
)

Checks if an entity casts shadows from the light source.

Parameters:
entityEntity to be checked.
lightLight to be checked.
See also:
xEntityCastShadows()
BBDECL int BBCALL xEntityIsReceiver ( Entity *  entity,
Light *  light 
)

Checks if entity receive shadows from the light source.

Parameters:
entityEntity to be checked.
lightLight to be checked.
See also:
xEntityReceiveShadows()