source: svn/trunk/newcon3bcm2_21bu/dta/src/settop_api/bsettop_pcm.h

/***************************************************************************
 *     Copyright (c) 2003-2006, Broadcom Corporation
 *     All Rights Reserved
 *     Confidential Property of Broadcom Corporation
 *
 *  THIS SOFTWARE MAY ONLY BE USED SUBJECT TO AN EXECUTED SOFTWARE LICENSE
 *  AGREEMENT  BETWEEN THE USER AND BROADCOM.  YOU HAVE NO RIGHT TO USE OR
 *  EXPLOIT THIS MATERIAL EXCEPT SUBJECT TO THE TERMS OF SUCH AN AGREEMENT.
 *
 * $brcm_Workfile:  $
 * $brcm_Revision:  $
 * $brcm_Date: $
 *
 * Module Description:
 *
 * Revision History:
 *
 * $brcm_Log:  $
 *
 ***************************************************************************/
         
#ifndef BSETTOP_PCM_H__
#define BSETTOP_PCM_H__

#include "bsettop_types.h"

#ifdef __cplusplus
extern "C"
{
#endif

/*=***********************************
The PCM interface is used to write PCM data to a PCM playback
channel.

PCM playback can be used for sound effects or music (often with a
CPU-based decoder for formats like MP3).

The API is the minimal needed for streaming data. The BSEAV team also
provides a file-based API located in BSEAV/lib/pcmfile. The file-based
API includes WAV file support.
**************************************/

#define BPCM_PLAYBACK_CHANNELS   1

/*
Summary:
        PCM playback state enumerations.
Description:
        These are the different states that the PCM playback channels can be in.
*/
typedef enum pcm_play_state
{
    ePCM_PLAY_STATE_CLOSED,
    ePCM_PLAY_STATE_OPENED,
    ePCM_PLAY_STATE_STARTED,
    ePCM_PLAY_STATE_STOPPED,
} pcm_play_state_t;

/*
Summary:
        PCM playback handle returned by bpcm_play_open.
Description:
        The implementation of the handle is private.
*/
typedef struct bpcm_play *bpcm_play_t;
/*
Summary:
        PCM audio settings which are used in bpcm_play_settings and bpcm_record_settings.
Description:
        The total bitrate of the PCM stream is:
        bits_per_second = bits_per_sample * sample_rate * channels.
*/
typedef struct bpcm_settings {
        unsigned bits_per_sample;       /* Either 8 or 16 */
        unsigned sample_rate;   /* Samples per channel per second. Either 32000, 44100, 48000. */
        unsigned channels;              /* Either 1 (mono) or 2 (stereo) */
} bpcm_settings;

/*
Summary:
        PCM play settings passed to bpcm_play_start.
Description:
        Even though there is no more data than just bpcm_settings, we've added this
        to support future API extensions.
*/
typedef struct bpcm_play_settings {
        bpcm_settings pcm;      /* PCM format */
        bsettop_callback callback; /* This callback notifies the user that there is
                space available in the pcm playback buffer. The user may call bpcm_play_get_buffer
                but should not call bpcm_play_write_complete. After receiving a callback,
                no additional callback will be received until bpcm_play_write_complete
                is called. */
        void *callback_context; /* User defined context which is passed into the
                above callback function. */
} bpcm_play_settings;

/*
Summary:
        Open a PCM playback channel.

*/
        bpcm_play_t bpcm_play_open(
                bobject_t id                            /* id corresponds to the pcm playback channel. */
                );


/*
Summary:
        Close a PCM playback channel.
Description:
        Playback must already be stopped.
*/

        void bpcm_play_close(
                bpcm_play_t pcmplay
                );

/*
Summary:
        Start playing PCM audio.
*/

bresult bpcm_play_start(
        bpcm_play_t pcmplay,
        bdisplay_t display,                                     /* which output to play to */
        bpcm_play_settings *settings
        );

/*
Summary:
        Status information returned by bpcm_play_get_status
*/
typedef struct bpcm_play_status {
    unsigned int index; /* Which pcm playback channel is playing? */
        pcm_play_state_t state; /* The state of the pcm playback channel. */
        unsigned queued_bytes;  /* Number of bytes waiting to be played. */
        unsigned long fifo_size;                        /* Size in bytes of the pcm buffer */
        void *buffer_base;              /* Pointer to the base of the pcm buffer.
                                           This can be used for calculating your exact position
                                           in the buffer for alignment considerations. */
} bpcm_play_status;

/*
Summary:
        Get status information.
*/

bresult bpcm_play_get_status(
        bpcm_play_t pcmplay,
        bpcm_play_status *status 
        );

/**
Summary:
Get space available in the pcm playback buffer.

Description:
This is a non-destructive call. You can call it as many times as you want.
After writing data into the buffer, you should call bpcm_play_write_complete
to report how much of the buffer was used.  On loop around length will be limited
to the buffer size minus the write offset then the next call will return the delta
between the read and write pointers.
**/

bresult bpcm_play_get_buffer(
        bpcm_play_t pcmplay,
        void **data,
        size_t *length
        );

/**
Summary:
update the ringbuffer write offset

Description call to update the rinbuffer write offset.  On loop around
of the ringbuffer the amount_written should not extend past the end of buffer.
This matches the behaivior of bpcm_play_get_buffer.
**/

bresult bpcm_play_write_complete(
        bpcm_play_t pcmplay,
        size_t amount_written
        );

/*
Summary:
Stop PCM playback
*/
bresult bpcm_play_stop(
        bpcm_play_t pcmplay
        );

/*
Summary:
        Required to initialize the bpcm_settings structure.
*/
void bpcm_play_settings_init(
        bpcm_play_settings *settings,   /* [out] */
        bpcm_play_t pcmplay             /* required for possible resource-dependent defaults */
        );

#ifdef CONFIG_PCM_TEST
void bpcm_play_test();
#endif

#ifdef __cplusplus
}
#endif

#endif /* BSETTOP_PCM_H__ */