Compositor Passes
From Multiverse
Contents |
Overview
A compositor pass is a single rendering action to be performed in a target pass.
Format:
pass type { }
where type is one of:
- clear: 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: 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: 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: 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.
Pass attributes
This section describes the attributes you can use in a 'pass' section of a .compositor script:
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
Example:
input 0 rt0
- 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 texture and rendered to in one or more target pass.
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. Default is RENDER_QUEUE_SKIES_EARLY.
Format:
first_render_queue id
Default:
first_render_queue 5
last_render_queue
For passes of type 'render_scene', this sets the last render queue id that is included in the render. Default is RENDER_QUEUE_SKIES_LATE.
Format:
last_render_queue id
Default:
last_render_queue 95
Clear section
For passes of type 'clear', this section defines the buffer clearing parameters. Format:
clear { }
The attributes of the 'clear' section of a compositor script are:
- 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 color used to fill the color buffer by this pass, if the color buffer is being cleared. See 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. See 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. See 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 { }
The attributes of the 'stencil' section of a compositor script are:
- 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 (See comp_func) and depth comparison is that both fail.
Format:
fail_op action
where action is one of the actions listed in the table below.
Default:
depth_fail_op keep
The following table describes the valid action.
| Action | Description |
|---|---|
| wrap | An |
| 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 (see comp_func) passes but the depth comparison fails.
Format:
depth_fail_op action
Default:
depth_fail_op keep
pass_op
Sets what to do with the stencil buffer value if the result of the stencil comparison (see comp_func) and the depth comparison pass.
Format:
pass_op action
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
This document is based on the OGRE Manual and is licensed under the Creative Commons Attribution-ShareAlike 2.5 License.
