Context Navigation

source: OGRE/trunk/ogrenew/OgreMain/include/OgreParticleEmitter.h @ 657

Revision 657, 24.1 KB checked in by mattausch, 19 years ago (diff)
added ogre dependencies and patched ogre sources

Line
1	/*
2	-----------------------------------------------------------------------------
3	This source file is part of OGRE
4	(Object-oriented Graphics Rendering Engine)
5	For the latest info, see http://www.ogre3d.org/
6
7	Copyright (c) 2000-2005 The OGRE Team
8	Also see acknowledgements in Readme.html
9
10	This program is free software; you can redistribute it and/or modify it under
11	the terms of the GNU Lesser General Public License as published by the Free Software
12	Foundation; either version 2 of the License, or (at your option) any later
13	version.
14
15	This program is distributed in the hope that it will be useful, but WITHOUT
16	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17	FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19	You should have received a copy of the GNU Lesser General Public License along with
20	this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21	Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22	http://www.gnu.org/copyleft/lesser.txt.
23	-----------------------------------------------------------------------------
24	*/
25	#ifndef __ParticleEmitter_H__
26	#define __ParticleEmitter_H__
27
28	#include "OgrePrerequisites.h"
29	#include "OgreString.h"
30	#include "OgreVector3.h"
31	#include "OgreColourValue.h"
32	#include "OgreStringInterface.h"
33	#include "OgreParticleEmitterCommands.h"
34	#include "OgreParticle.h"
35
36
37	namespace Ogre {
38
39
40	/** Abstract class defining the interface to be implemented by particle emitters.
41	@remarks
42	Particle emitters are the sources of particles in a particle system.
43	This class defines the ParticleEmitter interface, and provides a basic implementation
44	for tasks which most emitters will do (these are of course overridable).
45	Particle emitters can be grouped into types, e.g. 'point' emitters, 'box' emitters etc; each type will
46	create particles with a different starting point, direction and velocity (although
47	within the types you can configure the ranges of these parameters).
48	@par
49	Because there are so many types of emitters you could use, OGRE chooses not to dictate
50	the available types. It comes with some in-built, but allows plugins or applications to extend the emitter types available.
51	This is done by subclassing ParticleEmitter to have the appropriate emission behaviour you want,
52	and also creating a subclass of ParticleEmitterFactory which is responsible for creating instances
53	of your new emitter type. You register this factory with the ParticleSystemManager using
54	addEmitterFactory, and from then on emitters of this type can be created either from code or through
55	text particle scripts by naming the type.
56	@par
57	This same approach is used for ParticleAffectors (which modify existing particles per frame).
58	This means that OGRE is particularly flexible when it comes to creating particle system effects,
59	with literally infinite combinations of emitter and affector types, and paramters within those
60	types.
61	*/
62	class _OgreExport ParticleEmitter : public StringInterface
63	{
64	protected:
65
66	// Command object for setting / getting parameters
67	static EmitterCommands::CmdAngle msAngleCmd;
68	static EmitterCommands::CmdColour msColourCmd;
69	static EmitterCommands::CmdColourRangeStart msColourRangeStartCmd;
70	static EmitterCommands::CmdColourRangeEnd msColourRangeEndCmd;
71	static EmitterCommands::CmdDirection msDirectionCmd;
72	static EmitterCommands::CmdEmissionRate msEmissionRateCmd;
73	static EmitterCommands::CmdMaxTTL msMaxTTLCmd;
74	static EmitterCommands::CmdMaxVelocity msMaxVelocityCmd;
75	static EmitterCommands::CmdMinTTL msMinTTLCmd;
76	static EmitterCommands::CmdMinVelocity msMinVelocityCmd;
77	static EmitterCommands::CmdPosition msPositionCmd;
78	static EmitterCommands::CmdTTL msTTLCmd;
79	static EmitterCommands::CmdVelocity msVelocityCmd;
80	static EmitterCommands::CmdDuration msDurationCmd;
81	static EmitterCommands::CmdMinDuration msMinDurationCmd;
82	static EmitterCommands::CmdMaxDuration msMaxDurationCmd;
83	static EmitterCommands::CmdRepeatDelay msRepeatDelayCmd;
84	static EmitterCommands::CmdMinRepeatDelay msMinRepeatDelayCmd;
85	static EmitterCommands::CmdMaxRepeatDelay msMaxRepeatDelayCmd;
86
87
88	/// Parent particle system
89	ParticleSystem* mParent;
90	/// Position relative to the center of the ParticleSystem
91	Vector3 mPosition;
92	/// Rate in particles per second at which this emitter wishes to emit particles
93	Real mEmissionRate;
94	/// Name of the type of emitter, MUST be initialised by subclasses
95	String mType;
96	/// Base direction of the emitter, may not be used by some emitters
97	Vector3 mDirection;
98	// Notional up vector, just used to speed up generation of variant directions
99	Vector3 mUp;
100	/// Angle around direction which particles may be emitted, internally radians but angleunits for interface
101	Radian mAngle;
102	/// Min speed of particles
103	Real mMinSpeed;
104	/// Max speed of particles
105	Real mMaxSpeed;
106	/// Initial time-to-live of particles (min)
107	Real mMinTTL;
108	/// Initial time-to-live of particles (max)
109	Real mMaxTTL;
110	/// Initial colour of particles (range start)
111	ColourValue mColourRangeStart;
112	/// Initial colour of particles (range end)
113	ColourValue mColourRangeEnd;
114
115	/// Whether this emitter is currently enabled (defaults to true)
116	bool mEnabled;
117
118	/// Start time (in seconds from start of first call to ParticleSystem to update)
119	Real mStartTime;
120	/// Minimum length of time emitter will run for (0 = forever)
121	Real mDurationMin;
122	/// Maximum length of time the emitter will run for (0 = forever)
123	Real mDurationMax;
124	/// Current duration remainder
125	Real mDurationRemain;
126
127	/// Time between each repeat
128	Real mRepeatDelayMin;
129	Real mRepeatDelayMax;
130	/// Repeat delay left
131	Real mRepeatDelayRemain;
132
133	// Fractions of particles wanted to be emitted last time
134	Real mRemainder;
135
136	// NB Method below here are to help out people implementing emitters by providing the
137	// most commonly used approaches as piecemeal methods
138
139	/** Internal utility method for generating particle exit direction
140	@param destVector Reference to vector to complete with new direction (normalised)
141	*/
142	virtual void genEmissionDirection(Vector3& destVector);
143
144	/** Internal utility method to apply velocity to a particle direction.
145	@param destVector The vector to scale by a randomly generated scale between min and max speed.
146	Assumed normalised already, and likely already oriented in the right direction.
147	*/
148	virtual void genEmissionVelocity(Vector3& destVector);
149
150	/** Internal utility method for generating a time-to-live for a particle. */
151	virtual Real genEmissionTTL(void);
152
153	/** Internal utility method for generating a colour for a particle. */
154	virtual void genEmissionColour(ColourValue& destColour);
155
156	/** Internal utility method for generating an emission count based on a constant emission rate. */
157	virtual unsigned short genConstantEmissionCount(Real timeElapsed);
158
159	/** Internal method for setting up the basic parameter definitions for a subclass.
160	@remarks
161	Because StringInterface holds a dictionary of parameters per class, subclasses need to
162	call this to ask the base class to add it's parameters to their dictionary as well.
163	Can't do this in the constructor because that runs in a non-virtual context.
164	@par
165	The subclass must have called it's own createParamDictionary before calling this method.
166	*/
167	void addBaseParameters(void);
168
169	/** Internal method for initialising the duration & repeat of an emitter. */
170	void initDurationRepeat(void);
171
172
173	public:
174	ParticleEmitter(ParticleSystem* psys);
175	/** Virtual destructor essential. */
176	virtual ~ParticleEmitter();
177
178	/** Sets the position of this emitter relative to the particle system center. */
179	virtual void setPosition(const Vector3& pos);
180
181	/** Returns the position of this emitter relative to thte center of the particle system. */
182	virtual const Vector3& getPosition(void) const;
183
184	/** Sets the direction of the emitter.
185	@remarks
186	Most emitters will have a base direction in which they emit particles (those which
187	emit in all directions will ignore this parameter). They may not emit exactly along this
188	vector for every particle, many will introduce a random scatter around this vector using
189	the angle property.
190	@param direction
191	The base direction for particles emitted.
192	*/
193	virtual void setDirection(const Vector3& direction);
194
195	/** Returns the base direction of the emitter. */
196	virtual const Vector3& getDirection(void) const;
197
198	/** Sets the maximum angle away from the emitter direction which particle will be emitted.
199	@remarks
200	Whilst the direction property defines the general direction of emission for particles,
201	this property defines how far the emission angle can deviate away from this base direction.
202	This allows you to create a scatter effect - if set to 0, all particles will be emitted
203	exactly along the emitters direction vector, wheras if you set it to 180 degrees or more,
204	particles will be emitted in a sphere, i.e. in all directions.
205	@param degrees
206	Maximum angle which initial particle direction can deviate from the emitter base direction vector.
207	*/
208	virtual void setAngle(const Radian& angle);
209	#ifndef OGRE_FORCE_ANGLE_TYPES
210	inline void setAngle(Real angle) {
211	setAngle ( Angle(angle) );
212	}
213	#endif//OGRE_FORCE_ANGLE_TYPES
214
215	/** Returns the maximum angle which the initial particle direction can deviate from the emitters base direction. */
216	virtual const Radian& getAngle(void) const;
217
218	/** Sets the initial velocity of particles emitted.
219	@remarks
220	This method sets a constant speed for emitted particles. See the alternate version
221	of this method which takes 2 parameters if you want a variable speed.
222	@param
223	speed The initial speed in world units per second which every particle emitted starts with.
224	*/
225	virtual void setParticleVelocity(Real speed);
226
227
228	/** Sets the initial velocity range of particles emitted.
229	@remarks
230	This method sets the range of starting speeds for emitted particles.
231	See the alternate version of this method which takes 1 parameter if you want a
232	constant speed. This emitter will randomly choose a speed between the minimum and
233	maximum for each particle.
234	@param max The maximum speed in world units per second for the initial particle speed on emission.
235	@param min The minimum speed in world units per second for the initial particle speed on emission.
236	*/
237	virtual void setParticleVelocity(Real min, Real max);
238	/** Returns the minimum particle velocity. */
239	virtual void setMinParticleVelocity(Real min);
240	/** Returns the maximum particle velocity. */
241	virtual void setMaxParticleVelocity(Real max);
242
243	/** Returns the initial velocity of particles emitted. */
244	virtual Real getParticleVelocity(void) const;
245
246	/** Returns the minimum particle velocity. */
247	virtual Real getMinParticleVelocity(void) const;
248
249	/** Returns the maximum particle velocity. */
250	virtual Real getMaxParticleVelocity(void) const;
251
252	/** Sets the emission rate for this emitter.
253	@remarks
254	This method tells the emitter how many particles per second should be emitted. The emitter
255	subclass does not have to emit these in a continuous burst - this is a relative parameter
256	and the emitter may choose to emit all of the second's worth of particles every half-second
257	for example. This is controlled by the emitter's getEmissionCount method.
258	@par
259	Also, if the ParticleSystem's particle quota is exceeded, not all the particles requested
260	may be actually emitted.
261	@param
262	particlesPerSecond The number of particles to be emitted every second.
263	*/
264	virtual void setEmissionRate(Real particlesPerSecond);
265
266	/** Returns the emission rate set for this emitter. */
267	virtual Real getEmissionRate(void) const;
268
269	/** Sets the lifetime of all particles emitted.
270	@remarks
271	The emitter initialises particles with a time-to-live (TTL), the number of seconds a particle
272	will exist before being destroyed. This method sets a constant TTL for all particles emitted.
273	Note that affectors are able to modify the TTL of particles later.
274	@par
275	Also see the alternate version of this method which takes a min and max TTL in order to
276	have the TTL vary per particle.
277	@param ttl The number of seconds each particle will live for.
278	*/
279	virtual void setTimeToLive(Real ttl);
280	/** Sets the range of lifetime for particles emitted.
281	@remarks
282	The emitter initialises particles with a time-to-live (TTL), the number of seconds a particle
283	will exist before being destroyed. This method sets a range for the TTL for all particles emitted;
284	the ttl may be randomised between these 2 extremes or will vary some other way depending on the
285	emitter.
286	Note that affectors are able to modify the TTL of particles later.
287	@par
288	Also see the alternate version of this method which takes a single TTL in order to
289	set a constant TTL for all particles.
290	@param minTtl The minimum number of seconds each particle will live for.
291	@param maxTtl The maximum number of seconds each particle will live for.
292	*/
293	virtual void setTimeToLive(Real minTtl, Real maxTtl);
294
295	/** Sets the minimum time each particle will live for. */
296	virtual void setMinTimeToLive(Real min);
297	/** Sets the maximum time each particle will live for. */
298	virtual void setMaxTimeToLive(Real max);
299
300	/** Gets the time each particle will live for. */
301	virtual Real getTimeToLive(void) const;
302
303	/** Gets the minimum time each particle will live for. */
304	virtual Real getMinTimeToLive(void) const;
305	/** Gets the maximum time each particle will live for. */
306	virtual Real getMaxTimeToLive(void) const;
307
308	/** Sets the initial colour of particles emitted.
309	@remarks
310	Particles have an initial colour on emission which the emitter sets. This method sets
311	this colour. See the alternate version of this method which takes 2 colours in order to establish
312	a range of colours to be assigned to particles.
313	@param colour The colour which all particles will be given on emission.
314	*/
315	virtual void setColour(const ColourValue& colour);
316	/** Sets the range of colours for emitted particles.
317	@remarks
318	Particles have an initial colour on emission which the emitter sets. This method sets
319	the range of this colour. See the alternate version of this method which takes a single colour
320	in order to set a constant colour for all particles. Emitters may choose to randomly assign
321	a colour in this range, or may use some other method to vary the colour.
322	@param colourStart The start of the colour range
323	@param colourEnd The end of the colour range
324	*/
325	virtual void setColour(const ColourValue& colourStart, const ColourValue& colourEnd);
326	/** Sets the minimum colour of particles to be emitted. */
327	virtual void setColourRangeStart(const ColourValue& colour);
328	/** Sets the maximum colour of particles to be emitted. */
329	virtual void setColourRangeEnd(const ColourValue& colour);
330	/** Gets the colour of particles to be emitted. */
331	virtual const ColourValue& getColour(void) const;
332	/** Gets the minimum colour of particles to be emitted. */
333	virtual const ColourValue& getColourRangeStart(void) const;
334	/** Gets the maximum colour of particles to be emitted. */
335	virtual const ColourValue& getColourRangeEnd(void) const;
336
337	/** Gets the number of particles which this emitter would like to emit based on the time elapsed.
338	@remarks
339	For efficiency the emitter does not actually create new Particle instances (these are reused
340	by the ParticleSystem as existing particles 'die'). The implementation for this method must
341	return the number of particles the emitter would like to emit given the number of seconds which
342	have elapsed (passed in as a parameter).
343	@par
344	Based on the return value from this method, the ParticleSystem class will call
345	_initParticle once for each particle it chooses to allow to be emitted by this emitter.
346	The emitter should not track these _initParticle calls, it should assume all emissions
347	requested were made (even if they could not be because of particle quotas).
348	*/
349	virtual unsigned short _getEmissionCount(Real timeElapsed) = 0;
350
351	/** Initialises a particle based on the emitter's approach and parameters.
352	@remarks
353	See the _getEmissionCount method for details of why there is a separation between
354	'requested' emissions and actual initialised particles.
355	@param
356	pParticle Pointer to a particle which must be initialised based on how this emitter
357	starts particles. This is passed as a pointer rather than being created by the emitter so the
358	ParticleSystem can reuse Particle instances, and can also set defaults itself.
359	*/
360	virtual void _initParticle(Particle* pParticle) {
361	// Initialise size incase it's been altered
362	pParticle->resetDimensions();
363	}
364
365
366	/** Returns the name of the type of emitter.
367	@remarks
368	This property is useful for determining the type of emitter procedurally so another
369	can be created.
370	*/
371	const String &getType(void) const { return mType; }
372
373	/** Sets whether or not the emitter is enabled.
374	@remarks
375	You can turn an emitter off completely by setting this parameter to false.
376	*/
377	virtual void setEnabled(bool enabled);
378
379	/** Gets the flag indicating if this emitter is enabled or not. */
380	virtual bool getEnabled(void) const;
381
382	/** Sets the 'start time' of this emitter.
383	@remarks
384	By default an emitter starts straight away as soon as a ParticleSystem is first created,
385	or also just after it is re-enabled. This parameter allows you to set a time delay so
386	that the emitter does not 'kick in' until later.
387	@param startTime The time in seconds from the creation or enabling of the emitter.
388	*/
389	virtual void setStartTime(Real startTime);
390	/** Gets the start time of the emitter. */
391	virtual Real getStartTime(void) const;
392
393	/** Sets the duration of the emitter.
394	@remarks
395	By default emitters run indefinitely (unless you manually disable them). By setting this
396	parameter, you can make an emitter turn off on it's own after a set number of seconds. It
397	will then remain disabled until either setEnabled(true) is called, or if the 'repeatAfter' parameter
398	has been set it will also repeat after a number of seconds.
399	@par
400	Also see the alternative version of this method which allows you to set a min and max duration for
401	a random variable duration.
402	@param duration The duration in seconds.
403	*/
404	virtual void setDuration(Real duration);
405
406	/** Gets the duration of the emitter from when it is created or re-enabled. */
407	virtual Real getDuration(void) const;
408
409	/** Sets the range of random duration for this emitter.
410	@remarks
411	By default emitters run indefinitely (unless you manually disable them). By setting this
412	parameter, you can make an emitter turn off on it's own after a random number of seconds. It
413	will then remain disabled until either setEnabled(true) is called, or if the 'repeatAfter' parameter
414	has been set it will also repeat after a number of seconds.
415	@par
416	Also see the alternative version of this method which allows you to set a constant duration.
417	@param min The minimum duration in seconds.
418	@param max The minimum duration in seconds.
419	*/
420	virtual void setDuration(Real min, Real max);
421	/** Sets the minimum duration of this emitter in seconds (see setDuration for more details) */
422	virtual void setMinDuration(Real min);
423	/** Sets the maximum duration of this emitter in seconds (see setDuration for more details) */
424	virtual void setMaxDuration(Real max);
425	/** Gets the minimum duration of this emitter in seconds (see setDuration for more details) */
426	virtual Real getMinDuration(void) const;
427	/** Gets the maximum duration of this emitter in seconds (see setDuration for more details) */
428	virtual Real getMaxDuration(void) const;
429
430	/** Sets the time between repeats of the emitter.
431	@remarks
432	By default emitters run indefinitely (unless you manually disable them). However, if you manually
433	disable the emitter (by calling setEnabled(false), or it's duration runs out, it will cease to emit
434	@par
435	Also see the alternative version of this method which allows you to set a min and max duration for
436	a random variable duration.
437	@param duration The duration in seconds.
438	*/
439	virtual void setRepeatDelay(Real duration);
440
441	/** Gets the duration of the emitter from when it is created or re-enabled. */
442	virtual Real getRepeatDelay(void) const;
443
444	/** Sets the range of random duration for this emitter.
445	@remarks
446	By default emitters run indefinitely (unless you manually disable them). By setting this
447	parameter, you can make an emitter turn off on it's own after a random number of seconds. It
448	will then remain disabled until either setEnabled(true) is called, or if the 'repeatAfter' parameter
449	has been set it will also repeat after a number of seconds.
450	@par
451	Also see the alternative version of this method which allows you to set a constant duration.
452	@param min The minimum duration in seconds.
453	@param max The minimum duration in seconds.
454	*/
455	virtual void setRepeatDelay(Real min, Real max);
456	/** Sets the minimum duration of this emitter in seconds (see setRepeatDelay for more details) */
457	virtual void setMinRepeatDelay(Real min);
458	/** Sets the maximum duration of this emitter in seconds (see setRepeatDelay for more details) */
459	virtual void setMaxRepeatDelay(Real max);
460	/** Gets the minimum duration of this emitter in seconds (see setRepeatDelay for more details) */
461	virtual Real getMinRepeatDelay(void) const;
462	/** Gets the maximum duration of this emitter in seconds (see setRepeatDelay for more details) */
463	virtual Real getMaxRepeatDelay(void) const;
464
465
466
467	};
468
469	}
470
471
472	#endif
473

Note: See TracBrowser for help on using the repository browser.

Download in other formats: