Skip to main content
Parallel Split Shadow Mapping         (PSSM) - A method for high-detail shadows
1
Page actions
Print

Note: As of Ogre 1.6 PSSM is an officially supported technique. See Ogre 1.6 and it's PSSM demo (in PlayPen project). Specifically the Camera class has been altered to correctly support it.

All of the known shadow mapping techniques exhibit shadow quality problems due to the disparity between the distribution of shadowmap texels and screen pixels. These problems are most acute when the eye direction is near-parallel to the light direction.

The Parallel Split Shadow Maps (PSSM) proposed by Zhang (et al.) go some way to alleviating this issue by splitting the view frustum into parallel chunks along the z axis.

Ogre provides a way to do PSSM by means of multiple shadow textures. To do this, create a ShadowListener (Eihort) (to be renamed SceneManager::Listener in later versions):

Copy to clipboard
#include "OgreSceneManager.h"
class PSSMShadowListener:public Ogre::ShadowListener
{
    Ogre::Light *light;
    Ogre::ShadowCameraSetupPtr setup;
    Ogre::Camera *view_camera;        // NOT shadow camera!
    Ogre::SceneManager *sceneMgr;
    mutable int split_index;
public:
    PSSMShadowListener(Ogre::SceneManager *sm,Ogre::Light *l,Ogre::ShadowCameraSetupPtr s,Ogre::Camera *cam);
    virtual ~PSSMShadowListener() {}
    virtual void shadowTexturesUpdated(size_t numberOfShadowTextures);
    virtual void shadowTextureCasterPreViewProj(Ogre::Light* light,Ogre::Camera* camera);
    virtual void shadowTextureReceiverPreViewProj(Ogre::Light* light,Ogre::Frustum* frustum);
    virtual bool sortLightsAffectingFrustum(Ogre::LightList& lightList);
};

This is implemented as follows. We initialize with the scene's manager, its main light, the shadow camera setup pointer, and the view camera:

Copy to clipboard
PSSMShadowListener::PSSMShadowListener(Ogre::SceneManager *sm,Ogre::Light *l,ShadowCameraSetupPtr s,Camera *cam)
{
    sceneMgr=sm;
    light=l;
    setup=s;
    view_camera=cam;
    split_index=0;
}

The main work is done in shadowTextureCasterPreViewProj(), which overrides the default behaviour for making the shadow matrix. This function is passed a light and a camera - the shadow camera.
In this case the splits are hard-coded at 10 and 70 metres, and the number of textures is three.

Copy to clipboard
void PSSMShadowListener::shadowTextureCasterPreViewProj(Light* ,Camera* camera)
{
    static bool update=true;
    static float split_dist[]={0.1,10,10,70,70,500,0,0};
    float old_near=view_camera->getNearClipDistance();
    float old_far=view_camera->getFarClipDistance();
    if(split_index>0)
        view_camera->setNearClipDistance(split_dist[2*split_index]);
    view_camera->setFarClipDistance(split_dist[2*split_index+1]);
    if(update)
        setup->getShadowCamera(sceneMgr,view_camera, NULL, light, camera);
    view_camera->setNearClipDistance(old_near);
    view_camera->setFarClipDistance(old_far);
    split_index++;
    if(split_index>2)
        split_index=0;
}


We expect this to be called as many times as there are lights in the scene, although we don't actually use the lights that are passed to the function. So we must create two dummy lights to make sure it is called at least 3 times. These lights are expected to be sorted:

Copy to clipboard
struct lightsLess
{
    bool operator()(const Light* l1, const Light* l2) const
    {
        if (l1 == l2)
            return false;
        return l1->tempSquareDist < l2->tempSquareDist;
    }
};

bool PSSMShadowListener::sortLightsAffectingFrustum(Ogre::LightList& lightList)
{
    std::stable_sort(
        lightList.begin(), lightList.end(), 
        lightsLess());
    return true;
}

It doesn't matter what order they go in, but the sort seems to be required.

In setting up the scene, after creating your main light:

Copy to clipboard
ShadowCameraSetupPtr mCurrentShadowCameraSetup = ...;

    mSceneMgr->addShadowListener(new PSSMShadowListener(mSceneMgr,light,mCurrentShadowCameraSetup,mCamera));
    mSceneMgr->setShadowTextureCount(3);

    mSceneMgr->setShadowTechnique(Ogre::SHADOWTYPE_TEXTURE_ADDITIVE_INTEGRATED);
    mSceneMgr->setShadowTextureSelfShadow(true);
    mSceneMgr->setShadowTextureFadeStart(1.f);
    mSceneMgr->setShadowTextureFadeEnd(1.f);

    mSceneMgr->setShadowCameraSetup(mCurrentShadowCameraSetup);
    mSceneMgr->setShadowCasterRenderBackFaces(true);
    mSceneMgr->setShadowTextureSize(512);

PSSM gets by with smaller shadow textures than most shadow map techniques - you can get better quality from 3 512x512 textures with PSSM than one 1024x1024 without.

Materials

The shadowed materials need to be passed the shadow maps and their corresponding shadow view-projection matrices. In the following example, all three matrices are used in the vertex shader to produce three positions in the shadow spaces:

Copy to clipboard
vertex_program exampleVP cg
{
    source shadowed.cg
    entry_point VS_Main
    profiles vs_2_0 arbvp1 vp20
    default_params
    {
        param_named_auto worldViewProj    worldviewproj_matrix
        param_named_auto world        world_matrix
        param_named_auto shadow        texture_viewproj_matrix 0
        param_named_auto shadow1    texture_viewproj_matrix 1
        param_named_auto shadow2    texture_viewproj_matrix 2
    }
}
fragment_program exampleFP cg
{
    source shadowed.cg
    entry_point PS_Main
}

The texture_viewproj_matrix entries pass the matrices created by "GetShadowCamera" in the order that function was called.

Copy to clipboard
material shadowed_base
{
    technique 1
    {
        pass
        {
            vertex_program_ref exampleVP 
            {
            }
            fragment_program_ref exampleFP
            {
            }
            texture_unit 0
            {
                tex_coord_set 0
            }
            texture_unit 1
            {
                content_type shadow
            }
            texture_unit 2
            {
                content_type shadow
            }
            texture_unit 3
            {
                content_type shadow
            }
        }
    }
}

Ogre will iterate through its shadow list for each texture of content-type "shadow".
The vertex shader .cg file should contain something like this:

Copy to clipboard
float4x4 shadow            : Shadow;
float4x4 shadow1        : Shadow;
float4x4 shadow2        : Shadow;

...
vertexOutput VS_Main(vertexInput IN) 
{
    vertexOutput OUT;
    float4 worldPos = mul(world, half4(IN.position.xyz, 1.0));

    OUT.hPosition = mul( worldViewProj, half4(IN.position.xyz , 1.0));
    OUT.texCoordDiffuse= IN.texCoordDiffuse;

    OUT.shadow=mul(shadow,worldPos);
    OUT.shadow1=mul(shadow1,worldPos);
    OUT.shadow2=mul(shadow2,worldPos);
    OUT.dist=OUT.hPosition.z;
}

and the pixel shader:

Copy to clipboard
half4 PS_Main( vertexOutput IN): color
{
    half4 diffuseT = h4tex2D( diffuseTexture, IN.texCoordDiffuse.xy);

    half4 shadowT;
    if(IN.dist<10)
    {
        shadowT= tex2Dproj(shadowSampler,IN.shadow);
    }
    else if(dist<70)
    {
        shadowT= tex2Dproj(shadowSampler1,IN.shadow1);
    }
    else
    {
        shadowT= tex2Dproj(shadowSampler2,IN.shadow2);
    }
    return diffuseT*shadowT.x;
}

According to the Cg manual, tex2Dproj performs the depth test if passed a four-element vector. Otherwise:

Copy to clipboard
shadowT.x=(IN.shadowX.z < datum.x);


References

PSSM
PSSM discussion in GPU Gems at NVidia's web site.

Alias: Parallel_Split_Shadow_Mapping

History Source