Changeset 87300 in vbox for trunk/src

Timestamp:

Jan 18, 2021 2:38:25 PM (4 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

142259

Message:

Audio/ALSA: Documentation.

File:

• trunk/src/VBox/Devices/Audio/DrvHostALSAAudio.cpp (modified) (19 diffs)

trunk/src/VBox/Devices/Audio/DrvHostALSAAudio.cpp

@@ -76 +76 @@
 *********************************************************************************************************************************/
 
+/**
+ * Structure for maintaining an ALSA audio stream.
+ */
 typedef struct ALSAAUDIOSTREAM
 {
     /** The stream's acquired configuration. */
     PPDMAUDIOSTREAMCFG pCfg;
-    union
-    {
-        struct
-        {
-        } In;
-        struct
-        {
-        } Out;
-    };
+    /** Pointer to allocated ALSA PCM configuration to use. */
     snd_pcm_t          *phPCM;
+    /** Scratch buffer. */
     void               *pvBuf;
+    /** Size (in bytes) of allocated scratch buffer. */
     size_t              cbBuf;
 } ALSAAUDIOSTREAM, *PALSAAUDIOSTREAM;
@@ -116 +113 @@
 #define ALSA_RECOVERY_TRIES_MAX    5
 
+/**
+ * Structure for maintaining an ALSA audio stream configuration.
+ */
 typedef struct ALSAAUDIOSTREAMCFG
 {
@@ -125 +125 @@
     /** Whether resampling should be performed by alsalib or not. */
     int                 resample;
+    /** Number of audio channels. */
     int                 nchannels;
     /** Buffer size (in audio frames). */
@@ -136 +137 @@
 
 
-
+/**
+ * Converts internal audio PCM properties to an ALSA PCM format.
+ *
+ * @returns Converted ALSA PCM format.
+ * @param   pProps              Internal audio PCM configuration to convert.
+ */
 static snd_pcm_format_t alsaAudioPropsToALSA(PPDMAUDIOPCMPROPS pProps)
 {
@@ -159 +165 @@
 
 
+/**
+ * Converts an ALSA PCM format to internal PCM properties.
+ *
+ * @returns VBox status code.
+ * @param   fmt                 ALSA PCM format to convert.
+ * @param   pProps              Where to store the converted PCM properties on success.
+ */
 static int alsaALSAToAudioProps(snd_pcm_format_t fmt, PPDMAUDIOPCMPROPS pProps)
 {
@@ -244 +257 @@
 
 
+/**
+ * Sets the software parameters of an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream to set software parameters for.
+ * @param   fIn                 Whether this is an input stream or not.
+ * @param   pCfgReq             Requested configuration to set.
+ * @param   pCfgObt             Obtained configuration on success. Might differ from requested configuration.
+ */
 static int alsaStreamSetSWParams(snd_pcm_t *phPCM, bool fIn, PALSAAUDIOSTREAMCFG pCfgReq, PALSAAUDIOSTREAMCFG pCfgObt)
 {
@@ -306 +328 @@
 
 
+/**
+ * Closes an ALSA stream
+ *
+ * @returns VBox status code.
+ * @param   pphPCM              ALSA stream to close.
+ */
 static int alsaStreamClose(snd_pcm_t **pphPCM)
 {
@@ -329 +357 @@
 
 
+/**
+ * Opens (creates) an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   fIn                 Whether this is an input stream to create or not.
+ * @param   pCfgReq             Requested configuration to create stream with.
+ * @param   pCfgObt             Obtained configuration the stream got created on success.
+ * @param   pphPCM              Where to store the ALSA stream handle on success.
+ */
 static int alsaStreamOpen(bool fIn, PALSAAUDIOSTREAMCFG pCfgReq, PALSAAUDIOSTREAMCFG pCfgObt, snd_pcm_t **pphPCM)
 {
@@ -523 +560 @@
 #endif
 
-
+/**
+ * Returns the available audio frames queued.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream handle.
+ * @param   pFramesAvail        Where to store the available frames.
+ */
 static int alsaStreamGetAvail(snd_pcm_t *phPCM, snd_pcm_sframes_t *pFramesAvail)
 {
@@ -556 +599 @@
 }
 
-
+/**
+ * Tries to recover an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream handle.
+ */
 static int alsaStreamRecover(snd_pcm_t *phPCM)
 {
@@ -571 +619 @@
 }
 
-
+/**
+ * Resumes an ALSA stream.
+ *
+ * @returns VBox status code.
+ * @param   phPCM               ALSA stream to resume.
+ */
 static int alsaStreamResume(snd_pcm_t *phPCM)
 {
@@ -585 +638 @@
     return VINF_SUCCESS;
 }
-
 
 /**
@@ -608 +660 @@
     return rc;
 }
-
 
 /**
@@ -870 +921 @@
 }
 
-
+/**
+ * Destroys an ALSA input stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA input stream to destroy.
+ */
 static int alsaDestroyStreamIn(PALSAAUDIOSTREAM pStreamALSA)
 {
@@ -884 +940 @@
 }
 
-
+/**
+ * Destroys an ALSA output stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA output stream to destroy.
+ */
 static int alsaDestroyStreamOut(PALSAAUDIOSTREAM pStreamALSA)
 {
@@ -898 +959 @@
 }
 
-
+/**
+ * Creates an ALSA output stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA output stream to create.
+ * @param   pCfgReq             Requested configuration to create stream with.
+ * @param   pCfgAcq             Obtained configuration the stream got created with on success.
+ */
 static int alsaCreateStreamOut(PALSAAUDIOSTREAM pStreamALSA, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq)
 {
@@ -951 +1019 @@
 }
 
-
+/**
+ * Creates an ALSA input stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA input stream to create.
+ * @param   pCfgReq             Requested configuration to create stream with.
+ * @param   pCfgAcq             Obtained configuration the stream got created with on success.
+ */
 static int alsaCreateStreamIn(PALSAAUDIOSTREAM pStreamALSA, PPDMAUDIOSTREAMCFG pCfgReq, PPDMAUDIOSTREAMCFG pCfgAcq)
 {
@@ -1004 +1079 @@
 }
 
-
+/**
+ * Controls an ALSA input stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA input stream to control.
+ * @param   enmStreamCmd        Stream command to issue.
+ */
 static int alsaControlStreamIn(PALSAAUDIOSTREAM pStreamALSA, PDMAUDIOSTREAMCMD enmStreamCmd)
 {
@@ -1069 +1150 @@
 }
 
-
+/**
+ * Controls an ALSA output stream.
+ *
+ * @returns VBox status code.
+ * @param   pStreamALSA         ALSA output stream to control.
+ * @param   enmStreamCmd        Stream command to issue.
+ */
 static int alsaControlStreamOut(PALSAAUDIOSTREAM pStreamALSA, PDMAUDIOSTREAMCMD enmStreamCmd)
 {