### 7.4 Additive Light Masking

Additive light masking is about rendering the scene many times, each time representing a single light contribution whose influence is masked out in areas of shadow. Each pass is combined with (added to) the previous one such that when all the passes are complete, all the light contribution has correctly accumulated in the scene, and each light has been prevented from affecting areas which it should not be able to because of shadow casters. This is an effective technique which results in very realistic looking lighting, but it comes at a price: more rendering passes.

As many technical papers (and game marketing) will tell you, rendering realistic lighting like this requires multiple passes. Being a friendly sort of engine, Ogre frees you from most of the hard work though, and will let you use the exact same material definitions whether you use this lighting technique or not (for the most part, see Pass Classification and Vertex Programs). In order to do this technique, Ogre automatically categorises the Passes you define in your materials into 3 types:

1. ambient Passes categorised as ’ambient’ include any base pass which is not lit by any particular light, i.e. it occurs even if there is no ambient light in the scene. The ambient pass always happens first, and sets up the initial depth value of the fragments, and the ambient colour if applicable. It also includes any emissive / self illumination contribution. Only textures which affect ambient light (e.g. ambient occlusion maps) should be rendered in this pass.
2. diffuse/specular Passes categorised as ’diffuse/specular’ (or ’per-light’) are rendered once per light, and each pass contributes the diffuse and specular colour from that single light as reflected by the diffuse / specular terms in the pass. Areas in shadow from that light are masked and are thus not updated. The resulting masked colour is added to the existing colour in the scene. Again, no textures are used in this pass (except for textures used for lighting calculations such as normal maps).
3. decal Passes categorised as ’decal’ add the final texture colour to the scene, which is modulated by the accumulated light built up from all the ambient and diffuse/specular passes.

In practice, Passes rarely fall nicely into just one of these categories. For each Technique, Ogre compiles a list of ’Illumination Passes’, which are derived from the user defined passes, but can be split, to ensure that the divisions between illumination pass categories can be maintained. For example, if we take a very simple material definition:

    material TestIllumination
    {
    	technique
    	{
    		pass
    		{
    			ambient 0.5 0.2 0.2
    			diffuse 1 0 0
    			specular 1 0.8 0.8 15
    			texture_unit
    			{
    				texture grass.png
    			}
    		}
    	}
    }

Ogre will split this into 3 illumination passes, which will be the equivalent of this:

    material TestIlluminationSplitIllumination
    {
    	technique
    	{
    		// Ambient pass
    		pass
    		{
    			ambient 0.5 0.2 0.2
    			diffuse 0 0 0
    			specular 0 0 0
    		}

    		// Diffuse / specular pass
    		pass
    		{
    			scene_blend add
    			iteration once_per_light
    			diffuse 1 0 0
    			specular 1 0.8 0.8 15
    		}

    		// Decal pass
    		pass
    		{
    			scene_blend modulate
    			lighting off
    			texture_unit
    			{
    				texture grass.png
    			}
    		}
    	}
    }

So as you can see, even a simple material requires a minimum of 3 passes when using this shadow technique, and in fact it requires (num_lights + 2) passes in the general sense. You can use more passes in your original material and Ogre will cope with that too, but be aware that each pass may turn into multiple ones if it uses more than one type of light contribution (ambient vs diffuse/specular) and / or has texture units. The main nice thing is that you get the full multipass lighting behaviour even if you don’t define your materials in terms of it, meaning that your material definitions can remain the same no matter what lighting approach you decide to use.

#### Manually Categorising Illumination Passes

Alternatively, if you want more direct control over the categorisation of your passes, you can use the illumination_stage option in your pass to explicitly assign a pass unchanged to an illumination stage. This way you can make sure you know precisely how your material will be rendered under additive lighting conditions.

#### Pass Classification and Vertex Programs

Ogre is pretty good at classifying and splitting your passes to ensure that the multipass rendering approach required by additive lighting works correctly without you having to change your material definitions. However, there is one exception; when you use vertex programs, the normal lighting attributes ambient, diffuse, specular etc are not used, because all of that is determined by the vertex program. Ogre has no way of knowing what you’re doing inside that vertex program, so you have to tell it.

In practice this is very easy. Even though your vertex program could be doing a lot of complex, highly customised processing, it can still be classified into one of the 3 types listed above. All you need to do to tell Ogre what you’re doing is to use the pass attributes ambient, diffuse, specular and self_illumination, just as if you were not using a vertex program. Sure, these attributes do nothing (as far as rendering is concerned) when you’re using vertex programs, but it’s the easiest way to indicate to Ogre which light components you’re using in your vertex program. Ogre will then classify and potentially split your programmable pass based on this information - it will leave the vertex program as-is (so that any split passes will respect any vertex modification that is being done).

Note that when classifying a diffuse/specular programmable pass, Ogre checks to see whether you have indicated the pass can be run once per light (iteration once_per_light). If so, the pass is left intact, including it’s vertex and fragment programs. However, if this attribute is not included in the pass, Ogre tries to split off the per-light part, and in doing so it will disable the fragment program, since in the absence of the ’iteration once_per_light’ attribute it can only assume that the fragment program is performing decal work and hence must not be used per light.

So clearly, when you use additive light masking as a shadow technique, you need to make sure that programmable passes you use are properly set up so that they can be classified correctly. However, also note that the changes you have to make to ensure the classification is correct does not affect the way the material renders when you choose not to use additive lighting, so the principle that you should be able to use the same material definitions for all lighting scenarios still holds. Here is an example of a programmable material which will be classified correctly by the illumination pass classifier:

    // Per-pixel normal mapping Any number of lights, diffuse and specular
    material Examples/BumpMapping/MultiLightSpecular
    {
    	technique
    	{
    		// Base ambient pass
    		pass
    		{
    			// ambient only, not needed for rendering, but as information
    			// to lighting pass categorisation routine
    			ambient 1 1 1
    			diffuse 0 0 0
    			specular 0 0 0 0
    			// Really basic vertex program
    			vertex_program_ref Ogre/BasicVertexPrograms/AmbientOneTexture
    			{
    				param_named_auto worldViewProj worldviewproj_matrix
    				param_named_auto ambient ambient_light_colour
    			}
    		}
    		// Now do the lighting pass
    		// NB we don't do decal texture here because this is repeated per light
    		pass
    		{
    			// set ambient off, not needed for rendering, but as information
    			// to lighting pass categorisation routine
    			ambient 0 0 0
    			// do this for each light
    			iteration once_per_light
    			scene_blend add

    			// Vertex program reference
    			vertex_program_ref Examples/BumpMapVPSpecular
    			{
    				param_named_auto lightPosition light_position_object_space 0
    				param_named_auto eyePosition camera_position_object_space
    				param_named_auto worldViewProj worldviewproj_matrix
    			}

    			// Fragment program
    			fragment_program_ref Examples/BumpMapFPSpecular
    			{
    				param_named_auto lightDiffuse light_diffuse_colour 0
    				param_named_auto lightSpecular light_specular_colour 0
    			}

    			// Base bump map
    			texture_unit
    			{
    				texture NMBumpsOut.png
    				colour_op replace
    			}
    			// Normalisation cube map
    			texture_unit
    			{
    				cubic_texture nm.png combinedUVW
    				tex_coord_set 1
    				tex_address_mode clamp
    			}
    			// Normalisation cube map #2
    			texture_unit
    			{
    				cubic_texture nm.png combinedUVW
    				tex_coord_set 1
    				tex_address_mode clamp
    			}
    		}

    		// Decal pass
    		pass
    		{
    			lighting off
    			// Really basic vertex program
    			vertex_program_ref Ogre/BasicVertexPrograms/AmbientOneTexture
    			{
    				param_named_auto worldViewProj worldviewproj_matrix
    				param_named ambient float4 1 1 1 1
    			}
    			scene_blend dest_colour zero
    			texture_unit
    			{
    				texture RustedMetal.jpg
    			}
    		}
    	}
    }

Note that if you’re using texture shadows you have the additional option of using Integrated Texture Shadows rather than being forced to use this explicit sequence - allowing you to compress the number of passes into a much smaller number at the expense of defining an upper number of shadow casting lights. In this case the ’additive’ aspect of the shadow technique just affects the colour of the shadow texture and it’s up to you to combine the shadow textures in your receivers however you like.

#### Static Lighting

Despite their power, additive lighting techniques have an additional limitation; they do not combine well with pre-calculated static lighting in the scene. This is because they are based on the principle that shadow is an absence of light, but since static lighting in the scene already includes areas of light and shadow, additive lighting cannot remove light to create new shadows. Therefore, if you use the additive lighting technique you must either use it exclusively as your lighting solution (and you can combine it with per-pixel lighting to create a very impressive dynamic lighting solution), or you must use Integrated Texture Shadows to combine the static lighting according to your chosen approach.