summary refs log tree commit diff stats
path: root/libs/CocosDenshion/CocosDenshion.h
diff options
context:
space:
mode:
authorStarla Insigna <starla4444@gmail.com>2011-07-30 11:19:14 -0400
committerStarla Insigna <starla4444@gmail.com>2011-07-30 11:19:14 -0400
commit9cd57b731ab1c666d4a1cb725538fdc137763d12 (patch)
tree5bac45ae5157a1cb10c6e45500cbf72789917980 /libs/CocosDenshion/CocosDenshion.h
downloadcartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.tar.gz
cartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.tar.bz2
cartcollect-9cd57b731ab1c666d4a1cb725538fdc137763d12.zip
Initial commit (version 0.2.1)
Diffstat (limited to 'libs/CocosDenshion/CocosDenshion.h')
-rwxr-xr-xlibs/CocosDenshion/CocosDenshion.h440
1 files changed, 440 insertions, 0 deletions
diff --git a/libs/CocosDenshion/CocosDenshion.h b/libs/CocosDenshion/CocosDenshion.h new file mode 100755 index 0000000..638d852 --- /dev/null +++ b/libs/CocosDenshion/CocosDenshion.h
@@ -0,0 +1,440 @@
1/*
2 Copyright (c) 2010 Steve Oldmeadow
3
4 Permission is hereby granted, free of charge, to any person obtaining a copy
5 of this software and associated documentation files (the "Software"), to deal
6 in the Software without restriction, including without limitation the rights
7 to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
8 copies of the Software, and to permit persons to whom the Software is
9 furnished to do so, subject to the following conditions:
10
11 The above copyright notice and this permission notice shall be included in
12 all copies or substantial portions of the Software.
13
14 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
15 IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
16 FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
17 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
18 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
19 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
20 THE SOFTWARE.
21
22 $Id$
23 */
24
25
26
27/**
28@file
29@b IMPORTANT
30There are 3 different ways of using CocosDenshion. Depending on which you choose you
31will need to include different files and frameworks.
32
33@par SimpleAudioEngine
34This is recommended for basic audio requirements. If you just want to play some sound fx
35and some background music and have no interest in learning the lower level workings then
36this is the interface to use.
37
38Requirements:
39 - Firmware: OS 2.2 or greater
40 - Files: SimpleAudioEngine.*, CocosDenshion.*
41 - Frameworks: OpenAL, AudioToolbox, AVFoundation
42
43@par CDAudioManager
44CDAudioManager is basically a thin wrapper around an AVAudioPlayer object used for playing
45background music and a CDSoundEngine object used for playing sound effects. It manages the
46audio session for you deals with audio session interruption. It is fairly low level and it
47is expected you have some understanding of the underlying technologies. For example, for
48many use cases regarding background music it is expected you will work directly with the
49backgroundMusic AVAudioPlayer which is exposed as a property.
50
51Requirements:
52 - Firmware: OS 2.2 or greater
53 - Files: CDAudioManager.*, CocosDenshion.*
54 - Frameworks: OpenAL, AudioToolbox, AVFoundation
55
56@par CDSoundEngine
57CDSoundEngine is a sound engine built upon OpenAL and derived from Apple's oalTouch
58example. It can playback up to 32 sounds simultaneously with control over pitch, pan
59and gain. It can be set up to handle audio session interruption automatically. You
60may decide to use CDSoundEngine directly instead of CDAudioManager or SimpleAudioEngine
61because you require OS 2.0 compatibility.
62
63Requirements:
64 - Firmware: OS 2.0 or greater
65 - Files: CocosDenshion.*
66 - Frameworks: OpenAL, AudioToolbox
67
68*/
69
70#import <OpenAL/al.h>
71#import <OpenAL/alc.h>
72#import <AudioToolbox/AudioToolbox.h>
73#import <Foundation/Foundation.h>
74#import "CDConfig.h"
75
76
77#if !defined(CD_DEBUG) || CD_DEBUG == 0
78#define CDLOG(...) do {} while (0)
79#define CDLOGINFO(...) do {} while (0)
80
81#elif CD_DEBUG == 1
82#define CDLOG(...) NSLog(__VA_ARGS__)
83#define CDLOGINFO(...) do {} while (0)
84
85#elif CD_DEBUG > 1
86#define CDLOG(...) NSLog(__VA_ARGS__)
87#define CDLOGINFO(...) NSLog(__VA_ARGS__)
88#endif // CD_DEBUG
89
90
91#import "CDOpenALSupport.h"
92
93//Tested source limit on 2.2.1 and 3.1.2 with up to 128 sources and appears to work. Older OS versions e.g 2.2 may support only 32
94#define CD_SOURCE_LIMIT 32 //Total number of sources we will ever want, may actually get less
95#define CD_NO_SOURCE 0xFEEDFAC //Return value indicating playback failed i.e. no source
96#define CD_IGNORE_AUDIO_SESSION 0xBEEFBEE //Used internally to indicate audio session will not be handled
97#define CD_MUTE 0xFEEDBAB //Return value indicating sound engine is muted or non functioning
98#define CD_NO_SOUND = -1;
99
100#define CD_SAMPLE_RATE_HIGH 44100
101#define CD_SAMPLE_RATE_MID 22050
102#define CD_SAMPLE_RATE_LOW 16000
103#define CD_SAMPLE_RATE_BASIC 8000
104#define CD_SAMPLE_RATE_DEFAULT 44100
105
106extern NSString * const kCDN_BadAlContext;
107extern NSString * const kCDN_AsynchLoadComplete;
108
109extern float const kCD_PitchDefault;
110extern float const kCD_PitchLowerOneOctave;
111extern float const kCD_PitchHigherOneOctave;
112extern float const kCD_PanDefault;
113extern float const kCD_PanFullLeft;
114extern float const kCD_PanFullRight;
115extern float const kCD_GainDefault;
116
117enum bufferState {
118 CD_BS_EMPTY = 0,
119 CD_BS_LOADED = 1,
120 CD_BS_FAILED = 2
121};
122
123typedef struct _sourceGroup {
124 int startIndex;
125 int currentIndex;
126 int totalSources;
127 bool enabled;
128 bool nonInterruptible;
129 int *sourceStatuses;//pointer into array of source status information
130} sourceGroup;
131
132typedef struct _bufferInfo {
133 ALuint bufferId;
134 int bufferState;
135 void* bufferData;
136 ALenum format;
137 ALsizei sizeInBytes;
138 ALsizei frequencyInHertz;
139} bufferInfo;
140
141typedef struct _sourceInfo {
142 bool usable;
143 ALuint sourceId;
144 ALuint attachedBufferId;
145} sourceInfo;
146
147#pragma mark CDAudioTransportProtocol
148
149@protocol CDAudioTransportProtocol <NSObject>
150/** Play the audio */
151-(BOOL) play;
152/** Pause the audio, retain resources */
153-(BOOL) pause;
154/** Stop the audio, release resources */
155-(BOOL) stop;
156/** Return playback to beginning */
157-(BOOL) rewind;
158@end
159
160#pragma mark CDAudioInterruptProtocol
161
162@protocol CDAudioInterruptProtocol <NSObject>
163/** Is audio mute */
164-(BOOL) mute;
165/** If YES then audio is silenced but not stopped, calls to start new audio will proceed but silently */
166-(void) setMute:(BOOL) muteValue;
167/** Is audio enabled */
168-(BOOL) enabled;
169/** If NO then all audio is stopped and any calls to start new audio will be ignored */
170-(void) setEnabled:(BOOL) enabledValue;
171@end
172
173#pragma mark CDUtilities
174/**
175 Collection of utilities required by CocosDenshion
176 */
177@interface CDUtilities : NSObject
178{
179}
180
181/** Fundamentally the same as the corresponding method is CCFileUtils but added to break binding to cocos2d */
182+(NSString*) fullPathFromRelativePath:(NSString*) relPath;
183
184@end
185
186
187#pragma mark CDSoundEngine
188
189/** CDSoundEngine is built upon OpenAL and works with SDK 2.0.
190 CDSoundEngine is a sound engine built upon OpenAL and derived from Apple's oalTouch
191 example. It can playback up to 32 sounds simultaneously with control over pitch, pan
192 and gain. It can be set up to handle audio session interruption automatically. You
193 may decide to use CDSoundEngine directly instead of CDAudioManager or SimpleAudioEngine
194 because you require OS 2.0 compatibility.
195
196 Requirements:
197 - Firmware: OS 2.0 or greater
198 - Files: CocosDenshion.*
199 - Frameworks: OpenAL, AudioToolbox
200
201 @since v0.8
202 */
203@class CDSoundSource;
204@interface CDSoundEngine : NSObject <CDAudioInterruptProtocol> {
205
206 bufferInfo *_buffers;
207 sourceInfo *_sources;
208 sourceGroup *_sourceGroups;
209 ALCcontext *context;
210 NSUInteger _sourceGroupTotal;
211 UInt32 _audioSessionCategory;
212 BOOL _handleAudioSession;
213 ALfloat _preMuteGain;
214 NSObject *_mutexBufferLoad;
215 BOOL mute_;
216 BOOL enabled_;
217
218 ALenum lastErrorCode_;
219 BOOL functioning_;
220 float asynchLoadProgress_;
221 BOOL getGainWorks_;
222
223 //For managing dynamic allocation of sources and buffers
224 int sourceTotal_;
225 int bufferTotal;
226
227}
228
229@property (readwrite, nonatomic) ALfloat masterGain;
230@property (readonly) ALenum lastErrorCode;//Last OpenAL error code that was generated
231@property (readonly) BOOL functioning;//Is the sound engine functioning
232@property (readwrite) float asynchLoadProgress;
233@property (readonly) BOOL getGainWorks;//Does getting the gain for a source work
234/** Total number of sources available */
235@property (readonly) int sourceTotal;
236/** Total number of source groups that have been defined */
237@property (readonly) NSUInteger sourceGroupTotal;
238
239/** Sets the sample rate for the audio mixer. For best performance this should match the sample rate of your audio content */
240+(void) setMixerSampleRate:(Float32) sampleRate;
241
242/** Initializes the engine with a group definition and a total number of groups */
243-(id)init;
244
245/** Plays a sound in a channel group with a pitch, pan and gain. The sound could played looped or not */
246-(ALuint) playSound:(int) soundId sourceGroupId:(int)sourceGroupId pitch:(float) pitch pan:(float) pan gain:(float) gain loop:(BOOL) loop;
247
248/** Creates and returns a sound source object for the specified sound within the specified source group.
249 */
250-(CDSoundSource *) soundSourceForSound:(int) soundId sourceGroupId:(int) sourceGroupId;
251
252/** Stops playing a sound */
253- (void) stopSound:(ALuint) sourceId;
254/** Stops playing a source group */
255- (void) stopSourceGroup:(int) sourceGroupId;
256/** Stops all playing sounds */
257-(void) stopAllSounds;
258-(void) defineSourceGroups:(NSArray*) sourceGroupDefinitions;
259-(void) defineSourceGroups:(int[]) sourceGroupDefinitions total:(NSUInteger) total;
260-(void) setSourceGroupNonInterruptible:(int) sourceGroupId isNonInterruptible:(BOOL) isNonInterruptible;
261-(void) setSourceGroupEnabled:(int) sourceGroupId enabled:(BOOL) enabled;
262-(BOOL) sourceGroupEnabled:(int) sourceGroupId;
263-(BOOL) loadBufferFromData:(int) soundId soundData:(ALvoid*) soundData format:(ALenum) format size:(ALsizei) size freq:(ALsizei) freq;
264-(BOOL) loadBuffer:(int) soundId filePath:(NSString*) filePath;
265-(void) loadBuffersAsynchronously:(NSArray *) loadRequests;
266-(BOOL) unloadBuffer:(int) soundId;
267-(ALCcontext *) openALContext;
268
269/** Returns the duration of the buffer in seconds or a negative value if the buffer id is invalid */
270-(float) bufferDurationInSeconds:(int) soundId;
271/** Returns the size of the buffer in bytes or a negative value if the buffer id is invalid */
272-(ALsizei) bufferSizeInBytes:(int) soundId;
273/** Returns the sampling frequency of the buffer in hertz or a negative value if the buffer id is invalid */
274-(ALsizei) bufferFrequencyInHertz:(int) soundId;
275
276/** Used internally, never call unless you know what you are doing */
277-(void) _soundSourcePreRelease:(CDSoundSource *) soundSource;
278
279@end
280
281#pragma mark CDSoundSource
282/** CDSoundSource is a wrapper around an OpenAL sound source.
283 It allows you to manipulate properties such as pitch, gain, pan and looping while the
284 sound is playing. CDSoundSource is based on the old CDSourceWrapper class but with much
285 added functionality.
286
287 @since v1.0
288 */
289@interface CDSoundSource : NSObject <CDAudioTransportProtocol, CDAudioInterruptProtocol> {
290 ALenum lastError;
291@public
292 ALuint _sourceId;
293 ALuint _sourceIndex;
294 CDSoundEngine* _engine;
295 int _soundId;
296 float _preMuteGain;
297 BOOL enabled_;
298 BOOL mute_;
299}
300@property (readwrite, nonatomic) float pitch;
301@property (readwrite, nonatomic) float gain;
302@property (readwrite, nonatomic) float pan;
303@property (readwrite, nonatomic) BOOL looping;
304@property (readonly) BOOL isPlaying;
305@property (readwrite, nonatomic) int soundId;
306/** Returns the duration of the attached buffer in seconds or a negative value if the buffer is invalid */
307@property (readonly) float durationInSeconds;
308
309/** Stores the last error code that occurred. Check against AL_NO_ERROR */
310@property (readonly) ALenum lastError;
311/** Do not init yourself, get an instance from the sourceForSound factory method on CDSoundEngine */
312-(id)init:(ALuint) theSourceId sourceIndex:(int) index soundEngine:(CDSoundEngine*) engine;
313
314@end
315
316#pragma mark CDAudioInterruptTargetGroup
317
318/** Container for objects that implement audio interrupt protocol i.e. they can be muted and enabled.
319 Setting mute and enabled for the group propagates to all children.
320 Designed to be used with your CDSoundSource objects to get them to comply with global enabled and mute settings
321 if that is what you want to do.*/
322@interface CDAudioInterruptTargetGroup : NSObject <CDAudioInterruptProtocol> {
323 BOOL mute_;
324 BOOL enabled_;
325 NSMutableArray *children_;
326}
327-(void) addAudioInterruptTarget:(NSObject<CDAudioInterruptProtocol>*) interruptibleTarget;
328@end
329
330#pragma mark CDAsynchBufferLoader
331
332/** CDAsynchBufferLoader
333 TODO
334 */
335@interface CDAsynchBufferLoader : NSOperation {
336 NSArray *_loadRequests;
337 CDSoundEngine *_soundEngine;
338}
339
340-(id) init:(NSArray *)loadRequests soundEngine:(CDSoundEngine *) theSoundEngine;
341
342@end
343
344#pragma mark CDBufferLoadRequest
345
346/** CDBufferLoadRequest */
347@interface CDBufferLoadRequest: NSObject
348{
349 NSString *filePath;
350 int soundId;
351 //id loader;
352}
353
354@property (readonly) NSString *filePath;
355@property (readonly) int soundId;
356
357- (id)init:(int) theSoundId filePath:(const NSString *) theFilePath;
358@end
359
360/** Interpolation type */
361typedef enum {
362 kIT_Linear, //!Straight linear interpolation fade
363 kIT_SCurve, //!S curved interpolation
364 kIT_Exponential //!Exponential interpolation
365} tCDInterpolationType;
366
367#pragma mark CDFloatInterpolator
368@interface CDFloatInterpolator: NSObject
369{
370 float start;
371 float end;
372 float lastValue;
373 tCDInterpolationType interpolationType;
374}
375@property (readwrite, nonatomic) float start;
376@property (readwrite, nonatomic) float end;
377@property (readwrite, nonatomic) tCDInterpolationType interpolationType;
378
379/** Return a value between min and max based on t which represents fractional progress where 0 is the start
380 and 1 is the end */
381-(float) interpolate:(float) t;
382-(id) init:(tCDInterpolationType) type startVal:(float) startVal endVal:(float) endVal;
383
384@end
385
386#pragma mark CDPropertyModifier
387
388/** Base class for classes that modify properties such as pitch, pan and gain */
389@interface CDPropertyModifier: NSObject
390{
391 CDFloatInterpolator *interpolator;
392 float startValue;
393 float endValue;
394 id target;
395 BOOL stopTargetWhenComplete;
396
397}
398@property (readwrite, nonatomic) BOOL stopTargetWhenComplete;
399@property (readwrite, nonatomic) float startValue;
400@property (readwrite, nonatomic) float endValue;
401@property (readwrite, nonatomic) tCDInterpolationType interpolationType;
402
403-(id) init:(id) theTarget interpolationType:(tCDInterpolationType) type startVal:(float) startVal endVal:(float) endVal;
404/** Set to a fractional value between 0 and 1 where 0 equals the start and 1 equals the end*/
405-(void) modify:(float) t;
406
407-(void) _setTargetProperty:(float) newVal;
408-(float) _getTargetProperty;
409-(void) _stopTarget;
410-(Class) _allowableType;
411
412@end
413
414#pragma mark CDSoundSourceFader
415
416/** Fader for CDSoundSource objects */
417@interface CDSoundSourceFader : CDPropertyModifier{}
418@end
419
420#pragma mark CDSoundSourcePanner
421
422/** Panner for CDSoundSource objects */
423@interface CDSoundSourcePanner : CDPropertyModifier{}
424@end
425
426#pragma mark CDSoundSourcePitchBender
427
428/** Pitch bender for CDSoundSource objects */
429@interface CDSoundSourcePitchBender : CDPropertyModifier{}
430@end
431
432#pragma mark CDSoundEngineFader
433
434/** Fader for CDSoundEngine objects */
435@interface CDSoundEngineFader : CDPropertyModifier{}
436@end
437
438
439
440