Planet
navi homePPSaboutscreenshotsdownloaddevelopmentforum

source: downloads/ogre/OgreMain/include/OgreParticleEmitter.h @ 45

Last change on this file since 45 was 5, checked in by anonymous, 18 years ago

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