OGRE Manual v1.7 ('Cthugha'): Compositor Passes

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

### 3.2.3 Compositor Passes

A pass is a single rendering action to be performed in a target pass.
Format: 'pass' (render_quad | clear | stencil | render_scene | render_custom) [custom name] { }
There are four types of pass:

clear
  This kind of pass sets the contents of one or more buffers in the target to a fixed value. So this could clear the colour buffer to a fixed colour, set the depth buffer to a certain set of contents, fill the stencil buffer with a value, or any combination of the above.
stencil
  This kind of pass configures stencil operations for the subsequent passes. It can set the stencil compare function, operations and reference values for you to perform your own stencil effects.
render_scene
  This kind of pass performs a regular rendering of the scene. It will use the visibility_mask, lod_bias, and material_scheme from the parent target pass.
render_quad
  This kind of pass renders a quad over the entire render target, using a given material. You will undoubtedly want to pull in the results of other target passes into this operation to perform fullscreen effects.
render_custom
  This kind of pass is just a callback to user code for the composition pass specified in the custom name (and registered via CompositorManager::registerCustomCompositionPass) and allows the user to create custom render operations for more advanced effects. This is the only pass type that requires the custom name parameter.

Here are the attributes you can use in a 'pass' section of a .compositor script:

## Available Pass Attributes

- material
- input
- identifier
- first_render_queue
- last_render_queue
- material_scheme
- clear
- stencil

### material

For passes of type 'render_quad', sets the material used to render the quad. You will want to use shaders in this material to perform fullscreen effects, and use the input attribute to map other texture targets into the texture bindings needed by this material.
Format: material <Name>

### input

For passes of type 'render_quad', this is how you map one or more local render textures (See compositor_texture) into the material you're using to render the fullscreen quad. To bind more than one texture, repeat this attribute with different sampler indexes.
Format: input <sampler> <Name> [<MRTIndex>]

sampler
  The texture sampler to set, must be a number in the range [0, OGRE_MAX_TEXTURE_LAYERS-1].
Name
  The name of the local render texture to bind, as declared in compositor_texture and rendered to in one or more target pass.
MRTIndex
  If the local texture that you're referencing is a Multiple Render Target (MRT), this identifies the surface from the MRT that you wish to reference (0 is the first surface, 1 the second etc).

Example: input 0 rt0

### identifier

Associates a numeric identifier with the pass. This is useful for registering a listener with the compositor (CompositorInstance::addListener), and being able to identify which pass it is that's being processed when you get events regarding it. Numbers between 0 and 2^32 are allowed.
Format: identifier <number>
Example: identifier 99945
Default: identifier 0

### first_render_queue

For passes of type 'render_scene', this sets the first render queue id that is included in the render. Defaults to the value of RENDER_QUEUE_SKIES_EARLY.
Format: first_render_queue <id>
Default: first_render_queue 0

### last_render_queue

For passes of type 'render_scene', this sets the last render queue id that is included in the render. Defaults to the value of RENDER_QUEUE_SKIES_LATE.
Format: last_render_queue <id>
Default: last_render_queue 95

### material_scheme

If set, indicates the material scheme to use for this pass only. Useful for performing special-case rendering effects.
This will overwrite the scheme if set at the target scope as well.
Format: material_scheme <scheme name>
Default: None

## Clear Section

For passes of type 'clear', this section defines the buffer clearing parameters.
Format: clear { }
Here are the attributes you can use in a 'clear' section of a .compositor script:

- buffers
- colour_value
- depth_value
- stencil_value

  ### buffers

  Sets the buffers cleared by this pass.
  Format: buffers [colour] [depth] [stencil]
  Default: buffers colour depth

  ### colour_value

  Set the colour used to fill the colour buffer by this pass, if the colour buffer is being cleared (buffers).
  Format: colour_value <red> <green> <blue> <alpha>
  Default: colour_value 0 0 0 0

  ### depth_value

  Set the depth value used to fill the depth buffer by this pass, if the depth buffer is being cleared (buffers).
  Format: depth_value <depth>
  Default: depth_value 1.0

  ### stencil_value

  Set the stencil value used to fill the stencil buffer by this pass, if the stencil buffer is being cleared (buffers).
  Format: stencil_value <value>
  Default: stencil_value 0.0

## Stencil Section

For passes of type 'stencil', this section defines the stencil operation parameters.
Format: stencil { }
Here are the attributes you can use in a 'stencil' section of a .compositor script:

- check
- comp_func
- ref_value
- mask
- fail_op
- depth_fail_op
- pass_op
- two_sided

  ### check

  Enables or disables the stencil check, thus enabling the use of the rest of the features in this section. The rest of the options in this section do nothing if the stencil check is off. Format: check (on | off)

  ### comp_func

  Sets the function used to perform the following comparison:
  (ref_value & mask) comp_func (Stencil Buffer Value & mask)
  What happens as a result of this comparison will be one of 3 actions on the stencil buffer, depending on whether the test fails, succeeds but with the depth buffer check still failing, or succeeds with the depth buffer check passing too. You set the actions in the fail_op, depth_fail_op and pass_op respectively. If the stencil check fails, no colour or depth are written to the frame buffer.
  Format: comp_func (always_fail | always_pass | less | less_equal | not_equal | greater_equal | greater)
  Default: comp_func always_pass

  ### ref_value

  Sets the reference value used to compare with the stencil buffer as described in comp_func.
  Format: ref_value <value>
  Default: ref_value 0.0

  ### mask

  Sets the mask used to compare with the stencil buffer as described in comp_func.
  Format: mask <value>
  Default: mask 4294967295

  ### fail_op

  Sets what to do with the stencil buffer value if the result of the stencil comparison (comp_func) and depth comparison is that both fail.
  Format: fail_op (keep | zero | replace | increment | decrement | increment_wrap | decrement_wrap | invert)
  Default: depth_fail_op keep
  These actions mean:
  keep
    Leave the stencil buffer unchanged.
  zero
    Set the stencil value to zero.
  replace
    Set the stencil value to the reference value.
  increment
    Add one to the stencil value, clamping at the maximum value.
  decrement
    Subtract one from the stencil value, clamping at 0.
  increment_wrap
    Add one to the stencil value, wrapping back to 0 at the maximum.
  decrement_wrap
    Subtract one from the stencil value, wrapping to the maximum below 0.
  invert
    invert the stencil value.

  ### depth_fail_op

  Sets what to do with the stencil buffer value if the result of the stencil comparison (comp_func) passes but the depth comparison fails.
  Format: depth_fail_op (keep | zero | replace | increment | decrement | increment_wrap | decrement_wrap | invert)
  Default: depth_fail_op keep

  ### pass_op

  Sets what to do with the stencil buffer value if the result of the stencil comparison (comp_func) and the depth comparison pass.
  Format: pass_op (keep | zero | replace | increment | decrement | increment_wrap | decrement_wrap | invert)
  Default: pass_op keep

  ### two_sided

  Enables or disables two-sided stencil operations, which means the inverse of the operations applies to back-facing polygons.
  Format: two_sided (on | off)
  Default: two_sided off

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

This document was generated by Steve Streeting on December, 31 2009 using texi2html