Passes
From Multiverse
Overview
A pass is a single render of the geometry in question; a single call to the rendering API with a certain set of rendering properties. A technique can have between one and 16 passes, although clearly the more passes you use, the more expensive the technique will be to render.
To identify what each pass is used for, name the pass. Naming is optional. Passes not named within the script will take a name that is the pass index number. For example: the first pass in a technique is index 0 so its name would be "0" if it was not given a name in the script. The pass name must be unqiue within the technique or else the final pass is the resulting merge of all passes with the same name in the technique. The Multiverse Client writes a warning message to the trace file if this occurs. Named passes can help when copying a material and modifying an existing pass. See Copying Materials.
Passes have a set of global attributes (described below), zero or more nested texture_unit entries (see Using Vertex and Fragment Programs in a Pass).
Format:
pass [name] {
attribute1 values
attribute2 values
...
}
ambient
This attribute sets the ambient color reflectance properties of this pass. It applies only to the fixed-function pipeline.
Format:
ambient [red green blue [alpha] | vertexcolour ]
Valid color values are between 0.0 and 1.0.
Example:
ambient 0.0 0.8 0.0
The base color of a pass is determined by how much red, green and blue light is reflects at each vertex. This parameter determines how much ambient light (directionless global light) is reflected. It is also possible to make the ambient reflectance track the vertex color as defined in the mesh by using the keyword vertexcolour instead of the color values.
The default is full white, meaning objects are fully globally illuminated. Reduce this if you want to see diffuse or specular light effects, or change the blend of colors to make the object have a base color other than white. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a colour_op replace attribute.
Default:
ambient 1.0 1.0 1.0 1.0
diffuse
The diffuse attribute sets the diffuse color reflectance properties of this pass. It applies only to the fixed-function pipeline.
Format:
diffuse [ red green blue [alpha]| vertexcolour ]
Valid color values are between 0.0 and 1.0.
Example:
diffuse 1.0 0.5 0.5
The base color of a pass is determined by how much red, green and blue light is reflected at each vertex. This property determines how much diffuse light is reflected. It is also possible to make the diffuse reflectance track the vertex color as defined in the mesh by using the keyword vertexcolour instead of the color values.
The default value of diffuse is full white, meaning objects reflect the maximum white light they can from Light objects. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a colour_op replace attribute.
Default:
diffuse 1.0 1.0 1.0 1.0
specular
The specular attribute sets the specular color reflectance properties of this pass. It applies only to the fixed-function pipeline.
The base color of a pass is determined by how much red, green and blue light each vertex reflects. This attribute determines how much specular light (highlights from instances of the Light class in the scene) is reflected. It is also possible to make the diffuse reflectance track the vertex color as defined in the mesh by using the keyword vertexcolour instead of the color values.
The default is to reflect no specular light. The color of the specular highlights is determined by the color parameters, and the size of the highlights by the separate shininess parameter. The higher the value of the shininess parameter, the sharper the highlight ie the radius is smaller.
Beware of using shininess values in the range of 0 to 1 since this causes the the specular color to be applied to the whole surface that has the material applied to it. When the viewing angle to the surface changes, ugly flickering will also occur when shininess is in the range of 0 to 1. Shininess values between 1 and 128 work best in both DirectX and OpenGL renderers. This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.
Format:
specular [red green blue [alpha]| vertexcolour] shininess
Valid color values are between 0.0 and 1.0. Shininess can be any value greater than 0.
Example:
specular 1.0 1.0 1.0 12.5
Default:
specular 0.0 0.0 0.0 0.0 0.0
emissive
The emissive attribute sets the amount of self-illumination an object has. It applies only to the fixed-function pipeline.
If an object is self-illuminating, it does not need external sources to light it, ambient or otherwise: it's as if the object had its own personal ambient light. Despite its name, this object doesn't act as a light source for other objects in the scene (if you want it to, you have to create a light which is centered on the object). It is also possible to make the emissive color track the vertex color as defined in the mesh by using the keyword vertexcolour instead of the color values.
This setting has no effect if dynamic lighting is disabled using the 'lighting off' attribute, or if any texture layer has a 'colour_op replace' attribute.
Format:
emissive [red green blue [alpha]| vertexcolour]
Valid color values are between 0.0 and 1.0.
Example:
emissive 1.0 0.0 0.0
Default:
emissive 0.0 0.0 0.0 0.0
scene_blend
The scene_blend attribute sets how this pass performs blending with the existing contents of the scene. Whereas texture blending operations specified in texture_unit attributes are concerned with blending between texture layers, scene_blend is about combining the output of this pass as a whole with the existing contents of the rendering target. Thus scene_blend enables object transparency and other special effects. There are two formats, one using predefined blend types, the other allowing a roll-your-own approach using source and destination factors.
First format
scene_blend type
This is the simpler form, where a single parameter enumerates the most commonly-used blending types.
The following table describes valid scene_blend types.
| Blend type | Description |
|---|---|
| add | The color of the rendering output is added to the scene. Good for exposions, flares, lights, ghosts etc. Equivalent to 'scene_blend one one'. |
| modulate | The color of the rendering output is multiplied with the scene contents. Generally colors and darkens the scene, which is good for smoked glass or semi-transparent objects. Equivalent to 'scene_blend dest_colour zero'. |
| colour_blend | Color the scene based on the brightness of the input colors, but don't darken. Equivalent to scene_blend src_colour one_minus_src_colour.
|
| alpha_blend | The alpha value of the rendering output is used as a mask. Equivalent to scene_blend src_alpha one_minus_src_alpha.
|
Example:
scene_blend add
Second format
scene_blend src_factor dest_factor
This version of the attribute allows complete control over the blending operation, by specifying the source and destination blending factors. The resulting color which is written to the rendering target is (texture * sourceFactor) + (scene_pixel * destFactor).
The following table describes valid values for src_factor and dest_factor attributes:
| Blending Factor | Description |
|---|---|
| one | Constant value of 1.0 |
| zero | Constant value of 0.0 |
| dest_colour | The existing pixel color |
| src_colour | The texture pixel (texel) color |
| one_minus_dest_colour | 1 - dest_colour |
| one_minus_src_colour | 1 - src_colour |
| dest_alpha | The existing pixel alpha value |
| src_alpha | The texel alpha value |
| one_minus_dest_alpha | 1 - dest_alpha |
| one_minus_src_alpha | 1 - src_alpha |
Default (opaque):
scene_blend one zero
Example:
scene_blend one one_minus_dest_alpha
depth_check
The depth_check attribute sets whether or not this pass renders with depth-buffer checking.
If depth-buffer checking is on, whenever a pixel is about to be written to the frame buffer the depth buffer is checked to see if the pixel is in front of all other pixels written at that point. If not, the pixel is not written. If depth checking is off, pixels are written no matter what has been rendered before. Also see depth_func for more advanced depth check configuration.
Format:
depth_check [on|off]
Default:
depth_check on
depth_write
The depth_write attribute sets whether or not this pass renders with depth-buffer writing.
If depth-buffer writing is on, whenever a pixel is written to the frame buffer the depth buffer is updated with the depth value of that new pixel, thus affecting future rendering operations if future pixels are behind this one. If depth writing is off, pixels are written without updating the depth buffer. Depth writing should normally be on but can be turned off when rendering static backgrounds or when rendering a collection of transparent objects at the end of a scene so that they overlap each other correctly.
Format:
depth_write [on|off]
Default:
depth_write on
depth_func
The depth_func attribute sets the function used to compare depth values when depth checking is enabled.
If depth checking is enabled (see depth_check) a comparison occurs between the depth value of the pixel to be written and the current contents of the buffer. This comparison is normally less_equal, that is, the pixel is written if it is closer (or at the same distance) than the current contents.
Format:
depth_func function
The following table describes valid values of function.
| Function | Description |
|---|---|
| always_fail | Never writes a pixel to the render target |
| always_pass | Always writes a pixel to the render target |
| less | Write if (new_Z < existing_Z) |
| less_equal | Write if (new_Z <= existing_Z) |
| equal | Write if (new_Z == existing_Z) |
| not_equal | Write if (new_Z != existing_Z) |
| greater_equal | Write if (new_Z >= existing_Z) |
| greater | Write if (new_Z > existing_Z) |
Default:
depth_func less_equal
depth_bias
The depth_bias attribute sets the bias applied to the depth value of this pass. Use this attribute to make coplanar polygons appear on top of others, for example for decals.
The final depth bias value is constant_bias * minObservableDepth + maxSlope * slopescale_bias.
Slope scale biasing is relative to the angle of the polygon to the camera, which makes for a more appropriate bias value, but some older hardware ignores it. Constant biasing is expressed as a factor of the minimum depth value, so a value of one (1) will increase the depth by one "notch".
Format:
depth_bias constant_bias [slopescale_bias]
alpha_rejection
The alpha_rejection attribute sets the way the pass will have use alpha to totally reject pixels from the pipeline.
Format:
alpha_rejection function value
The function parameter can be any of the options listed in the material depth_function attribute. The value parameter can theoretically be any value between 0 and 255, but is best limited to 0 or 128 for hardware compatibility.
Example:
alpha_rejection greater_equal 128
Default:
alpha_rejection always_pass
cull_hardware
The cull_hardware attribute sets the hardware culling mode for this pass.
A typical way for the hardware rendering engine to cull triangles is based on the 'vertex winding' of triangles. Vertex winding refers to the direction in which the vertices are passed or indexed to in the rendering operation as viewed from the camera, and is either "clockwise" or "anticlockwise" (counter-clockwise).
If the option 'cull_hardware clockwise' is set, all triangles whose vertices are viewed in clockwise order from the camera will be culled by the hardware. 'anticlockwise' is the reverse (obviously), and 'none' turns off hardware culling so all triagles are rendered (useful for creating two-sided passes).
Format:
cull_hardware [clockwise|anticlockwise|none]
Default:
cull_hardware clockwise
This is the opposite of Direct3D's default (because the Multiverse Client uses a right-handed coordinate system).
cull_software
The cull_software attribute sets the software culling mode for this pass.
In some situations the engine will also cull geometry in software before sending it to the hardware renderer. This setting only takes effect on SceneManagers that use it (since it is best used on large groups of planar world geometry rather than on movable geometry since this would be expensive), but if used can cull geometry before it is sent to the hardware. In this case the culling is based on whether the 'back' or 'front' of the triangle is facing the camera - this definition is based on the face normal (a vector which sticks out of the front side of the polygon perpendicular to the face).
Since the Client expects face normals to be on counter-clockwise side of the face, 'cull_software back' is the software equivalent of 'cull_hardware clockwise' setting, which is why they are both the default. The naming is different to reflect the way the culling is done though, since most of the time face normals are precalculated and they don't have to be the way the Client expects; You could set 'cull_hardware none' and completely cull in software based on your own face normals, if you have the right SceneManager which uses them.
Format:
cull_software [back|front|none]
Default:
cull_software back
lighting
The lighting attribute sets whether or not dynamic lighting is turned on for this pass or not. If lighting is turned off, all objects rendered using the pass will be fully lit. This attribute has no effect if a vertex program is used.
Turning dynamic lighting off makes any ambient, diffuse, specular, emissive, and shading properties for this pass redundant. When lighting is turned on, objects are lit according to their vertex normals for diffuse and specular light, and globally for ambient and emissive.
Format:
lighting [on|off]
Default:
lighting on
shading
The shading attribute sets the kind of shading which should be used for representing dynamic lighting for this pass. When dynamic lighting is turned on, the effect is to generate color values at each vertex. Whether these values are interpolated across the face (and how) depends on this setting.
Format:
shading type
Where type is one of:
- flat: No interpolation takes place. Each face is shaded with a single color determined from the first vertex in the face.
- gouraud: Color at each vertex is linearly interpolated across the face.
- phong: Vertex normals are interpolated across the face, and these are used to determine color at each pixel. Gives a more natural lighting effect but is more expensive and works better at high levels of tesselation. Not supported on all hardware.
Default:
shading gouraud
polygon_mode
The polygon_mode attribute sets how polygons should be rasterized, that is, whether they are filled in, or drawn as lines or points.
Format:
polygon_mode mode
Where mode is one of:
- solid: The normal situation - polygons are filled in.
- wireframe: Polygons are drawn in outline only.
- points: Only the points of each polygon are rendered.
Default:
polygon_mode solid
fog_override
The fog_override attribute determines whether the pass overrides the scene fog settings with its own fog settings. This attribute is useful for things that you don't want to be affected by fog when the rest of the scene is fogged, or vice versa. This only affects fixed-function fog; the original scene fog parameters are still sent to shaders which use the fog_params parameter binding. This enables you to turn off fixed function fog and calculate it in the shader instead; if you want to disable shader fog you can do that through shader parameters anyway.
Format:
fog_override [ true | false ] [type colour density start end]
Default:
fog_override false
If you specify 'true' for the first parameter and you supply the rest of the parameters, you are telling the pass to use these fog settings in preference to the scene settings, whatever they might be. If you specify 'true' but provide no further parameters, you are telling this pass to never use fogging no matter what the scene says.
The parameters are:
- type - One of:
- none: No fog, equivalent of just using 'fog_override true'
- linear: Linear fog from the start and end distances.
- exp: Fog increases exponentially from the camera (fog = 1/e^(distance * density)), use density param to control it.
- exp2: Fog increases at the square of FOG_EXP, even quicker (fog = 1/e^(distance * density)^2), use density param to control it
- colour: Sequence of three floating point values from 0 to 1 indicating the red, green and blue intensities
- density: The density parameter used in the 'exp' or 'exp2' fog types. Not used in linear mode but param must still be there as a placeholder
- start: The start distance from the camera of linear fog. Must still be present in other modes, even though it is not used.
- end: The end distance from the camera of linear fog. Must still be present in other modes, even though it is not used.
Example:
fog_override true exp 1 1 1 0.002 100 10000
colour_write
The colour_write attribute sets whether or not this pass renders with color writing on or not.
If color writing is off no visible pixels are written to the screen during this pass. You might think this is useless, but if you render with color writing off, and with very minimal other settings, you can use this pass to initialize the depth buffer before subsequently rendering other passes which fill in the color data. This can give you significant performance boosts on some newer cards, especially when using complex fragment programs, because if the depth check fails then the fragment program is never run.
Format:
colour_write [on|off]
Default:
colour_write on
start_light
The start_light attribute sets the first light which will be considered for use with this pass. You can use this attribute to offset the starting point of the lights for this pass. In other words, if you set start_light to 2 then the first light to be processed in that pass will be the third actual light in the applicable list.
Use this attribute, for example, to process the first few lights in one pass, then other lights in another pass. Use it in conjunction with the iteration attribute to start the iteration from a given point in the list: for example, doing the first two lights in the first pass, and then iterating every two lights from then on perhaps.
Format:
start_light number
Default:
start_light 0
max_lights
The max_lights attribute sets the maximum number of lights which will be considered for use with this pass. The maximum number of lights which can be used when rendering fixed-function materials is set by the rendering system, typically eight. When using the programmable pipeline (wee section iteration), it is effectively only bounded by the number of passes you are willing to use. If you are not using pass iteration, the light limit applies once for this pass. If you are using pass iteration, the light limit applies across all iterations of this pass - for example if you have 12 lights in range with an 'iteration once_per_light' setup but your max_lights is set to four for that pass, the pass will only iterate four times.
Format:
max_lights number
Default:
max_lights 8
iteration
The iteration attribute sets whether or not this pass is iterated, that is, issued more than once.
Default:
iteration once
First format
By default, passes are only issued once. However, if you use the programmable pipeline, or you wish to exceed the normal limits on the number of lights which are supported, use the once_per_light parameter. In this case, only light index 0 is ever used, and the pass is issued multiple times, each time with a different light in light index 0. Clearly this will make the pass more expensive, but it may be the only way to achieve certain effects such as per-pixel lighting effects which take into account 1...n lights.
If you use once_per_light, add an ambient pass to the technique before this pass, otherwise when no lights are in range of this object it will not get rendered at all; this is important even when you have no ambient light in the scene, because you would still want the objects sihouette to appear.
iteration [ once | once_per_light ] [lightType]
Where lightType restricts the pass to lights of the specified type and is one of:
- point
- directional
- spot
Example:
iteration once_per_light point
In this example, the pass is executed once for each point light.
Second format
Using a number instead of "once" instructs the pass to iterate more than once after the render state is set up. The render state is not changed after the initial setup so repeated draw calls are very fast and ideal for passes using programmable shaders that iterate more than once with the same render state, for example, shaders for fur, motion blur, or special filtering.
iteration number [per_light [lightType]]
Where lightType restricts the pass to lights of the specified type and is one of:
- point
- directional
- spot
Example:
iteration 5 per_light point
In this example, the render state for the pass will be set up and then the draw call will execute five times for each point light.
iteration 5
In this example, the render state for the pass will be set up and then the draw call will execute five times.
Third format
iteration number [per_n_lights num_lights [lightType]]
Where number and num_lights are postive integers and lightType restricts the pass to lights of the specified type and is one of:
- point
- directional
- spot
Example:
iteration 1 per_n_lights 2 point
In this example, the render state for the pass will be set up and the draw call executed once for every two lights.
Example use of iteration
The following is a simple fur shader material script that uses a second pass with 10 iterations to grow the fur: Is this GLSL example valid for us?
// GLSL simple Fur
vertex_program GLSLDemo/FurVS glsl
{
source fur.vert
default_params
{
param_named_auto lightPosition light_position_object_space 0
param_named_auto eyePosition camera_position_object_space
param_named_auto passNumber pass_number
param_named_auto multiPassNumber pass_iteration_number
param_named furLength float 0.15
}
}
fragment_program GLSLDemo/FurFS glsl
{
source fur.frag
default_params
{
param_named Ka float 0.2
param_named Kd float 0.5
param_named Ks float 0.0
param_named furTU int 0
}
}
material Fur
{
technique GLSL
{
pass base_coat
{
ambient 0.7 0.7 0.7
diffuse 0.5 0.8 0.5
specular 1.0 1.0 1.0 1.5
vertex_program_ref GLSLDemo/FurVS
{
}
fragment_program_ref GLSLDemo/FurFS
{
}
texture_unit
{
texture Fur.tga
tex_coord_set 0
filtering trilinear
}
}
pass grow_fur
{
ambient 0.7 0.7 0.7
diffuse 0.8 1.0 0.8
specular 1.0 1.0 1.0 64
depth_write off
scene_blend src_alpha one
iteration 10
vertex_program_ref GLSLDemo/FurVS
{
}
fragment_program_ref GLSLDemo/FurFS
{
}
texture_unit
{
texture Fur.tga
tex_coord_set 0
filtering trilinear
}
}
}
}
Note: Use GPU program auto-parameters pass_iteration_number to tell the vertex or fragment program the pass number and iteration number.
point_size
The point_size attribute changes the size of points when rendering a point list, or a list of point sprites. The interpretation of this command depends on the point_size_attenuation option:
- if point_size_attenuation is off (the default), the point size is in screen pixels
- if point_size_attenuation is on, point size is expressed as normalized screen coordinates (1.0 is the height of the screen) when the point is at the origin.
NOTE: Some drivers have an upper limit on the size of points they support - this can even vary between APIs on the same card! Don't rely on point sizes that cause the points to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.
Format:
point_size size
Default:
point_size 1.0
point_sprites
The point_sprites attribute specifies whether or not hardware point sprite rendering is enabled for this pass. Enabling it means that a point list is rendered as a list of quads rather than a list of dots. It is very useful to use this option if you're using a billboardset and only need to use point oriented billboards which are all of the same size. You can also use it for any other point list render.
Format:
point_sprites on|off
Default:
point_sprites off
point_size_attenuation
The point_size_attenuation attribute defines whether point size is attenuated with view space distance, and in what fashion. This option is especially useful when you're using point_sprites since it defines how they reduce in size as they get further away from the camera.
Disable this option to make point sprites a constant screen size (like points), or enable it for points so they change size with distance.
You must provide the final three parameters only if attenuation is on. The formula for attenuation is that the size of the point is multiplied by 1 / (constant + linear * dist + quadratic * d^2); therefore turning it off is equivalent to (constant = 1, linear = 0, quadratic = 0) and standard perspective attenuation is (constant = 0, linear = 1, quadratic = 0). The latter is assumed if you leave out the final 3 parameters when you specify 'on'.
Note that the resulting attenuated size is clamped to the minimum and maximum point size, see the next section.
Format:
point_size_attenuation [on|off] [constant linear quadratic]
Default:
point_size_attenuation off
point_size_min
The point_size_min attribute sets the minimum point size after attenuation. See point_size.
Format:
point_size_min size
Default:
point_size_min 0
point_size_max
The point_size_max attribute sets the maximum point size after attenuation. See point_size. A value of 0 means the maximum is set to the same as the max size reported by the current card.
Format:
point_size_max size
Default:
point_size_max 0
This document is based on the OGRE Manual and is licensed under the Creative Commons Attribution-ShareAlike 2.5 License.
