Calling Vertex and Fragment Programs in a Pass

From Multiverse

Particle Scripts

Syntax  •  Attributes  •  Emitters  •  Affectors

Material Scripts

Techniques  •  Texture Units  •  Passes  •  Vertex and Fragment Programs  •  Calling Vertex and Fragment Programs  •  Copying Materials

Compositor Framework

Compositor Scripts  •  Compositor Techniques  •  Compositor Target Passes  •  Compositor Passes

Shaders

Writing Custom Shaders  •  Built-in Shaders  •  Troubleshooting

Contents 1 Overview 2 Parameter specification 2.1 param_indexed 2.2 param_indexed_auto 2.3 param_named 2.4 param_named_auto 3 Shadows and vertex programs

Overview

A pass section of a material script can call a vertex and fragment program defined in a .program script (see Vertex and Fragment Programs). Defining the program separately enables multiple materials and multiple .material scripts to call a single program.

To call a program, it must have a unique name. You can also provide parameters to a program when you call it, for example:

vertex_program_ref myVertexProgram
{
	param_indexed_auto 0 worldviewproj_matrix
	param_indexed      4 float4  10.0 0 0 0
}

This example binds a vertex program called 'myVertexProgram' to the pass, and gives it two parameters:

• The first parameter is an 'auto' parameter, meaning you do not have to supply a value as such, just a recognized code (in this case it's the world/view/projection matrix which the Multiverse Client automatically keeps up to date).
• The second parameter is a manually-specified parameter, a four-element float. The indexes are described later.

The syntax of the link to a vertex program and a fragment program is identical except that for a fragment program use 'fragment_program_ref' instead of 'vertex_program_ref'.

For most situations a vertex and fragment program are associated with each other in a pass. However, the association is not a requirement. You could have a vertex program used by several different fragment programs.

You can also mix fixed-pipeline and programmable pipeline (shaders). You could use the non-programable vertex fixed function pipeline and then provide a fragment_program_ref in a pass, so there would be no vertex_program_ref section in the pass. The fragment program referenced in the pass must meet the requirements as defined in the related API in order to read from the outputs of the vertex fixed pipeline. You could also just have a vertex program that outputs to the fragment fixed function pipeline.

How a shader reads from or writes to to the fixed-function pipeline depends on the language. For HLSL (DirectX API), see MSDN. For Cg, see "Language Profiles" in the Cg Users Manual in the Cg Toolkit. For Cg, the varying bindings allow shader programs to read from and write to the fixed function pipeline.

Parameter specification

Specify parameters to vertex and fragment programs with one of four attributes:

• param_indexed
• param_indexed_auto
• param_named
• param_named

Use the same syntax when defining a parameter just for a particular use of the program, or specifying the default program parameters. Parameters set in the specific use of the program override the defaults.

param_indexed

This attribute sets the value of an indexed parameter.

format:

param_indexed index type value

Where the options are:

index is a number representing the position in the parameter list which the value should be written. Derive this from your program definition. The index is relative to the way constants are stored on the card, which is in four-element blocks. For example if you defined a float4 parameter at index zero, the next index would be one. If you defined a matrix4x4 at index zero, the next usable index would be four, since a 4x4 matrix takes up four indexes.

type can be float4, matrix4x4, floatn, int4, or intn. Note that 'int' parameters are only available on some more advanced program syntaxes, check the D3D vertex / fragment program documentation for full details. Typically the most useful ones will be float4 and matrix4x4. Note that if you use a type which is not a multiple of 4, then the remaining values up to the multiple of 4 will be filled with zeroes for you (since GPUs always use banks of 4 floats per constant even if only one is used).

value is simply a space-delimited or tab-delimited list of values which can be converted into the type you have specified.

For example:

param_indexed 0 float4 10.0 0 0 0

param_indexed_auto

This attribute tells the Multiverse Client to automatically update a given parameter with a derived value. This frees you from writing code to update program parameters every frame when they are always changing.

format:

param_indexed_auto index value_code extra_params

Where index has the same meaning as param_indexed. You do not have to specify the size of the parameter.

For example:

param_indexed_auto 0 worldviewproj_matrix

In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4.

There are a large number of value_code values. They are loosely categorized below, and the following table lists all value_codes in alphabetical order.

World matrix parameters:

• world_matrix
• inverse_world_matrix
• transpose_world_matrix
• inverse_transpose_world_matrix
• world_matrix_array_3x4

View matrix parameters:

• view_matrix
• inverse_view_matrix
• transpose_view_matrix
• inverse_transpose_view_matrix

Projection matrix parameters:

• projection_matrix
• inverse_projection_matrix
• transpose_projection_matrix
• inverse_transpose_projection_matrix

Concatenated matrix and related parameters:

• worldview_matrix
• inverse_worldview_matrix
• transpose_worldview_matrix
• inverse_transpose_worldview_matrix
• viewproj_matrix
• inverse_viewproj_matrix
• transpose_viewproj_matrix
• inverse_transpose_viewproj_matrix
• worldviewproj_matrix
• inverse_worldviewproj_matrix
• transpose_worldviewproj_matrix
• inverse_transpose_worldviewproj_matrix
• render_target_flipping

Light parameters: NOTE: All of these parameters require an index in the 'extra_params' field, and relates to the nth closest light that could affect this object: Zero (0) refers to the closest light. Directional lights are always first in the list and always present.

• light_position
• light_direction
• light_position_object_space
• light_direction_object_space
• light_distance_object_space
• light_position_view_space
• light_direction_view_space
• light_power
• light_diffuse_colour_array
• light_specular_colour_array
• light_attenuation_array
• spotlight_params_array
• light_position_array
• light_direction_array
• light_position_object_space_array
• light_direction_object_space_array
• light_distance_object_space_array
• light_position_view_space_array
• light_direction_view_space_array
• light_power_array
• light_diffuse_colour
• light_specular_colour
• light_attenuation

Color parameters:

• ambient_light_colour
• surface_ambient_colour
• surface_diffuse_colour
• surface_specular_colour
• surface_emissive_colour
• surface_shininess
• derived_ambient_light_colour
• derived_scene_colour
• derived_light_diffuse_colour
• derived_light_specular_colour
• derived_light_diffuse_colour_array
• derived_light_specular_colour_array

Time parameters:

• time
• time_0_x
• costime_0_x
• sintime_0_x
• tantime_0_x
• time_0_x_packed
• time_0_1
• costime_0_1
• sintime_0_1
• tantime_0_1
• time_0_1_packed
• time_0_2pi
• costime_0_2pi
• sintime_0_2pi
• tantime_0_2pi
• time_0_2pi_packed

View and viewport parameters:

• viewport_width
• viewport_height
• inverse_viewport_width
• inverse_viewport_height
• iewport_size
• texel_offsets
• view_direction
• view_side_vector
• view_up_vector
• fov

Depth range parameters:

• scene_depth_range
• shadow_scene_depth_range

Texture parameters:

• texture_size
• inverse_texture_size
• packed_texture_size

Fog parameters:

• fog_colour
• fog_params

Other parameters:

• pass_number
• pass_iteration_number
• animation_parametric
• camera_position
• camera_position_object_space
• frame_time
• fps
• near_clip_distance
• far_clip_distance
• texture_viewproj_matrix
• custom
• mv_shadow_technique

Value Code	Description
ambient_light_colour	The colour of the ambient light currently set in the scene.
animation_parametric	Useful for hardware vertex animation. For morph animation, sets the parametric value (0..1) representing the distance between the first position keyframe (bound to positions) and the second position keyframe (bound to the first free texture coordinate) so that the vertex program can interpolate between them. For pose animation, indicates a group of up to 4 parametric weight values applying to a sequence of up to 4 poses (each one bound to x, y, z and w of the constant), one for each pose. The original positions are held in the usual position buffer, and the offsets to take those positions to the pose where weight == 1.0 are in the first 'n' free texture coordinates; 'n' being determined by the value passed to includes_pose_animation. If more than 4 simultaneous poses are required, then you'll need more than 1 shader constant to hold the parametric values, in which case you should use this binding more than once, referencing a different constant entry; the second one will contain the parametrics for poses 5-8, the third for poses 9-12, and so on.
camera_position	The current camera's position in world space.
camera_position_object_space	The current camera's position in object space, when the object is at (0,0,0).
costime_0_x	Cosine of time_0_x
costime_0_2pi	The same as costime0_x but scaled to [0..2*Pi]
costime_0_1	The same as costime0_x but scaled to [0..1]
custom	Allows you to map a custom parameter on an individual Renderable (see Renderable / setCustomParameter) to a parameter on a GPU program. It requires that you complete the 'extra_params' field with the index that was used in the Renderable / setCustomParameter call, and this will ensure that whenever this Renderable is used, it will have it's custom parameter mapped in. It's very important that this parameter has been defined on all Renderables that are assigned the material that contains this automatic mapping, otherwise the process will fail.
derived_ambient_light_colour	The derived ambient light color, with 'r', 'g', 'b' components filled with product of surface_ambient_colour and ambient_light_colour, respectively, and 'a' component filled with surface ambient alpha component.
derived_light_diffuse_colour	The derived light diffuse color, with 'r', 'g' and 'b' components filled with product of surface_diffuse_colour and light_diffuse_colour, respectively, and 'a' component filled with surface diffuse alpha component. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light).
derived_light_diffuse_colour_array	The same as derived_light_diffuse_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
derived_light_specular_colour	The derived light specular color, with 'r', 'g' and 'b' components filled with product of surface_specular_colour and light_specular_colour, respectively, and 'a' component filled with surface specular alpha component. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light).
derived_light_specular_colour_array	The same as derived_light_specular_color, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
derived_scene_colour	The derived scene colo, with 'r', 'g' and 'b' components filled with sum of derived_ambient_light_colour and surface_emissive_colour, respectively, and 'a' component filled with surface diffuse alpha component.
far_clip_distance	Far clip distance, in world units (may be 0 for infinite view projection)
fog_colour	The colour of the fog currently set in the scene.
fog_params	The parameters of the fog currently set in the scene. Packed as (exp_density, linear_start, linear_end, 1.0 / (linear_end - linear_start)).
fov	Vertical field of view, in radians
fps	The current frames per second
frame_time	The current frame time, factored by the optional parameter (or 1.0f if not supplied).
inverse_projection_matrix	The inverse of the projection matrix
inverse_texture_size	Provides inverse texture size of the selected texture unit. Requires a texture unit index parameter. Provided as float4(1 / width, 1 / height, 1 / depth, 1). For 2D-texture, depth sets to 1, for 1D-texture, height and depth sets to 1.
inverse_transpose_projection_matrix	The inverse transpose of the projection matrix
inverse_transpose_view_matrix	The inverse transpose of the view matrix
inverse_transpose_viewproj_matrix	The inverse transpose of the view & projection matrices
inverse_transpose_world_matrix	The inverse transpose of the world matrix
inverse_transpose_worldview_matrix	The inverse transpose of the current concatenated world and view matrices.
inverse_transpose_worldviewproj_matrix	The inverse transpose of the world, view and projection matrices
inverse_view_matrix	The inverse of the current view matrix.
inverse_viewport_height	1.0/the current viewport height in pixels.
inverse_viewport_width	1.0/the current viewport width in pixels.
inverse_viewproj_matrix	The inverse of the view & projection matrices
inverse_world_matrix	The inverse of the current world matrix.
inverse_worldview_matrix	The inverse of the current concatenated world and view matrices.
inverse_worldviewproj_matrix	The inverse of the world, view and projection matrices.
light_position	The position of a given light in world space. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) while directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both.
light_direction	The direction of a given light in world space. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (so zero refers to the closest light). If there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED - this property only works on directional lights, and we recommend that you use light_position instead since that returns a generic 4D vector.
light_position_object_space	The position of a given light in object space (ie when the object is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (so zero refers to the closest light). If there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both.
light_direction_object_space	The direction of a given light in object space when the object is at (0,0,0). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (so zero refers to the closest light). If there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED, except for spotlights - for directional lights we recommend that you use light_position_object_space instead since that returns a generic 4D vector.
light_distance_object_space	The distance of a given light from the centre of the object - this is a useful approximation to per-vertex distance calculations for relatively small objects. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). If there are no lights this close, then the parameter will be set to all zeroes.
light_position_view_space	The position of a given light in view space (ie when the camera is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. Note that this property will work with all kinds of lights, even directional lights, since the parameter is set as a 4D vector. Point lights will be (pos.x, pos.y, pos.z, 1.0f) whilst directional lights will be (-dir.x, -dir.y, -dir.z, 0.0f). Operations like dot products will work consistently on both.
light_direction_view_space	The direction of a given light in view space (ie when the camera is at (0,0,0)). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). NB if there are no lights this close, then the parameter will be set to all zeroes. DEPRECATED, except for spotlights - for directional lights we recommend that you use light_position_view_space instead since that returns a generic 4D vector.
light_power	The 'power' scaling for a given light, useful in HDR rendering. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (for example, 0 refers to the closest light).
light_diffuse_colour_array	The same as light_diffuse_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_specular_colour_array	The same as light_specular_colour, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_attenuation_array	The same as light_attenuation, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
spotlight_params_array	The same as spotlight_params, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_position_array	The same as light_position, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_direction_array	The same as light_direction, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_position_object_space_array	The same as light_position_object_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_direction_object_space_array	The same as light_direction_object_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_distance_object_space_array	The same as light_distance_object_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_position_view_space_array	The same as light_position_view_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_direction_view_space_array	The same as light_direction_view_space, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_power_array	The same as light_power, except that this populates an array of parameters with a number of lights, and the 'extra_params' field refers to the number of 'nth closest' lights to be processed. This parameter is not compatible with light-based pass_iteration options but can be used for single-pass lighting.
light_diffuse_colour	The diffuse colour of a given light; this requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light - note that directional lights are always first in the list and always present). If there are no lights this close, then the parameter will be set to black.
light_specular_colour	The specular colour of a given light; this requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). If there are no lights this close, then the parameter will be set to black.
light_attenuation	A float4 containing the four light attenuation variables for a given light. This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). If there are no lights this close, then the parameter will be set to all zeroes. The order of the parameters is range, constant attenuation, linear attenuation, quadric attenuation.
near_clip_distance	Near clip distance, in world units
mv_shadow_technique	Multiverse specific shadow technique in use. Is this still valid?
packed_texture_size	Provides packed texture size of the selected texture unit. Requires a texture unit index parameter. Provided as float4(width, height, 1 / width, 1 / height). For 3D-texture, depth is ignored, for 1D-texture, height sets to 1.
pass_iteration_number	Useful for GPU programs that need to know what the current pass iteration number is. The first iteration of a pass is numbered 0. The last iteration number is one less than what is set for the pass iteration number. If a pass has its iteration attribute set to 5 then the last iteration number (fifth execution of the pass) is four. See Passes#iteration.
pass_number	Sets the active pass index number in a GPU parameter. The first pass in a technique has an index of 0, the second an index of 1 and so on. This is useful for multi-pass shaders (for example, fur or blur shader) that need to know what pass it is. By setting up the auto parameter in a default program parameters list in a program definition, there is no requirement to set the pass number parameter in each pass and lose track. See Example use of iteration.
projection_matrix	The current projection matrix.
render_target_flipping	The value use to adjust transformed y position if bypassed projection matrix transform. It's -1 if the render target requires texture flipping, +1 otherwise.
scene_depth_range	Provides information about the depth range as viewed from the current camera being used to render. Provided as float4(minDepth, maxDepth, depthRange, 1 / depthRange).
shadow_scene_depth_range	Provides information about the depth range as viewed from the shadow camera relating to a selected light. Requires a light index parameter. Provided as float4(minDepth, maxDepth, depthRange, 1 / depthRange).
sintime_0_1	The same as sintime0_x but scaled to [0..1]
sintime_0_x	Sine of time_0_x
sintime_0_2pi	The same as sintime0_x but scaled to [0..2*Pi]
spotlight_params	A float4 containing the three spotlight parameters and a control value. The order of the parameters is cos(inner angle /2 ), cos(outer angle / 2), falloff, and the final w value is 1.0f. For non-spotlights the value is float4(1,0,0,1). This requires an index in the 'extra_params' field, and relates to the 'nth' closest light which could affect this object (ie 0 refers to the closest light). If there are less lights than this, the details are like a non-spotlight.
surface_ambient_colour	The ambient color reflectance properties of the pass (see ambient). This allows you access to fixed-function pipeline property handily.
surface_diffuse_colour	The diffuse colour reflectance properties of the pass (see diffuse). This allows you access to fixed-function pipeline property handily.
surface_emissive_colour	The amount of self-illumination of the pass (see emissive). This allows you access to fixed-function pipeline property handily.
surface_shininess	The shininess of the pass, affecting the size of specular highlights (See specular). This allows you bind to fixed-function pipeline property handily.
surface_specular_colour	The specular colour reflectance properties of the pass (see specular). This allows you access to fixed-function pipeline property handily.
transpose_worldviewproj_matrix	The transpose of the world, view and projection matrices
tantime_0_x	Tangent of time_0_x
tantime_0_2pi	The same as tantime0_x but scaled to [0..2*Pi]
tantime_0_1	The same as tantime0_x but scaled to [0..1]
texel_offsets	Provides details of the rendersystem-specific texture coordinate offsets required to map texels onto pixels. float4 (horizontalOffset, verticalOffset, horizontalOffset / viewport_width, verticalOffset / viewport_height).
texture_size	Provides texture size of the selected texture unit. Requires a texture unit index parameter. Provided as float4(width, height, depth, 1). For 2D-texture, depth sets to 1, for 1D-texture, height and depth sets to 1.
texture_viewproj_matrix	Applicable to vertex programs which have been specified as the 'shadow receiver' vertex program alternative, or where a texture unit is marked as content_type shadow; this provides details of the view/projection matrix for the current shadow projector. The optional 'extra_params' entry specifies which light the projector refers to (for the case of content_type shadow where more than one shadow texture may be present in a single pass), where 0 is the default and refers to the first light referenced in this pass.
time	The current time, factored by the optional parameter (or 1.0f if not supplied).
time_0_x	Single float time value, which repeats itself based on "cycle time" given as an 'extra_params' field
time_0_2pi	The same as time0_x but scaled to [0..2*Pi]
time_0_1	The same as time0_x but scaled to [0..1]
time_0_x_packed	Four-element vector of time0_x, sintime0_x, costime0_x, tantime0_x
time_0_1_packed	The same as time0_x_packed but all values scaled to [0..1]
time_0_2pi_packed	The same as time0_x_packed but scaled to [0..2*Pi]
transpose_view_matrix	The transpose of the view matrix
transpose_viewproj_matrix	The transpose of the view & projection matrices
transpose_projection_matrix	The transpose of the projection matrix
transpose_worldview_matrix	The transpose of the world and view matrices
transpose_world_matrix	The transpose of the world matrix
view_direction	View direction vector in object space
view_side_vector	View local X axis
view_up_vector	View local Y axis
view_matrix	The current view matrix.
viewport_height	The current viewport height in pixels
viewport_width	The current viewport width in pixels
viewport_size	4-element vector of viewport_width, viewport_height, inverse_viewport_width, inverse_viewport_height
viewproj_matrix	The current view and projection matrices concatenated.
world_matrix	The current world matrix.
world_matrix_array_3x4	An array of world matrices, each represented as only a 3x4 matrix (three rows of four columns) usually for doing hardware skinning. Make enough entries available in your vertex program for the number of bones in use, that is, an array of numBones*3 float4's.
worldviewproj_matrix	The current world, view and projection matrices concatenated.
worldview_matrix	The current world and view matrices concatenated.

param_named

This attribute is the same as param_indexed, but uses a named parameter instead of an index. You can use this only with high-level programs that include parameter names. You can use indexed parameters for high-level programs too, but they are less portable since if you reorder your parameters in the high-level program the indexes will change.

Format:

param_named name type value

The type parameter is required because the program is not compiled and loaded when the material script is parsed, but only when it is used, to save memory. Thus, at parse-time, the types of the parameters are not known.

Example:

param_named shininess float4 10.0 0 0 0

param_named_auto

This is the named equivalent of param_indexed_auto, for use with high-level programs.

Format:

 param_named_auto name value_code extra_params

Example:

param_named_auto worldViewProj WORLDVIEWPROJ_MATRIX

The allowed value codes and the meaning of extra_params are detailed in param_indexed_auto.

Shadows and vertex programs

When using shadows, the use of vertex programs can add some additional complexities, because the Multiverse Client can only automatically deal with everything when using the fixed-function pipeline. If you use vertex programs, and you are also using shadows, you may need to make some adjustments. For general information about shadows, see About Shadows.

If you use stencil shadows, then any vertex programs which do vertex deformation can be a problem, because stencil shadows are calculated on the CPU, which does not have access to the modified vertices. If the vertex program is doing standard skeletal animation, this is ok (see section above) because the Multiverse Client knows how to replicate the effect in software, but any other vertex deformation cannot be replicated, and you will either have to accept that the shadow will not reflect this deformation, or you should turn off shadows for that object.

If you use texture shadows, then vertex deformation is acceptable; however, when rendering the object into the shadow texture (the shadow caster pass), the shadow has to be rendered in a solid colour (linked to the ambient colour). You must therefore provide an alternative vertex program, so the Multiverse Client provides you with a way of specifying one to use when rendering the caster. Basically you link an alternative vertex program, using exactly the same syntax as the original vertex program link:

shadow_caster_vertex_program_ref myShadowCasterVertexProgram
{
	param_indexed_auto 0 worldviewproj_matrix
	param_indexed_auto 4 ambient_light_colour
}

When rendering a shadow caster, the Multiverse Client will automatically use the alternate program. You can bind the same or different parameters to the program. The most important thing is that you bind ambient_light_colour, since this determines the color of the shadow in modulative texture shadows. If you don't supply an alternate program, the Multiverse Client will fall back on a fixed-function material which will not reflect any vertex deformation in your vertex program.

In addition, when rendering the shadow receivers with shadow textures, the Multiverse Client needs to project the shadow texture. It does this automatically in fixed function mode, but if the receivers use vertex programs, they need to have a shadow receiver program which does the usual vertex deformation, but also generates projective texture coordinates. The additional program linked into the pass like this:

shadow_receiver_vertex_program_ref myShadowReceiverVertexProgram
{
	param_indexed_auto 0 worldviewproj_matrix
	param_indexed_auto 4 texture_viewproj_matrix
}

For the purposes of writing this alternate program, there is an automatic parameter binding of 'texture_viewproj_matrix' which provides the program with texture projection parameters. The vertex program should do its normal vertex processing, and generate texture coordinates using this matrix and place them in texture coord sets 0 and 1, since some shadow techniques use 2 texture units. The color of the vertices output by this vertex program must always be white, so as not to affect the final color of the rendered shadow.

When using additive texture shadows, the shadow pass render is actually the lighting render, so if you perform any fragment program lighting you also need to use shadow_receiver_fragment_program_ref to pull in a custom fragment program:

shadow_receiver_fragment_program_ref myShadowReceiverFragmentProgram
{
	param_named_auto lightDiffuse light_diffuse_colour 0 
}

You should pass the projected shadow coordinates from the custom vertex program. As for textures, texture unit 0 will always be the shadow texture. Any other textures which you bind in your pass will be carried across too, but will be moved up by 1 unit to make room for the shadow texture. Therefore your shadow receiver fragment program is likely to be the same as the bare lighting pass of your normal material, except that you insert an extra texture sampler at index 0, which you will use to adjust the result by (modulating diffuse and specular components).