VirtualBox

Changeset 62605 in vbox for trunk/src


Ignore:
Timestamp:
Jul 27, 2016 4:31:50 PM (8 years ago)
Author:
vboxsync
Message:

Audio: Documentation, misc. cleanup.

Location:
trunk/src/VBox/Devices/Audio
Files:
7 edited

Legend:

Unmodified
Added
Removed

  • trunk/src/VBox/Devices/Audio/AudioMixer.cpp

    r62585 r62605  
    6161
    6262
     63/**
     64 * Creates an audio sink and attaches it to the given mixer.
     65 *
     66 * @returns IPRT status code.
     67 * @param   pMixer              Mixer to attach created sink to.
     68 * @param   pszName             Name of the sink to create.
     69 * @param   enmDir              Direction of the sink to create.
     70 * @param   ppSink              Pointer which returns the created sink on success.
     71 */
    6372int AudioMixerCreateSink(PAUDIOMIXER pMixer, const char *pszName, AUDMIXSINKDIR enmDir, PAUDMIXSINK *ppSink)
    6473{
    … …  
    110119}
    111120
    112 int AudioMixerCreate(const char *pszName, uint32_t uFlags, PAUDIOMIXER *ppMixer)
     121/**
     122 * Creates an audio mixer.
     123 *
     124 * @returns IPRT status code.
     125 * @param   pszName             Name of the audio mixer.
     126 * @param   fFlags              Creation flags. Not used at the moment and must be 0.
     127 * @param   ppMixer             Pointer which returns the created mixer object.
     128 */
     129int AudioMixerCreate(const char *pszName, uint32_t fFlags, PAUDIOMIXER *ppMixer)
    113130{
    114131    AssertPtrReturn(pszName, VERR_INVALID_POINTER);
    115     /** @todo Add flag validation. */
     132    /** @todo Add fFlags validation. */
    116133    AssertPtrReturn(ppMixer, VERR_INVALID_POINTER);
    117134
    … …  
    149166}
    150167
     168/**
     169 * Helper function for the internal debugger to print the mixer's current
     170 * state, along with the attached sinks.
     171 *
     172 * @param   pMixer              Mixer to print debug output for.
     173 * @param   pHlp                Debug info helper to use.
     174 * @param   pszArgs             Optional arguments. Not being used at the moment.
     175 */
    151176void AudioMixerDebug(PAUDIOMIXER pMixer, PCDBGFINFOHLP pHlp, const char *pszArgs)
    152177{
    … …  
    165190}
    166191
     192/**
     193 * Destroys an audio mixer.
     194 *
     195 * @param   pMixer              Audio mixer to destroy.
     196 */
    167197void AudioMixerDestroy(PAUDIOMIXER pMixer)
    168198{
    … …  
    195225}
    196226
    197 int AudioMixerGetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg)
    198 {
    199     AssertPtrReturn(pMixer, VERR_INVALID_POINTER);
    200     AssertPtrReturn(pCfg,   VERR_INVALID_POINTER);
    201 
    202     /** @todo Perform a deep copy, if needed. */
    203     *pCfg = pMixer->devFmt;
    204 
    205     return VINF_SUCCESS;
    206 }
    207 
     227/**
     228 * Invalidates all internal data, internal version.
     229 *
     230 * @returns IPRT status code.
     231 * @param   pMixer              Mixer to invalidate data for.
     232 */
    208233int audioMixerInvalidateInternal(PAUDIOMIXER pMixer)
    209234{
    … …  
    223248}
    224249
     250/**
     251 * Invalidates all internal data.
     252 *
     253 * @returns IPRT status code.
     254 * @param   pMixer              Mixer to invalidate data for.
     255 */
    225256void AudioMixerInvalidate(PAUDIOMIXER pMixer)
    226257{
    … …  
    233264}
    234265
     266/**
     267 * Removes a formerly attached audio sink for an audio mixer, internal version.
     268 *
     269 * @returns IPRT status code.
     270 * @param   pMixer              Mixer to remove sink from.
     271 * @param   pSink               Sink to remove.
     272 */
    235273static int audioMixerRemoveSinkInternal(PAUDIOMIXER pMixer, PAUDMIXSINK pSink)
    236274{
    … …  
    256294}
    257295
     296/**
     297 * Removes a formerly attached audio sink for an audio mixer.
     298 *
     299 * @returns IPRT status code.
     300 * @param   pMixer              Mixer to remove sink from.
     301 * @param   pSink               Sink to remove.
     302 */
     303
    258304void AudioMixerRemoveSink(PAUDIOMIXER pMixer, PAUDMIXSINK pSink)
    259305{
    260306    audioMixerSinkRemoveAllStreamsInternal(pSink);
    261307    audioMixerRemoveSinkInternal(pMixer, pSink);
    262 }
    263 
    264 int AudioMixerSetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg)
    265 {
    266     AssertPtrReturn(pMixer, VERR_INVALID_POINTER);
    267     AssertPtrReturn(pCfg, VERR_INVALID_POINTER);
    268 
    269     /** @todo Perform a deep copy, if needed. */
    270     pMixer->devFmt = *pCfg;
    271 
    272     return VINF_SUCCESS;
    273308}
    274309
    … …  
    298333 ********************************************************************************************************************************/
    299334
     335/**
     336 * Adds an audio stream to a specific audio sink.
     337 *
     338 * @returns IPRT status code.
     339 * @param   pSink               Sink to add audio stream to.
     340 * @param   pStream             Stream to add.
     341 */
    300342int AudioMixerSinkAddStream(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream)
    301343{
    … …  
    384426}
    385427
     428/**
     429 * Creates an audio mixer stream.
     430 *
     431 * @returns IPRT status code.
     432 * @param   pSink               Sink to use for creating the stream.
     433 * @param   pConn               Audio connector interface to use.
     434 * @param   pCfg                Audio stream configuration to use.
     435 * @param   fFlags              Stream creation flags. Currently unused, set to 0.
     436 * @param   ppStream            Pointer which receives the the newly created audio stream.
     437 */
    386438int AudioMixerSinkCreateStream(PAUDMIXSINK pSink,
    387439                               PPDMIAUDIOCONNECTOR pConn, PPDMAUDIOSTREAMCFG pCfg, uint32_t fFlags, PAUDMIXSTREAM *ppStream)
    … …  
    465517}
    466518
     519/**
     520 * Static helper function to translate a sink command
     521 * to a PDM audio stream command.
     522 *
     523 * @returns PDM audio stream command, or PDMAUDIOSTREAMCMD_UNKNOWN if not found.
     524 * @param   enmCmd              Mixer sink command to translate.
     525 */
    467526static PDMAUDIOSTREAMCMD audioMixerSinkToStreamCmd(AUDMIXSINKCMD enmCmd)
    468527{
    … …  
    480539}
    481540
     541/**
     542 * Controls a mixer sink.
     543 *
     544 * @returns IPRT status code.
     545 * @param   pSink               Mixer sink to control.
     546 * @param   enmSinkCmd          Sink command to set.
     547 */
    482548int AudioMixerSinkCtl(PAUDMIXSINK pSink, AUDMIXSINKCMD enmSinkCmd)
    483549{
    … …  
    518584}
    519585
     586/**
     587 * Destroys a mixer sink and removes it from the attached mixer (if any).
     588 *
     589 * @param   pSink               Mixer sink to destroy.
     590 */
    520591void AudioMixerSinkDestroy(PAUDMIXSINK pSink)
    521592{
    … …  
    538609}
    539610
     611/**
     612 * Destroys a mixer sink.
     613 *
     614 * @param   pSink               Mixer sink to destroy.
     615 */
    540616static void audioMixerSinkDestroyInternal(PAUDMIXSINK pSink)
    541617{
    … …  
    570646 *
    571647 * @returns Amount of bytes ready to be read from the sink.
    572  * @param   pSink           Sink to return number of available samples for.
     648 * @param   pSink               Sink to return number of available samples for.
    573649 */
    574650uint32_t AudioMixerSinkGetReadable(PAUDMIXSINK pSink)
    … …  
    591667 *
    592668 * @returns Amount of bytes ready to be written to the sink.
    593  * @param   pSink           Sink to return number of available samples for.
     669 * @param   pSink               Sink to return number of available samples for.
    594670 */
    595671uint32_t AudioMixerSinkGetWritable(PAUDMIXSINK pSink)
    … …  
    611687 *
    612688 * @returns Mixing direction.
    613  * @param   pSink           Sink to return direction for.
    614  *
    615  * @remark
     689 * @param   pSink               Sink to return direction for.
    616690 */
    617691AUDMIXSINKDIR AudioMixerSinkGetDir(PAUDMIXSINK pSink)
    … …  
    621695}
    622696
     697/**
     698 * Returns a specific mixer stream from a sink, based on its index.
     699 *
     700 * @returns Mixer stream if found, or NULL if not found.
     701 * @param   pSink               Sink to retrieve mixer stream from.
     702 * @param   uIndex              Index of the mixer stream to return.
     703 */
    623704PAUDMIXSTREAM AudioMixerSinkGetStream(PAUDMIXSINK pSink, uint8_t uIndex)
    624705{
    … …  
    639720}
    640721
     722/**
     723 * Returns the current status of a mixer sink.
     724 *
     725 * @returns IPRT status code.
     726 * @param   pSink               Mixer sink to return status for.
     727 */
    641728AUDMIXSINKSTS AudioMixerSinkGetStatus(PAUDMIXSINK pSink)
    642729{
    … …  
    650737}
    651738
     739/**
     740 * Returns the number of attached mixer streams to a mixer sink.
     741 *
     742 * @returns IPRT status code.
     743 * @param   pSink               Mixer sink to return number for.
     744 */
    652745uint8_t AudioMixerSinkGetStreamCount(PAUDMIXSINK pSink)
    653746{
    … …  
    658751}
    659752
     753/**
     754 * Reads audio data from a mixer sink.
     755 *
     756 * @returns IPRT status code.
     757 * @param   pSink               Mixer sink to read data from.
     758 * @param   enmOp               Mixer operation to use for reading the data.
     759 * @param   pvBuf               Buffer where to store the read data.
     760 * @param   cbBuf               Buffer size (in bytes) where to store the data.
     761 * @param   pcbRead             Number of bytes read. Optional.
     762 */
    660763int AudioMixerSinkRead(PAUDMIXSINK pSink, AUDMIXOP enmOp, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead)
    661764{
    … …  
    744847}
    745848
     849/**
     850 * Removes a mixer stream from a mixer sink, internal version.
     851 *
     852 * @returns IPRT status code.
     853 * @param   pSink               Sink to remove mixer stream from.
     854 * @param   pStream             Stream to remove.
     855 */
    746856static int audioMixerSinkRemoveStreamInternal(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream)
    747857{
    … …  
    773883}
    774884
     885/**
     886 * Removes a mixer stream from a mixer sink.
     887 *
     888 * @param   pSink               Sink to remove mixer stream from.
     889 * @param   pStream             Stream to remove.
     890 */
    775891void AudioMixerSinkRemoveStream(PAUDMIXSINK pSink, PAUDMIXSTREAM pStream)
    776892{
    … …  
    851967}
    852968
     969/**
     970 * Sets the audio format of a mixer sink.
     971 *
     972 * @returns IPRT status code.
     973 * @param   pSink               Sink to set audio format for.
     974 * @param   pPCMProps           Audio format (PCM properties) to set.
     975 */
    853976int AudioMixerSinkSetFormat(PAUDMIXSINK pSink, PPDMPCMPROPS pPCMProps)
    854977{
    … …  
    9091032}
    9101033
     1034/**
     1035 * Updates a mixer sink, internal version.
     1036 *
     1037 * @returns IPRT status code.
     1038 * @param   pSink               Mixer sink to update.
     1039 */
    9111040static int audioMixerSinkUpdateInternal(PAUDMIXSINK pSink)
    9121041{
    … …  
    10531182}
    10541183
     1184/**
     1185 * Updates (invalidates) a mixer sink.
     1186 *
     1187 * @returns IPRT status code.
     1188 * @param   pSink               Mixer sink to update.
     1189 */
    10551190int AudioMixerSinkUpdate(PAUDMIXSINK pSink)
    10561191{
    … …  
    10691204}
    10701205
     1206/**
     1207 * Updates the (master) volume of a mixer sink.
     1208 *
     1209 * @returns IPRT status code.
     1210 * @param   pSink               Mixer sink to update volume for.
     1211 * @param   pVolMaster          Master volume to set.
     1212 */
    10711213static int audioMixerSinkUpdateVolume(PAUDMIXSINK pSink, const PPDMAUDIOVOLUME pVolMaster)
    10721214{
    … …  
    11031245}
    11041246
     1247/**
     1248 * Writes data to a mixer sink.
     1249 *
     1250 * @returns IPRT status code.
     1251 * @param   pSink               Sink to write data to.
     1252 * @param   enmOp               Mixer operation to use when writing data to the sink.
     1253 * @param   pvBuf               Buffer containing the audio data to write.
     1254 * @param   cbBuf               Size (in bytes) of the buffer containing the audio data.
     1255 * @param   pcbWritten          Number of bytes written. Optional.
     1256 */
    11051257int AudioMixerSinkWrite(PAUDMIXSINK pSink, AUDMIXOP enmOp, const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten)
    11061258{
    … …  
    11581310 ********************************************************************************************************************************/
    11591311
     1312/**
     1313 * Controls a mixer stream.
     1314 *
     1315 * @returns IPRT status code.
     1316 * @param   pMixStream          Mixer stream to control.
     1317 * @param   enmCmd              Mixer stream command to use.
     1318 * @param   fCtl                Additional control flags. Pass 0.
     1319 */
    11601320int AudioMixerStreamCtl(PAUDMIXSTREAM pMixStream, PDMAUDIOSTREAMCMD enmCmd, uint32_t fCtl)
    11611321{
    … …  
    11681328}
    11691329
     1330/**
     1331 * Destroys a mixer stream, internal version.
     1332 *
     1333 * @param   pMixStream          Mixer stream to destroy.
     1334 */
    11701335static void audioMixerStreamDestroyInternal(PAUDMIXSTREAM pMixStream)
    11711336{
    … …  
    11971362}
    11981363
     1364/**
     1365 * Destroys a mixer stream.
     1366 *
     1367 * @param   pMixStream          Mixer stream to destroy.
     1368 */
    11991369void AudioMixerStreamDestroy(PAUDMIXSTREAM pMixStream)
    12001370{
    … …  
    12281398}
    12291399
     1400/**
     1401 * Returns whether a mixer stream currently is active (playing/recording) or not.
     1402 *
     1403 * @returns @true if playing/recording, @false if not.
     1404 * @param   pMixStream          Mixer stream to return status for.
     1405 */
    12301406bool AudioMixerStreamIsActive(PAUDMIXSTREAM pMixStream)
    12311407{
    … …  
    12371413}
    12381414
     1415/**
     1416 * Returns whether a mixer stream is valid (e.g. initialized and in a working state) or not.
     1417 *
     1418 * @returns @true if valid, @false if not.
     1419 * @param   pMixStream          Mixer stream to return status for.
     1420 */
    12391421bool AudioMixerStreamIsValid(PAUDMIXSTREAM pMixStream)
    12401422{

  • trunk/src/VBox/Devices/Audio/AudioMixer.h

    r62366 r62605  
    197197    /** Invalid operation, do not use. */
    198198    AUDMIXOP_INVALID = 0,
     199    /** Copy data from A to B, overwriting data in B. */
    199200    AUDMIXOP_COPY,
     201    /** Blend data from A with (existing) data in B. */
    200202    AUDMIXOP_BLEND,
    201203    /** The usual 32-bit hack. */
    … …  
    209211int AudioMixerCreateSink(PAUDIOMIXER pMixer, const char *pszName, AUDMIXSINKDIR enmDir, PAUDMIXSINK *ppSink);
    210212void AudioMixerDestroy(PAUDIOMIXER pMixer);
    211 int AudioMixerGetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg);
    212213void AudioMixerInvalidate(PAUDIOMIXER pMixer);
    213214void AudioMixerRemoveSink(PAUDIOMIXER pMixer, PAUDMIXSINK pSink);
    214 int AudioMixerSetDeviceFormat(PAUDIOMIXER pMixer, PPDMAUDIOSTREAMCFG pCfg);
    215215int AudioMixerSetMasterVolume(PAUDIOMIXER pMixer, PPDMAUDIOVOLUME pVol);
    216216void AudioMixerDebug(PAUDIOMIXER pMixer, PCDBGFINFOHLP pHlp, const char *pszArgs);

  • trunk/src/VBox/Devices/Audio/DevIchAc97.cpp

    r62463 r62605  
    24322432             */
    24332433            if (pDrv->uLUN == 0)
    2434                 pDrv->Flags |= PDMAUDIODRVFLAG_PRIMARY;
     2434                pDrv->Flags |= PDMAUDIODRVFLAGS_PRIMARY;
    24352435
    24362436            LogFunc(("LUN#%RU8: pCon=%p, drvFlags=0x%x\n", uLUN, pDrv->pConnector, pDrv->Flags));
    … …  
    26932693        if (RT_SUCCESS(rc))
    26942694        {
    2695             /* Set a default audio format for our mixer. */
    2696             PDMAUDIOSTREAMCFG streamCfg;
    2697             streamCfg.uHz           = 44100;
    2698             streamCfg.cChannels     = 2;
    2699             streamCfg.enmFormat     = PDMAUDIOFMT_S16;
    2700             streamCfg.enmEndianness = PDMAUDIOHOSTENDIANNESS;
    2701 
    2702             rc = AudioMixerSetDeviceFormat(pThis->pMixer, &streamCfg);
    2703             AssertRC(rc);
    2704 
    27052695            /* Add all required audio sinks. */
    27062696            int rc2 = AudioMixerCreateSink(pThis->pMixer, "[Playback] PCM Output", AUDMIXSINKDIR_OUTPUT, &pThis->pSinkOutput);
    … …  
    27282718             * might not worth showing an own error message box in the GUI.
    27292719             */
    2730             if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
     2720            if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
    27312721                continue;
    27322722
    … …  
    28472837            /* Only register primary driver.
    28482838             * The device emulation does the output multiplexing then. */
    2849             if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
     2839            if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
    28502840                continue;
    28512841

  • trunk/src/VBox/Devices/Audio/DevIchHda.cpp

    r62463 r62605  
    28562856
    28572857            if (   RT_FAILURE(rc2)
    2858                 && (pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY)) /* We only care about primary drivers here, the rest may fail. */
     2858                && (pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY)) /* We only care about primary drivers here, the rest may fail. */
    28592859            {
    28602860                if (RT_SUCCESS(rc))
    … …  
    56005600             */
    56015601            if (pDrv->uLUN == 0)
    5602                 pDrv->Flags |= PDMAUDIODRVFLAG_PRIMARY;
     5602                pDrv->Flags |= PDMAUDIODRVFLAGS_PRIMARY;
    56035603
    56045604            LogFunc(("LUN#%u: pCon=%p, drvFlags=0x%x\n", uLUN, pDrv->pConnector, pDrv->Flags));
    … …  
    59165916        if (RT_SUCCESS(rc))
    59175917        {
    5918             /* Set a default audio format for our mixer. */
    5919             PDMAUDIOSTREAMCFG streamCfg;
    5920             streamCfg.uHz           = 44100;
    5921             streamCfg.cChannels     = 2;
    5922             streamCfg.enmFormat     = PDMAUDIOFMT_S16;
    5923             streamCfg.enmEndianness = PDMAUDIOHOSTENDIANNESS;
    5924 
    5925             rc = AudioMixerSetDeviceFormat(pThis->pMixer, &streamCfg);
    5926             AssertRC(rc);
    5927 
    59285918            /*
    59295919             * Add mixer output sinks.
    … …  
    60126002             * might not worth showing an own error message box in the GUI.
    60136003             */
    6014             if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
     6004            if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
    60156005                continue;
    60166006
    … …  
    62216211            /* Only register primary driver.
    62226212             * The device emulation does the output multiplexing then. */
    6223             if (pDrv->Flags != PDMAUDIODRVFLAG_PRIMARY)
     6213            if (pDrv->Flags != PDMAUDIODRVFLAGS_PRIMARY)
    62246214                continue;
    62256215

  • trunk/src/VBox/Devices/Audio/DevSB16.cpp

    r62350 r62605  
    258258             */
    259259            if (pDrv->uLUN == 0)
    260                 pDrv->Flags |= PDMAUDIODRVFLAG_PRIMARY;
     260                pDrv->Flags |= PDMAUDIODRVFLAGS_PRIMARY;
    261261
    262262            LogFunc(("LUN#%RU8: pCon=%p, drvFlags=0x%x\n", uLUN, pDrv->pConnector, pDrv->Flags));
    … …  
    18511851            }
    18521852
    1853             if (pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY)
     1853            if (pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY)
    18541854            {
    18551855                /* Only do the next DMA transfer if we're able to write the entire
    … …  
    24212421         * might not worth showing an own error message box in the GUI.
    24222422         */
    2423         if (!(pDrv->Flags & PDMAUDIODRVFLAG_PRIMARY))
     2423        if (!(pDrv->Flags & PDMAUDIODRVFLAGS_PRIMARY))
    24242424            continue;
    24252425
    … …  
    24682468            /* Only register primary driver.
    24692469             * The device emulation does the output multiplexing then. */
    2470             if (pDrv->Flags != PDMAUDIODRVFLAG_PRIMARY)
     2470            if (pDrv->Flags != PDMAUDIODRVFLAGS_PRIMARY)
    24712471                continue;
    24722472

  • trunk/src/VBox/Devices/Audio/DrvAudio.cpp

    r62590 r62605  
    246246#endif /* !VBOX_AUDIO_TESTCASE */
    247247
    248 static DECLCALLBACK(int) drvAudioStreamControl(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
     248/**
     249 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamControl}
     250 */
     251static DECLCALLBACK(int) drvAudioStreamControl(PPDMIAUDIOCONNECTOR pInterface,
     252                                               PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
    249253{
    250254    AssertPtrReturn(pInterface, VERR_INVALID_POINTER);
    … …  
    270274}
    271275
     276/**
     277 * Controls an audio stream.
     278 *
     279 * @returns IPRT status code.
     280 * @param   pThis               Pointer to driver instance.
     281 * @param   pStream             Stream to control.
     282 * @param   enmStreamCmd        Control command.
     283 */
    272284static int drvAudioStreamControlInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
    273285{
    … …  
    363375}
    364376
     377/**
     378 * Controls a stream's backend.
     379 * If the stream has no backend available, VERR_NOT_FOUND is returned.
     380 *
     381 * @returns IPRT status code.
     382 * @param   pThis               Pointer to driver instance.
     383 * @param   pStream             Stream to control.
     384 * @param   enmStreamCmd        Control command.
     385 */
    365386static int drvAudioStreamControlInternalBackend(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream, PDMAUDIOSTREAMCMD enmStreamCmd)
    366387{
    … …  
    369390
    370391    PPDMAUDIOSTREAM pHstStream = drvAudioGetHostStream(pStream);
    371     AssertPtr(pHstStream);
     392    if (!pHstStream) /* Stream does not have a host backend? Bail out. */
     393        return VERR_NOT_FOUND;
    372394
    373395    LogFlowFunc(("[%s] enmStreamCmd=%RU32, fStatus=0x%x\n", pHstStream->szName, enmStreamCmd, pHstStream->fStatus));
    … …  
    375397    AssertPtr(pThis->pHostDrvAudio);
    376398
    377     int rc = VINF_SUCCESS;
    378 
    379     if (RT_SUCCESS(rc))
    380     {
    381         switch (enmStreamCmd)
    382         {
    383             case PDMAUDIOSTREAMCMD_ENABLE:
    384             {
    385                 if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
     399    int rc;
     400
     401    switch (enmStreamCmd)
     402    {
     403        case PDMAUDIOSTREAMCMD_ENABLE:
     404        {
     405            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
     406            {
     407                LogRel2(("Audio: Enabling stream '%s'\n", pHstStream->szName));
     408                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_ENABLE);
     409                if (RT_SUCCESS(rc))
    386410                {
    387                     LogRel2(("Audio: Enabling stream '%s'\n", pHstStream->szName));
    388                     rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_ENABLE);
    389                     if (RT_SUCCESS(rc))
    390                     {
    391                         pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_ENABLED;
    392                     }
    393                     else
    394                         LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     411                    pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_ENABLED;
    395412                }
     413                else
     414                    LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     415            }
     416            break;
     417        }
     418
     419        case PDMAUDIOSTREAMCMD_DISABLE:
     420        {
     421            if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED)
     422            {
     423                LogRel2(("Audio: Disabling stream '%s'\n", pHstStream->szName));
     424                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_DISABLE);
     425                if (RT_SUCCESS(rc))
     426                {
     427                    pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_ENABLED;
     428                    pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE;
     429                    AudioMixBufReset(&pHstStream->MixBuf);
     430                }
     431                else
     432                    LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     433            }
     434            break;
     435        }
     436
     437        case PDMAUDIOSTREAMCMD_PAUSE:
     438        {
     439            /* Only pause if the stream is enabled. */
     440            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
    396441                break;
    397             }
    398 
    399             case PDMAUDIOSTREAMCMD_DISABLE:
    400             {
    401                 if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED)
     442
     443            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED))
     444            {
     445                LogRel2(("Audio: Pausing stream '%s'\n", pHstStream->szName));
     446                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_PAUSE);
     447                if (RT_SUCCESS(rc))
    402448                {
    403                     LogRel2(("Audio: Disabling stream '%s'\n", pHstStream->szName));
    404                     rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_DISABLE);
    405                     if (RT_SUCCESS(rc))
    406                     {
    407                         pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_ENABLED;
    408                         pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PENDING_DISABLE;
    409                         AudioMixBufReset(&pHstStream->MixBuf);
    410                     }
    411                     else
    412                         LogRel2(("Audio: Disabling stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     449                    pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_PAUSED;
    413450                }
     451                else
     452                    LogRel2(("Audio: Pausing stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     453            }
     454            break;
     455        }
     456
     457        case PDMAUDIOSTREAMCMD_RESUME:
     458        {
     459            /* Only need to resume if the stream is enabled. */
     460            if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
    414461                break;
    415             }
    416 
    417             case PDMAUDIOSTREAMCMD_PAUSE:
    418             {
    419                 /* Only pause if the stream is enabled. */
    420                 if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
    421                     break;
    422 
    423                 if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED))
     462
     463            if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED)
     464            {
     465                LogRel2(("Audio: Resuming stream '%s'\n", pHstStream->szName));
     466                rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_RESUME);
     467                if (RT_SUCCESS(rc))
    424468                {
    425                     LogRel2(("Audio: Pausing stream '%s'\n", pHstStream->szName));
    426                     rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_PAUSE);
    427                     if (RT_SUCCESS(rc))
    428                     {
    429                         pHstStream->fStatus |= PDMAUDIOSTRMSTS_FLAG_PAUSED;
    430                     }
    431                     else
    432                         LogRel2(("Audio: Pausing stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     469                    pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PAUSED;
    433470                }
    434                 break;
    435             }
    436 
    437             case PDMAUDIOSTREAMCMD_RESUME:
    438             {
    439                 /* Only need to resume if the stream is enabled. */
    440                 if (!(pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_ENABLED))
    441                     break;
    442 
    443                 if (pHstStream->fStatus & PDMAUDIOSTRMSTS_FLAG_PAUSED)
    444                 {
    445                     LogRel2(("Audio: Resuming stream '%s'\n", pHstStream->szName));
    446                     rc = pThis->pHostDrvAudio->pfnStreamControl(pThis->pHostDrvAudio, pHstStream, PDMAUDIOSTREAMCMD_RESUME);
    447                     if (RT_SUCCESS(rc))
    448                     {
    449                         pHstStream->fStatus &= ~PDMAUDIOSTRMSTS_FLAG_PAUSED;
    450                     }
    451                     else
    452                         LogRel2(("Audio: Resuming stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
    453                 }
    454                 break;
    455             }
    456 
    457             default:
    458             {
    459                 AssertMsgFailed(("Command %RU32 not implemented\n", enmStreamCmd));
    460                 rc = VERR_NOT_IMPLEMENTED;
    461                 break;
    462             }
     471                else
     472                    LogRel2(("Audio: Resuming stream '%s' failed with %Rrc\n", pHstStream->szName, rc));
     473            }
     474            break;
     475        }
     476
     477        default:
     478        {
     479            AssertMsgFailed(("Command %RU32 not implemented\n", enmStreamCmd));
     480            rc = VERR_NOT_IMPLEMENTED;
     481            break;
    463482        }
    464483    }
    … …  
    470489}
    471490
     491/**
     492 * Initializes an audio stream with a given host and guest stream configuration.
     493 *
     494 * @returns IPRT status code.
     495 * @param   pThis               Pointer to driver instance.
     496 * @param   pStream             Stream to initialize.
     497 * @param   pCfgHost            Stream configuration to use for the host side (backend).
     498 * @param   pCfgGuest           Stream configuration to use for the guest side.
     499 */
    472500static int drvAudioStreamInitInternal(PDRVAUDIO pThis,
    473501                                      PPDMAUDIOSTREAM pStream, PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest)
    … …  
    592620}
    593621
     622/**
     623 * Re-initializes an audio stream with its existing host and guest stream configuration.
     624 *
     625 * @returns IPRT status code.
     626 * @param   pThis               Pointer to driver instance.
     627 * @param   pStream             Stream to re-initialize.
     628 */
    594629static int drvAudioStreamReInitInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream)
    595630{
    … …  
    657692
    658693/**
    659  * Writes VM audio output data from the guest stream into the host stream.
    660  * The attached host driver backend then will play out the audio in a
    661  * later step then.
    662  *
    663  * @return  IPRT status code.
    664  * @return  int
    665  * @param   pThis
    666  * @param   pGstStrmOut
    667  * @param   pvBuf
    668  * @param   cbBuf
    669  * @param   pcbWritten
     694 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamWrite}
    670695 */
    671696static DECLCALLBACK(int) drvAudioStreamWrite(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
    … …  
    759784}
    760785
     786/**
     787 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamAddRef}
     788 */
    761789static DECLCALLBACK(uint32_t) drvAudioStreamAddRef(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    762790{
    … …  
    769797}
    770798
     799/**
     800 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamRelease}
     801 */
    771802static DECLCALLBACK(uint32_t) drvAudioStreamRelease(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    772803{
    … …  
    782813}
    783814
     815/**
     816 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamIterate}
     817 */
    784818static DECLCALLBACK(int) drvAudioStreamIterate(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    785819{
    … …  
    806840}
    807841
     842/**
     843 * Does one iteration of an audio stream.
     844 * This function gives the backend the chance of iterating / altering data and
     845 * does the actual mixing between the guest <-> host mixing buffers.
     846 *
     847 * @returns IPRT status code.
     848 * @param   pThis               Pointer to driver instance.
     849 * @param   pStream             Stream to iterate.
     850 *
     851 * @remark
     852 */
    808853static int drvAudioStreamIterateInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream)
    809854{
    … …  
    856901        else if (pHstStream->enmDir == PDMAUDIODIR_OUT)
    857902        {
    858             uint32_t cSamplesLive = AudioMixBufLive(&pGstStream->MixBuf);
    859             if (!cSamplesLive) /* No live samples at the moment? */
    860             {
    861                 /* When playing samples, the host is the parent while the guest is the child.
    862                  * So try mixing not yet mixed guest-side samples to the host-side buffer. */
    863                 rc = AudioMixBufMixToParent(&pGstStream->MixBuf, AudioMixBufUsed(&pGstStream->MixBuf), &cSamplesMixed);
    864                 if (   RT_SUCCESS(rc)
    865                     && cSamplesMixed)
    866                 {
    867                     Log3Func(("[%s] %RU32 samples mixed\n", pHstStream->szName, cSamplesMixed));
    868                 }
    869 
    870                 if (RT_SUCCESS(rc))
    871                     cSamplesLive = AudioMixBufLive(&pGstStream->MixBuf);
    872             }
    873 
    874             Log3Func(("[%s] %RU32 live samples\n", pHstStream->szName, cSamplesLive));
    875 
    876             if (!cSamplesLive) /* No live samples (anymore)? */
     903            /* When playing samples, the host is the parent while the guest is the child.
     904             * So try mixing not yet mixed guest-side samples to the host-side buffer. */
     905            rc = AudioMixBufMixToParent(&pGstStream->MixBuf, AudioMixBufUsed(&pGstStream->MixBuf), &cSamplesMixed);
     906            if (   RT_SUCCESS(rc)
     907                && cSamplesMixed)
     908            {
     909                Log3Func(("[%s] %RU32 samples mixed, guest has %RU32 samples left (%RU32 live)\n",
     910                          pHstStream->szName, cSamplesMixed,
     911                          AudioMixBufUsed(&pGstStream->MixBuf), AudioMixBufLive(&pGstStream->MixBuf)));
     912            }
     913
     914            uint32_t cSamplesLeft = AudioMixBufUsed(&pGstStream->MixBuf);
     915            if (!cSamplesLeft) /* No samples (anymore)? */
    877916            {
    878917                fTryClosePending = true;
    … …  
    911950}
    912951
     952/**
     953 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamPlay}
     954 */
    913955static DECLCALLBACK(int) drvAudioStreamPlay(PPDMIAUDIOCONNECTOR pInterface,
    914956                                            PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesPlayed)
    … …  
    9911033                    STAM_COUNTER_ADD(&pHstStream->Out.StatSamplesPlayed, cSamplesPlayed);
    9921034#endif
     1035                    cSamplesLive = AudioMixBufLive(&pGstStream->MixBuf);
    9931036                }
    9941037            }
    995 
    996             Log3Func(("[%s] strmSts=0x%x, cSamplesPlayed=%RU32, rc=%Rrc\n", pHstStream->szName, strmSts, cSamplesPlayed, rc));
    9971038        }
    9981039
    … …  
    10321073}
    10331074
     1075/**
     1076 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamCapture}
     1077 */
    10341078static DECLCALLBACK(int) drvAudioStreamCapture(PPDMIAUDIOCONNECTOR pInterface,
    10351079                                               PPDMAUDIOSTREAM pStream, uint32_t *pcSamplesCaptured)
    … …  
    11201164
    11211165#ifdef VBOX_WITH_AUDIO_CALLBACKS
     1166/**
     1167 * Duplicates an audio callback.
     1168 *
     1169 * @returns Pointer to duplicated callback, or NULL on failure.
     1170 * @param   pCB                 Callback to duplicate.
     1171 */
    11221172static PPDMAUDIOCALLBACK drvAudioCallbackDuplicate(PPDMAUDIOCALLBACK pCB)
    11231173{
     1174    AssertPtrReturn(pCB, VERR_INVALID_POINTER);
     1175
    11241176    PPDMAUDIOCALLBACK pCBCopy = (PPDMAUDIOCALLBACK)RTMemDup((void *)pCB, sizeof(PDMAUDIOCALLBACK));
    11251177    if (!pCBCopy)
    … …  
    11411193}
    11421194
     1195/**
     1196 * Destroys a given callback.
     1197 *
     1198 * @param   pCB                 Callback to destroy.
     1199 */
    11431200static void drvAudioCallbackDestroy(PPDMAUDIOCALLBACK pCB)
    11441201{
    … …  
    11551212}
    11561213
     1214/**
     1215 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnRegisterCallbacks}
     1216 */
    11571217static DECLCALLBACK(int) drvAudioRegisterCallbacks(PPDMIAUDIOCONNECTOR pInterface,
    11581218                                                   PPDMAUDIOCALLBACK paCallbacks, size_t cCallbacks)
    … …  
    12021262}
    12031263
     1264/**
     1265 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnCallback}
     1266 */
    12041267static DECLCALLBACK(int) drvAudioCallback(PPDMIAUDIOCONNECTOR pInterface, PDMAUDIOCALLBACKTYPE enmType,
    12051268                                          void *pvUser, size_t cbUser)
    … …  
    13051368}
    13061369
     1370/**
     1371 * Handles state changes for all audio streams.
     1372 *
     1373 * @param   pDrvIns             Pointer to driver instance.
     1374 * @param   enmCmd              Stream command to set for all streams.
     1375 */
    13071376static void drvAudioStateHandler(PPDMDRVINS pDrvIns, PDMAUDIOSTREAMCMD enmCmd)
    13081377{
    … …  
    13201389}
    13211390
    1322 static DECLCALLBACK(int) drvAudioInit(PCFGMNODE pCfgHandle, PPDMDRVINS pDrvIns)
     1391/**
     1392 * Intializes an audio driver instance.
     1393 *
     1394 * @returns IPRT status code.
     1395 * @param   pDrvIns             Pointer to driver instance.
     1396 * @param   pCfgHandle          CFGM handle to use for configuration.
     1397 */
     1398static int drvAudioInit(PPDMDRVINS pDrvIns, PCFGMNODE pCfgHandle)
    13231399{
    13241400    AssertPtrReturn(pCfgHandle, VERR_INVALID_POINTER);
    … …  
    13421418}
    13431419
     1420/**
     1421 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamRead}
     1422 */
    13441423static DECLCALLBACK(int) drvAudioStreamRead(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream,
    13451424                                            void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead)
    … …  
    14321511}
    14331512
     1513/**
     1514 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamCreate}
     1515 */
    14341516static DECLCALLBACK(int) drvAudioStreamCreate(PPDMIAUDIOCONNECTOR pInterface,
    14351517                                              PPDMAUDIOSTREAMCFG pCfgHost, PPDMAUDIOSTREAMCFG pCfgGuest,
    … …  
    16061688}
    16071689
     1690/**
     1691 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnGetConfig}
     1692 */
    16081693static DECLCALLBACK(int) drvAudioGetConfig(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOBACKENDCFG pCfg)
    16091694{
    … …  
    16351720}
    16361721
     1722/**
     1723 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnGetStatus}
     1724 */
    16371725static DECLCALLBACK(PDMAUDIOBACKENDSTS) drvAudioGetStatus(PPDMIAUDIOCONNECTOR pInterface, PDMAUDIODIR enmDir)
    16381726{
    … …  
    16611749}
    16621750
     1751/**
     1752 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamGetReadable}
     1753 */
    16631754static DECLCALLBACK(uint32_t) drvAudioStreamGetReadable(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    16641755{
    … …  
    16881779        cReadable = AudioMixBufLive(&pGstStream->MixBuf);
    16891780
    1690     Log3Func(("[%s] cbReadable=%RU32\n", pHstStream->szName, cReadable));
     1781    Log3Func(("[%s] cbReadable=%RU32 (%zu bytes)\n", pHstStream->szName, cReadable,
     1782              AUDIOMIXBUF_S2B(&pGstStream->MixBuf, cReadable)));
    16911783
    16921784    rc2 = RTCritSectLeave(&pThis->CritSect);
    … …  
    16971789}
    16981790
     1791/**
     1792 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamGetWritable}
     1793 */
    16991794static DECLCALLBACK(uint32_t) drvAudioStreamGetWritable(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    17001795{
    … …  
    17151810        AssertRC(rc2);
    17161811
     1812        AssertMsgFailed(("Guest stream '%s' does not have a host stream attached\n", pStream->szName));
    17171813        return 0;
    17181814    }
    17191815
    17201816    PPDMAUDIOSTREAM pGstStream = pHstStream->pPair;
    1721 
    1722     uint32_t cWritable = 0;
    1723 
    1724     if (AudioMixBufLive(&pHstStream->MixBuf) == 0)
    1725         cWritable = AudioMixBufFreeBytes(&pGstStream->MixBuf);
    1726 
    1727     Log3Func(("[%s] cWritable=%RU32\n", pHstStream->szName, cWritable));
     1817    AssertPtr(pGstStream);
     1818
     1819    uint32_t cWritable = AudioMixBufFree(&pGstStream->MixBuf);
     1820
     1821    Log3Func(("[%s] cWritable=%RU32 (%zu bytes)\n", pHstStream->szName, cWritable,
     1822              AUDIOMIXBUF_S2B(&pGstStream->MixBuf, cWritable)));
    17281823
    17291824    rc2 = RTCritSectLeave(&pThis->CritSect);
    … …  
    17341829}
    17351830
     1831/**
     1832 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamGetStatus}
     1833 */
    17361834static DECLCALLBACK(PDMAUDIOSTRMSTS) drvAudioStreamGetStatus(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    17371835{
    … …  
    17611859}
    17621860
     1861/**
     1862 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamSetVolume}
     1863 */
    17631864static DECLCALLBACK(int) drvAudioStreamSetVolume(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream, PPDMAUDIOVOLUME pVol)
    17641865{
    … …  
    17791880}
    17801881
     1882/**
     1883 * @interface_method_impl{PDMIAUDIOCONNECTOR,pfnStreamDestroy}
     1884 */
    17811885static DECLCALLBACK(int) drvAudioStreamDestroy(PPDMIAUDIOCONNECTOR pInterface, PPDMAUDIOSTREAM pStream)
    17821886{
    … …  
    18551959}
    18561960
     1961/**
     1962 * Calls the backend to give it the chance to destroy its part of the audio stream.
     1963 *
     1964 * @returns IPRT status code.
     1965 * @param   pThis               Pointer to driver instance.
     1966 * @param   pHstStream          Host audio stream to call the backend destruction for.
     1967 */
    18571968static int drvAudioStreamDestroyInternalBackend(PDRVAUDIO pThis, PPDMAUDIOSTREAM pHstStream)
    18581969{
    … …  
    18811992}
    18821993
     1994/**
     1995 * Destroys an audio stream.
     1996 *
     1997 * @returns IPRT status code.
     1998 * @param   pThis               Pointer to driver instance.
     1999 * @param   pStream             Pointer to audio stream to destroy.
     2000 *                              That pointer will be invalid after successful destruction.
     2001 */
    18832002static int drvAudioStreamDestroyInternal(PDRVAUDIO pThis, PPDMAUDIOSTREAM pStream)
    18842003{
    … …  
    20682187    }
    20692188
    2070     rc = drvAudioInit(pCfgHandle, pDrvIns);
     2189    rc = drvAudioInit(pDrvIns, pCfgHandle);
    20712190    if (RT_SUCCESS(rc))
    20722191    {

  • trunk/src/VBox/Devices/Audio/DrvAudioCommon.cpp

    r62581 r62605  
    202202}
    203203
     204/**
     205 * Converts a recording source enumeration to a string.
     206 *
     207 * @returns Stringified recording source, or "Unknown", if not found.
     208 * @param   enmRecSrc           Recording source to convert.
     209 */
    204210const char *DrvAudioHlpRecSrcToStr(PDMAUDIORECSOURCE enmRecSrc)
    205211{
    … …  
    281287}
    282288
     289/**
     290 * Converts an audio format to a string.
     291 *
     292 * @returns Stringified audio format, or "Unknown", if not found.
     293 * @param   enmFmt              Audio format to convert.
     294 */
    283295const char *DrvAudioHlpAudFmtToStr(PDMAUDIOFMT enmFmt)
    284296{
    … …  
    308320
    309321    AssertMsgFailed(("Bogus audio format %ld\n", enmFmt));
    310     return "Invalid";
    311 }
    312 
     322    return "Unknown";
     323}
     324
     325/**
     326 * Converts a given string to an audio format.
     327 *
     328 * @returns Audio format for the given string, or PDMAUDIOFMT_INVALID if not found.
     329 * @param   pszFmt              String to convert to an audio format.
     330 */
    313331PDMAUDIOFMT DrvAudioHlpStrToAudFmt(const char *pszFmt)
    314332{
    … …  
    332350}
    333351
     352/**
     353 * Checks whether the given PCM properties are equal with the given
     354 * stream configuration.
     355 *
     356 * @returns @true if equal, @false if not.
     357 * @param   pProps              PCM properties to compare.
     358 * @param   pCfg                Stream configuration to compare.
     359 */
    334360bool DrvAudioHlpPCMPropsAreEqual(PPDMPCMPROPS pProps, PPDMAUDIOSTREAMCFG pCfg)
    335361{
    … …  
    372398}
    373399
     400/**
     401 * Checks whether two given PCM properties are equal.
     402 *
     403 * @returns @true if equal, @false if not.
     404 * @param   pProps1             First properties to compare.
     405 * @param   pProps2             Second properties to compare.
     406 */
    374407bool DrvAudioHlpPCMPropsAreEqual(PPDMPCMPROPS pProps1, PPDMPCMPROPS pProps2)
    375408{
    … …  
    377410    AssertPtrReturn(pProps2, false);
    378411
    379     if (pProps1 == pProps2)
     412    if (pProps1 == pProps2) /* If the pointers match, take a shortcut. */
    380413        return true;
    381414
    … …  
    408441}
    409442
     443/**
     444 * Checks whether a given stream configuration is valid or not.
     445 *
     446 * Returns @true if configuration is valid, @false if not.
     447 * @param   pCfg                Stream configuration to check.
     448 */
    410449bool DrvAudioHlpStreamCfgIsValid(PPDMAUDIOSTREAMCFG pCfg)
    411450{
    … …  
    500539}
    501540
     541/**
     542 * Prints an audio stream configuration to the debug log.
     543 *
     544 * @param   pCfg                Stream configuration to log.
     545 */
    502546void DrvAudioHlpStreamCfgPrint(PPDMAUDIOSTREAMCFG pCfg)
    503547{
    … …  
    546590}
    547591
     592/**
     593 * Calculates the audio bit rate of the given bits per sample, the Hz and the number
     594 * of audio channels.
     595 *
     596 * Divide the result by 8 to get the byte rate.
     597 *
     598 * @returns The calculated bit rate.
     599 * @param   cBits               Number of bits per sample.
     600 * @param   uHz                 Hz (Hertz) rate.
     601 * @param   cChannels           Number of audio channels.
     602 */
    548603uint32_t DrvAudioHlpCalcBitrate(uint8_t cBits, uint32_t uHz, uint8_t cChannels)
    549604{
    … …  
    551606}
    552607
     608/**
     609 * Calculates the audio bit rate out of a given audio stream configuration.
     610 *
     611 * Divide the result by 8 to get the byte rate.
     612 *
     613 * @returns The calculated bit rate.
     614 * @param   pCfg                Audio stream configuration to calculate bit rate for.
     615 *
     616 * @remark
     617 */
    553618uint32_t DrvAudioHlpCalcBitrate(PPDMAUDIOSTREAMCFG pCfg)
    554619{
    … …  
    663728}
    664729
     730/**
     731 * Opens or creates a wave (.WAV) file.
     732 *
     733 * @returns IPRT status code.
     734 * @param   pFile               Pointer to audio file handle to use.
     735 * @param   pszFile             File path of file to open or create.
     736 * @param   fOpen               Open flags.
     737 * @param   pProps              PCM properties to use.
     738 * @param   fFlags              Audio file flags.
     739 */
    665740int DrvAudioHlpWAVFileOpen(PPDMAUDIOFILE pFile, const char *pszFile, uint32_t fOpen, PPDMPCMPROPS pProps,
    666741                           PDMAUDIOFILEFLAGS fFlags)
    … …  
    729804}
    730805
     806/**
     807 * Closes a wave (.WAV) audio file.
     808 *
     809 * @returns IPRT status code.
     810 * @param   pFile               Audio file handle to close.
     811 */
    731812int DrvAudioHlpWAVFileClose(PPDMAUDIOFILE pFile)
    732813{
    … …  
    759840}
    760841
     842/**
     843 * Returns the raw PCM audio data size of a wave file.
     844 * This does *not* include file headers and other data which does
     845 * not belong to the actual PCM audio data.
     846 *
     847 * @returns Size (in bytes) of the raw PCM audio data.
     848 * @param   pFile               Audio file handle to retrieve the audio data size for.
     849 */
    761850size_t DrvAudioHlpWAVFileGetDataSize(PPDMAUDIOFILE pFile)
    762851{
    … …  
    771860}
    772861
     862/**
     863 * Write PCM data to a wave (.WAV) file.
     864 *
     865 * @returns IPRT status code.
     866 * @param   pFile               Audio file handle to write PCM data to.
     867 * @param   pvBuf               Audio data to write.
     868 * @param   cbBuf               Size (in bytes) of audio data to write.
     869 * @param   fFlags              Additional write flags. Not being used at the moment and must be 0.
     870 *
     871 * @remark
     872 */
    773873int DrvAudioHlpWAVFileWrite(PPDMAUDIOFILE pFile, const void *pvBuf, size_t cbBuf, uint32_t fFlags)
    774874{
    775875    AssertPtrReturn(pFile, VERR_INVALID_POINTER);
    776876    AssertPtrReturn(pvBuf, VERR_INVALID_POINTER);
    777     /** @todo Validate fFlags. */
     877
     878    AssertReturn(fFlags == 0, VERR_INVALID_PARAMETER); /** @todo fFlags are currently not implemented. */
    778879
    779880    Assert(pFile->enmType == PDMAUDIOFILETYPE_WAV);
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette