/libs/cocos2d/CCParticleSystem.h

  1/*
  2 * cocos2d for iPhone: http://www.cocos2d-iphone.org
  3 *
  4 * Copyright (c) 2008-2010 Ricardo Quesada
  5 * 
  6 * Permission is hereby granted, free of charge, to any person obtaining a copy
  7 * of this software and associated documentation files (the "Software"), to deal
  8 * in the Software without restriction, including without limitation the rights
  9 * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
 10 * copies of the Software, and to permit persons to whom the Software is
 11 * furnished to do so, subject to the following conditions:
 12 * 
 13 * The above copyright notice and this permission notice shall be included in
 14 * all copies or substantial portions of the Software.
 15 * 
 16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 19 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 21 * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
 22 * THE SOFTWARE.
 23 *
 24 */
 25
 26
 27#import "CCProtocols.h"
 28#import "CCNode.h"
 29#import "ccTypes.h"
 30#import "ccConfig.h"
 31
 32#if CC_ENABLE_PROFILERS
 33@class CCProfilingTimer;
 34#endif
 35
 36//* @enum
 37enum {
 38	/** The Particle emitter lives forever */
 39	kCCParticleDurationInfinity = -1,
 40
 41	/** The starting size of the particle is equal to the ending size */
 42	kCCParticleStartSizeEqualToEndSize = -1,
 43	
 44	/** The starting radius of the particle is equal to the ending radius */
 45	kCCParticleStartRadiusEqualToEndRadius = -1,
 46
 47	// backward compatible
 48	kParticleStartSizeEqualToEndSize = kCCParticleStartSizeEqualToEndSize,
 49	kParticleDurationInfinity = kCCParticleDurationInfinity,
 50};
 51
 52//* @enum
 53enum {
 54	/** Gravity mode (A mode) */
 55	kCCParticleModeGravity,
 56	
 57	/** Radius mode (B mode) */
 58	kCCParticleModeRadius,	
 59};
 60
 61
 62/** @typedef tCCPositionType
 63 possible types of particle positions
 64 */
 65typedef enum {
 66	/** If the emitter is repositioned, the living particles won't be repositioned */
 67	kCCPositionTypeFree,
 68	/** If the emitter is repositioned, the living particles will be repositioned too */
 69	kCCPositionTypeGrouped,
 70}tCCPositionType;
 71
 72// backward compatible
 73enum {
 74	kPositionTypeFree = kCCPositionTypeFree,
 75	kPositionTypeGrouped = kCCPositionTypeGrouped,
 76}; 
 77
 78/** @struct tCCParticle
 79 Structure that contains the values of each particle
 80 */
 81typedef struct sCCParticle {
 82	CGPoint				pos;
 83	CGPoint				startPos;
 84
 85	ccColor4F	color;
 86	ccColor4F	deltaColor;
 87
 88	float		size;
 89	float		deltaSize;
 90
 91	float		rotation;
 92	float		deltaRotation;
 93
 94	ccTime		timeToLive;
 95
 96	union {
 97		// Mode A: gravity, direction, radial accel, tangential accel
 98		struct {
 99			CGPoint		dir;
100			float		radialAccel;
101			float		tangentialAccel;
102		} A;
103	
104		// Mode B: radius mode
105		struct {
106			float		angle;
107			float		degreesPerSecond;
108			float		radius;
109			float		deltaRadius;
110		} B;
111	} mode;
112
113}tCCParticle;
114
115typedef void (*CC_UPDATE_PARTICLE_IMP)(id, SEL, tCCParticle*, CGPoint);
116
117@class CCTexture2D;
118
119/** Particle System base class
120 Attributes of a Particle System:
121	- emmision rate of the particles
122	- Gravity Mode (Mode A):
123		- gravity
124		- direction
125		- speed +-  variance
126		- tangential acceleration +- variance
127		- radial acceleration +- variance
128	- Radius Mode (Mode B):
129		- startRadius +- variance
130		- endRadius +- variance
131		- rotate +- variance
132	- Properties common to all modes:
133		- life +- life variance
134		- start spin +- variance
135		- end spin +- variance
136		- start size +- variance
137		- end size +- variance
138		- start color +- variance
139		- end color +- variance
140		- life +- variance
141		- blending function
142	- texture
143
144 cocos2d also supports particles generated by Particle Designer (http://particledesigner.71squared.com/).
145 'Radius Mode' in Particle Designer uses a fixed emit rate of 30 hz. Since that can't be guarateed in cocos2d,
146 cocos2d uses a another approach, but the results are almost identical. 
147 
148 cocos2d supports all the variables used by Particle Designer plus a bit more:
149	- spinning particles (supported when using CCQuadParticleSystem)
150	- tangential acceleration (Gravity mode)
151	- radial acceleration (Gravity mode)
152	- radius direction (Radius mode) (Particle Designer supports outwards to inwards direction only)
153 
154 It is possible to customize any of the above mentioned properties in runtime. Example:
155 
156 @code
157	emitter.radialAccel = 15;
158	emitter.startSpin = 0;
159 @endcode
160 
161 */
162@interface CCParticleSystem : CCNode <CCTextureProtocol>
163{	
164	// is the particle system active ?
165	BOOL active;
166	// duration in seconds of the system. -1 is infinity
167	float duration;
168	// time elapsed since the start of the system (in seconds)
169	float elapsed;
170	
171	// position is from "superclass" CocosNode
172	// Emitter centerOfGravity position
173	CGPoint centerOfGravity;
174	// Position variance
175	CGPoint posVar;
176	
177	// The angle (direction) of the particles measured in degrees
178	float angle;
179	// Angle variance measured in degrees;
180	float angleVar;
181	
182	// Different modes
183	
184	int emitterMode_;
185	union {
186		// Mode A:Gravity + Tangential Accel + Radial Accel
187		struct {
188			// gravity of the particles
189			CGPoint gravity;
190
191			// The speed the particles will have.
192			float speed;
193			// The speed variance
194			float speedVar;
195
196			// Tangential acceleration
197			float tangentialAccel;
198			// Tangential acceleration variance
199			float tangentialAccelVar;
200
201			// Radial acceleration
202			float radialAccel;
203			// Radial acceleration variance
204			float radialAccelVar;
205			} A;
206
207		// Mode B: circular movement (gravity, radial accel and tangential accel don't are not used in this mode)
208		struct {
209	
210			// The starting radius of the particles
211			float startRadius;
212			// The starting radius variance of the particles
213			float startRadiusVar;
214			// The ending radius of the particles
215			float endRadius;
216			// The ending radius variance of the particles
217			float endRadiusVar;			
218			// Number of degress to rotate a particle around the source pos per second
219			float rotatePerSecond;
220			// Variance in degrees for rotatePerSecond
221			float rotatePerSecondVar;
222		} B;
223	} mode;
224	
225	// start ize of the particles
226	float startSize;
227	// start Size variance
228	float startSizeVar;
229	// End size of the particle
230	float endSize;
231	// end size of variance
232	float endSizeVar;
233	
234	// How many seconds will the particle live
235	float life;
236	// Life variance
237	float lifeVar;
238	
239	// Start color of the particles
240	ccColor4F startColor;
241	// Start color variance
242	ccColor4F startColorVar;
243	// End color of the particles
244	ccColor4F endColor;
245	// End color variance
246	ccColor4F endColorVar;
247	
248	// start angle of the particles
249	float startSpin;
250	// start angle variance
251	float startSpinVar;
252	// End angle of the particle
253	float endSpin;
254	// end angle ariance
255	float endSpinVar;
256	
257	
258	// Array of particles
259	tCCParticle *particles;
260	// Maximum particles
261	int totalParticles;
262	// Count of active particles
263	int particleCount;
264	
265	// color modulate
266//	BOOL colorModulate;
267	
268	// How many particles can be emitted per second
269	float emissionRate;
270	float emitCounter;
271	
272	// Texture of the particles
273	CCTexture2D *texture_;
274	// blend function
275	ccBlendFunc	blendFunc_;
276
277	// movment type: free or grouped
278	tCCPositionType	positionType_;
279
280	// Whether or not the node will be auto-removed when there are not particles
281	BOOL	autoRemoveOnFinish_;
282
283	//  particle idx
284	int particleIdx;
285	
286	// Optimization
287	CC_UPDATE_PARTICLE_IMP	updateParticleImp;
288	SEL						updateParticleSel;
289	
290// profiling
291#if CC_ENABLE_PROFILERS
292	CCProfilingTimer* _profilingTimer;
293#endif
294}
295
296/** Is the emitter active */
297@property (nonatomic,readonly) BOOL active;
298/** Quantity of particles that are being simulated at the moment */
299@property (nonatomic,readonly) int	particleCount;
300/** How many seconds the emitter wil run. -1 means 'forever' */
301@property (nonatomic,readwrite,assign) float duration;
302/** centerOfGravity of the emitter */
303@property (nonatomic,readwrite,assign) CGPoint centerOfGravity;
304/** Position variance of the emitter */
305@property (nonatomic,readwrite,assign) CGPoint posVar;
306/** life, and life variation of each particle */
307@property (nonatomic,readwrite,assign) float life;
308/** life variance of each particle */
309@property (nonatomic,readwrite,assign) float lifeVar;
310/** angle and angle variation of each particle */
311@property (nonatomic,readwrite,assign) float angle;
312/** angle variance of each particle */
313@property (nonatomic,readwrite,assign) float angleVar;
314
315/** Gravity value. Only available in 'Gravity' mode. */
316@property (nonatomic,readwrite,assign) CGPoint gravity;
317/** speed of each particle. Only available in 'Gravity' mode.  */
318@property (nonatomic,readwrite,assign) float speed;
319/** speed variance of each particle. Only available in 'Gravity' mode. */
320@property (nonatomic,readwrite,assign) float speedVar;
321/** tangential acceleration of each particle. Only available in 'Gravity' mode. */
322@property (nonatomic,readwrite,assign) float tangentialAccel;
323/** tangential acceleration variance of each particle. Only available in 'Gravity' mode. */
324@property (nonatomic,readwrite,assign) float tangentialAccelVar;
325/** radial acceleration of each particle. Only available in 'Gravity' mode. */
326@property (nonatomic,readwrite,assign) float radialAccel;
327/** radial acceleration variance of each particle. Only available in 'Gravity' mode. */
328@property (nonatomic,readwrite,assign) float radialAccelVar;
329
330/** The starting radius of the particles. Only available in 'Radius' mode. */
331@property (nonatomic,readwrite,assign) float startRadius;
332/** The starting radius variance of the particles. Only available in 'Radius' mode. */
333@property (nonatomic,readwrite,assign) float startRadiusVar;
334/** The ending radius of the particles. Only available in 'Radius' mode. */
335@property (nonatomic,readwrite,assign) float endRadius;
336/** The ending radius variance of the particles. Only available in 'Radius' mode. */
337@property (nonatomic,readwrite,assign) float endRadiusVar;			
338/** Number of degress to rotate a particle around the source pos per second. Only available in 'Radius' mode. */
339@property (nonatomic,readwrite,assign) float rotatePerSecond;
340/** Variance in degrees for rotatePerSecond. Only available in 'Radius' mode. */
341@property (nonatomic,readwrite,assign) float rotatePerSecondVar;
342
343/** start size in pixels of each particle */
344@property (nonatomic,readwrite,assign) float startSize;
345/** size variance in pixels of each particle */
346@property (nonatomic,readwrite,assign) float startSizeVar;
347/** end size in pixels of each particle */
348@property (nonatomic,readwrite,assign) float endSize;
349/** end size variance in pixels of each particle */
350@property (nonatomic,readwrite,assign) float endSizeVar;
351/** start color of each particle */
352@property (nonatomic,readwrite,assign) ccColor4F startColor;
353/** start color variance of each particle */
354@property (nonatomic,readwrite,assign) ccColor4F startColorVar;
355/** end color and end color variation of each particle */
356@property (nonatomic,readwrite,assign) ccColor4F endColor;
357/** end color variance of each particle */
358@property (nonatomic,readwrite,assign) ccColor4F endColorVar;
359//* initial angle of each particle
360@property (nonatomic,readwrite,assign) float startSpin;
361//* initial angle of each particle
362@property (nonatomic,readwrite,assign) float startSpinVar;
363//* initial angle of each particle
364@property (nonatomic,readwrite,assign) float endSpin;
365//* initial angle of each particle
366@property (nonatomic,readwrite,assign) float endSpinVar;
367/** emission rate of the particles */
368@property (nonatomic,readwrite,assign) float emissionRate;
369/** maximum particles of the system */
370@property (nonatomic,readwrite,assign) int totalParticles;
371/** conforms to CocosNodeTexture protocol */
372@property (nonatomic,readwrite, retain) CCTexture2D * texture;
373/** conforms to CocosNodeTexture protocol */
374@property (nonatomic,readwrite) ccBlendFunc blendFunc;
375/** whether or not the particles are using blend additive.
376 If enabled, the following blending function will be used.
377 @code
378	source blend function = GL_SRC_ALPHA;
379	dest blend function = GL_ONE;
380 @endcode
381 */
382@property (nonatomic,readwrite) BOOL blendAdditive;
383/** particles movement type: Free or Grouped
384 @since v0.8
385 */
386@property (nonatomic,readwrite) tCCPositionType positionType;
387/** whether or not the node will be auto-removed when it has no particles left.
388 By default it is NO.
389 @since v0.8
390 */
391@property (nonatomic,readwrite) BOOL autoRemoveOnFinish;
392/** Switch between different kind of emitter modes:
393   - kCCParticleModeGravity: uses gravity, speed, radial and tangential acceleration
394   - kCCParticleModeRadius: uses radius movement + rotation
395 */
396@property (nonatomic,readwrite) int emitterMode;
397
398/** creates an initializes a CCParticleSystem from a plist file.
399 This plist files can be creted manually or with Particle Designer:
400	http://particledesigner.71squared.com/
401 @since v0.99.3
402 */
403+(id) particleWithFile:(NSString*)plistFile;
404
405/** initializes a CCParticleSystem from a plist file.
406 This plist files can be creted manually or with Particle Designer:
407	http://particledesigner.71squared.com/
408 @since v0.99.3
409 */
410-(id) initWithFile:(NSString*) plistFile;
411
412/** initializes a CCQuadParticleSystem from a NSDictionary.
413 @since v0.99.3
414 */
415-(id) initWithDictionary:(NSDictionary*)dictionary;
416
417//! Initializes a system with a fixed number of particles
418-(id) initWithTotalParticles:(int) numberOfParticles;
419//! Add a particle to the emitter
420-(BOOL) addParticle;
421//! Initializes a particle
422-(void) initParticle: (tCCParticle*) particle;
423//! stop emitting particles. Running particles will continue to run until they die
424-(void) stopSystem;
425//! Kill all living particles.
426-(void) resetSystem;
427//! whether or not the system is full
428-(BOOL) isFull;
429
430//! should be overriden by subclasses
431-(void) updateQuadWithParticle:(tCCParticle*)particle newPosition:(CGPoint)pos;
432//! should be overriden by subclasses
433-(void) postStep;
434
435@end
436