/*----------------------------------------------------------------------------
 *
 * File:
 * eas_pcm.h
 *
 * Contents and purpose:
 * External function prototypes for eas_pcm.c module
 *
 *
 * Copyright Sonic Network Inc. 2005

 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 *----------------------------------------------------------------------------
 * Revision Control:
 *   $Revision: 847 $
 *   $Date: 2007-08-27 21:30:08 -0700 (Mon, 27 Aug 2007) $
 *----------------------------------------------------------------------------
*/

#ifndef _EAS_PCM_H
#define _EAS_PCM_H

/* default gain setting - roughly unity gain */
#define PCM_DEFAULT_GAIN_SETTING    0x6000

typedef struct s_pcm_state_tag *EAS_PCM_HANDLE;
typedef void (*EAS_PCM_CALLBACK) (EAS_DATA_HANDLE pEASData, EAS_VOID_PTR cbInstData, EAS_PCM_HANDLE pcmHandle, EAS_STATE state);

/* parameters for EAS_PEOpenStream */
typedef struct s_pcm_open_params_tag
{
    EAS_FILE_HANDLE     fileHandle;
    EAS_I32             decoder;
    EAS_U32             sampleRate;
    EAS_I32             size;
    EAS_U32             loopStart;
    EAS_U32             loopSamples;
    EAS_I32             blockSize;
    EAS_U32             flags;
    EAS_U32             envData;
    EAS_I16             volume;
    EAS_PCM_CALLBACK    pCallbackFunc;
    EAS_VOID_PTR        cbInstData;
 } S_PCM_OPEN_PARAMS;

/*----------------------------------------------------------------------------
 * EAS_PEInit()
 *----------------------------------------------------------------------------
 * Purpose:
 * Initializes the PCM engine
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEInit (EAS_DATA_HANDLE pEASData);

/*----------------------------------------------------------------------------
 * EAS_PEShutdown()
 *----------------------------------------------------------------------------
 * Purpose:
 * Shuts down the PCM engine
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEShutdown (EAS_DATA_HANDLE pEASData);

/*----------------------------------------------------------------------------
 * EAS_PEOpenStream()
 *----------------------------------------------------------------------------
 * Purpose:
 * Starts up a PCM playback
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEOpenStream (EAS_DATA_HANDLE pEASData, S_PCM_OPEN_PARAMS *pParams, EAS_PCM_HANDLE *pHandle);

/*----------------------------------------------------------------------------
 * EAS_PEContinueStream()
 *----------------------------------------------------------------------------
 * Purpose:
 * Continues a PCM stream
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEContinueStream (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle, EAS_I32 size);

/*----------------------------------------------------------------------------
 * EAS_PEGetFileHandle()
 *----------------------------------------------------------------------------
 * Purpose:
 * Returns the file handle of a stream
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEGetFileHandle (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle, EAS_FILE_HANDLE *pFileHandle);

/*----------------------------------------------------------------------------
 * EAS_PERender()
 *----------------------------------------------------------------------------
 * Purpose:
 * Render a buffer of PCM audio
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PERender (EAS_DATA_HANDLE pEASData, EAS_I32 numSamples);

/*----------------------------------------------------------------------------
 * EAS_PEUpdateParams()
 *----------------------------------------------------------------------------
 * Purpose:
 * Update the pitch and volume parameters using MIDI controls
 *
 * Inputs:
 *
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEUpdateParams (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I16 pitch, EAS_I16 gainLeft, EAS_I16 gainRight);

/*----------------------------------------------------------------------------
 * EAS_PELocate()
 *----------------------------------------------------------------------------
 * Purpose:
 * This function seeks to the requested place in the file. Accuracy
 * is dependent on the sample rate and block size.
 *
 * Inputs:
 * pEASData         - pointer to overall EAS data structure
 * pState           - stream handle
 * time             - media time in milliseconds
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PELocate (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I32 time);

/*----------------------------------------------------------------------------
 * EAS_PEUpdateVolume()
 *----------------------------------------------------------------------------
 * Purpose:
 * Update the volume parameters for a PCM stream
 *
 * Inputs:
 * pEASData         - pointer to EAS library instance data
 * handle           - pointer to S_PCM_STATE for this stream
 * gainLeft         - linear gain multipler in 1.15 fraction format
 * gainRight        - linear gain multipler in 1.15 fraction format
 * initial          - initial settings, set current gain
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 * Notes
 * In mono mode, leftGain controls the output gain and rightGain is ignored
 *----------------------------------------------------------------------------
*/
/*lint -esym(715, pEASData) reserved for future use */
EAS_RESULT EAS_PEUpdateVolume (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I16 volume);

/*----------------------------------------------------------------------------
 * EAS_PEUpdatePitch()
 *----------------------------------------------------------------------------
 * Purpose:
 * Update the pitch parameter for a PCM stream
 *
 * Inputs:
 * pEASData         - pointer to EAS library instance data
 * pState           - pointer to S_PCM_STATE for this stream
 * pitch            - new pitch value in pitch cents
 *----------------------------------------------------------------------------
*/
/*lint -esym(715, pEASData) reserved for future use */
EAS_RESULT EAS_PEUpdatePitch (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE pState, EAS_I16 pitch);

/*----------------------------------------------------------------------------
 * EAS_PEState()
 *----------------------------------------------------------------------------
 * Purpose:
 * Returns the current state of the stream
 *
 * Inputs:
 * pEASData         - pointer to overall EAS data structure
 * handle           - pointer to file handle
 * pState           - pointer to variable to store state
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 * Notes:
 * This interface is also exposed in the internal library for use by the other modules.
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEState (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle, EAS_STATE *pState);

/*----------------------------------------------------------------------------
 * EAS_PEClose()
 *----------------------------------------------------------------------------
 * Purpose:
 * Close the file and clean up
 *
 * Inputs:
 * pEASData         - pointer to overall EAS data structure
 * handle           - pointer to file handle
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEClose (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);

/*----------------------------------------------------------------------------
 * EAS_PEReset()
 *----------------------------------------------------------------------------
 * Purpose:
 * Reset the sequencer. Used for locating backwards in the file.
 *
 * Inputs:
 * pEASData         - pointer to overall EAS data structure
 * handle           - pointer to file handle
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEReset (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);

/*----------------------------------------------------------------------------
 * EAS_PEPause()
 *----------------------------------------------------------------------------
 * Purpose:
 * Mute and pause rendering a PCM stream. Sets the gain target to zero and stops the playback
 * at the end of the next audio frame.
 *
 * Inputs:
 * pEASData         - pointer to EAS library instance data
 * handle           - pointer to S_PCM_STATE for this stream
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEPause (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);

/*----------------------------------------------------------------------------
 * EAS_PEResume()
 *----------------------------------------------------------------------------
 * Purpose:
 * Resume rendering a PCM stream. Sets the gain target back to its
 * previous setting and restarts playback at the end of the next audio
 * frame.
 *
 * Inputs:
 * pEASData         - pointer to EAS library instance data
 * handle           - pointer to S_PCM_STATE for this stream
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PEResume (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);

/*----------------------------------------------------------------------------
 * EAS_PERelease()
 *----------------------------------------------------------------------------
 * Purpose:
 * Put the PCM stream envelope into release.
 *
 * Inputs:
 * pEASData         - pointer to EAS library instance data
 * handle           - pointer to S_PCM_STATE for this stream
 *
 * Outputs:
 *
 *
 * Side Effects:
 *
 *----------------------------------------------------------------------------
*/
EAS_RESULT EAS_PERelease (EAS_DATA_HANDLE pEASData, EAS_PCM_HANDLE handle);

#endif /* end _EAS_PCM_H */