Changeset 68077 in vbox for trunk

Timestamp:

Jul 21, 2017 10:17:32 AM (7 years ago)

Author:

vboxsync

Message:

vmm/pdmaudioifs.h: Documentation.

File:

• trunk/include/VBox/vmm/pdmaudioifs.h (modified) (5 diffs)

trunk/include/VBox/vmm/pdmaudioifs.h

@@ -285 +285 @@
      *  interleaved / non-interleaved layouts. */
     PDMAUDIOSTREAMLAYOUT_COMPLEX,
-    /** Raw (pass through) data, with no data layout processing done. */
+    /** Raw (pass through) data, with no data layout processing done.
+     *
+     *  This means that this stream will operate on PDMAUDIOSAMPLE data
+     *  directly. Don't use this if you don't have to. */
     PDMAUDIOSTREAMLAYOUT_RAW,
     /** Hack to blow the type up to 32-bit. */
@@ -1177 +1180 @@
 
     /**
-     * Returns the number of bytes which are readable from the audio (input) stream.
-     *
-     * @returns Number of readable bytes.
+     * Returns the amount which is readable from the audio (input) stream.
+     *
+     * @returns For non-raw layout streams: Number of readable bytes.
+     *          for raw layout streams    : Number of readable audio samples.
      * @param   pInterface          Pointer to the interface structure containing the called function pointer.
      * @param   pStream             Pointer to audio stream.
@@ -1186 +1190 @@
 
     /**
-     * Returns the number of bytes which are writable to the audio (output) stream.
-     *
-     * @returns Number of writable bytes.
+     * Returns the amount which is writable to the audio (output) stream.
+     *
+     * @returns For non-raw layout streams: Number of writable bytes.
+     *          for raw layout streams    : Number of writable audio samples.
      * @param   pInterface          Pointer to the interface structure containing the called function pointer.
      * @param   pStream             Pointer to audio stream.
@@ -1227 +1232 @@
      * @param   pStream             Pointer to audio stream.
      * @param   pvBuf               Pointer to audio data buffer to play.
-     * @param   cbBuf               Size (in bytes) of audio data buffer.
-     * @param   pcbWritten          Returns number of bytes written.  Optional.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, const void *pvBuf, uint32_t cbBuf, uint32_t *pcbWritten));
+     * @param   cxBuf               For non-raw layout streams: Size (in bytes) of audio data buffer,
+     *                              for raw layout streams    : Size (in audio samples) of audio data buffer.
+     * @param   pcxWritten          For non-raw layout streams: Returns number of bytes written.    Optional.
+     *                              for raw layout streams    : Returns number of samples written.  Optional.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnStreamPlay, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, const void *pvBuf, uint32_t cxBuf, uint32_t *pcxWritten));
 
     /**
@@ -1255 +1262 @@
      * @param   pStream             Pointer to audio stream.
      * @param   pvBuf               Buffer where to store read audio data.
-     * @param   cbBuf               Size (in bytes) of buffer.
-     * @param   pcbRead             Returns number of bytes read.  Optional.
-     */
-    DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, void *pvBuf, uint32_t cbBuf, uint32_t *pcbRead));
+     * @param   cxBuf               For non-raw layout streams: Size (in bytes) of audio data buffer,
+     *                              for raw layout streams    : Size (in audio samples) of audio data buffer.
+     * @param   pcxRead             For non-raw layout streams: Returns number of bytes read.    Optional.
+     *                              for raw layout streams    : Returns number of samples read.  Optional.
+     */
+    DECLR3CALLBACKMEMBER(int, pfnStreamCapture, (PPDMIHOSTAUDIO pInterface, PPDMAUDIOBACKENDSTREAM pStream, void *pvBuf, uint32_t cxBuf, uint32_t *pcxRead));
 
     /**