source: OGRE/trunk/ogrenew/Docs/manual/manual_21.html @ 692

Revision 692, 9.3 KB checked in by mattausch, 18 years ago (diff)

adding ogre 1.2 and dependencies
Line 
1<HTML>
2<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
3<!-- Created on , 12 2006 by texi2html 1.64 -->
4<!--
5Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
6            Karl Berry  <karl@freefriends.org>
7            Olaf Bachmann <obachman@mathematik.uni-kl.de>
8            and many others.
9Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
10Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
11 
12-->
13<HEAD>
14<TITLE>OGRE Manual v1.2.0 ('Dagon'): Compositor Scripts</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Compositor Scripts">
17<META NAME="keywords" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Compositor Scripts">
18<META NAME="resource-type" CONTENT="document">
19<META NAME="distribution" CONTENT="global">
20<META NAME="Generator" CONTENT="texi2html 1.64">
21<LINK TYPE="text/css" rel="stylesheet" href="../style.css"> 
22</HEAD>
23
24<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
25
26<A NAME="SEC111"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_20.html#SEC106"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_13.html#SEC22"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_22.html#SEC115"> &gt; </A>]</TD>
31<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
32<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
33<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
34<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
35</TR></TABLE>
36<HR SIZE=1>
37<H2> 3.2 Compositor Scripts </H2>
38<!--docid::SEC111::-->
39<P>
40
41The 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.
42</P><P>
43
44<A NAME="SEC112"></A>
45<H2> Compositor Fundamentals </H2>
46<!--docid::SEC112::-->
47<P>
48
49Performing 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. <BR><BR>
50</P><P>
51
52So that we can discuss how to implement these techniques efficiently, a number of definitions are required:<BR><BR>
53<DL COMPACT>
54<DT>Compositor
55<DD>Definition 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.
56<DT>Compositor Instance
57<DD>An instance of a compositor as applied to a single viewport. You create these based on compositor definitions, See section <A HREF="manual_25.html#SEC144">3.2.4 Applying a Compositor</A>.
58<DT>Compositor Chain
59<DD>It 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. See section <A HREF="manual_25.html#SEC144">3.2.4 Applying a Compositor</A>
60<DT>Target
61<DD>This 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 <A HREF="manual_22.html#compositor_texture">texture line</A>. A target which is not the output target has a defined size and pixel format which you can control.
62<DT>Output Target
63<DD>As 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.
64<DT>Target Pass
65<DD>A 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 <A HREF="manual_23.html#SEC117">target or target_output line</A>, the latter being the final output target pass, of which there can be only one.
66<DT>Pass
67<DD>Within a Target Pass, there are one or more individual <A HREF="manual_24.html#SEC124">passes</A>, 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.
68</DL>
69<P>
70
71<A NAME="SEC113"></A>
72<H2> Loading scripts  </H2>
73<!--docid::SEC113::-->
74<P>
75
76Compositor 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.<BR><BR>
77</P><P>
78
79<A NAME="SEC114"></A>
80<H2> Format  </H2>
81<!--docid::SEC114::-->
82<P>
83
84Several 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:<BR><BR>
85<TABLE><tr><td>&nbsp;</td><td class=example><pre>// This is a comment
86// Black and white effect
87compositor B&#38;W
88{
89    technique
90    {
91        // Temporary textures
92        texture rt0 target_width target_height PF_A8R8G8B8
93
94        target rt0
95        {
96            // Render output from previous compositor (or original scene)
97            input previous
98        }
99
100        target_output
101        {
102            // Start with clear output
103            input none
104            // Draw a fullscreen quad with the black and white image
105            pass render_quad
106            {
107                // Renders a fullscreen quad with a material
108                material Ogre/Compositor/BlackAndWhite
109                input 0 rt0
110            }
111        }
112    }
113}
114</pre></td></tr></table></P><P>
115
116Every compositor in the script must be given a name, which is the line 'compositor &#60;name&#62;' 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".<BR><BR>
117</P><P>
118
119The major components of a compositor are the <A HREF="manual_22.html#SEC115">techniques</A>, the <A HREF="manual_23.html#SEC117">target passes</A> and the <A HREF="manual_24.html#SEC124">passes</A>, which are covered in detail in the following sections.<BR><BR>
120</P><P>
121
122<A NAME="Compositor Techniques"></A>
123<HR SIZE=1>
124<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
125<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_20.html#SEC106"> &lt; </A>]</TD>
126<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_13.html#SEC22"> Up </A>]</TD>
127<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_22.html#SEC115"> &gt; </A>]</TD>
128<TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT"> &nbsp; <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
129<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
130<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
131<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
132</TR></TABLE>
133<BR> 
134<FONT SIZE="-1">
135This document was generated
136by <I>Steve Streeting</I> on <I>, 12 2006</I>
137using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
138"><I>texi2html</I></A>
139
140</BODY>
141</HTML>
Note: See TracBrowser for help on using the repository browser.