Wiley.Games.on.Symbian.OS.A.Handbook.for.Mobile.Development.Apr.2008 (779888), страница 33
Текст из файла (страница 33)
The CMdaAudioOutputStream class contains methods to feed a running stream of audio datainto the DevSound interface to produce real-time audio output from thedevice. The observer mixin class to implement is MMdaAudioOutputStreamCallback.class CAudioDemo : public CActive , MMdaAudioOutputStreamCallback{public:virtual void MaoscOpenComplete(TInt aError);virtual void MaoscPlayComplete(TInt aError);virtual void MaoscBufferCopied(TInt aError, const TDesC8 &aBuffer);private:CMdaAudioOutputStream* iStreamUtil;};136ADDING AUDIO TO GAMES ON SYMBIAN OSConstruction is similar to the CMdaAudioPlayerUtility class.Priority and priority preference parameters are supplied to the NewL()factory method together with the observer.void CAudioDemo::ConstructL(){iStreamUtil = CMdaAudioOutputStream::NewL(*this, EMdaPriorityMax,EMdaPriorityPreferenceTime);}The stream has to be opened first using the Open() method prior tostarting streaming.
The TMdaPackage* parameter is not used in SymbianOS after v9.1, so passing NULL is okay.void CAudioDemo::OpenStreamL(){iStreamUtil->Open(NULL);...}Open() is asynchronous and it will complete by calling MaoscOpenComplete(). If the callback does not receive an error code, the streamis ready to use. The next step is to configure the stream for the specificdata format it will process.The SetDataTypeL() method sets up the data format. The definitions of the FourCC codes required for this function can be found inMmfFourCC.h. Not all formats are supported on all phones, so even ifthe platform SDK header file contains a FourCC code, it doesn’t meanall the phones using that platform version will support that particularformat. The DevSound API contains methods to query the list of formatssupported by a certain device (see section 4.3.4).The SetAudioPropertiesL() method has to be called to setthe sample rate and number of channels (mono/stereo) to complete thestream setup.
The TMdaAudioDataSettings enumeration in audio.hcontains the values that can be used as parameters to this method.void CAudioDemo::MaoscOpenComplete(TInt aError){if (aError == KErrNone){// setup the format of the stream dataTRAP(aError, iStreamUtil->SetDataTypeL(KMMFFourCCCodePCM16))if (aError == KErrNone){// setup the sample rate and number of channelsTRAP(aError, iStreamUtil->SetAudioPropertiesL(TMdaAudioDataSettings::ESampleRate8000Hz,TMdaAudioDataSettings::EChannelsMono));}}SOUND EFFECTS137if (aError != KErrNone){// Errors, handle here}}Using the stream to play audio data involves continuously feeding itwith data in the specified format.
The audio data should be packaged inan 8 bit descriptor and passed to the stream using WriteL() method.void CAudioDemo::PlayStreamL(){...iPlayBuffer = new (ELeave) TUint8[KPlayBufSize];TPtr8 playBuf(iPlayBuffer,KPlayBufSize);playBuf.Copy(iEffectBuffer,KEffectSize);iStreamUtil->WriteL(playBuf);...}Once WriteL() is called, the buffer will be copied to the internal DevSound buffer to be processed and played. After WriteL() returns, neitherthe buffered data nor the buffer itself should be modified. The frameworkwill call MaoscBufferCopied() when data copying finishes.void CAudioDemo::MaoscBufferCopied(TInt aError, const TDesC8 &aBuffer){...TPtr8 buf(const_cast<TUint8*>(aBuffer.Ptr()),KPlayBufSize);buf.Copy(iEffectBuffer2, KEffectSize2);iStreamUtil->WriteL(buf);...}This method has a buffer parameter that will actually be the bufferwritten to the stream when this callback is called.
This same buffershould be used to send more audio data to the stream by refilling it.The copied data will start playing when this callback is called (notimmediately, but after the buffers in lower levels of the audio systemare exhausted – which is practically very soon), and the stream refillingin MaoscBufferCopied() should be done as quickly as possible.Otherwise, the data in the copied buffer will run out, causing an underflowthat will automatically stop the streaming. The normal way to stopstreaming is by calling the Stop() method. The framework calls theMaoscPlayComplete() callback when streaming ends playing. If theerror code indicates an underflow but the end of the file has not beenreached, it is best to supply more data by calling WriteL() to fill thestream buffer again and continue streaming.138ADDING AUDIO TO GAMES ON SYMBIAN OSvoid CAudioDemo::MaoscPlayComplete(TInt aError){if (aError == KErrNone){// playback terminated normally after a call to Stop()}else if (aError == KErrUnderflow){// the end of the sound data has been reached or// data hasn’t been supplied to the stream fast enough}else{// Other errors, handle here}}The stream supports an internal queue, so that many buffers can bewritten to the stream at once.
They will be played one after another inthe order of queuing. Practically, only two buffers of sufficient size willbe enough to have seamless audio without pauses or clicks. While onebuffer is being played, the other can be filled, and this ‘double buffering’method will be enough to eliminate possible audio ‘flicker.’To implement a multi-channel audio engine using streaming, a doublebuffering stream should be created in a separate dedicated high-prioritythread and must be continuously filled with silence data (suitable for thedata format being used).
All the in-game sound effects should be preloadedinto the memory during audio engine initialization. The game engineshould process the game events and resolve which effect needs to be playedat a certain moment. The main event processing thread should pass theeffect ID to the software mixer thread, and the first MaoscBufferCopiedevent that runs should mix the effect data into the running stream.The fact that buffer copying is asynchronous and non-preemptivemeans the playing of effects will be delayed until the last copied buffercompletes playing. There is already an existing delay in the audio subsystem because of the DevSound and hardware buffers, and any extradelay might cause the game audio effects to become unresponsive.
It istherefore important to choose the right buffer size while implementingthe streaming audio engine.Some compressed formats require a fixed buffer size, but any buffersize is suitable for PCM format. Actually, mixing compressed audio datais more challenging and requires more processing power, so it is notfeasible to implement software mixers using compressed data formats formost types of games. PCM is the easiest to mix and fastest to process,because it is the raw format that most audio hardware uses.A basic example implementing a software mixer can be foundamong the example code provided on the website for this book, developer.symbian.com/gamesbook.SOUND EFFECTS1394.3.4 DevSound APIDevSound is the lowest level audio API available, but its implementationis hardware-dependent (that is, it differs from device to device) andis not available on all platforms.
Some platforms allow direct access toDevSound through the CMMFDevSound interface. The advantage of usingCMMFDevSound to implement an audio engine is that it will allow finergrained control on audio hardware than other classes and allow morecontrol over buffer management.The CMMFDevSound class contains methods to:• determine which formats a particular phone supports• initialize and configure devices• play raw audio data and tones.The observer mixin class to implement is MDevSoundObserver.class CAudioDemo : public CActive , MDevSoundObserver{public:virtual void InitializeComplete(TInt aError);virtual void ToneFinished(TInt aError);virtual void BufferToBeFilled(CMMFBuffer* aBuffer);virtual void PlayError(TInt aError);virtual void BufferToBeEmptied(CMMFBuffer* aBuffer);virtual void RecordError(TInt aError);virtual void ConvertError(TInt aError);virtual void DeviceMessage(TUid aMessageType, const TDesC8& aMsg);private:CMMFDevSound* iDevSound;};Construction is simple and requires no setup:void CAudioDemo::ConstructL(){iDevSound = CMMFDevSound::NewL(*this);}The object needs to be initialized prior to use after construction.The class supports some methods that query the hardware for supportedcapabilities.
These methods can be called after the object is constructed,but prior to its full initialization. This way, the client can query thehardware and select a supported setup to initialize the object with thecorrect audio settings.The Capabilities() method retrieves the supported audio settingsin a TMMFCapabilities object. The iEncoding, iChannels andiRate members of TMMFCapabilities are bit fields. They represent140ADDING AUDIO TO GAMES ON SYMBIAN OSthe supported options as set flags from the TMMFSoundEncoding,TMMFSampleRate and TMMFMonoStereo enumerations.
iBufferSize is the maximum size of the DevSound audio buffer. Another usefulmethod is GetSupportedInputDataTypesL(), which returns a listof FourCCs supported on the device for playback.The InitializeL() method initializes CMMFDevSound. The observer and the mode are passed in, together with the data type specifiedas a FourCC code. InitializeL() is asynchronous and needs to becalled from an active scheduler loop in a state machine fashion.void CAudioDemo::RunL(){// Initialize StateiDevSound->InitializeL(*this, KMMFFourCCCodePCM16, EMMFStatePlaying);}InitializeL() will complete by calling InitializeComplete(). The DevSound interface is ready for configuration atthis state.
SetConfigL() is called to configure the playback parameters by passing in a TMMFCapabilities object containing the desiredvalues. The playback parameters are sample rate, encoding, number ofchannels (mono or stereo), and buffer size.The buffer size is fixed for some codecs; so the size set here is‘preferred’ size. The bit field parameters should only contain one of theoptions the device supports. The encoding parameter should always beset to EMMFSoundEncoding16BitPCM, because this parameter is notused any more and the encoding is actually determined by the FourCCparameter passed to InitializeL().Buffer size is a trade-off between a game’s audio responsiveness andRAM usage; so calculating this value correctly according to the needs ofthe game is very important. Smaller buffer sizes give lower latency audiobut will be more susceptible to underflow as data needs to be suppliedmuch more frequently. Big buffers give more latency, but the stream willbe much more robust against underflow.For some devices, the buffer size set here determines the internal buffersize used by DevSound and setting this value properly is the only way toachieve low latency PCM playback on these devices.void CAudioDemo::InitializeComplete(TInt aError){if (aError == KErrNone){TMMFCapabilities caps;caps.iRate = EMMFSampleRate8000Hz;caps.iEncoding = EMMFSoundEncoding16BitPCM;caps.iChannels = EMMFMono;caps.iBufferSize = 0; // Use the default buffer sizeSOUND EFFECTS141iDevSound->SetConfigL(caps);}...}Calling PlayInitL() method starts playback.void CAudioDemo::PlaySoundL(){...iDevSound->PlayInitL();...}If there is any error during initialization, the framework calls thePlayError() function of the observer with the appropriate error code.Otherwise, the framework calls BufferToBeFilled() with a bufferreference.BufferToBeFilled() is similar to MaoscBufferCopied() ofCMdaAudioOutputStream.
The audio data to be played has to becopied to the passed CMMFBuffer buffer in this function. The differenceis that there is no automatic streaming, so the code has to call thePlayData() method explicitly to play the data copied into the buffer.The amount of data that should be copied to the returned buffer, or in otherwords the buffer size, is determined by a call to the RequestSize()function on the buffer.The framework will call BufferToBeFilled() again when one ofthe internal buffers becomes available after the call to PlayData(). Tofinish the buffer-filling callback loop, the last buffer to be sent to the audiodevice should be marked as the last one by calling SetLastBuffer()on the CMMFBuffer object.void CAudioDemo::BufferToBeFilled(CMMFBuffer* aBuffer){CMMFDataBuffer* ptrBuf = reinterpret_cast<CMMFDataBuffer*>(aBuffer);TInt playsize;if (iEffectSize – iEffectMixPoint > aBuffer->RequestSize()){playsize = aBuffer->RequestSize();}else{playsize = iEffectSize - iEffectMixPoint;ptrBuf->SetLastBuffer(ETrue);}ptrBuf->Data().Copy(iEffect + iEffectMixPoint, playsize);iEffectMixPoint += playsize;142ADDING AUDIO TO GAMES ON SYMBIAN OSiDevSound->PlayData();}An underflow condition will occur if PlayData() is not called soonenough after the BufferToBeFilled() callback.
![](https://s.studizba.com/z.php?f=/templates/si/i/noavatar.png&w=100&h=100&t=1"){kind=avatar}
