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

Revision 692, 18.5 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'): Particle System Attributes</TITLE>
15
16<META NAME="description" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Particle System Attributes">
17<META NAME="keywords" CONTENT="OGRE Manual v1.2.0 ('Dagon'): Particle System Attributes">
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="SEC149"></A>
27<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
28<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_26.html#SEC145"> &lt; </A>]</TD>
29<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_26.html#SEC145"> Up </A>]</TD>
30<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_28.html#SEC167"> &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<H3> 3.3.1 Particle System Attributes </H3>
38<!--docid::SEC149::-->
39This section describes to attributes which you can set on every particle system using scripts. All atributes have default values so all settings are optional in your script.<BR><BR>
40<P>
41
42<A NAME="quota"></A>
43<A NAME="SEC150"></A>
44<H3> quota </H3>
45<!--docid::SEC150::-->
46<P>
47
48Sets the maximum number of particles this system is allowed to contain at one time. When this limit is exhausted, the emitters will not be allowed to emit any more particles until some destroyed (e.g. through their time_to_live running out). Note that you will almost always want to change this, since it defaults to a very low value (particle pools are only ever increased in size, never decreased).<BR><BR>
49</P><P>
50
51format: quota &#60;max_particles&#62;<BR>
52example: quota 10000<BR>
53default: 10<BR>
54</P><P>
55
56<A NAME="particle_material"></A>
57<A NAME="SEC151"></A>
58<H3> material  </H3>
59<!--docid::SEC151::-->
60<P>
61
62Sets the name of the material which all particles in this system will use. All paticles in a system use the same material, although each particle can tint this material through the use of it's colour property.<BR><BR>
63</P><P>
64
65format: material &#60;material_name&#62;<BR>
66example: material Examples/Flare<BR>
67default: none (blank material)<BR>
68</P><P>
69
70<A NAME="particle_width"></A>
71<A NAME="SEC152"></A>
72<H3> particle_width </H3>
73<!--docid::SEC152::-->
74<P>
75
76Sets the width of particles in world coordinates. Note that this property is absolute when billboard_type (see below) is set to 'point' or 'perpendicular_self', but is scaled by the length of the direction vector when billboard_type is 'oriented_common', 'oriented_self' or 'perpendicular_common'.<BR>
77</P><P>
78
79format: particle_width &#60;width&#62;<BR>
80example: particle_width 20<BR>
81default: 100<BR>
82</P><P>
83
84<A NAME="particle_height"></A>
85<A NAME="SEC153"></A>
86<H3> particle_height </H3>
87<!--docid::SEC153::-->
88<P>
89
90Sets the height of particles in world coordinates. Note that this property is absolute when billboard_type (see below) is set to 'point' or 'perpendicular_self', but is scaled by the length of the direction vector when billboard_type is 'oriented_common', 'oriented_self' or 'perpendicular_common'.<BR>
91</P><P>
92
93format: particle_height &#60;height&#62;<BR>
94example: particle_height 20<BR>
95default: 100<BR>
96</P><P>
97
98<A NAME="cull_each"></A>
99<A NAME="SEC154"></A>
100<H3> cull_each </H3>
101<!--docid::SEC154::-->
102<P>
103
104All particle systems are culled by the bounding box which contains all the particles in the system. This is normally sufficient for fairly locally constrained particle systems where most particles are either visible or not visible together. However, for those that spread particles over a wider area (e.g. a rain system), you may want to actually cull each particle individually to save on time, since it is far more likely that only a subset of the particles will be visible. You do this by setting the cull_each parameter to true.<BR><BR>
105</P><P>
106
107format: cull_each &#60;true|false&#62;<BR>
108example: cull_each true<BR>
109default: false<BR>
110</P><P>
111
112<A NAME="particle_renderer"></A>
113<A NAME="SEC155"></A>
114<H3> renderer </H3>
115<!--docid::SEC155::-->
116<P>
117
118Particle systems do not render themselves, they do it through ParticleRenderer classes. Those classes are registered with a manager in order to provide particle systems with a particular 'look'. OGRE comes configured with a default billboard-based renderer, but more can be added through plugins. Particle renders are registered with a unique name, and you can use that name in this attribute to determine the renderer to use. The default is 'billboard'.<BR><BR>
119</P><P>
120
121Particle renderers can have attributes, which can be passed by setting them on the root particle system.<BR><BR>
122</P><P>
123
124format: renderer &#60;renderer_name&#62;<BR>
125default: billboard<BR>
126</P><P>
127
128<A NAME="particle_sorted"></A>
129<A NAME="SEC156"></A>
130<H3> sorted </H3>
131<!--docid::SEC156::-->
132<P>
133
134By default, particles are not sorted. By setting this attribute to 'true', theparticles will be sorted with respect to the camera, furthest first. This can make certain rendering effects look better at a small sorting expense.<BR><BR>
135</P><P>
136
137format: sorted &#60;true|false&#62;<BR>
138default: false<BR>
139</P><P>
140
141<A NAME="particle_localspace"></A>
142<A NAME="SEC157"></A>
143<H3> local_space </H3>
144<!--docid::SEC157::-->
145<P>
146
147By default, particles are emitted into world space, such that if you transform the node to which the system is attached, it will not affect the particles (only the emitters). This tends to give the normal expected behaviour, which is to model how real world particles travel independently from the objects they are emitted from. However, to create some effects you may want the particles to remain attached to the local space the emitter is in and to follow them directly. This option allows you to do that.<BR><BR>
148</P><P>
149
150format: local_space &#60;true|false&#62;<BR>
151default: false<BR>
152</P><P>
153
154<A NAME="billboard_type"></A>
155<A NAME="SEC158"></A>
156<H3> billboard_type </H3>
157<!--docid::SEC158::-->
158<P>
159
160This is actually an attribute of the 'billboard' particle renderer (the default), and is an example of passing attributes to a particle renderer by declaring them directly within the system declaration. Particles using the default renderer are rendered using billboards, which are rectangles formed by 2 triangles which rotate to face the given direction. However, there is more than 1 way to orient a billboard. The classic approach is for the billboard to directly face the camera: this is the default behaviour. However this arrangement only looks good for particles which are representing something vaguely spherical like a light flare. For more linear effectd like laser fire, you actually want the particle to have an orientation of it's own.<BR><BR>
161</P><P>
162
163format: billboard_type &#60;point|oriented_common|oriented_self|perpendicular_common|perpendicular_self&#62;<BR>
164example: billboard_type oriented_self<BR>
165default: point<BR>
166</P><P>
167
168The options for this parameter are:
169<DL COMPACT>
170<DT>point
171<DD>    The default arrangement, this approximates spherical particles and the billboards always fully face the camera.
172<DT>oriented_common
173<DD>    Particles are oriented around a common, typically fixed direction vector (see <A HREF="manual_27.html#SEC161">common_direction</A>), which acts as their local Y axis. The billboard rotates only around this axis, giving the particle some sense of direction. Good for rainstorms, starfields etc where the particles will travelling in one direction - this is slightly faster than oriented_self (see below).
174<DT>oriented_self
175<DD>    Particles are oriented around their own direction vector, which acts as their local Y axis. As the particle changes direction, so the billboard reorients itself to face this way. Good for laser fire, fireworks and other 'streaky' particles that should look like they are travelling in their own direction.
176<DT>perpendicular_common
177<DD>    Particles are perpendicular to a common, typically fixed direction vector (see <A HREF="manual_27.html#SEC161">common_direction</A>), which acts as their local Z axis, and their local Y axis coplanar with common direction and the common up vector (see <A HREF="manual_27.html#SEC162">common_up_vector</A>). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for aureolas, rings etc where the particles will perpendicular to the ground - this is slightly faster than perpendicular_self (see below).
178<DT>perpendicular_self
179<DD>    Particles are perpendicular to their own direction vector, which acts as their local Z axis, and their local Y axis coplanar with their own direction vector and the common up vector (see <A HREF="manual_27.html#SEC162">common_up_vector</A>). The billboard never rotates to face the camera, you might use double-side material to ensure particles never culled by back-facing. Good for rings stack etc where the particles will perpendicular to their travelling direction.
180</DL>
181<P>
182
183<A NAME="billboard_origin"></A>
184<A NAME="SEC159"></A>
185<H3> billboard_origin </H3>
186<!--docid::SEC159::-->
187<P>
188
189Specifying the point which acts as the origin point for all billboard particles, controls the fine tuning of where a billboard particle appears in relation to it's position.<BR><BR>
190</P><P>
191
192format: billboard_origin &#60;top_left|top_center|top_right|center_left|center|center_right|bottom_left|bottom_center|bottom_right&#62;<BR>
193example: billboard_origin top_right<BR>
194default: center<BR>
195</P><P>
196
197The options for this parameter are:
198<DL COMPACT>
199<DT>top_left
200<DD>    The billboard origin is the top-left corner.
201<DT>top_center
202<DD>    The billboard origin is the center of top edge.
203<DT>top_right
204<DD>    The billboard origin is the top-right corner.
205<DT>center_left
206<DD>    The billboard origin is the center of left edge.
207<DT>center
208<DD>    The billboard origin is the center.
209<DT>center_right
210<DD>    The billboard origin is the center of right edge.
211<DT>bottom_left
212<DD>    The billboard origin is the bottom-left corner.
213<DT>bottom_center
214<DD>    The billboard origin is the center of bottom edge.
215<DT>bottom_right
216<DD>    The billboard origin is the bottom-right corner.
217</DL>
218<P>
219
220<A NAME="billboard_rotation_type"></A>
221<A NAME="SEC160"></A>
222<H3> billboard_rotation_type </H3>
223<!--docid::SEC160::-->
224<P>
225
226By default, billboard particles will rotate the texture coordinates to according with particle rotation. But rotate texture coordinates has some disadvantage, e.g. the corners of the texture will lost after rotate, and the corners of the billboard will fill with unwant texture area when using wrap address mode or sub-texture sampling. This settings allow you specifying other rotation type.<BR><BR>
227</P><P>
228
229format: billboard_rotation_type &#60;vertex|texcoord&#62;<BR>
230example: billboard_rotation_type vertex<BR>
231default: texcoord<BR>
232</P><P>
233
234The options for this parameter are:
235<DL COMPACT>
236<DT>vertex
237<DD>    Billboard particles will rotate the vertices around their facing direction to according with particle rotation. Rotate vertices guarantee texture corners exactly match billboard corners, thus has advantage mentioned above, but should take more time to generate the vertices.
238<DT>texcoord
239<DD>    Billboard particles will rotate the texture coordinates to according with particle rotation. Rotate texture coordinates is faster than rotate vertices, but has some disadvantage mentioned above.
240</DL>
241<P>
242
243<A NAME="common_direction"></A>
244<A NAME="SEC161"></A>
245<H3> common_direction </H3>
246<!--docid::SEC161::-->
247<P>
248
249Only required if <A HREF="manual_27.html#SEC158">billboard_type</A> is set to oriented_common or perpendicular_common, this vector is the common direction vector used to orient all particles in the system.<BR><BR>
250</P><P>
251
252format: common_direction &#60;x&#62; &#60;y&#62; &#60;z&#62;<BR>
253example: common_direction 0 -1 0<BR>
254default: 0 0 1<BR>
255<BR><BR>
256See also: <A HREF="manual_28.html#SEC167">3.3.2 Particle Emitters</A>, <A HREF="manual_31.html#SEC191">3.3.5 Particle Affectors</A>
257</P><P>
258
259<A NAME="common_up_vector"></A>
260<A NAME="SEC162"></A>
261<H3> common_up_vector </H3>
262<!--docid::SEC162::-->
263<P>
264
265Only required if <A HREF="manual_27.html#SEC158">billboard_type</A> is set to perpendicular_self or perpendicular_common, this vector is the common up vector used to orient all particles in the system.<BR><BR>
266</P><P>
267
268format: common_up_vector &#60;x&#62; &#60;y&#62; &#60;z&#62;<BR>
269example: common_up_vector 0 1 0<BR>
270default: 0 1 0<BR>
271<BR><BR>
272See also: <A HREF="manual_28.html#SEC167">3.3.2 Particle Emitters</A>, <A HREF="manual_31.html#SEC191">3.3.5 Particle Affectors</A>
273</P><P>
274
275<A NAME="particle_point_rendering"></A>
276<A NAME="SEC163"></A>
277<H3> point_rendering </H3>
278<!--docid::SEC163::-->
279<P>
280
281This is actually an attribute of the 'billboard' particle renderer (the default), and sets whether or not the billboardset will use point rendering rather than manually generated quads.<BR><BR>
282</P><P>
283
284By default a billboardset is rendered by generating geometry for a textured quad in memory, taking into account the size and orientation settings, and uploading it to the video card. The alternative is to use hardware point rendering, which means that     only one position needs to be sent per billboard rather than 4 and      the hardware sorts out how this is rendered based on the render state.<BR><BR>
285</P><P>
286
287Using point rendering is faster than generating quads manually, but     is more restrictive. The following restrictions apply:
288<UL>
289<LI>Only the 'point' orientation type is supported
290<LI>Size and appearance of each particle is controlled by the material pass (<A HREF="manual_16.html#SEC56">point_size</A>, <A HREF="manual_16.html#SEC58">point_size_attenuation</A>, <A HREF="manual_16.html#SEC57">point_sprites</A>)
291<LI>Per-particle size is not supported (stems from the above)
292<LI>Per-particle rotation is not supported, and this can only be controlled through texture unit rotation in the material definition
293<LI>Only 'center' origin is supported
294<LI>Some drivers have an upper limit on the size of points they support - this can even vary between APIs on the same card! Don't rely on point sizes that cause the point sprites to get very large on screen, since they may get clamped on some cards. Upper sizes can range from 64 to 256 pixels.
295</UL>
296You will almost certainly want to enable in your material pass both point attenuation and point sprites if you use this option. <BR><BR>
297<P>
298
299<A NAME="particle_accurate_facing"></A>
300<A NAME="SEC164"></A>
301<H3> accurate_facing </H3>
302<!--docid::SEC164::-->
303<P>
304
305This is actually an attribute of the 'billboard' particle renderer (the default), and sets whether or not the billboardset will use a slower but more accurate calculation for facing the billboard to the camera. Bt default it uses the camera direction, which is faster but means the billboards don't stay in the same orientation as you rotate the camera. The 'accurate_facing true' option makes the calculation based on a vector from each billboard to the camera, which means the orientation is constant even whilst the camera rotates. <BR><BR>
306</P><P>
307
308format: accurate_facing on|off<BR>
309default: accurate_facing off 0<BR>
310<BR><BR>
311</P><P>
312
313<A NAME="iteration_interval"></A>
314<A NAME="SEC165"></A>
315<H3> iteration_interval </H3>
316<!--docid::SEC165::-->
317Usually particle systems are updated based on the frame rate; however this can give variable results with more extreme frame rate ranges, particularly at lower frame rates. You can use this option to make the update frequency a fixed interval, whereby at lower frame rates, the particle update will be repeated at the fixed interval until the frame time is used up. A value of 0 means the default frame time iteration. <BR><BR>
318<P>
319
320format: iteration_interval &#60;secs&#62;<BR>
321example: iteration_interval 0.01<BR>
322default: iteration_interval 0<BR>
323<BR><BR>
324</P><P>
325
326<A NAME="nonvisible_update_timeout"></A>
327<A NAME="SEC166"></A>
328<H3> nonvisible_update_timeout </H3>
329<!--docid::SEC166::-->
330Sets when the particle system should stop updating after it hasn't been visible for a while. By default, visible particle systems update all the time, even when not in view. This means that they are guaranteed to be consistent when they do enter view. However, this comes at a cost, updating particle systems can be expensive, especially if they are perpetual.
331<BR><BR>
332This option lets you set a 'timeout' on the particle system, so that if it isn't visible for this amount of time, it will stop updating until it is next visible. A value of 0 disables the timeout and always updates.<BR><BR>
333<P>
334
335format: nonvisible_update_timeout &#60;secs&#62;<BR>
336example: nonvisible_update_timeout 10<BR>
337default: nonvisible_update_timeout 0<BR>
338<BR><BR>
339</P><P>
340
341<A NAME="Particle Emitters"></A>
342<HR SIZE=1>
343<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
344<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_26.html#SEC145"> &lt; </A>]</TD>
345<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_26.html#SEC145"> Up </A>]</TD>
346<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_28.html#SEC167"> &gt; </A>]</TD>
347<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>
348<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_toc.html#SEC_Contents">Contents</A>]</TD>
349<TD VALIGN="MIDDLE" ALIGN="LEFT">[Index]</TD>
350<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="manual_abt.html#SEC_About"> ? </A>]</TD>
351</TR></TABLE>
352<BR> 
353<FONT SIZE="-1">
354This document was generated
355by <I>Steve Streeting</I> on <I>, 12 2006</I>
356using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
357"><I>texi2html</I></A>
358
359</BODY>
360</HTML>
Note: See TracBrowser for help on using the repository browser.