From 9cd57b731ab1c666d4a1cb725538fdc137763d12 Mon Sep 17 00:00:00 2001 From: Starla Insigna Date: Sat, 30 Jul 2011 11:19:14 -0400 Subject: Initial commit (version 0.2.1) --- libs/CocosDenshion/CocosDenshion.h | 440 +++++++++++++++++++++++++++++++++++++ 1 file changed, 440 insertions(+) create mode 100755 libs/CocosDenshion/CocosDenshion.h (limited to 'libs/CocosDenshion/CocosDenshion.h') 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 @@ +/* + Copyright (c) 2010 Steve Oldmeadow + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in + all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN + THE SOFTWARE. + + $Id$ + */ + + + +/** +@file +@b IMPORTANT +There are 3 different ways of using CocosDenshion. Depending on which you choose you +will need to include different files and frameworks. + +@par SimpleAudioEngine +This is recommended for basic audio requirements. If you just want to play some sound fx +and some background music and have no interest in learning the lower level workings then +this is the interface to use. + +Requirements: + - Firmware: OS 2.2 or greater + - Files: SimpleAudioEngine.*, CocosDenshion.* + - Frameworks: OpenAL, AudioToolbox, AVFoundation + +@par CDAudioManager +CDAudioManager is basically a thin wrapper around an AVAudioPlayer object used for playing +background music and a CDSoundEngine object used for playing sound effects. It manages the +audio session for you deals with audio session interruption. It is fairly low level and it +is expected you have some understanding of the underlying technologies. For example, for +many use cases regarding background music it is expected you will work directly with the +backgroundMusic AVAudioPlayer which is exposed as a property. + +Requirements: + - Firmware: OS 2.2 or greater + - Files: CDAudioManager.*, CocosDenshion.* + - Frameworks: OpenAL, AudioToolbox, AVFoundation + +@par CDSoundEngine +CDSoundEngine is a sound engine built upon OpenAL and derived from Apple's oalTouch +example. It can playback up to 32 sounds simultaneously with control over pitch, pan +and gain. It can be set up to handle audio session interruption automatically. You +may decide to use CDSoundEngine directly instead of CDAudioManager or SimpleAudioEngine +because you require OS 2.0 compatibility. + +Requirements: + - Firmware: OS 2.0 or greater + - Files: CocosDenshion.* + - Frameworks: OpenAL, AudioToolbox + +*/ + +#import +#import +#import +#import +#import "CDConfig.h" + + +#if !defined(CD_DEBUG) || CD_DEBUG == 0 +#define CDLOG(...) do {} while (0) +#define CDLOGINFO(...) do {} while (0) + +#elif CD_DEBUG == 1 +#define CDLOG(...) NSLog(__VA_ARGS__) +#define CDLOGINFO(...) do {} while (0) + +#elif CD_DEBUG > 1 +#define CDLOG(...) NSLog(__VA_ARGS__) +#define CDLOGINFO(...) NSLog(__VA_ARGS__) +#endif // CD_DEBUG + + +#import "CDOpenALSupport.h" + +//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 +#define CD_SOURCE_LIMIT 32 //Total number of sources we will ever want, may actually get less +#define CD_NO_SOURCE 0xFEEDFAC //Return value indicating playback failed i.e. no source +#define CD_IGNORE_AUDIO_SESSION 0xBEEFBEE //Used internally to indicate audio session will not be handled +#define CD_MUTE 0xFEEDBAB //Return value indicating sound engine is muted or non functioning +#define CD_NO_SOUND = -1; + +#define CD_SAMPLE_RATE_HIGH 44100 +#define CD_SAMPLE_RATE_MID 22050 +#define CD_SAMPLE_RATE_LOW 16000 +#define CD_SAMPLE_RATE_BASIC 8000 +#define CD_SAMPLE_RATE_DEFAULT 44100 + +extern NSString * const kCDN_BadAlContext; +extern NSString * const kCDN_AsynchLoadComplete; + +extern float const kCD_PitchDefault; +extern float const kCD_PitchLowerOneOctave; +extern float const kCD_PitchHigherOneOctave; +extern float const kCD_PanDefault; +extern float const kCD_PanFullLeft; +extern float const kCD_PanFullRight; +extern float const kCD_GainDefault; + +enum bufferState { + CD_BS_EMPTY = 0, + CD_BS_LOADED = 1, + CD_BS_FAILED = 2 +}; + +typedef struct _sourceGroup { + int startIndex; + int currentIndex; + int totalSources; + bool enabled; + bool nonInterruptible; + int *sourceStatuses;//pointer into array of source status information +} sourceGroup; + +typedef struct _bufferInfo { + ALuint bufferId; + int bufferState; + void* bufferData; + ALenum format; + ALsizei sizeInBytes; + ALsizei frequencyInHertz; +} bufferInfo; + +typedef struct _sourceInfo { + bool usable; + ALuint sourceId; + ALuint attachedBufferId; +} sourceInfo; + +#pragma mark CDAudioTransportProtocol + +@protocol CDAudioTransportProtocol +/** Play the audio */ +-(BOOL) play; +/** Pause the audio, retain resources */ +-(BOOL) pause; +/** Stop the audio, release resources */ +-(BOOL) stop; +/** Return playback to beginning */ +-(BOOL) rewind; +@end + +#pragma mark CDAudioInterruptProtocol + +@protocol CDAudioInterruptProtocol +/** Is audio mute */ +-(BOOL) mute; +/** If YES then audio is silenced but not stopped, calls to start new audio will proceed but silently */ +-(void) setMute:(BOOL) muteValue; +/** Is audio enabled */ +-(BOOL) enabled; +/** If NO then all audio is stopped and any calls to start new audio will be ignored */ +-(void) setEnabled:(BOOL) enabledValue; +@end + +#pragma mark CDUtilities +/** + Collection of utilities required by CocosDenshion + */ +@interface CDUtilities : NSObject +{ +} + +/** Fundamentally the same as the corresponding method is CCFileUtils but added to break binding to cocos2d */ ++(NSString*) fullPathFromRelativePath:(NSString*) relPath; + +@end + + +#pragma mark CDSoundEngine + +/** CDSoundEngine is built upon OpenAL and works with SDK 2.0. + CDSoundEngine is a sound engine built upon OpenAL and derived from Apple's oalTouch + example. It can playback up to 32 sounds simultaneously with control over pitch, pan + and gain. It can be set up to handle audio session interruption automatically. You + may decide to use CDSoundEngine directly instead of CDAudioManager or SimpleAudioEngine + because you require OS 2.0 compatibility. + + Requirements: + - Firmware: OS 2.0 or greater + - Files: CocosDenshion.* + - Frameworks: OpenAL, AudioToolbox + + @since v0.8 + */ +@class CDSoundSource; +@interface CDSoundEngine : NSObject { + + bufferInfo *_buffers; + sourceInfo *_sources; + sourceGroup *_sourceGroups; + ALCcontext *context; + NSUInteger _sourceGroupTotal; + UInt32 _audioSessionCategory; + BOOL _handleAudioSession; + ALfloat _preMuteGain; + NSObject *_mutexBufferLoad; + BOOL mute_; + BOOL enabled_; + + ALenum lastErrorCode_; + BOOL functioning_; + float asynchLoadProgress_; + BOOL getGainWorks_; + + //For managing dynamic allocation of sources and buffers + int sourceTotal_; + int bufferTotal; + +} + +@property (readwrite, nonatomic) ALfloat masterGain; +@property (readonly) ALenum lastErrorCode;//Last OpenAL error code that was generated +@property (readonly) BOOL functioning;//Is the sound engine functioning +@property (readwrite) float asynchLoadProgress; +@property (readonly) BOOL getGainWorks;//Does getting the gain for a source work +/** Total number of sources available */ +@property (readonly) int sourceTotal; +/** Total number of source groups that have been defined */ +@property (readonly) NSUInteger sourceGroupTotal; + +/** Sets the sample rate for the audio mixer. For best performance this should match the sample rate of your audio content */ ++(void) setMixerSampleRate:(Float32) sampleRate; + +/** Initializes the engine with a group definition and a total number of groups */ +-(id)init; + +/** Plays a sound in a channel group with a pitch, pan and gain. The sound could played looped or not */ +-(ALuint) playSound:(int) soundId sourceGroupId:(int)sourceGroupId pitch:(float) pitch pan:(float) pan gain:(float) gain loop:(BOOL) loop; + +/** Creates and returns a sound source object for the specified sound within the specified source group. + */ +-(CDSoundSource *) soundSourceForSound:(int) soundId sourceGroupId:(int) sourceGroupId; + +/** Stops playing a sound */ +- (void) stopSound:(ALuint) sourceId; +/** Stops playing a source group */ +- (void) stopSourceGroup:(int) sourceGroupId; +/** Stops all playing sounds */ +-(void) stopAllSounds; +-(void) defineSourceGroups:(NSArray*) sourceGroupDefinitions; +-(void) defineSourceGroups:(int[]) sourceGroupDefinitions total:(NSUInteger) total; +-(void) setSourceGroupNonInterruptible:(int) sourceGroupId isNonInterruptible:(BOOL) isNonInterruptible; +-(void) setSourceGroupEnabled:(int) sourceGroupId enabled:(BOOL) enabled; +-(BOOL) sourceGroupEnabled:(int) sourceGroupId; +-(BOOL) loadBufferFromData:(int) soundId soundData:(ALvoid*) soundData format:(ALenum) format size:(ALsizei) size freq:(ALsizei) freq; +-(BOOL) loadBuffer:(int) soundId filePath:(NSString*) filePath; +-(void) loadBuffersAsynchronously:(NSArray *) loadRequests; +-(BOOL) unloadBuffer:(int) soundId; +-(ALCcontext *) openALContext; + +/** Returns the duration of the buffer in seconds or a negative value if the buffer id is invalid */ +-(float) bufferDurationInSeconds:(int) soundId; +/** Returns the size of the buffer in bytes or a negative value if the buffer id is invalid */ +-(ALsizei) bufferSizeInBytes:(int) soundId; +/** Returns the sampling frequency of the buffer in hertz or a negative value if the buffer id is invalid */ +-(ALsizei) bufferFrequencyInHertz:(int) soundId; + +/** Used internally, never call unless you know what you are doing */ +-(void) _soundSourcePreRelease:(CDSoundSource *) soundSource; + +@end + +#pragma mark CDSoundSource +/** CDSoundSource is a wrapper around an OpenAL sound source. + It allows you to manipulate properties such as pitch, gain, pan and looping while the + sound is playing. CDSoundSource is based on the old CDSourceWrapper class but with much + added functionality. + + @since v1.0 + */ +@interface CDSoundSource : NSObject { + ALenum lastError; +@public + ALuint _sourceId; + ALuint _sourceIndex; + CDSoundEngine* _engine; + int _soundId; + float _preMuteGain; + BOOL enabled_; + BOOL mute_; +} +@property (readwrite, nonatomic) float pitch; +@property (readwrite, nonatomic) float gain; +@property (readwrite, nonatomic) float pan; +@property (readwrite, nonatomic) BOOL looping; +@property (readonly) BOOL isPlaying; +@property (readwrite, nonatomic) int soundId; +/** Returns the duration of the attached buffer in seconds or a negative value if the buffer is invalid */ +@property (readonly) float durationInSeconds; + +/** Stores the last error code that occurred. Check against AL_NO_ERROR */ +@property (readonly) ALenum lastError; +/** Do not init yourself, get an instance from the sourceForSound factory method on CDSoundEngine */ +-(id)init:(ALuint) theSourceId sourceIndex:(int) index soundEngine:(CDSoundEngine*) engine; + +@end + +#pragma mark CDAudioInterruptTargetGroup + +/** Container for objects that implement audio interrupt protocol i.e. they can be muted and enabled. + Setting mute and enabled for the group propagates to all children. + Designed to be used with your CDSoundSource objects to get them to comply with global enabled and mute settings + if that is what you want to do.*/ +@interface CDAudioInterruptTargetGroup : NSObject { + BOOL mute_; + BOOL enabled_; + NSMutableArray *children_; +} +-(void) addAudioInterruptTarget:(NSObject*) interruptibleTarget; +@end + +#pragma mark CDAsynchBufferLoader + +/** CDAsynchBufferLoader + TODO + */ +@interface CDAsynchBufferLoader : NSOperation { + NSArray *_loadRequests; + CDSoundEngine *_soundEngine; +} + +-(id) init:(NSArray *)loadRequests soundEngine:(CDSoundEngine *) theSoundEngine; + +@end + +#pragma mark CDBufferLoadRequest + +/** CDBufferLoadRequest */ +@interface CDBufferLoadRequest: NSObject +{ + NSString *filePath; + int soundId; + //id loader; +} + +@property (readonly) NSString *filePath; +@property (readonly) int soundId; + +- (id)init:(int) theSoundId filePath:(const NSString *) theFilePath; +@end + +/** Interpolation type */ +typedef enum { + kIT_Linear, //!Straight linear interpolation fade + kIT_SCurve, //!S curved interpolation + kIT_Exponential //!Exponential interpolation +} tCDInterpolationType; + +#pragma mark CDFloatInterpolator +@interface CDFloatInterpolator: NSObject +{ + float start; + float end; + float lastValue; + tCDInterpolationType interpolationType; +} +@property (readwrite, nonatomic) float start; +@property (readwrite, nonatomic) float end; +@property (readwrite, nonatomic) tCDInterpolationType interpolationType; + +/** Return a value between min and max based on t which represents fractional progress where 0 is the start + and 1 is the end */ +-(float) interpolate:(float) t; +-(id) init:(tCDInterpolationType) type startVal:(float) startVal endVal:(float) endVal; + +@end + +#pragma mark CDPropertyModifier + +/** Base class for classes that modify properties such as pitch, pan and gain */ +@interface CDPropertyModifier: NSObject +{ + CDFloatInterpolator *interpolator; + float startValue; + float endValue; + id target; + BOOL stopTargetWhenComplete; + +} +@property (readwrite, nonatomic) BOOL stopTargetWhenComplete; +@property (readwrite, nonatomic) float startValue; +@property (readwrite, nonatomic) float endValue; +@property (readwrite, nonatomic) tCDInterpolationType interpolationType; + +-(id) init:(id) theTarget interpolationType:(tCDInterpolationType) type startVal:(float) startVal endVal:(float) endVal; +/** Set to a fractional value between 0 and 1 where 0 equals the start and 1 equals the end*/ +-(void) modify:(float) t; + +-(void) _setTargetProperty:(float) newVal; +-(float) _getTargetProperty; +-(void) _stopTarget; +-(Class) _allowableType; + +@end + +#pragma mark CDSoundSourceFader + +/** Fader for CDSoundSource objects */ +@interface CDSoundSourceFader : CDPropertyModifier{} +@end + +#pragma mark CDSoundSourcePanner + +/** Panner for CDSoundSource objects */ +@interface CDSoundSourcePanner : CDPropertyModifier{} +@end + +#pragma mark CDSoundSourcePitchBender + +/** Pitch bender for CDSoundSource objects */ +@interface CDSoundSourcePitchBender : CDPropertyModifier{} +@end + +#pragma mark CDSoundEngineFader + +/** Fader for CDSoundEngine objects */ +@interface CDSoundEngineFader : CDPropertyModifier{} +@end + + + + -- cgit 1.4.1