[ < ] | [ Up ] | [ > ] |  |  |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 3.1.5 Using Vertex and Fragment Programs in a Pass

Within a pass section of a material script, you can reference a vertex and / or a fragment program which is been defined in a .program script (See section 3.1.4 Declaring Vertex and Fragment Programs). The programs are defined separately from the usage of them in the pass, since the programs are very likely to be reused between many separate materials, probably across many different .material scripts, so this approach lets you define the program only once and use it many times.

As well as naming the program in question, you can also provide parameters to it. Here's a simple example:

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

In this example, we bind a vertex program called 'myVertexProgram' (which will be defined elsewhere) to the pass, and give it 2 parameters, one is an 'auto' parameter, meaning we do not have to supply a value as such, just a recognised code (in this case it's the world/view/projection matrix which is kept up to date automatically by Ogre). The second parameter is a manually specified parameter, a 4-element float. The indexes are described later.

The syntax of the link to a vertex program and a fragment program are identical, the only difference is that 'fragment_program_ref' is used instead of 'vertex_program_ref'.

### Parameter specification

Parameters can be specified using one of 4 commands as shown below. The same syntax is used whether you are defining a parameter just for this particular use of the program, or when specifying the Default Program Parameters. Parameters set in the specific use of the program override the defaults.

- param_indexed
- param_indexed_auto
- param_named
- param_named_auto

### param_indexed

This command sets the value of an indexed parameter.

format: param_indexed <index> <type> <value>
example: param_indexed 0 float4 10.0 0 0 0

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

The value of 'type' can be float4, matrix4x4, float<n>, int4, int<n>. Note that 'int' parameters are only available on some more advanced program syntaxes, check the D3D or GL 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 or tab-delimited list of values which can be converted into the type you have specified.

### param_indexed_auto

This command tells Ogre 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>
example: param_indexed_auto 0 worldviewproj_matrix

'index' has the same meaning as param_indexed; note this time you do not have to specify the size of the parameter because the engine knows this already. In the example, the world/view/projection matrix is being used so this is implicitly a matrix4x4.

'value_code' is one of a list of recognised values:

world_matrix
  The current world matrix.
world_matrix_array_3x4
  An array of world matrices, each represented as only a 3x4 matrix (3 rows of 4columns) usually for doing hardware skinning. You should make enough entries available in your vertex program for the number of bones in use, ie an array of numBones*3 float4's.
view_matrix
  The current view matrix.
projection_matrix
  The current projection matrix.
worldview_matrix
  The current world and view matrices concatenated.
viewproj_matrix
  The current view and projection matrices concatenated.
worldviewproj_matrix
  The current world, view and projection matrices concatenated.
inverse_world_matrix
  The inverse of the current world matrix.
inverse_view_matrix
  The inverse of the current view matrix.
inverse_worldview_matrix
  The inverse of the current concatenated world and view matrices.
inverse_transpose_world_matrix
  The inverse transpose of the current world matrix.
inverse_transpose_worldview_matrix
  The inverse transpose of the current concatenated world and view matrices.
inverse_viewproj_matrix
  The inverse of the view & projection matrices
inverse_transpose_viewproj_matrix
  The inverse transpose of the view & projection matrices
transpose_viewproj_matrix
  The transpose of the view & projection matrices
transpose_view_matrix
  The transpose of the view matrix
inverse_transpose_view_matrix
  The inverse transpose of the view matrix
transpose_projection_matrix
  The transpose of the projection matrix
inverse_projection_matrix
  The inverse of the projection matrix
inverse_transpose_projection_matrix
  The inverse transpose of the projection matrix
transpose_worldviewproj_matrix
  The transpose of the world, view and projection matrices
inverse_worldviewproj_matrix
  The inverse of the world, view and projection matrices
inverse_transpose_worldviewproj_matrix
  The inverse transpose of the world, view and projection matrices
transpose_worldview_matrix
  The transpose of the world and view matrices
inverse_transpose_worldview_matrix
  The inverse transpose of the world and view matrices
transpose_world_matrix
  The transpose of the world matrix
inverse_transpose_world_matrix
  The inverse transpose of the world matrix
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). NB 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). NB if there are no lights this close, then the parameter will be set to black.
light_attenuation
  A float4 containing the 4 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). NB 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.
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) whilst 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 (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 - 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 (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_object_space
  The direction 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 (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 - this property only works on directional lights, and we recommend that you use light_position_object_space instead since that returns a generic 4D vector.
ambient_light_colour
  The colour of the ambient light currently set in the scene.
camera_position
  The current cameras position in world space.
camera_position_object_space
  The current cameras position in object space (ie when the object is at (0,0,0)).
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
costime_0_x
  Cosine of time_0_x
sintime_0_x
  Sine of time_0_x
tantime_0_x
  Tangent of time_0_x
time_0_x_packed
  4-element vector of time0_x, sintime0_x, costime0_x, tantime0_x
time_0_1
  As time0_x but scaled to [0..1]
costime_0_1
  As costime0_x but scaled to [0..1]
sintime_0_1
  As sintime0_x but scaled to [0..1]
tantime_0_1
  As tantime0_x but scaled to [0..1]
time_0_1_packed
  As time0_x_packed but all values scaled to [0..1]
time_0_2pi
  As time0_x but scaled to [0..2*Pi]
costime_0_2pi
  As costime0_x but scaled to [0..2*Pi]
sintime_0_2pi
  As sintime0_x but scaled to [0..2*Pi]
tantime_0_2pi
  As tantime0_x but scaled to [0..2*Pi]
time_0_2pi_packed
  As time0_x_packed but scaled to [0..2*Pi]
fps
  The current frames per second
viewport_width
  The current viewport width in pixels
viewport_height
  The current viewport height in pixels
inverse_viewport_width
  1.0/the current viewport width in pixels
inverse_viewport_height
  1.0/the current viewport height in pixels
view_direction
  View direction vector in object space
view_side_vector
  View local X axis
view_up_vector
  View local Y axis
fov
  Vertical field of view, in radians
near_clip_distance
  Near clip distance, in world units
far_clip_distance
  Far clip distance, in world units (may be 0 for infinite view projection)
texture_viewproj_matrix
  Only applicable to vertex programs which have been specified as the 'shadow receiver' vertex program alternative; this provides details of the view/projection matrix for the current shadow projector.
custom
  This 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.

### param_named

This is the same as param_indexed, but uses a named parameter instead of an index. This can only be used with high-level programs which include parameter names; if you're using an assembler program then you have no choice but to use indexes. Note that you can use indexed parameters for high-level programs too, but it is less portable since if you reorder your parameters in the high-level program the indexes will change.
format: param_named <name> <type> <value>
example: param_named shininess float4 10.0 0 0 0
The type is required because the program is not compiled and loaded when the material script is parsed, so at this stage we have no idea what types the parameters are. Programs are only loaded and compiled when they are used, to save memory.

### 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 (See section 7. Shadows), the use of vertex programs can add some additional complexities, because Ogre 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.

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 Ogre 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 Ogre 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, Ogre 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 ambiend_light_colour, since this determines the colour of the shadow in modulative texture shadows. If you don't supply an alternate program, Ogre will fall back on a fixed-function material which will not reflect any vertex deformation you do in your vertex program.

In addition, when rendering the shadow receivers with shadow textures, Ogre 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 it's 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 colour of the vertices output by this vertex program must always be white, so as not to affect the final colour of the rendered shadow.

[ < ] | [ Up ] | [ > ] |  |  |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Steve Streeting on , 20 2005 using texi2html