falkTX
/
rtaudio
mirror of https://github.com/falkTX/rtaudio
1
0
Fork 0
Code Releases 27 Activity
Browse Source

[doc] document C interface.

tags/5.1.0
Stephen Sinclair 6 years ago
parent
6c585b5941
commit
acb8458e22
3 changed files with 178 additions and 25 deletions
Unified View
Diff Options
Show Stats Download Patch File Download Diff File
  1. +2
    -2
      doc/doxygen/Doxyfile.in
  2. +1
    -1
      doc/doxygen/header.html
  3. +175
    -22
      rtaudio_c.h

+ 2
- 2
doc/doxygen/Doxyfile.in View File

@@ -327,7 +327,7 @@ INLINE_GROUPED_CLASSES = NO
# structs, classes, and unions are shown on a separate page (for HTML and Man # structs, classes, and unions are shown on a separate page (for HTML and Man
# pages) or section (for LaTeX and RTF). # 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 # 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 # 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 # 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. # 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 # 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. # determine which symbols to keep in memory and which to flush to disk.


+ 1
- 1
doc/doxygen/header.html View File

@@ -6,5 +6,5 @@
</HEAD> </HEAD>
<BODY BGCOLOR="#FFFFFF"> <BODY BGCOLOR="#FFFFFF">
<CENTER> <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> <HR>

+ 175
- 22
rtaudio_c.h View File

@@ -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 #ifndef RTAUDIO_C_H
#define RTAUDIO_C_H #define RTAUDIO_C_H


@@ -15,6 +33,18 @@
extern "C" { extern "C" {
#endif #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; typedef unsigned long rtaudio_format_t;


#define RTAUDIO_FORMAT_SINT8 0x01 #define RTAUDIO_FORMAT_SINT8 0x01
@@ -24,6 +54,20 @@ typedef unsigned long rtaudio_format_t;
#define RTAUDIO_FORMAT_FLOAT32 0x10 #define RTAUDIO_FORMAT_FLOAT32 0x10
#define RTAUDIO_FORMAT_FLOAT64 0x20 #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; typedef unsigned int rtaudio_stream_flags_t;


#define RTAUDIO_FLAGS_NONINTERLEAVED 0x1 #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_HOG_DEVICE 0x4
#define RTAUDIO_FLAGS_SCHEDULE_REALTIME 0x8 #define RTAUDIO_FLAGS_SCHEDULE_REALTIME 0x8
#define RTAUDIO_FLAGS_ALSA_USE_DEFAULT 0x10 #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; typedef unsigned int rtaudio_stream_status_t;


#define RTAUDIO_STATUS_INPUT_OVERFLOW 0x1 #define RTAUDIO_STATUS_INPUT_OVERFLOW 0x1
#define RTAUDIO_STATUS_OUTPUT_UNDERFLOW 0x2 #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, typedef int (*rtaudio_cb_t)(void *out, void *in, unsigned int nFrames,
double stream_time, rtaudio_stream_status_t status, double stream_time, rtaudio_stream_status_t status,
void *userdata); void *userdata);


/*! \brief Error codes for RtAudio.

See \ref RtAudioError.
*/
typedef enum rtaudio_error { 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_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); typedef void (*rtaudio_error_cb_t)(rtaudio_error_t err, const char *msg);


//! Audio API specifier. See \ref RtAudio::Api.
typedef enum 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; } rtaudio_api_t;


#define NUM_SAMPLE_RATES 16 #define NUM_SAMPLE_RATES 16
#define MAX_NAME_LENGTH 512 #define MAX_NAME_LENGTH 512

//! The public device information structure for returning queried values.
//! See \ref RtAudio::DeviceInfo.
typedef struct rtaudio_device_info { typedef struct rtaudio_device_info {
int probed; int probed;
unsigned int output_channels; unsigned int output_channels;
@@ -90,12 +172,16 @@ typedef struct rtaudio_device_info {
char name[MAX_NAME_LENGTH]; char name[MAX_NAME_LENGTH];
} rtaudio_device_info_t; } rtaudio_device_info_t;


//! The structure for specifying input or ouput stream parameters.
//! See \ref RtAudio::StreamParameters.
typedef struct rtaudio_stream_parameters { typedef struct rtaudio_stream_parameters {
unsigned int device_id; unsigned int device_id;
unsigned int num_channels; unsigned int num_channels;
unsigned int first_channel; unsigned int first_channel;
} rtaudio_stream_parameters_t; } rtaudio_stream_parameters_t;


//! The structure for specifying stream options.
//! See \ref RtAudio::StreamOptions.
typedef struct rtaudio_stream_options { typedef struct rtaudio_stream_options {
rtaudio_stream_flags_t flags; rtaudio_stream_flags_t flags;
unsigned int num_buffers; unsigned int num_buffers;
@@ -105,26 +191,64 @@ typedef struct rtaudio_stream_options {


typedef struct rtaudio *rtaudio_t; typedef struct rtaudio *rtaudio_t;


//! Determine the current RtAudio version. See \ref RtAudio::getVersion().
RTAUDIOAPI const char *rtaudio_version(void); 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); 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); 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); 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); 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 rtaudio_api_t rtaudio_compiled_api_by_name(const char *name);


RTAUDIOAPI const char *rtaudio_error(rtaudio_t audio); RTAUDIOAPI const char *rtaudio_error(rtaudio_t audio);


//! Create an instance of struct rtaudio.
RTAUDIOAPI rtaudio_t rtaudio_create(rtaudio_api_t api); RTAUDIOAPI rtaudio_t rtaudio_create(rtaudio_api_t api);

//! Free an instance of struct rtaudio.
RTAUDIOAPI void rtaudio_destroy(rtaudio_t audio); 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); 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); 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, RTAUDIOAPI rtaudio_device_info_t rtaudio_get_device_info(rtaudio_t audio,
int i); 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); 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); 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 RTAUDIOAPI int
rtaudio_open_stream(rtaudio_t audio, rtaudio_stream_parameters_t *output_params, rtaudio_open_stream(rtaudio_t audio, rtaudio_stream_parameters_t *output_params,
rtaudio_stream_parameters_t *input_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, unsigned int *buffer_frames, rtaudio_cb_t cb,
void *userdata, rtaudio_stream_options_t *options, void *userdata, rtaudio_stream_options_t *options,
rtaudio_error_cb_t errcb); 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); RTAUDIOAPI void rtaudio_close_stream(rtaudio_t audio);

//! Starts a stream. See \ref RtAudio::startStream().
RTAUDIOAPI int rtaudio_start_stream(rtaudio_t audio); 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); 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); 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); 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); 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); 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); 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); 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); 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); RTAUDIOAPI void rtaudio_show_warnings(rtaudio_t audio, int show);


#ifdef __cplusplus #ifdef __cplusplus
} }
#endif #endif
#endif /* RTAUDIO_C_H */ #endif /* RTAUDIO_C_H */

/*! }@ */

Write Preview
Loading…
Cancel
Save