source: OGRE/trunk/ogrenew/Docs/src/CompositorScript.inc @ 692

Revision 692, 22.5 KB checked in by mattausch, 19 years ago (diff)

adding ogre 1.2 and dependencies

RevLine 
[692]1@node Compositor Scripts
2@section Compositor Scripts
3
4The compositor framework is a subsection of the OGRE API that allows you to easily define full screen post-processing effects. Compositor scripts offer you the ability to define compositor effects in a script which can be reused and modified easily, rather than having to use the API to define them. You still need to use code to instantiate a compositor against one of your visible viewports, but this is a much simpler process than actually defining the compositor itself.
5
6@heading Compositor Fundamentals
7
8Performing post-processing effects generally involves first rendering the scene to a texture, either in addition to or instead of the main window. Once the scene is in a texture, you can then pull the scene image into a fragment program and perform operations on it by rendering it through full screen quad. The target of this post processing render can be the main result (e.g. a window), or it can be another render texture so that you can perform multi-stage convolutions on the image. You can even 'ping-pong' the render back and forth between a couple of render textures to perform convolutions which require many iterations, without using a separate texture for each stage. Eventually you'll want to render the result to the final output, which you do with a full screen quad. This might replace the whole window (thus the main window doesn't need to render the scene itself), or it might be a combinational effect. @*@*
9
10So that we can discuss how to implement these techniques efficiently, a number of definitions are required:@*@*
11@table @asis
12@item Compositor
13Definition of a fullscreen effect that can be applied to a user viewport. This is what you're defining when writing compositor scripts as detailed in this section.
14@item Compositor Instance
15An instance of a compositor as applied to a single viewport. You create these based on compositor definitions, @xref{Applying a Compositor}.
16@item Compositor Chain
17It is possible to enable more than one compositor instance on a viewport at the same time, with one compositor taking the results of the previous one as input. This is known as a compositor chain. Every viewport which has at least one compositor attached to it has a compositor chain. @xref{Applying a Compositor}
18@item Target
19This is a RenderTarget, ie the place where the result of a series of render operations is sent. A target may be the final output (and this is implicit, you don't have to declare it), or it may be an intermediate render texture, which you declare in your script with the @ref{compositor_texture,texture line}. A target which is not the output target has a defined size and pixel format which you can control.
20@item Output Target
21As Target, but this is the single final result of all operations. The size and pixel format of this target cannot be controlled by the compositor since it is defined by the application using it, thus you don't declare it in your script. However, you do declare a Target Pass for it, see below.
22@item Target Pass
23A Target may be rendered to many times in the course of a composition effect. In particular if you 'ping pong' a convolution between a couple of textures, you will have more than one Target Pass per Target. Target passes are declared in the script using a @ref{Compositor Target Passes,target or target_output line}, the latter being the final output target pass, of which there can be only one.
24@item Pass
25Within a Target Pass, there are one or more individual @ref{Compositor Passes,passes}, which perform a very specific action, such as rendering the original scene (or pulling the result from the previous compositor in the chain), rendering a fullscreen quad, or clearing one or more buffers. Typically within a single target pass you will use the either a 'render scene' pass or a 'render quad' pass, not both. Clear can be used with either type.
26@end table
27
28@heading Loading scripts
29
30Compositor scripts are loaded when resource groups are initialised: OGRE looks in all resource locations associated with the group (see Root::addResourceLocation) for files with the '.compositor' extension and parses them. If you want to parse files manually, use CompositorSerializer::parseScript.@*@*
31
32@heading Format
33
34Several compositors may be defined in a single script. The script format is pseudo-C++, with sections delimited by curly braces ('{', '}'), and comments indicated by starting a line with '//' (note, no nested form comments allowed). The general format is shown below in the example below:@*@*
35@example
36// This is a comment
37// Black and white effect
38compositor B&W
39{
40    technique
41    {
42        // Temporary textures
43        texture rt0 target_width target_height PF_A8R8G8B8
44
45        target rt0
46        {
47            // Render output from previous compositor (or original scene)
48            input previous
49        }
50
51        target_output
52        {
53            // Start with clear output
54            input none
55            // Draw a fullscreen quad with the black and white image
56            pass render_quad
57            {
58                // Renders a fullscreen quad with a material
59                material Ogre/Compositor/BlackAndWhite
60                input 0 rt0
61            }
62        }
63    }
64}
65@end example
66
67Every compositor in the script must be given a name, which is the line 'compositor <name>' before the first opening '{'. This name must be globally unique. It can include path characters (as in the example) to logically divide up your compositors, and also to avoid duplicate names, but the engine does not treat the name as hierarchical, just as a string.  Names can include spaces but must be surrounded by double quotes ie compositor "My Name".@*@*
68
69The major components of a compositor are the @ref{Compositor Techniques,techniques}, the @ref{Compositor Target Passes,target passes} and the @ref{Compositor Passes,passes}, which are covered in detail in the following sections.@*@*
70
71@node Compositor Techniques
72@subsection Techniques
73
74A compositor technique is much like a @ref{Techniques,material technique} in that it describes one approach to achieving the effect you're looking for. A compositor definition can have more than one technique if you wish to provide some fallback should the hardware not support the technique you'd prefer to use. Techniques are evaluated for hardware support based on 2 things:
75@table @asis
76@item Material support
77All @ref{Compositor Passes,passes} that render a fullscreen quad use a material; for the technique to be supported, all of the materials referenced must have at least one supported material technique. If they don't, the compositor technique is marked as unsupported and won't be used.
78@item Texture format support
79This one is slightly more complicated. When you request a @ref{compositor_texture,texture} in your technique, you request a pixel format. Not all formats are natively supported by hardware, especially the floating point formats. However, in this case the hardware will typically downgrade the texture format requested to one that the hardware does support - with compositor effects though, you might want to use a different approach if this is the case. So, when evaluating techniques, the compositor will first look for native support for the exact pixel format you've asked for, and will skip onto the next technique if it is not supported, thus allowing you to define other techniques with simpler pixel formats which use a different approach. If it doesn't find any techniques which are natively supported, it tries again, this time allowing the hardware to downgrade the texture format and thus should find at least some support for what you've asked for.
80@end table
81
82As with material techniques, compositor techniques are evaluated in the order you define them in the script, so techniques declared first are preferred over those declared later.
83
84Format: technique { }@*@*
85
86Techniques can have the following nested elements:
87@itemize @bullet
88@item @ref{compositor_texture,texture}
89@item @ref{Compositor Target Passes,target}
90@item @ref{Compositor Target Passes,target_output}
91@end itemize
92
93@anchor{compositor_texture}
94@subheading texture
95
96This declares a render texture for use in subsequent @ref{Compositor Target Passes,target passes}.
97
98@*@*
99Format: texture <Name> <Width> <Height> <Pixel Format>@*@*
100
101Here is a description of the parameters:
102@table @asis
103@item Name
104A name to give the render texture, which must be unique within this compositor. This name is used to reference the texture in @ref{Compositor Target Passes,target passes}, when the texture is rendered to, and in @ref{Compositor Passes,passes}, when the texture is used as input to a material rendering a fullscreen quad.
105@item Width, Height
106The dimensions of the render texture. You can either specify a fixed width and height, or you can request that the texture matches the physical dimensions of the viewport to which the compositor is attached (specify target_width and target_height instead of numerical dimensions).
107@item Pixel Format
108The pixel format of the render texture. This affects how much memory it will take, what colour channels will be available, and what precision you will have within those channels. The available options are PF_A8R8G8B8, PF_R8G8B8A8, PF_R8G8B8, PF_FLOAT16_RGBA, PF_FLOAT16_RGB, PF_FLOAT16_R, PF_FLOAT32_RGBA, PF_FLOAT32_RGB, and PF_FLOAT32_R.
109@end table
110
111Example: texture rt0 512 512 PF_R8G8B8A8@*
112Example: texture rt1 target_width target_height PF_FLOAT32_RGB@*@*
113
114@node Compositor Target Passes
115@subsection Target Passes
116
117A target pass is the action of rendering to a given target, either a render texture or the final output. You can update the same render texture multiple times by adding more than one target pass to your compositor script - this is very useful for 'ping pong' renders between a couple of render textures to perform complex convolutions that cannot be done in a single render, such as blurring.@*@*
118
119There are two types of target pass, the sort that updates a render texture:@*@*
120Format: target <Name> { }@*@*
121... and the sort that defines the final output render:@*@*
122Format: target_output { }@*@*
123
124The contents of both are identical, the only real difference is that you can only have a single target_output entry, whilst you can have many target entries. Here are the attributes you can use in a 'target' or 'target_output' section of a .compositor script:
125
126@itemize @bullet
127@item
128@ref{compositor_target_input,input}
129@item
130@ref{only_initial}
131@item
132@ref{visibility_mask}
133@item
134@ref{compositor_lod_bias,lod_bias}
135@item
136@ref{material_scheme}
137@item
138@ref{Compositor Passes,pass}
139@end itemize
140
141@heading Attribute Descriptions
142@anchor{compositor_target_input}
143@subheading input
144Sets input mode of the target, which tells the target pass what is pulled in before any of its own passes are rendered.@*@*
145Format: input (none | previous)@*@*
146Default: input none@*@*
147@table @asis
148@item none
149The target will have nothing as input, all the contents of the target must be generated using its own passes. Note this does not mean the target will be empty, just no data will be pulled in. For it to truly be blank you'd need a 'clear' pass within this target.
150@item previous
151The target will pull in the previous contents of the viewport. This will be either the original scene if this is the first compositor in the chain, or it will be the output from the previous compositor in the chain if the viewport has multiple compositors enabled.
152@end table
153
154@anchor{only_initial}
155@subheading only_initial
156If set to on, this target pass will only execute once initially after the effect has been enabled. This could be useful to perform once-off renders, after which the static contents are used by the rest of the compositor.@*@*
157Format: only_initial (on | off)@*@*
158Default: only_initial off@*@*
159
160
161@anchor{visibility_mask}
162@subheading visibility_mask
163Sets the visibility mask for any render_scene passes performed in this target pass. This is a bitmask (although it must be specified as decimal, not hex) and maps to SceneManager::setVisibilityMask.
164Format: visibility_mask <mask>@*@*
165Default: visibility_mask 4294967295@*@*
166
167@anchor{compositor_lod_bias}
168@subheading lod_bias
169Set the scene LOD bias for any render_scene passes performed in this target pass. The default is 1.0, everything below that means lower quality, higher means higher quality.@*@*
170Format: lod_bias <lodbias>@*@*
171Default: lod_bias 1.0@*@*
172
173@anchor{material_scheme}
174@subheading material_scheme
175Set the material scheme for any render_scene passes performed in this target pass. Material schemes allow you to select alternative rendering paths for all objects in the scene.@*@*
176Format: material_scheme <Name>@*@*
177Default: material_scheme Default@*@*
178
179@node Compositor Passes
180@subsection Compositor Passes
181
182A pass is a single rendering action to be performed in a target pass. @*@*
183Format: 'pass' (render_quad | clear | stencil | render_scene) { }@*@*
184
185There are four types of pass:
186@table @asis
187@item clear
188This 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.
189@item stencil
190This 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.
191@item render_scene
192This kind of pass performs a regular rendering of the scene. It will use the @ref{visibility_mask}, @ref{compositor_lod_bias,lod_bias}, and @ref{material_scheme} from the parent target pass.
193@item render_quad
194This 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.
195@end table
196
197Here are the attributes you can use in a 'pass' section of a .compositor script:
198
199@heading Available Pass Attributes
200@itemize @bullet
201@item
202@ref{material}
203@item
204@ref{compositor_pass_input,input}
205@item
206@ref{first_render_queue}
207@item
208@ref{last_render_queue}
209@item
210@ref{compositor_clear,clear}
211@item
212@ref{compositor_stencil,stencil}
213@end itemize
214
215@anchor{material}
216@subheading material
217For 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 @ref{compositor_pass_input,input} attribute to map other texture targets into the texture bindings needed by this material.@*@*
218Format: material <Name>@*@*
219
220@anchor{compositor_pass_input}
221@subheading input
222For passes of type 'render_quad', this is how you map one or more local render textures (@xref{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.@*@*
223Format: input <sampler> <Name>@*@*
224@table @asis
225@item sampler
226The texture sampler to set, must be a number in the range [0, OGRE_MAX_TEXTURE_LAYERS-1].
227@item Name
228The name of the local render texture to bind, as declared in @ref{compositor_texture} and rendered to in one or more @ref{Compositor Target Passes,target pass}.
229@end table
230Example: input 0 rt0
231
232@anchor{first_render_queue}
233@subheading first_render_queue
234For 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.@*@*
235Format: first_render_queue <id>@*@*
236Default: first_render_queue 5@*@*
237
238@anchor{last_render_queue}
239@subheading last_render_queue
240For 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.@*@*
241Format: last_render_queue <id>@*@*
242Default: last_render_queue 95
243
244@anchor{compositor_clear}
245@heading Clear Section
246For passes of type 'clear', this section defines the buffer clearing parameters. @*@*
247Format: clear { }@*@*
248
249Here are the attributes you can use in a 'clear' section of a .compositor script:
250@itemize @bullet
251@item
252@ref{compositor_clear_buffers,buffers}
253@item
254@ref{compositor_clear_colour_value,colour_value}
255@item
256@ref{compositor_clear_depth_value,depth_value}
257@item
258@ref{compositor_clear_stencil_value,stencil_value}
259
260@anchor{compositor_clear_buffers}
261@subheading buffers
262Sets the buffers cleared by this pass.@*@*
263
264Format: buffers [colour] [depth] [stencil]@*@*
265Default: buffers colour depth@*@*
266
267@anchor{compositor_clear_colour_value}
268@subheading colour_value
269Set the colour used to fill the colour buffer by this pass, if the colour buffer is being cleared (@ref{compositor_clear_buffers,buffers}). @*@*
270Format: colour_value <red> <green> <blue> <alpha>@*@*
271Default: colour_value 0 0 0 0@*@*
272
273@anchor{compositor_clear_depth_value}
274@subheading depth_value
275Set the depth value used to fill the depth buffer by this pass, if the depth buffer is being cleared (@ref{compositor_clear_buffers,buffers}). @*@*
276Format: depth_value <depth>@*@*
277Default: depth_value 1.0@*@*
278
279@anchor{compositor_clear_stencil_value}
280@subheading stencil_value
281Set the stencil value used to fill the stencil buffer by this pass, if the stencil buffer is being cleared (@ref{compositor_clear_buffers,buffers}). @*@*
282Format: stencil_value <value>@*@*
283Default: stencil_value 0.0@*@*
284@end itemize
285
286@anchor{compositor_stencil}
287@heading Stencil Section
288For passes of type 'stencil', this section defines the stencil operation parameters. @*@*
289
290Format: stencil { }@*@*
291
292Here are the attributes you can use in a 'stencil' section of a .compositor script:
293
294@itemize @bullet
295@item
296@ref{compositor_stencil_check,check}
297@item
298@ref{compositor_stencil_comp_func,comp_func}
299@item
300@ref{compositor_stencil_ref_value,ref_value}
301@item
302@ref{compositor_stencil_mask,mask}
303@item
304@ref{compositor_stencil_fail_op,fail_op}
305@item
306@ref{compositor_stencil_depth_fail_op,depth_fail_op}
307@item
308@ref{compositor_stencil_pass_op,pass_op}
309@item
310@ref{compositor_stencil_two_sided,two_sided}
311
312@anchor{compositor_stencil_check}
313@subheading check
314Enables 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.
315Format: check (on | off)@*@*
316
317@anchor{compositor_stencil_comp_func}
318@subheading comp_func
319Sets the function used to perform the following comparison:@*@*
320(ref_value & mask) comp_func (Stencil Buffer Value & mask)@*@*
321
322What 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 @ref{compositor_stencil_fail_op,fail_op}, @ref{compositor_stencil_depth_fail_op,depth_fail_op} and @ref{compositor_stencil_pass_op,pass_op} respectively. If the stencil check fails, no colour or depth are written to the frame buffer.@*@*
323Format: comp_func (always_fail | always_pass | less | less_equal | not_equal | greater_equal | greater)@*@*
324Default: comp_func always_pass@*@*
325
326@anchor{compositor_stencil_ref_value}
327@subheading ref_value
328Sets the reference value used to compare with the stencil buffer as described in @ref{compositor_stencil_comp_func,comp_func}.@*@*
329Format: ref_value <value>@*@*
330Default: ref_value 0.0@*@*
331
332@anchor{compositor_stencil_mask}
333@subheading mask
334Sets the mask used to compare with the stencil buffer as described in @ref{compositor_stencil_comp_func,comp_func}.@*@*
335Format: mask <value>@*@*
336Default: mask 4294967295@*@*
337
338@anchor{compositor_stencil_fail_op}
339@subheading fail_op
340Sets what to do with the stencil buffer value if the result of the stencil comparison (@ref{compositor_stencil_comp_func,comp_func}) and depth comparison is that both fail.@*@*
341Format: fail_op (keep | zero | replace | increment | decrement | increment_wrap | decrement_wrap | invert)@*@*
342Default: depth_fail_op keep@*@*
343These actions mean:
344@table @asis
345@item keep
346Leave the stencil buffer unchanged.
347@item zero
348Set the stencil value to zero.
349@item replace
350Set the stencil value to the reference value.
351@item increment
352Add one to the stencil value, clamping at the maximum value.
353@item decrement
354Subtract one from the stencil value, clamping at 0.
355@item increment_wrap
356Add one to the stencil value, wrapping back to 0 at the maximum.
357@item decrement_wrap
358Subtract one from the stencil value, wrapping to the maximum below 0.
359@item invert
360invert the stencil value.
361@end table
362
363
364@anchor{compositor_stencil_depth_fail_op}
365@subheading depth_fail_op
366Sets what to do with the stencil buffer value if the result of the stencil comparison (@ref{compositor_stencil_comp_func,comp_func}) passes but the depth comparison fails. @*@*
367
368Format: depth_fail_op (keep | zero | replace | increment | decrement | increment_wrap | decrement_wrap | invert)@*@*
369Default: depth_fail_op keep@*@*
370
371@anchor{compositor_stencil_pass_op}
372@subheading pass_op
373Sets what to do with the stencil buffer value if the result of the stencil comparison (@ref{compositor_stencil_comp_func,comp_func}) and the depth comparison pass. @*@*
374Format: pass_op (keep | zero | replace | increment | decrement | increment_wrap | decrement_wrap | invert)@*@*
375Default: pass_op keep@*@*
376
377@anchor{compositor_stencil_two_sided}
378@subheading two_sided
379Enables or disables two-sided stencil operations, which means the inverse of the operations applies to back-facing polygons.@*@*
380Format: two_sided (on | off)@*@*
381Default: two_sided off@*@*
382@end itemize
383
384@node Applying a Compositor
385@subsection Applying a Compositor
386
387Adding a compositor instance to a viewport is very simple. All you need to do is:@*@*
388@example
389CompositorManager::getSingleton().addCompositor(viewport, compositorName);
390@end example
391@*@*
392Where viewport is a pointer to your viewport, and compositorName is the name of the compositor to create an instance of. By doing this, a new instance of a compositor will be added to a new compositor chain on that viewport. You can call the method multiple times to add further compositors to the chain on this viewport. By default, each compositor which is added is disabled, but you can change this state by calling:@*@*
393@example
394CompositorManager::getSingleton().setCompositorEnabled(viewport, compositorName, enabledOrDisabled);
395@end example
396@*@*
397For more information on defining and using compositors, see Demo_Compositor in the Samples area, together with the Examples.compositor script in the media area.
398
Note: See TracBrowser for help on using the repository browser.