Changeset 518 for pjproject/trunk/pjmedia/include/pjmedia/sound.h

Timestamp:

Jun 18, 2006 2:02:36 AM (18 years ago)

Author:

bennylp

Message:

Updated doxygen documentation to all headers in PJMEDIA

File:

• pjproject/trunk/pjmedia/include/pjmedia/sound.h (modified) (2 diffs)

pjproject/trunk/pjmedia/include/pjmedia/sound.h

@@ -31 +31 @@
 
 /**
- * @defgroup PJMED_SND Sound device abstraction.
- * @ingroup PJMEDIA
+ * @defgroup PJMED_SND Sound Hardware Abstraction
+ * @ingroup PJMED_SND_PORT
+ * @brief PJMEDIA abstraction for sound device hardware
  * @{
+ *
+ * This section describes lower level abstraction for sound device
+ * hardware. Application normally uses the higher layer @ref
+ * PJMED_SND_PORT abstraction since it works seamlessly with 
+ * @ref PJMEDIA_PORT_CONCEPT.
+ *
+ * The sound hardware abstraction basically runs <b>asychronously</b>,
+ * and application must register callbacks to be called to receive/
+ * supply audio frames from/to the sound hardware.
+ *
+ * A full duplex sound stream (created with #pjmedia_snd_open()) 
+ * requires application to supply two callbacks:
+ *  - <b><tt>rec_cb</tt></b> callback to be called when it has finished
+ *    capturing one media frame, and 
+ *  - <b><tt>play_cb</tt></b> callback to be called when it needs media 
+ *    frame to be played to the sound playback hardware.
+ *
+ * Half duplex sound stream (created with #pjmedia_snd_open_rec() or
+ * #pjmedia_snd_open_player()) will only need one of the callback to
+ * be specified.
+ *
+ * After sound stream is created, application need to call
+ * #pjmedia_snd_stream_start() to start capturing/playing back media
+ * frames from/to the sound device.
  */
 
@@ -114 +139 @@
  * Create sound stream for both capturing audio and audio playback,  from the 
  * same device. This is the recommended way to create simultaneous recorder 
- * and player streams, because it should work on backends that does not allow
+ * and player streams (instead of creating separate capture and playback
+ * streams), because it works on backends that does not allow
  * a device to be opened more than once.
  *