[doc] document C interface.

author: Stephen Sinclair <radarsat1@gmail.com> 2019-04-17 15:13:48 +0200
committer: Stephen Sinclair <radarsat1@gmail.com> 2019-04-17 15:13:56 +0200
commit: acb8458e225384abcf3511d81eca971702aded20 (patch)
tree: c761c360f86507ed1d00d969dc9450906494e240
parent: 6c585b5941945f9d6731dbd74902d146d32874c4 (diff)
3 files changed, 178 insertions, 25 deletions
diff --git a/doc/doxygen/Doxyfile.in b/doc/doxygen/Doxyfile.in
index e984531..e91b1f9 100644
--- a/doc/doxygen/Doxyfile.in
+++ b/doc/doxygen/Doxyfile.in
@@ -327,7 +327,7 @@ INLINE_GROUPED_CLASSES = NO
 # structs, classes, and unions are shown on a separate page (for HTML and Man 
 # pages) or section (for LaTeX and RTF).
 
-INLINE_SIMPLE_STRUCTS  = NO
+INLINE_SIMPLE_STRUCTS  = YES
 
 # When TYPEDEF_HIDES_STRUCT is enabled, a typedef of a struct, union, or enum 
 # is documented as struct, union, or enum with the name of the typedef. So 
@@ -337,7 +337,7 @@ INLINE_SIMPLE_STRUCTS  = NO
 # be useful for C code in case the coding convention dictates that all compound 
 # types are typedef'ed and only the typedef is referenced, never the tag name.
 
-TYPEDEF_HIDES_STRUCT   = NO
+TYPEDEF_HIDES_STRUCT   = YES
 
 # The SYMBOL_CACHE_SIZE determines the size of the internal cache use to 
 # determine which symbols to keep in memory and which to flush to disk. 
diff --git a/doc/doxygen/header.html b/doc/doxygen/header.html
index 031694a..ba3f857 100644
--- a/doc/doxygen/header.html
+++ b/doc/doxygen/header.html
@@ -6,5 +6,5 @@
 </HEAD>
 <BODY BGCOLOR="#FFFFFF">
 <CENTER>
-<a class="qindex" href="index.html">Home</a> &nbsp; <a class="qindex" href="annotated.html">Class/Enum List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; </CENTER>
+<a class="qindex" href="index.html">Home</a> &nbsp; <a class="qindex" href="annotated.html">Class/Enum List</a> &nbsp; <a class="qindex" href="files.html">File List</a> &nbsp; <a class="qindex" href="functions.html">Compound Members</a> &nbsp; <a class="qindex" href="group__C-interface.html">C interface</a> &nbsp; </CENTER>
 <HR>
diff --git a/rtaudio_c.h b/rtaudio_c.h
index 6d0131a..a7ca7f4 100644
--- a/rtaudio_c.h
+++ b/rtaudio_c.h
@@ -1,3 +1,21 @@
+/************************************************************************/
+/*! \defgroup C-interface
+    @{
+
+    \brief C interface to realtime audio i/o C++ classes.
+
+    RtAudio offers a C-style interface, principally for use in binding
+    RtAudio to other programming languages.  All structs, enums, and
+    functions listed here have direct analogs (and simply call to)
+    items in the C++ RtAudio class and its supporting classes and
+    types
+*/
+/************************************************************************/
+
+/*!
+  \file rtaudio_c.h
+ */
+
 #ifndef RTAUDIO_C_H
 #define RTAUDIO_C_H
 
@@ -15,6 +33,18 @@
 extern "C" {
 #endif
 
+/*! \typedef typedef unsigned long rtaudio_format_t;
+    \brief RtAudio data format type.
+
+    - \e RTAUDIO_FORMAT_SINT8:   8-bit signed integer.
+    - \e RTAUDIO_FORMAT_SINT16:  16-bit signed integer.
+    - \e RTAUDIO_FORMAT_SINT24:  24-bit signed integer.
+    - \e RTAUDIO_FORMAT_SINT32:  32-bit signed integer.
+    - \e RTAUDIO_FORMAT_FLOAT32: Normalized between plus/minus 1.0.
+    - \e RTAUDIO_FORMAT_FLOAT64: Normalized between plus/minus 1.0.
+
+    See \ref RtAudioFormat.
+*/
 typedef unsigned long rtaudio_format_t;
 
 #define RTAUDIO_FORMAT_SINT8 0x01
@@ -24,6 +54,20 @@ typedef unsigned long rtaudio_format_t;
 #define RTAUDIO_FORMAT_FLOAT32 0x10
 #define RTAUDIO_FORMAT_FLOAT64 0x20
 
+/*! \typedef typedef unsigned long rtaudio_stream_flags_t;
+    \brief RtAudio stream option flags.
+
+    The following flags can be OR'ed together to allow a client to
+    make changes to the default stream behavior:
+
+    - \e RTAUDIO_FLAGS_NONINTERLEAVED:   Use non-interleaved buffers (default = interleaved).
+    - \e RTAUDIO_FLAGS_MINIMIZE_LATENCY: Attempt to set stream parameters for lowest possible latency.
+    - \e RTAUDIO_FLAGS_HOG_DEVICE:       Attempt grab device for exclusive use.
+    - \e RTAUDIO_FLAGS_ALSA_USE_DEFAULT: Use the "default" PCM device (ALSA only).
+    - \e RTAUDIO_FLAGS_JACK_DONT_CONNECT: Do not automatically connect ports (JACK only).
+
+    See \ref RtAudioStreamFlags.
+*/
 typedef unsigned int rtaudio_stream_flags_t;
 
 #define RTAUDIO_FLAGS_NONINTERLEAVED 0x1
@@ -31,48 +75,86 @@ typedef unsigned int rtaudio_stream_flags_t;
 #define RTAUDIO_FLAGS_HOG_DEVICE 0x4
 #define RTAUDIO_FLAGS_SCHEDULE_REALTIME 0x8
 #define RTAUDIO_FLAGS_ALSA_USE_DEFAULT 0x10
+#define RTAUDIO_FLAGS_JACK_DONT_CONNECT = 0x20
 
+/*! \typedef typedef unsigned long rtaudio_stream_status_t;
+    \brief RtAudio stream status (over- or underflow) flags.
+
+    Notification of a stream over- or underflow is indicated by a
+    non-zero stream \c status argument in the RtAudioCallback function.
+    The stream status can be one of the following two options,
+    depending on whether the stream is open for output and/or input:
+
+    - \e RTAUDIO_STATUS_INPUT_OVERFLOW:   Input data was discarded because of an overflow condition at the driver.
+    - \e RTAUDIO_STATUS_OUTPUT_UNDERFLOW: The output buffer ran low, likely producing a break in the output sound.
+
+    See \ref RtAudioStreamStatus.
+*/
 typedef unsigned int rtaudio_stream_status_t;
 
 #define RTAUDIO_STATUS_INPUT_OVERFLOW 0x1
 #define RTAUDIO_STATUS_OUTPUT_UNDERFLOW 0x2
 
+//! RtAudio callback function prototype.
+/*!
+   All RtAudio clients must create a function of this type to read
+   and/or write data from/to the audio stream.  When the underlying
+   audio system is ready for new input or output data, this function
+   will be invoked.
+
+   See \ref RtAudioCallback.
+ */
 typedef int (*rtaudio_cb_t)(void *out, void *in, unsigned int nFrames,
                             double stream_time, rtaudio_stream_status_t status,
                             void *userdata);
 
+/*! \brief Error codes for RtAudio.
+
+    See \ref RtAudioError.
+*/
 typedef enum rtaudio_error {
-  RTAUDIO_ERROR_WARNING,
-  RTAUDIO_ERROR_DEBUG_WARNING,
-  RTAUDIO_ERROR_UNSPECIFIED,
-  RTAUDIO_ERROR_NO_DEVICES_FOUND,
-  RTAUDIO_ERROR_INVALID_DEVICE,
-  RTAUDIO_ERROR_MEMORY_ERROR,
-  RTAUDIO_ERROR_INVALID_PARAMETER,
-  RTAUDIO_ERROR_INVALID_USE,
-  RTAUDIO_ERROR_DRIVER_ERROR,
-  RTAUDIO_ERROR_SYSTEM_ERROR,
-  RTAUDIO_ERROR_THREAD_ERROR,
+  RTAUDIO_ERROR_WARNING,           /*!< A non-critical error. */
+  RTAUDIO_ERROR_DEBUG_WARNING,     /*!< A non-critical error which might be useful for debugging. */
+  RTAUDIO_ERROR_UNSPECIFIED,       /*!< The default, unspecified error type. */
+  RTAUDIO_ERROR_NO_DEVICES_FOUND,  /*!< No devices found on system. */
+  RTAUDIO_ERROR_INVALID_DEVICE,    /*!< An invalid device ID was specified. */
+  RTAUDIO_ERROR_MEMORY_ERROR,      /*!< An error occured during memory allocation. */
+  RTAUDIO_ERROR_INVALID_PARAMETER, /*!< An invalid parameter was specified to a function. */
+  RTAUDIO_ERROR_INVALID_USE,       /*!< The function was called incorrectly. */
+  RTAUDIO_ERROR_DRIVER_ERROR,      /*!< A system driver error occured. */
+  RTAUDIO_ERROR_SYSTEM_ERROR,      /*!< A system error occured. */
+  RTAUDIO_ERROR_THREAD_ERROR,      /*!< A thread error occured. */
 } rtaudio_error_t;
 
+//! RtAudio error callback function prototype.
+/*!
+    \param err Type of error.
+    \param msg Error description.
+
+    See \ref RtAudioErrorCallback.
+ */
 typedef void (*rtaudio_error_cb_t)(rtaudio_error_t err, const char *msg);
 
+//! Audio API specifier.  See \ref RtAudio::Api.
 typedef enum rtaudio_api {
-  RTAUDIO_API_UNSPECIFIED,
-  RTAUDIO_API_LINUX_ALSA,
-  RTAUDIO_API_LINUX_PULSE,
-  RTAUDIO_API_LINUX_OSS,
-  RTAUDIO_API_UNIX_JACK,
-  RTAUDIO_API_MACOSX_CORE,
-  RTAUDIO_API_WINDOWS_WASAPI,
-  RTAUDIO_API_WINDOWS_ASIO,
-  RTAUDIO_API_WINDOWS_DS,
-  RTAUDIO_API_DUMMY,
-  RTAUDIO_API_NUM,
+  RTAUDIO_API_UNSPECIFIED,    /*!< Search for a working compiled API. */
+  RTAUDIO_API_LINUX_ALSA,     /*!< The Advanced Linux Sound Architecture API. */
+  RTAUDIO_API_LINUX_PULSE,    /*!< The Linux PulseAudio API. */
+  RTAUDIO_API_LINUX_OSS,      /*!< The Linux Open Sound System API. */
+  RTAUDIO_API_UNIX_JACK,      /*!< The Jack Low-Latency Audio Server API. */
+  RTAUDIO_API_MACOSX_CORE,    /*!< Macintosh OS-X Core Audio API. */
+  RTAUDIO_API_WINDOWS_WASAPI, /*!< The Microsoft WASAPI API. */
+  RTAUDIO_API_WINDOWS_ASIO,   /*!< The Steinberg Audio Stream I/O API. */
+  RTAUDIO_API_WINDOWS_DS,     /*!< The Microsoft DirectSound API. */
+  RTAUDIO_API_DUMMY,          /*!< A compilable but non-functional API. */
+  RTAUDIO_API_NUM,            /*!< Number of values in this enum. */
 } rtaudio_api_t;
 
 #define NUM_SAMPLE_RATES 16
 #define MAX_NAME_LENGTH 512
+
+//! The public device information structure for returning queried values.
+//! See \ref RtAudio::DeviceInfo.
 typedef struct rtaudio_device_info {
   int probed;
   unsigned int output_channels;
@@ -90,12 +172,16 @@ typedef struct rtaudio_device_info {
   char name[MAX_NAME_LENGTH];
 } rtaudio_device_info_t;
 
+//! The structure for specifying input or ouput stream parameters.
+//! See \ref RtAudio::StreamParameters.
 typedef struct rtaudio_stream_parameters {
   unsigned int device_id;
   unsigned int num_channels;
   unsigned int first_channel;
 } rtaudio_stream_parameters_t;
 
+//! The structure for specifying stream options.
+//! See \ref RtAudio::StreamOptions.
 typedef struct rtaudio_stream_options {
   rtaudio_stream_flags_t flags;
   unsigned int num_buffers;
@@ -105,26 +191,64 @@ typedef struct rtaudio_stream_options {
 
 typedef struct rtaudio *rtaudio_t;
 
+//! Determine the current RtAudio version.  See \ref RtAudio::getVersion().
 RTAUDIOAPI const char *rtaudio_version(void);
+
+//! Determine the number of available compiled audio APIs, the length
+//! of the array returned by rtaudio_compiled_api().  See \ref
+//! RtAudio::getCompiledApi().
 RTAUDIOAPI unsigned int rtaudio_get_num_compiled_apis(void);
+
+//! Return an array of rtaudio_api_t compiled into this instance of
+//! RtAudio.  This array is static (do not free it) and has the length
+//! returned by rtaudio_get_num_compiled_apis().  See \ref
+//! RtAudio::getCompiledApi().
 RTAUDIOAPI const rtaudio_api_t *rtaudio_compiled_api(void);
+
+//! Return the name of a specified rtaudio_api_t.  This string can be
+//! used to look up an API by rtaudio_compiled_api_by_name().  See
+//! \ref RtAudio::getApiName().
 RTAUDIOAPI const char *rtaudio_api_name(rtaudio_api_t api);
+
+//! Return the display name of a specified rtaudio_api_t.  See \ref
+//! RtAudio::getApiDisplayName().
 RTAUDIOAPI const char *rtaudio_api_display_name(rtaudio_api_t api);
+
+//! Return the rtaudio_api_t having the given name.  See \ref
+//! RtAudio::getCompiledApiByName().
 RTAUDIOAPI rtaudio_api_t rtaudio_compiled_api_by_name(const char *name);
 
 RTAUDIOAPI const char *rtaudio_error(rtaudio_t audio);
 
+//! Create an instance of struct rtaudio.
 RTAUDIOAPI rtaudio_t rtaudio_create(rtaudio_api_t api);
+
+//! Free an instance of struct rtaudio.
 RTAUDIOAPI void rtaudio_destroy(rtaudio_t audio);
 
+//! Returns the audio API specifier for the current instance of
+//! RtAudio.  See RtAudio::getCurrentApi().
 RTAUDIOAPI rtaudio_api_t rtaudio_current_api(rtaudio_t audio);
 
+//! Queries for the number of audio devices available.  See \ref
+//! RtAudio::getDeviceCount().
 RTAUDIOAPI int rtaudio_device_count(rtaudio_t audio);
+
+//! Return a struct rtaudio_device_info for a specified device number.
+//! See \ref RtAudio::getDeviceInfo().
 RTAUDIOAPI rtaudio_device_info_t rtaudio_get_device_info(rtaudio_t audio,
                                                          int i);
+
+//! Returns the index of the default output device.  See \ref
+//! RtAudio::getDefaultOutputDevice().
 RTAUDIOAPI unsigned int rtaudio_get_default_output_device(rtaudio_t audio);
+
+//! Returns the index of the default input device.  See \ref
+//! RtAudio::getDefaultInputDevice().
 RTAUDIOAPI unsigned int rtaudio_get_default_input_device(rtaudio_t audio);
 
+//! Opens a stream with the specified parameters.  See \ref RtAudio::openStream().
+//! \return an \ref rtaudio_error.
 RTAUDIOAPI int
 rtaudio_open_stream(rtaudio_t audio, rtaudio_stream_parameters_t *output_params,
                     rtaudio_stream_parameters_t *input_params,
@@ -132,22 +256,51 @@ rtaudio_open_stream(rtaudio_t audio, rtaudio_stream_parameters_t *output_params,
                     unsigned int *buffer_frames, rtaudio_cb_t cb,
                     void *userdata, rtaudio_stream_options_t *options,
                     rtaudio_error_cb_t errcb);
+
+//! Closes a stream and frees any associated stream memory.  See \ref RtAudio::closeStream().
 RTAUDIOAPI void rtaudio_close_stream(rtaudio_t audio);
+
+//! Starts a stream.  See \ref RtAudio::startStream().
 RTAUDIOAPI int rtaudio_start_stream(rtaudio_t audio);
+
+//! Stop a stream, allowing any samples remaining in the output queue
+//! to be played.  See \ref RtAudio::stopStream().
 RTAUDIOAPI int rtaudio_stop_stream(rtaudio_t audio);
+
+//! Stop a stream, discarding any samples remaining in the
+//! input/output queue.  See \ref RtAudio::abortStream().
 RTAUDIOAPI int rtaudio_abort_stream(rtaudio_t audio);
 
+//! Returns 1 if a stream is open and false if not.  See \ref RtAudio::isStreamOpen().
 RTAUDIOAPI int rtaudio_is_stream_open(rtaudio_t audio);
+
+//! Returns 1 if a stream is running and false if it is stopped or not
+//! open.  See \ref RtAudio::isStreamRunning().
 RTAUDIOAPI int rtaudio_is_stream_running(rtaudio_t audio);
 
+//! Returns the number of elapsed seconds since the stream was
+//! started.  See \ref RtAudio::getStreamTime().
 RTAUDIOAPI double rtaudio_get_stream_time(rtaudio_t audio);
+
+//! Set the stream time to a time in seconds greater than or equal to
+//! 0.0.  See \ref RtAudio::setStreamTime().
 RTAUDIOAPI void rtaudio_set_stream_time(rtaudio_t audio, double time);
+
+//! Returns the internal stream latency in sample frames.  See \ref
+//! RtAudio::getStreamLatency().
 RTAUDIOAPI int rtaudio_get_stream_latency(rtaudio_t audio);
+
+//! Returns actual sample rate in use by the stream.  See \ref
+//! RtAudio::getStreamSampleRate().
 RTAUDIOAPI unsigned int rtaudio_get_stream_sample_rate(rtaudio_t audio);
 
+//! Specify whether warning messages should be printed to stderr.  See
+//! \ref RtAudio::showWarnings().
 RTAUDIOAPI void rtaudio_show_warnings(rtaudio_t audio, int show);
 
 #ifdef __cplusplus
 }
 #endif
 #endif /* RTAUDIO_C_H */
+
+/*! }@ */
author	Stephen Sinclair <radarsat1@gmail.com>	2019-04-17 15:13:48 +0200
committer	Stephen Sinclair <radarsat1@gmail.com>	2019-04-17 15:13:56 +0200
commit	acb8458e225384abcf3511d81eca971702aded20 (patch)
tree	c761c360f86507ed1d00d969dc9450906494e240
parent	6c585b5941945f9d6731dbd74902d146d32874c4 (diff)