CascadeAudioPlaybackDevice.h

Go to the documentation of this file.

//
// CascadeAudioPlaybackDevice.h - header file for class CascadeAudioPlaybackDevice
//
// Copyright (c) 2003, Roku, LLC.  All rights reserved.
//

#ifndef _ROKU_INCLUDE_CASCADE_AV_CASCADEAUDIOPLAYBACKDEVICE_H
#define _ROKU_INCLUDE_CASCADE_AV_CASCADEAUDIOPLAYBACKDEVICE_H

#include <cascade/CascadeTypedefs.h>

class CascadeAudioPlaybackDevice
{
public:
        CascadeAudioPlaybackDevice() { }
        virtual ~CascadeAudioPlaybackDevice() { }
public:
    virtual bool GetBufferRequirements(u32 & nMinNumBuffersToSet, u32 & nMaxNumBuffersToSet, u32 & nMinBufferSizeToSet, u32 & nMaxBufferSizeToSet, u32 & nBufferSizeMultipleToSet) = 0;
        // GetBufferRequirements() sets the parameters passed in with the buffer requirements of the driver
        // These parameters are set as follows:
        //  nMinNumBuffersToSet       - the minimum number of buffers that can be queued by the driver
        //  nMaxNumBuffersToSet       - the maximum number of buffers that can be queued by the driver
        //  nMinBufferSizeToSet       - the minimum size of a buffer that can be queued by the driver
        //  nMaxBufferSizeToSet       - the maximum size of a buffer that can be queued by the driver
        //  nBufferSizeMultipleToSet  - buffer lengths must be a multiple of this number 
        // call GetBufferRequirements() before opening the driver so you know the legal parameters
        // for use with Open()
        virtual bool GetDefaultBufferRequirements(u32 & nNumBuffersToSet, u32 & nBufferSizeInBytesToSet) = 0;
           // Gets the default number of buffers and buffer size that the driver recommends
           // be passed into Open()
        virtual bool Open(u32 nNumBuffers, u32 nBufferSizeInBytes, void ** ppBufferLocationsToSet) = 0;
        // Open() opens the driver.
        // Call GetBufferRequirements() to determine the maximum number of buffers that can be used
        // and the buffer size multiple that must be used.
        // Set the parameters as follows:
        //  nNumBuffers            - the number of buffers you want for streaming.  This number MUST be
        //                           <= to the maximum number of buffers returned by GetBufferRequirements()
        //  nBufferSizeInBytes     - the size of each individual streaming buffer.  This size MUST
        //                           a multiple of the size multiple returned by GetBufferRequirements()
        //  ppBufferLocationsToSet - a pointer to an array of void pointers.  This array of void
        //                           pointers must have nNumBuffers elements.  The elements will
        //                           be filled with pointers to buffer memory allocated by the driver.
        virtual bool Close() = 0;
        // Close() closes the driver.  Any playing audio stops immediately -
        // all pending buffers are flushed.
        virtual bool QueueBuffer(s16 * pData, u32 nSamples) = 0;
        // QueueBuffer() is used to queue a buffer to the driver.
        // pData contains right and left interleaved 16 bit words of PCM audio data
        // nSamples is the number of samples of audio data contained in pData
        // Note: (nSamples * 2) is the byte size of the buffer
        virtual u32  WaitForBuffer() = 0;
        // WaitForBuffer() blocks the calling thread until at least 1
        // buffer is available for queueing by the driver.  WaitForBuffer()
        // returns the number of buffers available for queueing or 0, to indicate an
        // error.  When finished streaming, repeatedly call WaitForBuffer() until it returns
        // the same number of buffers you passed into the Open() call.  (This means all buffers
        // are available for queuing).  An easy way to do this is, for example:
        // while ((0 != WaitForBuffer()) && (nNumBuffers != WaitForBuffer()));
        // Contrast this with Flush() which immediately flushes all buffers without continuing
        // playback of queued buffers.  WaitForBuffer() will always return all buffers
        // if it is preceded by a call to Flush.
    virtual bool GetNumBuffersAvailable(u32 & nNumBuffersAvailableToSet) = 0;
        // GetNumBufferesAvailable() sets nNumBuffersAvailableToSet with the number of buffers currently
        // available for setting.  It is like WaitForBuffer() but doesn't ever wait.
        virtual bool Pause() = 0;
        // Pause() pauses the audio driver.
        // NOTE: if you Pause() the audio driver and then call WaitForBuffer()
        // you may block indefinitely (if all queued buffers are busy in the driver).
        virtual bool Play() = 0;
        // Play() resumes playback of the audio driver.  The audio driver is initialized
        // in Play() state so that playing starts as soon as buffers are queued.
        virtual bool Flush() = 0;
        // Flush() causes the driver to immediately dequeue all queued buffers.
        // After calling Flush() the state of the driver is the same as it was after
        // the driver was opened and before the first buffer was queued.
        virtual bool SetVolume(u16 nVolume) = 0;
        // call SetVolume() to set the output volume of audio playback.  Legal values for
        // volume are 0 - 0xFFFF which is a linear range of volume
        // where 0 is no volume and 0xFFFF is full volume.
        virtual bool SetSampleRate(u32 nSampleRate) = 0;
        // SetSampleRate() sets the sample rate of the samples that are passed in via
        // QueueBuffer().
        // nSampleRate is the sample rate in kHz.  For example a value of 44100 means 44.1kHZ.
        // The driver is initialized with a default value of 44100 o 44.1kHZ.
    virtual u32 GetSampleRate() = 0;
        // GetSampleRate() gets the sample rate.  The driver must be opened.  If not,
        // GetSampleRate() returns 0.
    virtual bool IsSupportedSampleRate(u32 nSampleRate) = 0;
        // IsSupportedSampleRate() returns true if nSampleRate is supported by the device,
        // false otherwise.
    virtual bool SetOutputFlags(bool bAnalog, bool bSPDIF) = 0;
        // SetOutputFlags() specifies which outputs the playback device should
        // direct playback to: analog, spdif, both, or none.
    virtual void GetOutputFlags(bool & bAnalogToSet, bool & bSPDIFToSet) = 0;
        // GetOutputFlags() sets bAnalogToSet and bSPDIFToSet with the current
        // values of the output flags.
public:
    static CascadeAudioPlaybackDevice * AcquireDefaultAudioPlaybackDevice();
        // AcquireDefaultAudioPlaybackDevice() returns the default CascadeAudioPlaybackDevice
        // for this system.  Only 1 client may acquire the default audio playback device
        // at a time.  If AcquireDefaultAudioPlaybackDevice() fails, NULL is returned.
    static void ReleaseDefaultAudioPlaybackDevice(CascadeAudioPlaybackDevice * pDevice);
        // call ReleaseDefaultAudioPlaybackDevice() when you are done with the device.
        // If the device is not closed when ReleaseDefaultAudioPlaybackDevice() is called,
        // it will be closed automatically.
};

#endif // #ifndef _ROKU_INCLUDE_CASCADE_AV_CASCADEAUDIOPLAYBACKDEVICE_H

//  LOG
//  08-Aug-03   dwoodward       created from AJW's CascadeDevAudioPlay class
//  09-Dec-03   dwoodward   added GetNumBuffersAvailable()
//  28-Mar-04   dwoodward   added IsSupportedSampleRate()
//  29-Sep-04   dwoodward   added SetOutputFlags() and GetOutputFlags()
//  23-Feb-05   dwoodward   added GetDefaultBufferRequirements(), AcquireDefaultAudioPlaybackDevice(), ReleaseDefaultAudioPlaybackDevice(),
//                          and modified parameters to GetBufferRequirements()
//  03-Mar-05   dwoodward   added GetSampleRate()

---