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

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

adding ogre 1.2 and dependencies
Line 
1/*
2-----------------------------------------------------------------------------
3This source file is part of OGRE
4        (Object-oriented Graphics Rendering Engine)
5For the latest info, see http://www.ogre3d.org/
6
7Copyright (c) 2000-2005 The OGRE Team
8Also see acknowledgements in Readme.html
9
10This program is free software; you can redistribute it and/or modify it under
11the terms of the GNU Lesser General Public License as published by the Free Software
12Foundation; either version 2 of the License, or (at your option) any later
13version.
14
15This program is distributed in the hope that it will be useful, but WITHOUT
16ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
17FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
18
19You should have received a copy of the GNU Lesser General Public License along with
20this program; if not, write to the Free Software Foundation, Inc., 59 Temple
21Place - Suite 330, Boston, MA 02111-1307, USA, or go to
22http://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
37namespace 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.