source: OGRE/trunk/ogrenew/Docs/manual/manual_28.html @ 657

Revision 657, 12.5 KB checked in by mattausch, 19 years ago (diff)

added ogre dependencies and patched ogre sources
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.0.7: Overlay Scripts</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.0.7: Overlay Scripts">
17<META NAME="keywords" CONTENT="OGRE Manual v1.0.7: Overlay 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="SEC138"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_27.html#SEC130"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_29.html#SEC145"> &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.3 Overlay Scripts </H2>
38<!--docid::SEC138::-->
39<P>
40
41Overlay scripts offer you the ability to define overlays in a script which can be reused easily. Whilst you could set up all overlays for a scene in code using the methods of the SceneManager, Overlay and OverlayElement classes, in practice it's a bit unwieldy. Instead you can store overlay definitions in text files which can then be loaded whenever required.<BR><BR>
42</P><P>
43
44<A NAME="SEC139"></A>
45<H2> Loading scripts   </H2>
46<!--docid::SEC139::-->
47<P>
48
49Overlay scripts are loaded at initialisation time by the system: by default it looks in all common resource locations (see Root::addResourceLocation) for files with the '.overlay' extension and parses them. If you want to parse files with a different extension, use the OverlayManager::getSingleton().parseAllSources method with your own extension, or if you want to parse an individual file, use OverlayManager::getSingleton().parseScript.<BR><BR>
50</P><P>
51
52<A NAME="SEC140"></A>
53<H2> Format   </H2>
54<!--docid::SEC140::-->
55<P>
56
57Several overlays may be defined in a single script. The script format is pseudo-C++, with sections delimited by curly braces ({}), comments indicated by starting a line with '//' (note, no nested form comments allowed), and inheritance through the use of templates. The general format is shown below in a typical example:
58<TABLE><tr><td>&nbsp;</td><td class=example><pre>// The name of the overlay comes first
59MyOverlays/ANewOverlay
60{
61    zorder 200
62
63    container Panel(MyOverlayElements/TestPanel)
64    {
65        // Center it horzontally, put it at the top
66        left 0.25
67        top 0
68        width 0.5
69        height 0.1
70        material MyMaterials/APanelMaterial
71
72        // Another panel nested in this one
73        container Panel(MyOverlayElements/AnotherPanel)
74        {
75             left 0
76             top 0
77             width 0.1
78             height 0.1
79             material MyMaterials/NestedPanel
80        }
81    }
82
83}
84</pre></td></tr></table></P><P>
85
86The above example defines a single overlay called 'MyOverlays/ANewOverlay', with 2 panels in it, one nested under the other. It uses relative metrics (the default if no metrics_mode option is found).<BR><BR>
87</P><P>
88
89Every overlay in the script must be given a name, which is the line before the first opening '{'. This name must be globally unique. It can include path characters (as in the example) to logically divide up your overlays, and also to avoid duplicate names, but the engine does not treat the name a hierarchical, just as a string. Within the braces are the properties of the overlay, and any nested elements. The overlay itself only has a single property 'zorder' which determines how'high' it is in the stack of overlays if more than one is displayed at the same time. Overlays with higher zorder values are displayed on top.<BR><BR>
90</P><P>
91
92<A NAME="SEC141"></A>
93<H2> Adding elements to the overlay </H2>
94<!--docid::SEC141::-->
95<P>
96
97Within an overlay, you can include any number of 2D or 3D elements. You do this by defining a nested block headed by:
98<DL COMPACT>
99<DT>'element'
100<DD>if you want to define a 2D element which cannot have children of it's own
101<DT>'container'
102<DD>if you want to define a 2D container object (which may itself have nested containers or elements)
103<DT>'entity'
104<DD>if you want to include a 3D element (can only occur directly under the overlay, not under a 2D element)
105</DL>
106<BR>
107The element and container blocks are pretty identical apart from their ability to store nested blocks.
108<P>
109
110<A NAME="SEC142"></A>
111<H2> 'container' / 'element' blocks </H2>
112<!--docid::SEC142::-->
113<P>
114
115These are delimited by curly braces. The format for the header preceding the first brace is:<BR><BR>
116</P><P>
117
118[container | element] &#60;type_name&#62; ( &#60;instance_name&#62;) [: &#60;template_name&#62;]<BR>
119{ ...<BR><BR>
120<DL COMPACT>
121<DT>type_name
122<DD>Must resolve to the name of a OverlayElement type which has been registered with the OverlayManager. Plugins register with the OverlayManager to advertise their ability to create elements, and at this time advertise the name of the type. OGRE comes preconfigured with types 'Panel', 'BorderPanel' and 'TextArea'.
123<DT>instance_name
124<DD>Must be a name unique among all other elements / containers by which to identify the element. Note that you can obtain a pointer to any named element by calling OverlayManager::getSingleton().getOverlayElement(name).
125<DT>template_name
126<DD>Optional template on which to base this item. See templates.
127</DL>
128<P>
129
130The properties which can be included within the braces depend on the custom type. However the following are always valid:
131<UL>
132<LI>
133<A HREF="manual_29.html#SEC146">metrics_mode</A>
134<LI>
135<A HREF="manual_29.html#SEC147">horz_align</A>
136<LI>
137<A HREF="manual_29.html#SEC148">vert_align</A>
138<LI>
139<A HREF="manual_29.html#SEC149">left</A>
140<LI>
141<A HREF="manual_29.html#SEC150">top</A>
142<LI>
143<A HREF="manual_29.html#SEC151">width</A>
144<LI>
145<A HREF="manual_29.html#SEC152">height</A>
146<LI>
147<A HREF="manual_29.html#overlay_material">material</A>
148<LI>
149<A HREF="manual_29.html#SEC154">caption</A>
150</UL>
151<P>
152
153<A NAME="SEC143"></A>
154<H3> 'entity' blocks </H3>
155<!--docid::SEC143::-->
156<P>
157
158These are delimited by curly braces. The format for the header preceding the first brace is:<BR><BR>
159</P><P>
160
161entity &#60;mesh_name&#62; ( &#60;entity_name&#62;)<BR>
162{ ...<BR><BR>
163</P><P>
164
165<DL COMPACT>
166<DT>mesh_name
167<DD>The name of a .mesh file defining the entity geometry
168<DT>entity_name
169<DD>The name to give the entity created, must be unique to this entity.
170<DT>position
171<DD>The position of the entity, as an x, y, z triple.
172<DT>rotation
173<DD>The rotation of the entity, expressed as &#60;angle_in_degrees&#62; &#60;axis_x&#62; &#60;axis_y&#62; &#60;axis_z&#62;
174</DL>
175<P>
176
177This is treated like any other Entity, See section <A HREF="manual_10.html#SEC13">2.6 Entities</A>.
178</P><P>
179
180<A NAME="SEC144"></A>
181<H2> Templates </H2>
182<!--docid::SEC144::-->
183<P>
184
185You can use templates to create numerous elements with the same properties. A template is an abstract element and it is not added to an overlay. It acts as a base class that elements can inherit and get its default properties. To create a template, the keyword 'template' must be the first word in the element definition (before container, element, or entity). The template element is created in the topmost scope - it is NOT specified in an Overlay. It is recommended that you define templates in a separate overlay though this is not essential. Having templates defined in a separate file will allow different look &#38; feels to be easily substituted.<BR><BR>
186</P><P>
187
188Elements can inherit a template in a similar way to C++ inheritance - by using the : operator on the element definition. The : operator is placed after the closing bracket of the name (separated by a space). The name of the template to inherit is then placed after the : operator (also separated by a space).<BR><BR>
189</P><P>
190
191A template can contain template children which are created when the template is subclassed and instantiated. Using the template keyword for the children of a template is optional but recommended for clarity, as the children of a template are always going to be templates themselves.<BR><BR>
192<TABLE><tr><td>&nbsp;</td><td class=example><pre>template container BorderPanel(MyTemplates/BasicBorderPanel)
193{
194    left 0
195    top 0
196    width 1
197    height 1
198
199// setup the texture UVs for a borderpanel
200
201// do this in a template so it doesn't need to be redone everywhere
202    material Core/StatsBlockCenter
203    border_size 0.05 0.05 0.06665 0.06665
204    border_material Core/StatsBlockBorder
205    border_topleft_uv 0.0000 1.0000 0.1914 0.7969
206    border_top_uv 0.1914 1.0000 0.8086 0.7969
207    border_topright_uv 0.8086 1.0000 1.0000 0.7969
208    border_left_uv 0.0000 0.7969 0.1914 0.2148
209    border_right_uv 0.8086 0.7969 1.0000 0.2148
210    border_bottomleft_uv 0.0000 0.2148 0.1914 0.0000
211    border_bottom_uv 0.1914 0.2148 0.8086 0.0000
212    border_bottomright_uv 0.8086 0.2148 1.0000 0.0000
213}
214template container Button(MyTemplates/BasicButton) : MyTemplates/BasicBorderPanel
215{
216    left 0.82
217    top 0.45
218    width 0.16
219    height 0.13
220    material Core/StatsBlockCenter
221    border_up_material Core/StatsBlockBorder/Up
222    border_down_material Core/StatsBlockBorder/Down
223}
224template element TextArea(MyTemplates/BasicText)
225{
226    font_name Ogre
227    char_height 0.08
228    colour_top 1 1 0
229    colour_bottom 1 0.2 0.2
230    left 0.03
231    top 0.02
232    width 0.12
233    height 0.09
234}
235
236MyOverlays/AnotherOverlay
237{
238    zorder 490
239    container BorderPanel(MyElements/BackPanel) : MyTemplates/BasicBorderPanel
240    {
241        left 0
242        top 0
243        width 1
244        height 1
245
246        container Button(MyElements/HostButton) : MyTemplates/BasicButton
247        {
248            left 0.82
249            top 0.45
250            caption MyTemplates/BasicText HOST
251        }
252
253        container Button(MyElements/JoinButton) : MyTemplates/BasicButton
254        {
255            left 0.82
256            top 0.60
257            caption MyTemplates/BasicText JOIN
258        }
259    }
260}
261</pre></td></tr></table>The above example uses templates to define a button. Note that the button template inherits from the borderPanel template. This reduces the number of attributes needed to instantiate a button.<BR><BR>
262</P><P>
263
264Also note that the instantiate of a Button needs a template name for the caption attribute. So templates can also be used by elements that need dynamic creation of children elements (the button creates a TextAreaElement in this case for its caption).<BR><BR>
265</P><P>
266
267See section <A HREF="manual_29.html#SEC145">3.3.1 OverlayElement Attributes</A>, <A HREF="manual_30.html#SEC156">3.3.2 Standard OverlayElements</A>
268</P><P>
269
270<A NAME="OverlayElement Attributes"></A>
271<HR SIZE=1>
272<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
273<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_27.html#SEC130"> &lt; </A>]</TD>
274<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_14.html#SEC23"> Up </A>]</TD>
275<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_29.html#SEC145"> &gt; </A>]</TD>
276<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>
277<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
278<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
279<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
280</TR></TABLE>
281<BR> 
282<FONT SIZE="-1">
283This document was generated
284by <I>Steve Streeting</I> on <I>, 12 2006</I>
285using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
286"><I>texi2html</I></A>
287
288</BODY>
289</HTML>
Note: See TracBrowser for help on using the repository browser.