21.45. The ShadowMapping Object

This object is used by the renderers to create an array of shadow map textures for lights in the scene.

The ShadowMapping object will request the following shaders to the ShaderManager:

• shaders/shadowmapping.cgfx

Shadow mapping is enabled by setting the shadowRendering option when the renderer is created:

renderer = Renderer.create(graphicsDevice,
                           mathDevice,
                           shaderManager,
                           effectManager,
                           { shadowRendering: true });

Here Renderer can be either DeferredRendering or ForwardRendering.

To enable shadows for a light set the shadows argument when it is created:

var light = Light.create(
    {
        name : lightName,
        color : color,
        point : true,
        shadows : true,
        halfExtents: v3Build.call(mathDevice, 40, 40, 40),
        origin: v3Build.call(mathDevice, 0, 10, 0),
        material : lightMaterial
    });

Only point and spot lights support shadows.

By default all materials cast shadows. If you want a material to ignore this you can set the noshadows flag:

var material = Material.create(graphicsDevice);
material.meta.noshadows = true;

Required scripts

The ShadowMapping object requires:

/*{{ javascript("jslib/shadowmapping.js") }}*/
/*{{ javascript("jslib/camera.js") }}*/

21.45.1. Constructor

21.45.1.1. create

Summary

Creates and returns a ShadowMapping object.

Syntax

var shadowMapping = ShadowMapping.create(graphicsDevice, mathsDevice, shaderManager, effectsManager, sizeLow, sizeHigh);

sizeLow

A JavaScript number. The size in pixels of the low resolution shadow maps. Defaults to 512.

sizeHigh

A JavaScript number. The size in pixels of the high resolution shadow maps. Defaults to 1024.

Returns a ShadowMapping object.

21.45.2. Methods

21.45.2.1. updateShader

Summary

Updates the shadow mapping shader.

Syntax

shadowMapping.updateShader();

21.45.2.2. update

Summary

The default update function to be registered on the effects by the renderer.

Syntax

effect = Effect.create("blinn");
effectManager.add(effect);

effectTypeData = {  prepare : forwardPrepareFn,
                    shaderName : "shaders/forwardrendering.cgfx",
                    techniqueName : "blinn",
                    update : forwardUpdateFn,
                    shadowMappingShaderName : "shaders/shadowmapping.cgfx",
                    shadowMappingTechniqueName : "rigid",
                    shadowMappingUpdate : shadowMapping.update,
                    loadTechniques : loadTechniques };
effectTypeData.loadTechniques(shaderManager);
effect.add(rigid, effectTypeData);

21.45.2.3. skinnedUpdate

Summary

The default skinned update function to be registered on the effects by the renderer.

Syntax

effect = Effect.create("blinn_skinned");
effectManager.add(effect);

effectTypeData = {  prepare : forwardPrepareFn,
                    shaderName : "shaders/forwardrendering.cgfx",
                    techniqueName : "blinn_skinned",
                    update : forwardUpdateFn,
                    shadowMappingShaderName : "shaders/shadowmapping.cgfx",
                    shadowMappingTechniqueName : "skinned",
                    shadowMappingUpdate : shadowMapping.skinnedUpdate,
                    loadTechniques : loadTechniques };
effectTypeData.loadTechniques(shaderManager);
effect.add(rigid, effectTypeData);

21.45.2.4. updateBuffers

Summary

Update all the buffers and textures used by the ShadowMapping object to use new texture sizes.

Syntax

shadowMapping.updateBuffers(sizeLow, sizeHigh);

sizeLow

A JavaScript number. The size in pixels of the low resolution shadow maps. Defaults to 512.

sizeHigh

A JavaScript number. The size in pixels of the high resolution shadow maps. Defaults to 1024.

Returns true if buffers where updated successfully, false otherwise. If sizeLow and sizeHigh are the same as the current low and high resolution values then no update is done and the function returns true. If sizeLow and sizeHigh are undefined then the buffers are recreated with their previous resolutions.

21.45.2.5. destroyBuffers

Summary

Destroy all the buffers and textures used by the ShadowMapping object.

Syntax

shadowMapping.destroyBuffers();

21.45.2.6. drawShadowMap

Summary

Draw the shadow map for a light instance.

Syntax

cameraMatrix = camera.matrix;
shadowMapping.drawShadowMap(cameraMatrix, minExtentsHigh, lightInstance);

cameraMatrix

The viewing camera matrix.

minExtentsHigh

A JavaScript number. If any of the lights extents components are greater than this value then a high resolution map is generated, otherwise a low resolution map is generated.

lightInstance

The LightInstance object to draw a shadow map for.

Returns null. The function adds the following properties to the lightInstance object:

• If the shadow map is not empty then shadows is set to true, false otherwise.

• shadowMap ShadowMap object for lightInstance.

• The following TechniqueParameters are added to the lightInstance.techniqueParameters:

  • shadowProjection - The projection matrix Matrix43 from model space to light space.
  • shadowDepth - A Vector4. The dot product of this vector with a world position gives its depth from the light’s perspective.
  • shadowSize - A JavaScript number giving size of the texture in pixels (assumed to be a square).
  • shadowMapTexture - The exponential shadow map Texture object.

Note

Currently this function will continue to draw shadows for static nodes when they or their renderables are disabled.

21.45.2.7. blurShadowMaps

Summary

Blur all of the shadow maps to give softer shadows.

Syntax

shadowMapping.blurShadowMaps();

21.45.2.8. destroy

Summary

Releases the ShadowMapping object and all the resources it allocated.

Syntax

shadowMapping.destroy();

21.45.3. Properties

21.45.3.1. version

Summary

The version number of the ShadowMapping implementation.

Syntax

var versionNumber = shadowMapping.version;

21.46. The ShadowMap Object

21.46.1. Properties

21.46.1.1. texture

Summary

The exponential shadow map’s texture.

Syntax

var shadowMapTexture = shadowMap.texture;

A Texture object. The shadow map texture is given in RGBA format.

21.46.1.2. renderTarget

Summary

The exponential shadow map’s render target.

Syntax

var shadowMapRenderTarget = shadowMap.renderTarget;

A RenderTarget object.

21.46.1.3. lightInstance

Summary

The light instance for the exponential shadow map.

Syntax

var shadowMapLightInstance = shadowMap.lightInstance;

A lightInstance object.