pdmaudioifs.h revision 0c64f283f499a1ec6e8861ea98e7f252284e8358
/** @file
* PDM - Pluggable Device Manager, audio interfaces.
*/
/*
* Copyright (C) 2006-2014 Oracle Corporation
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License (GPL) as published by the Free Software
* Foundation, in version 2 as it comes in the "COPYING" file of the
* VirtualBox OSE distribution. VirtualBox OSE is distributed in the
* hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
*
* The contents of this file may alternatively be used under the terms
* of the Common Development and Distribution License Version 1.0
* (CDDL) only, as it comes in the "COPYING.CDDL" file of the
* VirtualBox OSE distribution, in which case the provisions of the
* CDDL are applicable instead of those of the GPL.
*
* You may elect to license modified versions of this file under the
* terms and conditions of either the GPL or the CDDL or both.
*/
#ifndef ___VBox_vmm_pdmaudioifs_h
#define ___VBox_vmm_pdmaudioifs_h
typedef struct
{
int mute;
uint32_t r;
uint32_t l;
} volume_t;
#ifdef VBOX_WITH_PDM_AUDIO_DRIVER
typedef enum PDMAUDIOFMT
{
/** Hack to blow the type up to 32-bit. */
AUD_FMT_32BIT_HACK = 0x7fffffff
} PDMAUDIOFMT;
#endif
/**
* Function pointer for device emulation callback.
*/
/**
* Structure holding all necessary callback data to communicate
* with the sound device emulation, e.g. for reading or writing
* audio data.
*/
typedef struct PDMAUDIOCALLBACK
{
/** Callback function to use in the device emulation. */
/** Opaque pointer to context data given on callback
* creation. Set by the device emulation. */
void *pvContext;
/**
* Audio configuration of a certain backend.
*/
typedef struct PDMAUDIOBACKENDCFG
{
/**
* An audio sample. At the moment stereo (left + right channels) only.
* @todo Replace this with a more generic union
* which then also could handle 2.1 or 5.1 sound.
*/
typedef struct PDMAUDIOSAMPLE
{
typedef enum PDMAUDIOENDIANESS
{
/** The usual invalid endian. */
/** Little endian. */
/** Bit endian. */
/** Endianness doesn't have a meaning in the context. */
/** The end of the valid endian values (exclusive). */
/** Hack to blow the type up to 32-bit. */
PDMAUDIOENDIANESS_32BIT_HACK = 0x7fffffff
#ifdef VBOX_WITH_PDM_AUDIO_DRIVER
typedef struct PDMAUDIOSTREAMCFG
{
/** Frequency in Hertz (Hz). */
/** Number of channels (2 for stereo). */
/** Audio format. */
/** @todo Use RT_LE2H_*? */
#endif
#if defined(RT_LITTLE_ENDIAN)
#elif defined(RT_BIG_ENDIAN)
#else
# error "Port me!"
#endif
typedef enum
{
/** Hack to blow the type up to 32-bit. */
PDMAUDIOMIXERCTL_32BIT_HACK = 0x7fffffff
typedef enum
{
/** Hack to blow the type up to 32-bit. */
PDMAUDIORECSOURCE_32BIT_HACK = 0x7fffffff
/**
* Audio stream commands. Used in the audio connector
* as well as in the actual host backends.
*/
typedef enum PDMAUDIOSTREAMCMD
{
/** Unknown command, do not use. */
/** Enables the stream. */
/** Disables the stream. */
/** Hack to blow the type up to 32-bit. */
PDMAUDIOSTREAMCMD_32BIT_HACK = 0x7fffffff
/**
* for in or out directions.
*/
typedef struct PDMPCMPROPS
{
/** Sample width. Bits per sample. */
/** Signed or unsigned sample. */
bool fSigned;
/** Shift count used for faster calculation of various
* values, such as the alignment, bytes to samples and so on.
* Depends on number of stream channels and the stream format
* being used.
*
** @todo Use some RTAsmXXX functions instead?
*/
/** Number of audio channels. */
/** Alignment mask. */
/** Sample frequency in Hertz (Hz). */
/** Bandwidth (bytes/s). */
/** Whether the endianess is swapped or not. */
bool fSwapEndian;
} PDMPCMPROPS, *PPDMPCMPROPS;
/**
* Structure for holding rate processing information
* of a source + destination audio stream. This is needed
* because both streams can differ regarding their rates
* and therefore need to be treated accordingly.
*/
typedef struct PDMAUDIOSTRMRATE
{
/** Current (absolute) offset in the output
* (destination) stream. */
/** Increment for moving dstOffset for the
* destination stream. This is needed because the
* source <-> destination rate might be different. */
/** Current (absolute) offset in the input
* stream. */
/** Last processed sample of the input stream.
* Needed for interpolation. */
/**
* Note: All internal handling is done in samples,
* not in bytes!
*/
typedef uint32_t PDMAUDIOMIXBUFFMT;
typedef PDMAUDIOMIXBUFFMT *PPDMAUDIOMIXBUFFMT;
typedef struct PDMAUDIOMIXBUF *PPDMAUDIOMIXBUF;
typedef struct PDMAUDIOMIXBUF
{
/** Name of the buffer. */
char *pszName;
/** Sample buffer. */
/** Size of the sample buffer (in samples). */
* in the samples buffer. */
/** Total samples already mixed down to the
* parent buffer (if any). Always starting at
* the parent's offReadWrite position.
* Note: Count always is specified in parent samples,
* as the sample count can differ between parent
* and child. */
/** Pointer to parent buffer (if any). */
/** List of children mix buffers to keep
* in sync with (if being a parent buffer). */
/** Intermediate structure for buffer
* conversion tasks. */
/** This buffer's audio format. */
/**
* Ratio of the associated parent stream's frequency by this stream's
* frequency (1<<32), represented as a signed 64 bit integer.
*
* For example, if the parent stream has a frequency of 44 khZ, and this
* stream has a frequency of 11 kHz, the ration then would be
* (44/11 * (1 << 32)).
*
* Currently this does not get changed once assigned.
*/
/* For quickly converting samples <-> bytes and
* vice versa. */
/**
* Represents an audio input on the host of a certain
* backend (e.g. DirectSound, PulseAudio etc).
*
* One host audio input is assigned to exactly one parent
* guest input stream.
*/
struct PDMAUDIOGSTSTRMIN;
typedef PDMAUDIOGSTSTRMIN *PPDMAUDIOGSTSTRMIN;
typedef struct PDMAUDIOHSTSTRMIN
{
/** List node. */
/** PCM properties. */
/** Whether this input is enabled or not. */
bool fEnabled;
/** This stream's mixing buffer. */
/** Pointer to (parent) guest stream. */
/*
* Represents an audio output on the host through a certain
* backend (e.g. DirectSound, PulseAudio etc).
*
* One host audio output can have multiple (1:N) guest outputs
* assigned.
*/
typedef struct PDMAUDIOHSTSTRMOUT
{
/** List node. */
/** Stream properites. */
/** Enabled or disabled flag. */
bool fEnabled;
/** Whether this stream was marked as being disabled
* but there are still associated guest output streams
* which rely on its data. */
bool fPendingDisable;
/** This stream's mixing buffer. */
/** Associated guest output streams. */
/**
* Guest audio stream state.
*/
typedef struct PDMAUDIOGSTSTRMSTATE
{
/** Guest audio out stream active or not. */
bool fActive;
/** Guest audio output stream has some samples or not. */
bool fEmpty;
/** Set to @c true if this stream is muted, @c false if not. */
bool fMuted;
/** Name of this stream. */
char *pszName;
/** Left channel volume. */
/** Right channel volume. */
/**
* Represents an audio input from the guest (that is, from the
* emulated device, e.g. Intel HDA).
*
* Each guest input can have multiple host input streams.
*/
typedef struct PDMAUDIOGSTSTRMIN
{
/** Guest stream properites. */
/** Current stream state. */
/** This stream's mixing buffer. */
/** Pointer to associated host input stream. */
/**
* Callback set by the device emulation on creation.
* This function is used to mix the guest input samples into the target
* host input recording buffer. */
/**
* Represents an audio output from the guest (that is, from the
* emulated device, e.g. Intel HDA).
*
* Each guest output is assigned to a single host output.
*/
typedef struct PDMAUDIOGSTSTRMOUT
{
/** List node. */
/** Guest output stream properites. */
/** Current stream state. */
/** This stream's mixing buffer. */
/** Pointer to the associated host output stream. */
/**
* Callback set by the device emulation on creation.
* This function is used to tell the device emulation that we're ready to
* process new samples.
*/
#ifdef VBOX_WITH_PDM_AUDIO_DRIVER
/** Pointer to a audio connector interface. */
typedef struct PDMIAUDIOCONNECTOR *PPDMIAUDIOCONNECTOR;
/**
* Audio connector interface (up).
*/
typedef struct PDMIAUDIOCONNECTOR
{
/**
* Reads PCM audio data from the host (input).
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmIn Pointer to guest input stream to write to.
* @param pvBuf Where to store the read data.
* @param cbSize Number of bytes to read.
* @param pcbRead Bytes of audio data read. Optional.
*/
DECLR3CALLBACKMEMBER(int, pfnRead, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn, void *pvBuf, size_t cbSize, uint32_t *pcbRead));
/**
* Writes PCM audio data to the host (output).
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmOut Pointer to guest output stream to read from.
* @param pvBuf Audio data to be written.
* @param cbSize Number of bytes to be written.
* @param pcbWritten Bytes of audio data written. Optional.
*/
DECLR3CALLBACKMEMBER(int, pfnWrite, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut, const void *pvBuf, size_t cbSize, uint32_t *pcbWritten));
/**
* Checks whether the specified guest input stream is in a working state.
*
* @returns True if a host voice in is available, false if not.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmIn Pointer to guest input stream to check.
*/
DECLR3CALLBACKMEMBER(bool, pfnIsInputOK, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
/**
* Checks whether the specified guest output stream is in a working state.
*
* @returns True if a host voice out is available, false if not.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmOut Pointer to guest output stream to check.
*/
DECLR3CALLBACKMEMBER(bool, pfnIsOutputOK, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
/**
* Initializes the NULL audio driver as a fallback.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
*/
/**
* Sets the audio volume of a specific guest output stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmOut Pointer to guest output stream.
* @param fMute Whether to mute or not.
* @param uVolLeft Left audio stream volume.
* @param uVolRight Right audio stream volume.
*/
DECLR3CALLBACKMEMBER(int, pfnIsSetOutVolume, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut,
/**
* Sets the overall audio volume.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param fMute Whether to mute or not.
* @param uVolLeft Left audio stream volume.
* @param uVolRight Right audio stream volume.
*/
/**
* Enables a specific guest output stream and starts the audio device.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmOut Pointer to guest output stream.
* @param fEnable Whether to enable or disable the specified output stream.
*/
DECLR3CALLBACKMEMBER(int, pfnEnableOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut, bool fEnable));
/**
* Enables a specific guest input stream and starts the audio device.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmIn Pointer to guest input stream.
* @param fEnable Whether to enable or disable the specified input stream.
*/
DECLR3CALLBACKMEMBER(int, pfnEnableIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn, bool fEnable));
/**
* Closes a specific guest input stream.
*
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmIn Pointer to guest input stream.
*/
DECLR3CALLBACKMEMBER(void, pfnCloseIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
/**
* Closes a specific guest output stream.
*
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmOut Pointer to guest output stream.
*/
DECLR3CALLBACKMEMBER(void, pfnCloseOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
/**
* Opens an input audio channel.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pszName Name of the audio channel.
* @param enmRecSource Specifies the type of recording source to be opened.
* @param fnCallback Callback function to be assigned to this input stream.
* @param pvCallback Pointer to parameters assigned to the callback function.
* @param pCfg Pointer to PDMAUDIOSTREAMCFG to use.
* @param ppGstStrmIn Pointer where to return the guest guest input stream on success.
*/
/**
* Opens an output audio channel.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pszName Name of the audio channel.
* @param fnCallback Callback function to be assigned to this input stream.
* @param pvCallback Pointer to parameters assigned to the callback function.
* @param pCfg Pointer to PDMAUDIOSTREAMCFG to use.
* @param ppGstStrmOut Pointer where to return the guest guest input stream on success.
*/
/**
* Checks whether a specific guest input stream is active or not.
*
* @returns Whether the specified stream is active or not.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmIn Pointer to guest input stream.
*/
DECLR3CALLBACKMEMBER(bool, pfnIsActiveIn, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMIN pGstStrmIn));
/**
* Checks whether a specific guest output stream is active or not.
*
* @returns Whether the specified stream is active or not.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pGstStrmOut Pointer to guest output stream.
*/
DECLR3CALLBACKMEMBER(bool, pfnIsActiveOut, (PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOGSTSTRMOUT pGstStrmOut));
/** PDMIAUDIOCONNECTOR interface ID. */
#define PDMIAUDIOCONNECTOR_IID "a41ca770-ed07-4f57-a0a6-41377d9d484f"
/** Pointer to a host audio interface. */
typedef struct PDMIHOSTAUDIO *PPDMIHOSTAUDIO;
/**
* PDM host audio interface.
*/
typedef struct PDMIHOSTAUDIO
{
/**
* Initialize the host-specific audio device.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
*/
/**
* Initialize the host-specific audio device for input stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmIn Pointer to host input stream.
* @param pStreamCfg Pointer to stream configuration.
* @param enmRecSource Specifies the type of recording source to be initialized.
* @param pcSamples Returns how many samples the backend can handle. Optional.
*/
DECLR3CALLBACKMEMBER(int, pfnInitIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, PPDMAUDIOSTREAMCFG pStreamCfg, PDMAUDIORECSOURCE enmRecSource, uint32_t *pcSamples));
/**
* Initialize the host-specific output device for output stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmOut Pointer to host output stream.
* @param pStreamCfg Pointer to stream configuration.
* @param pcSamples Returns how many samples the backend can handle. Optional.
*/
DECLR3CALLBACKMEMBER(int, pfnInitOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, PPDMAUDIOSTREAMCFG pStreamCfg, uint32_t *pcSamples));
/**
* Control the host audio device for an input stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmOut Pointer to host output stream.
* @param enmStreamCmd The stream command to issue.
*/
DECLR3CALLBACKMEMBER(int, pfnControlOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, PDMAUDIOSTREAMCMD enmStreamCmd));
/**
* Control the host audio device for an output stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmOut Pointer to host output stream.
* @param enmStreamCmd The stream command to issue.
*/
DECLR3CALLBACKMEMBER(int, pfnControlIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, PDMAUDIOSTREAMCMD enmStreamCmd));
/**
* End the host audio input streamm.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmIn Pointer to host input stream.
*/
/**
* End the host output stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmOut Pointer to host output stream.
*/
DECLR3CALLBACKMEMBER(int, pfnFiniOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut));
/**
* Play audio out from stream buffer.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmOut Pointer to host output stream.
* @param pcSamplesPlayed Pointer to number of samples captured.
*/
DECLR3CALLBACKMEMBER(int, pfnPlayOut, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMOUT pHstStrmOut, uint32_t *pcSamplesPlayed));
/**
* Records audio to input stream.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pHstStrmIn Pointer to host input stream.
* @param pcSamplesCaptured Pointer to number of samples captured.
*/
DECLR3CALLBACKMEMBER(int, pfnCaptureIn, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOHSTSTRMIN pHstStrmIn, uint32_t *pcSamplesCaptured));
/**
* Gets the configuration from the host audio (backend) driver.
*
* @returns VBox status code.
* @param pInterface Pointer to the interface structure containing the called function pointer.
* @param pBackendCfg Pointer where to store the backend audio configuration to.
*/
DECLR3CALLBACKMEMBER(int, pfnGetConf, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDCFG pBackendCfg));
#define PDMIHOSTAUDIO_IID "39feea4f-c824-4197-bcff-7d4a6ede7420"
#endif /* VBOX_WITH_PDM_AUDIO_DRIVER */
#endif /* ___VBox_vmm_pdmaudioifs_h */