some patches for master attached
1) Constify a param in pa_cvolume_scale_mask
2) A small efficiency tweak to volume handling
3) A big collection of API documentation improvements
Includes typo fixes; neatening; addition of more return info; and such
4) A patch merging and deduplicating some pa_buffer_attr documentation
From 60ce6302d2df32a3fe756ebb4e142ce09b044000 Mon Sep 17 00:00:00 2001
From: jnqnfe <jnq...@gmail.com>
Date: Thu, 31 Aug 2017 18:32:47 +0100
Subject: pa_cvolume_scale_mask: constify param
diff --git a/src/pulse/volume.c b/src/pulse/volume.c
index ffd42ecb..6b0c4b68 100644
--- a/src/pulse/volume.c
+++ b/src/pulse/volume.c
@@ -789,7 +789,7 @@ pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max) {
return v;
}
-pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, pa_channel_map *cm, pa_channel_position_mask_t mask) {
+pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask) {
unsigned c;
pa_volume_t t = 0;
diff --git a/src/pulse/volume.h b/src/pulse/volume.h
index 03497f74..08db7cfe 100644
--- a/src/pulse/volume.h
+++ b/src/pulse/volume.h
@@ -396,7 +396,7 @@ pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
* of all channels selected via cm/mask equals max. This also modifies
* the volume of those channels that are unmasked. The proportions
* between the channel volumes are kept. \since 0.9.16 */
-pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, pa_channel_map *cm, pa_channel_position_mask_t mask);
+pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask);
/** Set the passed volume to all channels at the specified channel
* position. Will return the updated volume struct, or NULL if there
From e7c89c7b78d6fcc003ec5e9fa8fad77d7b920b1f Mon Sep 17 00:00:00 2001
From: jnqnfe <jnq...@gmail.com>
Date: Mon, 4 Sep 2017 02:32:37 +0100
Subject: small volume tweak
diff --git a/src/pulse/volume.c b/src/pulse/volume.c
index 6b0c4b68..ead54152 100644
--- a/src/pulse/volume.c
+++ b/src/pulse/volume.c
@@ -477,10 +477,10 @@ pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const
pa_return_val_if_fail(pa_cvolume_valid(a), NULL);
pa_return_val_if_fail(pa_cvolume_valid(b), NULL);
- for (i = 0; i < a->channels && i < b->channels; i++)
- dest->values[i] = pa_sw_volume_multiply(a->values[i], b->values[i]);
+ dest->channels = PA_MIN(a->channels, b->channels);
- dest->channels = (uint8_t) i;
+ for (i = 0; i < dest->channels; i++)
+ dest->values[i] = pa_sw_volume_multiply(a->values[i], b->values[i]);
return dest;
}
@@ -512,10 +512,10 @@ pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa
pa_return_val_if_fail(pa_cvolume_valid(a), NULL);
pa_return_val_if_fail(pa_cvolume_valid(b), NULL);
- for (i = 0; i < a->channels && i < b->channels; i++)
- dest->values[i] = pa_sw_volume_divide(a->values[i], b->values[i]);
+ dest->channels = PA_MIN(a->channels, b->channels);
- dest->channels = (uint8_t) i;
+ for (i = 0; i < dest->channels; i++)
+ dest->values[i] = pa_sw_volume_divide(a->values[i], b->values[i]);
return dest;
}
@@ -942,10 +942,10 @@ pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvo
pa_return_val_if_fail(pa_cvolume_valid(a), NULL);
pa_return_val_if_fail(pa_cvolume_valid(b), NULL);
- for (i = 0; i < a->channels && i < b->channels; i++)
- dest->values[i] = PA_MAX(a->values[i], b->values[i]);
+ dest->channels = PA_MIN(a->channels, b->channels);
- dest->channels = (uint8_t) i;
+ for (i = 0; i < dest->channels; i++)
+ dest->values[i] = PA_MAX(a->values[i], b->values[i]);
return dest;
}
From 7212f99292e3c8f1167e814315528089a56033ae Mon Sep 17 00:00:00 2001
From: jnqnfe <jnq...@gmail.com>
Date: Mon, 4 Sep 2017 20:19:48 +0100
Subject: api documentation improvements
includes typo fixes, neatening, addition of more return info, and such.
diff --git a/src/pulse/channelmap.h b/src/pulse/channelmap.h
index 6eabe20b..290e1ed2 100644
--- a/src/pulse/channelmap.h
+++ b/src/pulse/channelmap.h
@@ -46,10 +46,12 @@
*
* \li pa_channel_map_init_mono() - Create a channel map with only mono audio.
* \li pa_channel_map_init_stereo() - Create a standard stereo mapping.
- * \li pa_channel_map_init_auto() - Create a standard channel map for a specific number of channels
- * \li pa_channel_map_init_extend() - Similar to
- * pa_channel_map_init_auto() but synthesize a channel map if no
- * predefined one is known for the specified number of channels.
+ * \li pa_channel_map_init_auto() - Create a standard channel map for a specific
+ * number of channels.
+ * \li pa_channel_map_init_extend() - Similar to pa_channel_map_init_auto() but
+ * synthesize a channel map if no predefined
+ * one is known for the specified number of
+ * channels.
*
* \section conv_sec Convenience Functions
*
@@ -261,7 +263,7 @@ typedef enum pa_channel_map_def {
* mixing of streams */
typedef struct pa_channel_map {
uint8_t channels;
- /**< Number of channels */
+ /**< Number of channels mapped */
pa_channel_position_t map[PA_CHANNELS_MAX];
/**< Channel labels */
@@ -306,7 +308,7 @@ const char* pa_channel_position_to_pretty_string(pa_channel_position_t pos);
* it might become part of an ABI. */
#define PA_CHANNEL_MAP_SNPRINT_MAX 336
-/** Make a human readable string from the specified channel map */
+/** Make a human readable string from the specified channel map. Returns \a s. */
char* pa_channel_map_snprint(char *s, size_t l, const pa_channel_map *map);
/** Parse a channel position list or well-known mapping name into a
diff --git a/src/pulse/context.h b/src/pulse/context.h
index ae2a0682..05a2fe5c 100644
--- a/src/pulse/context.h
+++ b/src/pulse/context.h
@@ -46,7 +46,7 @@
* that some implementations may block all other events
* when a deferred event is active.
* \li I/O events - Events that trigger on file descriptor activities.
- * \li Times events - Events that trigger after a fixed amount of time.
+ * \li Timer events - Events that trigger after a fixed amount of time.
*
* The abstraction is represented as a number of function pointers in the
* pa_mainloop_api structure.
@@ -104,10 +104,10 @@
* pa_operation object for each asynchronous operation.
*
* There are only two actions (besides reference counting) that can be
- * performed on a pa_operation: querying its state with
+ * performed on an pa_operation: querying its state with
* pa_operation_get_state() and aborting it with pa_operation_cancel().
*
- * A pa_operation object is reference counted, so an application must
+ * An pa_operation object is reference counted, so an application must
* make sure to unreference it, even if it has no intention of using it.
*
* \subsection conn_subsec Connecting
@@ -115,7 +115,7 @@
* A context must be connected to a server before any operation can be
* issued. Calling pa_context_connect() will initiate the connection
* procedure. Unlike most asynchronous operations, connecting does not
- * result in a pa_operation object. Instead, the application should
+ * result in an pa_operation object. Instead, the application should
* register a callback using pa_context_set_state_callback().
*
* \subsection disc_subsec Disconnecting
@@ -199,13 +199,14 @@ int pa_context_is_pending(pa_context *c);
pa_context_state_t pa_context_get_state(pa_context *c);
/** Connect the context to the specified server. If server is NULL,
-connect to the default server. This routine may but will not always
-return synchronously on error. Use pa_context_set_state_callback() to
-be notified when the connection is established. If flags doesn't have
-PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
-accessible a new daemon is spawned. If api is non-NULL, the functions
-specified in the structure are used when forking a new child
-process. */
+ * connect to the default server. This routine may but will not always
+ * return synchronously on error. Use pa_context_set_state_callback() to
+ * be notified when the connection is established. If flags doesn't have
+ * PA_CONTEXT_NOAUTOSPAWN set and no specific server is specified or
+ * accessible a new daemon is spawned. If api is non-NULL, the functions
+ * specified in the structure are used when forking a new child
+ * process. Returns negative on certain errors such as invalid state
+ * or parameters. */
int pa_context_connect(pa_context *c, const char *server, pa_context_flags_t flags, const pa_spawn_api *api);
/** Terminate the context connection immediately */
@@ -237,11 +238,12 @@ const char* pa_context_get_server(pa_context *c);
/** Return the protocol version of the library. */
uint32_t pa_context_get_protocol_version(pa_context *c);
-/** Return the protocol version of the connected server. */
+/** Return the protocol version of the connected server.
+ * Returns PA_INVALID_INDEX on error. */
uint32_t pa_context_get_server_protocol_version(pa_context *c);
/** Update the property list of the client, adding new entries. Please
- * note that it is highly recommended to set as much properties
+ * note that it is highly recommended to set as many properties
* initially via pa_context_new_with_proplist() as possible instead a
* posteriori with this function, since that information may then be
* used to route streams of the client to the right device. \since 0.9.11 */
@@ -252,7 +254,8 @@ pa_operation *pa_context_proplist_remove(pa_context *c, const char *const keys[]
/** Return the client index this context is
* identified in the server with. This is useful for usage with the
- * introspection functions, such as pa_context_get_client_info(). \since 0.9.11 */
+ * introspection functions, such as pa_context_get_client_info().
+ * Returns PA_INVALID_INDEX on error. \since 0.9.11 */
uint32_t pa_context_get_index(pa_context *s);
/** Create a new timer event source for the specified time (wrapper
@@ -271,7 +274,8 @@ void pa_context_rttime_restart(pa_context *c, pa_time_event *e, pa_usec_t usec);
* of this size. It is not recommended writing smaller blocks than
* this (unless required due to latency demands) because this
* increases CPU usage. If ss is NULL you will be returned the
- * byte-exact tile size. If you pass a valid ss, then the tile size
+ * byte-exact tile size. if ss is invalid, (size_t -1) will be
+ * returned. If you pass a valid ss, then the tile size
* will be rounded down to multiple of the frame size. This is
* supposed to be used in a construct such as
* pa_context_get_tile_size(pa_stream_get_context(s),
diff --git a/src/pulse/def.h b/src/pulse/def.h
index 87b7dd40..7211b60e 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -97,7 +97,7 @@ typedef enum pa_operation_state {
/**< The operation has completed */
PA_OPERATION_CANCELLED
/**< The operation has been cancelled. Operations may get cancelled by the
- * application, or as a result of the context getting disconneted while the
+ * application, or as a result of the context getting disconnected while the
* operation is pending. */
} pa_operation_state_t;
@@ -118,7 +118,9 @@ typedef enum pa_context_flags {
PA_CONTEXT_NOAUTOSPAWN = 0x0001U,
/**< Disabled autospawning of the PulseAudio daemon if required */
PA_CONTEXT_NOFAIL = 0x0002U
- /**< Don't fail if the daemon is not available when pa_context_connect() is called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon to appear. \since 0.9.15 */
+ /**< Don't fail if the daemon is not available when pa_context_connect() is
+ * called, instead enter PA_CONTEXT_CONNECTING state and wait for the daemon
+ * to appear. \since 0.9.15 */
} pa_context_flags_t;
/** \cond fulldocs */
@@ -259,7 +261,7 @@ typedef enum pa_stream_flags {
PA_STREAM_FIX_CHANNELS = 0x0100,
/**< Use the number of channels and the channel map of the sink,
* and possibly ignore the number of channels and the map the
- * sample spec and the passed channel map contains. Usage similar
+ * sample spec and the passed channel map contain. Usage similar
* to PA_STREAM_FIX_FORMAT. Only supported when the server is at
* least PA 0.9.8. It is ignored on older servers.
*
@@ -295,7 +297,7 @@ typedef enum pa_stream_flags {
PA_STREAM_START_MUTED = 0x1000U,
/**< Create in muted state. If neither PA_STREAM_START_UNMUTED nor
- * PA_STREAM_START_MUTED it is left to the server to decide
+ * PA_STREAM_START_MUTED are set, it is left to the server to decide
* whether to create the stream in muted or in unmuted
* state. \since 0.9.11 */
@@ -330,7 +332,7 @@ typedef enum pa_stream_flags {
PA_STREAM_START_UNMUTED = 0x10000U,
/**< Create in unmuted state. If neither PA_STREAM_START_UNMUTED
- * nor PA_STREAM_START_MUTED it is left to the server to decide
+ * nor PA_STREAM_START_MUTED are set it is left to the server to decide
* whether to create the stream in muted or in unmuted
* state. \since 0.9.15 */
@@ -703,7 +705,7 @@ typedef struct pa_timing_info {
int64_t write_index;
/**< Current write index into the playback buffer in bytes. Think
* twice before using this for seeking purposes: it might be out
- * of date a the time you want to use it. Consider using
+ * of date at the time you want to use it. Consider using
* PA_SEEK_RELATIVE instead. */
int read_index_corrupt;
@@ -714,7 +716,7 @@ typedef struct pa_timing_info {
int64_t read_index;
/**< Current read index into the playback buffer in bytes. Think
* twice before using this for seeking purposes: it might be out
- * of date a the time you want to use it. Consider using
+ * of date at the time you want to use it. Consider using
* PA_SEEK_RELATIVE_ON_READ instead. */
pa_usec_t configured_sink_usec;
@@ -758,16 +760,16 @@ typedef struct pa_spawn_api {
/** Seek type for pa_stream_write(). */
typedef enum pa_seek_mode {
PA_SEEK_RELATIVE = 0,
- /**< Seek relatively to the write index */
+ /**< Seek relative to the write index. */
PA_SEEK_ABSOLUTE = 1,
- /**< Seek relatively to the start of the buffer queue */
+ /**< Seek relative to the start of the buffer queue. */
PA_SEEK_RELATIVE_ON_READ = 2,
- /**< Seek relatively to the read index. */
+ /**< Seek relative to the read index. */
PA_SEEK_RELATIVE_END = 3
- /**< Seek relatively to the current end of the buffer queue. */
+ /**< Seek relative to the current end of the buffer queue. */
} pa_seek_mode_t;
/** \cond fulldocs */
diff --git a/src/pulse/format.h b/src/pulse/format.h
index f606b3b5..2143bb51 100644
--- a/src/pulse/format.h
+++ b/src/pulse/format.h
@@ -78,7 +78,8 @@ typedef enum pa_encoding {
/** Returns a printable string representing the given encoding type. \since 1.0 */
const char *pa_encoding_to_string(pa_encoding_t e) PA_GCC_CONST;
-/** Converts a string of the form returned by \a pa_encoding_to_string() back to a \a pa_encoding_t. \since 1.0 */
+/** Converts a string of the form returned by \a pa_encoding_to_string() back to
+ * a \a pa_encoding_t. \since 1.0 */
pa_encoding_t pa_encoding_from_string(const char *encoding);
/** Represents the format of data provided in a stream or processed by a sink. \since 1.0 */
@@ -90,7 +91,8 @@ typedef struct pa_format_info {
/**< Additional encoding-specific properties such as sample rate, bitrate, etc. */
} pa_format_info;
-/** Allocates a new \a pa_format_info structure. Clients must initialise at least the encoding field themselves. \since 1.0 */
+/** Allocates a new \a pa_format_info structure. Clients must initialise at
+ * least the encoding field themselves. Free with pa_format_info_free. \since 1.0 */
pa_format_info* pa_format_info_new(void);
/** Returns a new \a pa_format_info struct and representing the same format as \a src. \since 1.0 */
@@ -102,7 +104,8 @@ void pa_format_info_free(pa_format_info *f);
/** Returns non-zero when the format info structure is valid. \since 1.0 */
int pa_format_info_valid(const pa_format_info *f);
-/** Returns non-zero when the format info structure represents a PCM (i.e.\ uncompressed data) format. \since 1.0 */
+/** Returns non-zero when the format info structure represents a PCM
+ * (i.e.\ uncompressed data) format. \since 1.0 */
int pa_format_info_is_pcm(const pa_format_info *f);
/** Returns non-zero if the format represented by \a first is a subset of
@@ -121,7 +124,7 @@ int pa_format_info_is_compatible(const pa_format_info *first, const pa_format_in
* it might become part of an ABI. \since 1.0 */
#define PA_FORMAT_INFO_SNPRINT_MAX 256
-/** Return a human-readable string representing the given format. \since 1.0 */
+/** Make a human-readable string representing the given format. Returns \a s. \since 1.0 */
char *pa_format_info_snprint(char *s, size_t l, const pa_format_info *f);
/** Parse a human-readable string of the form generated by
diff --git a/src/pulse/mainloop-api.h b/src/pulse/mainloop-api.h
index 4d847313..6b2a55d6 100644
--- a/src/pulse/mainloop-api.h
+++ b/src/pulse/mainloop-api.h
@@ -31,14 +31,21 @@
* Main loop abstraction layer. Both the PulseAudio core and the
* PulseAudio client library use a main loop abstraction layer. Due to
* this it is possible to embed PulseAudio into other
- * applications easily. Two main loop implementations are
+ * applications easily. Three main loop implementations are
* currently available:
- * \li A minimal implementation based on the C library's poll() function (See \ref mainloop.h)
- * \li A wrapper around the GLIB main loop. Use this to embed PulseAudio into your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h)
+ * \li A minimal implementation based on the C library's poll() function
+ * (See \ref mainloop.h).
+ * \li A special version of the previous implementation where all of
+ * PulseAudio's internal handling runs in a separate thread
+ * (See \ref thread-mainloop.h).
+ * \li A wrapper around the GLIB main loop. Use this to embed PulseAudio into
+ * your GLIB/GTK+/GNOME programs (See \ref glib-mainloop.h).
*
- * The structure pa_mainloop_api is used as vtable for the main loop abstraction.
+ * The structure pa_mainloop_api is used as a vtable for the main loop abstraction.
*
- * This mainloop abstraction layer has no direct support for UNIX signals. Generic, mainloop implementation agnostic support is available through \ref mainloop-signal.h.
+ * This mainloop abstraction layer has no direct support for UNIX signals.
+ * Generic, mainloop implementation agnostic support is available through
+ * \ref mainloop-signal.h.
* */
PA_C_DECL_BEGIN
diff --git a/src/pulse/mainloop.h b/src/pulse/mainloop.h
index 6e2ca5f9..a7df8a19 100644
--- a/src/pulse/mainloop.h
+++ b/src/pulse/mainloop.h
@@ -77,7 +77,7 @@ struct pollfd;
/** An opaque main loop object */
typedef struct pa_mainloop pa_mainloop;
-/** Allocate a new main loop object */
+/** Allocate a new main loop object. Free with pa_mainloop_free. */
pa_mainloop *pa_mainloop_new(void);
/** Free a main loop object */
@@ -106,7 +106,10 @@ specified with the main loop's quit() routine in the integer variable retval poi
to. On success returns the number of sources dispatched in this iteration. */
int pa_mainloop_iterate(pa_mainloop *m, int block, int *retval);
-/** Run unlimited iterations of the main loop object until the main loop's quit() routine is called. */
+/** Run unlimited iterations of the main loop object until the main loop's
+quit() routine is called. Returns a negative value on error. Optionally return
+the return value as specified with the main loop's quit() routine in the integer
+variable retval points to. */
int pa_mainloop_run(pa_mainloop *m, int *retval);
/** Return the abstract main loop abstraction layer vtable for this
diff --git a/src/pulse/proplist.h b/src/pulse/proplist.h
index bc9e8f8e..260152d2 100644
--- a/src/pulse/proplist.h
+++ b/src/pulse/proplist.h
@@ -271,7 +271,7 @@ PA_C_DECL_BEGIN
* as keys and arbitrary data as values. \since 0.9.11 */
typedef struct pa_proplist pa_proplist;
-/** Allocate a property list. \since 0.9.11 */
+/** Allocate a property list. Free with pa_proplist_free. \since 0.9.11 */
pa_proplist* pa_proplist_new(void);
/** Free the property list. \since 0.9.11 */
@@ -283,7 +283,7 @@ int pa_proplist_key_valid(const char *key);
/** Append a new string entry to the property list, possibly
* overwriting an already existing entry with the same key. An
* internal copy of the data passed is made. Will accept only valid
- * UTF-8. \since 0.9.11 */
+ * UTF-8. Returns zero on success. \since 0.9.11 */
int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
/** Append a new string entry to the property list, possibly
@@ -291,19 +291,20 @@ int pa_proplist_sets(pa_proplist *p, const char *key, const char *value);
* internal copy of the data passed is made. Will accept only valid
* UTF-8. The string passed in must contain a '='. Left hand side of
* the '=' is used as key name, the right hand side as string
- * data. \since 0.9.16 */
+ * data. Returns zero on success. \since 0.9.16 */
int pa_proplist_setp(pa_proplist *p, const char *pair);
/** Append a new string entry to the property list, possibly
* overwriting an already existing entry with the same key. An
* internal copy of the data passed is made. Will accept only valid
* UTF-8. The data can be passed as printf()-style format string with
- * arguments. \since 0.9.11 */
+ * arguments. Returns zero one success. \since 0.9.11 */
int pa_proplist_setf(pa_proplist *p, const char *key, const char *format, ...) PA_GCC_PRINTF_ATTR(3,4);
/** Append a new arbitrary data entry to the property list, possibly
* overwriting an already existing entry with the same key. An
- * internal copy of the data passed is made. \since 0.9.11 */
+ * internal copy of the data passed is made.
+ * Returns zero on success. \since 0.9.11 */
int pa_proplist_set(pa_proplist *p, const char *key, const void *data, size_t nbytes);
/** Return a string entry for the specified key. Will return NULL if
@@ -315,8 +316,8 @@ const char *pa_proplist_gets(pa_proplist *p, const char *key);
/** Store the value for the specified key in \a data. Will store a
* NUL-terminated string for string entries. The \a data pointer returned will
* point to an internally allocated buffer. The caller should make a
- * copy of the data before the property list is accessed again. \since
- * 0.9.11 */
+ * copy of the data before the property list is accessed again.
+ * Returns zero on success, negative on error. \since 0.9.11 */
int pa_proplist_get(pa_proplist *p, const char *key, const void **data, size_t *nbytes);
/** Update mode enum for pa_proplist_update(). \since 0.9.11 */
@@ -347,7 +348,8 @@ typedef enum pa_update_mode {
void pa_proplist_update(pa_proplist *p, pa_update_mode_t mode, const pa_proplist *other);
/** Removes a single entry from the property list, identified be the
- * specified key name. \since 0.9.11 */
+ * specified key name. Returns zero on success, negative on error.
+ * \since 0.9.11 */
int pa_proplist_unset(pa_proplist *p, const char *key);
/** Similar to pa_proplist_unset() but takes an array of keys to
@@ -384,7 +386,7 @@ char *pa_proplist_to_string_sep(pa_proplist *p, const char *sep);
pa_proplist *pa_proplist_from_string(const char *str);
/** Returns 1 if an entry for the specified key exists in the
- * property list. \since 0.9.11 */
+ * property list. Returns negative on error. \since 0.9.11 */
int pa_proplist_contains(pa_proplist *p, const char *key);
/** Remove all entries from the property list object. \since 0.9.11 */
diff --git a/src/pulse/pulseaudio.h b/src/pulse/pulseaudio.h
index 063d5e23..e9fec55d 100644
--- a/src/pulse/pulseaudio.h
+++ b/src/pulse/pulseaudio.h
@@ -114,11 +114,11 @@
* integer value or a NULL pointer. On success, zero or a positive integer
* value or a valid pointer is returned.
*
- * Functions of the \ref simple generally return -1 or NULL on failure and
+ * Functions of the \ref simple API generally return -1 or NULL on failure and
* can optionally store an error code (see ::pa_error_code) using a pointer
* argument.
*
- * Functions of the \ref async return an negative error code or NULL on
+ * Functions of the \ref async API return an negative error code or NULL on
* failure (see ::pa_error_code). In the later case, pa_context_errno()
* can be used to obtain the error code of the last failed operation.
*
diff --git a/src/pulse/sample.h b/src/pulse/sample.h
index 4299eecf..b624a833 100644
--- a/src/pulse/sample.h
+++ b/src/pulse/sample.h
@@ -259,7 +259,8 @@ typedef struct pa_sample_spec {
/** Type for usec specifications (unsigned). Always 64 bit. */
typedef uint64_t pa_usec_t;
-/** Return the amount of bytes playback of a second of audio with the specified sample type takes */
+/** Return the amount of bytes that constitute playback of one second of
+ * audio, with the specified sample type. */
size_t pa_bytes_per_second(const pa_sample_spec *spec) PA_GCC_PURE;
/** Return the size of a frame with the specific sample type */
@@ -272,13 +273,14 @@ size_t pa_sample_size(const pa_sample_spec *spec) PA_GCC_PURE;
* full sample spec. \since 0.9.15 */
size_t pa_sample_size_of_format(pa_sample_format_t f) PA_GCC_PURE;
-/** Calculate the time the specified bytes take to play with the
- * specified sample type. The return value will always be rounded
- * down for non-integral return values. */
+/** Calculate the time it would take to play a buffer of the specified
+ * size with the specified sample type. The return value will always
+ * be rounded down for non-integral return values. */
pa_usec_t pa_bytes_to_usec(uint64_t length, const pa_sample_spec *spec) PA_GCC_PURE;
-/** Calculates the number of bytes that are required for the specified
- * time. The return value will always be rounded down for non-integral
+/** Calculates the size of a buffer required, for playback duration
+ * of the time specified, with the specified sample type. The
+ * return value will always be rounded down for non-integral
* return values. \since 0.9 */
size_t pa_usec_to_bytes(pa_usec_t t, const pa_sample_spec *spec) PA_GCC_PURE;
@@ -316,7 +318,7 @@ pa_sample_format_t pa_parse_sample_format(const char *format) PA_GCC_PURE;
* it might become part of an ABI. */
#define PA_SAMPLE_SPEC_SNPRINT_MAX 32
-/** Pretty print a sample type specification to a string */
+/** Pretty print a sample type specification to a string. Returns \a s. */
char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
/** Maximum required string length for pa_bytes_snprint(). Please note
@@ -326,26 +328,30 @@ char* pa_sample_spec_snprint(char *s, size_t l, const pa_sample_spec *spec);
* ABI. \since 0.9.16 */
#define PA_BYTES_SNPRINT_MAX 11
-/** Pretty print a byte size value (i.e.\ "2.5 MiB") */
+/** Pretty print a byte size value (i.e.\ "2.5 MiB"). Returns \a s. */
char* pa_bytes_snprint(char *s, size_t l, unsigned v);
-/** Return 1 when the specified format is little endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is little endian, 0 when
+ * big endian. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
int pa_sample_format_is_le(pa_sample_format_t f) PA_GCC_PURE;
-/** Return 1 when the specified format is big endian, return -1 when
- * endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is big endian, 0 when
+ * little endian. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
int pa_sample_format_is_be(pa_sample_format_t f) PA_GCC_PURE;
#ifdef WORDS_BIGENDIAN
#define pa_sample_format_is_ne(f) pa_sample_format_is_be(f)
#define pa_sample_format_is_re(f) pa_sample_format_is_le(f)
#else
-/** Return 1 when the specified format is native endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is native endian, 0 when
+ * not. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
#define pa_sample_format_is_ne(f) pa_sample_format_is_le(f)
-/** Return 1 when the specified format is reverse endian, return -1
- * when endianness does not apply to this format. \since 0.9.16 */
+/** Returns 1 when the specified format is reverse endian, 0 when
+ * native. Returns -1 when endianness does not apply to the
+ * specified format, or endianess is unknown. \since 0.9.16 */
#define pa_sample_format_is_re(f) pa_sample_format_is_be(f)
#endif
diff --git a/src/pulse/scache.h b/src/pulse/scache.h
index e799b1d1..2b85854e 100644
--- a/src/pulse/scache.h
+++ b/src/pulse/scache.h
@@ -84,15 +84,16 @@ PA_C_DECL_BEGIN
* PA_INVALID_INDEX on failure. \since 0.9.11 */
typedef void (*pa_context_play_sample_cb_t)(pa_context *c, uint32_t idx, void *userdata);
-/** Make this stream a sample upload stream */
+/** Make this stream a sample upload stream. Returns zero on success. */
int pa_stream_connect_upload(pa_stream *s, size_t length);
/** Finish the sample upload, the stream name will become the sample
* name. You cancel a sample upload by issuing
- * pa_stream_disconnect() */
+ * pa_stream_disconnect(). Returns zero on success. */
int pa_stream_finish_upload(pa_stream *s);
-/** Remove a sample from the sample cache. Returns an operation object which may be used to cancel the operation while it is running */
+/** Remove a sample from the sample cache. Returns an operation object which
+ * may be used to cancel the operation while it is running. */
pa_operation* pa_context_remove_sample(pa_context *c, const char *name, pa_context_success_cb_t cb, void *userdata);
/** Play a sample from the sample cache to the specified device. If
@@ -102,7 +103,7 @@ pa_operation* pa_context_play_sample(
pa_context *c /**< Context */,
const char *name /**< Name of the sample to play */,
const char *dev /**< Sink to play this sample on */,
- pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side which is a good idea. */ ,
+ pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ ,
pa_context_success_cb_t cb /**< Call this function after successfully starting playback, or NULL */,
void *userdata /**< Userdata to pass to the callback */);
@@ -114,7 +115,7 @@ pa_operation* pa_context_play_sample_with_proplist(
pa_context *c /**< Context */,
const char *name /**< Name of the sample to play */,
const char *dev /**< Sink to play this sample on */,
- pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side which is a good idea. */ ,
+ pa_volume_t volume /**< Volume to play this sample with. Starting with 0.9.15 you may pass here PA_VOLUME_INVALID which will leave the decision about the volume to the server side, which is a good idea. */ ,
pa_proplist *proplist /**< Property list for this sound. The property list of the cached entry will be merged into this property list */,
pa_context_play_sample_cb_t cb /**< Call this function after successfully starting playback, or NULL */,
void *userdata /**< Userdata to pass to the callback */);
diff --git a/src/pulse/simple.h b/src/pulse/simple.h
index 7b84f71b..44ae65d8 100644
--- a/src/pulse/simple.h
+++ b/src/pulse/simple.h
@@ -130,15 +130,16 @@ pa_simple* pa_simple_new(
/** Close and free the connection to the server. The connection object becomes invalid when this is called. */
void pa_simple_free(pa_simple *s);
-/** Write some data to the server. */
+/** Write some data to the server. Returns zero on success, negative on error. */
int pa_simple_write(pa_simple *s, const void *data, size_t bytes, int *error);
-/** Wait until all data already written is played by the daemon. */
+/** Wait until all data already written is played by the daemon.
+ * Returns zero on success, negative on error. */
int pa_simple_drain(pa_simple *s, int *error);
/** Read some data from the server. This function blocks until \a bytes amount
* of data has been received from the server, or until an error occurs.
- * Returns a negative value on failure. */
+ * Returns zero on success, negative on failure. */
int pa_simple_read(
pa_simple *s, /**< The connection object. */
void *data, /**< A pointer to a buffer. */
@@ -151,7 +152,8 @@ int pa_simple_read(
/** Return the playback or record latency. */
pa_usec_t pa_simple_get_latency(pa_simple *s, int *error);
-/** Flush the playback or record buffer. This discards any audio in the buffer. */
+/** Flush the playback or record buffer. This discards any audio in the buffer.
+ * Returns zero on success, negative on error. */
int pa_simple_flush(pa_simple *s, int *error);
PA_C_DECL_END
diff --git a/src/pulse/stream.h b/src/pulse/stream.h
index 7b9ba98b..68627984 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -186,7 +186,7 @@
* Once the stream is up, data can start flowing between the client and the
* server. Two different access models can be used to transfer the data:
*
- * \li Asynchronous - The application register a callback using
+ * \li Asynchronous - The application registers a callback using
* pa_stream_set_write_callback() and
* pa_stream_set_read_callback() to receive notifications
* that data can either be written or read.
@@ -222,9 +222,11 @@
* accomplish that the pa_stream_write() function takes a seek mode
* and an offset argument. The seek mode is one of:
*
- * \li PA_SEEK_RELATIVE - seek relative to the current write index
- * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer, (i.e. the first that was ever played in the stream)
- * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use this to write data to the output buffer that should be played as soon as possible
+ * \li PA_SEEK_RELATIVE - seek relative to the current write index.
+ * \li PA_SEEK_ABSOLUTE - seek relative to the beginning of the playback buffer,
+ * (i.e. the first that was ever played in the stream).
+ * \li PA_SEEK_RELATIVE_ON_READ - seek relative to the current read index. Use
+ * this to write data to the output buffer that should be played as soon as possible.
* \li PA_SEEK_RELATIVE_END - seek relative to the last byte ever written.
*
* If an application just wants to append some data to the output
@@ -309,10 +311,10 @@
* been created -- uncork them all with a single call to
* pa_stream_cork() for the master stream.
*
- * To make sure that a particular stream doesn't stop to play when a
+ * To make sure that a particular stream doesn't stop playing when a
* server side buffer underrun happens on it while the other
* synchronized streams continue playing and hence deviate, you need to
- * pass a "prebuf" pa_buffer_attr of 0 when connecting it.
+ * pass a pa_buffer_attr with prebuf set to 0 when connecting.
*
* \section disc_sec Disconnecting
*
@@ -396,7 +398,8 @@ pa_context* pa_stream_get_context(pa_stream *p);
/** Return the sink input resp.\ source output index this stream is
* identified in the server with. This is useful with the
* introspection functions such as pa_context_get_sink_input_info()
- * or pa_context_get_source_output_info(). */
+ * or pa_context_get_source_output_info(). This returns PA_INVALID_INDEX
+ * on failure. */
uint32_t pa_stream_get_index(pa_stream *s);
/** Return the index of the sink or source this stream is connected to
@@ -406,8 +409,8 @@ uint32_t pa_stream_get_index(pa_stream *s);
*
* Please note that streams may be moved between sinks/sources and thus
* it is recommended to use pa_stream_set_moved_callback() to be notified
- * about this. This function will return with -PA_ERR_NOTSUPPORTED when the
- * server is older than 0.9.8. \since 0.9.8 */
+ * about this. This function will return with PA_INVALID_INDEX on failure,
+ * including the being server older than 0.9.8. \since 0.9.8 */
uint32_t pa_stream_get_device_index(pa_stream *s);
/** Return the name of the sink or source this stream is connected to
@@ -417,8 +420,8 @@ uint32_t pa_stream_get_device_index(pa_stream *s);
*
* Please note that streams may be moved between sinks/sources and thus
* it is recommended to use pa_stream_set_moved_callback() to be notified
- * about this. This function will return with -PA_ERR_NOTSUPPORTED when the
- * server is older than 0.9.8. \since 0.9.8 */
+ * about this. This function will fail when the server is older than
+ * 0.9.8. \since 0.9.8 */
const char *pa_stream_get_device_name(pa_stream *s);
/** Return 1 if the sink or source this stream is connected to has
@@ -454,7 +457,9 @@ int pa_stream_is_corked(pa_stream *s);
*
* Since 5.0, it's possible to specify a single-channel volume even if the
* stream has multiple channels. In that case the same volume is applied to all
- * channels. */
+ * channels.
+ *
+ * Returns zero on success. */
int pa_stream_connect_playback(
pa_stream *s /**< The stream to connect to a sink */,
const char *dev /**< Name of the sink to connect to, or NULL for default */ ,
@@ -463,14 +468,14 @@ int pa_stream_connect_playback(
const pa_cvolume *volume /**< Initial volume, or NULL for default */,
pa_stream *sync_stream /**< Synchronize this stream with the specified one, or NULL for a standalone stream */);
-/** Connect the stream to a source. */
+/** Connect the stream to a source. Returns zero on success. */
int pa_stream_connect_record(
pa_stream *s /**< The stream to connect to a source */ ,
const char *dev /**< Name of the source to connect to, or NULL for default */,
const pa_buffer_attr *attr /**< Buffer attributes, or NULL for default */,
pa_stream_flags_t flags /**< Additional flags, or 0 for default */);
-/** Disconnect a stream from a source/sink. */
+/** Disconnect a stream from a source/sink. Returns zero on success. */
int pa_stream_disconnect(pa_stream *s);
/** Prepare writing data to the server (for playback streams). This
@@ -504,7 +509,14 @@ int pa_stream_disconnect(pa_stream *s);
* pa_stream_write() use pa_stream_cancel_write(). Calling
* pa_stream_begin_write() twice without calling pa_stream_write() or
* pa_stream_cancel_write() in between will return exactly the same
- * \a data pointer and \a nbytes values. \since 0.9.16 */
+ * \a data pointer and \a nbytes values.
+ *
+ * On success, will return zero and a valid (non-NULL) pointer. If the
+ * return value is non-zero, or the pointer is NULL, this indicates an
+ * error. Callers should also pay careful attention to the returned
+ * length, which may not be the same as that passed in, as mentioned above.
+ *
+ * \since 0.9.16 */
int pa_stream_begin_write(
pa_stream *p,
void **data,
@@ -517,8 +529,8 @@ int pa_stream_begin_write(
* pa_stream_cancel_write() nor pa_stream_write() have been called
* yet. Accessing the memory previously returned by
* pa_stream_begin_write() after this call is invalid. Any further
- * explicit freeing of the memory area is not necessary. \since
- * 0.9.16 */
+ * explicit freeing of the memory area is not necessary.
+ * Returns zero on success. \since 0.9.16 */
int pa_stream_cancel_write(
pa_stream *p);
@@ -530,9 +542,9 @@ int pa_stream_cancel_write(
*
* The client may freely seek around in the output buffer. For
* most applications it is typical to pass 0 and PA_SEEK_RELATIVE
- * as values for the arguments \a offset and \a seek. After the write
- * call succeeded the write index will be at the position after where
- * this chunk of data has been written to.
+ * as values for the arguments \a offset and \a seek respectively.
+ * After a successful write call the write index will be at the
+ * position after where this chunk of data has been written to.
*
* As an optimization for avoiding needless memory copies you may call
* pa_stream_begin_write() before this call and then place your audio
@@ -540,10 +552,12 @@ int pa_stream_cancel_write(
* a pointer to that memory area to pa_stream_write(). After the
* invocation of pa_stream_write() the memory area may no longer be
* accessed. Any further explicit freeing of the memory area is not
- * necessary. It is OK to write the memory area returned by
+ * necessary. It is OK to write to the memory area returned by
* pa_stream_begin_write() only partially with this call, skipping
* bytes both at the end and at the beginning of the reserved memory
- * area.*/
+ * area.
+ *
+ * Returns zero on success. */
int pa_stream_write(
pa_stream *p /**< The stream to use */,
const void *data /**< The data to write */,
@@ -578,14 +592,16 @@ int pa_stream_write_ext_free(
* Use pa_stream_drop() to actually remove the data from the buffer
* and move the read index forward. pa_stream_drop() should not be
* called if the buffer is empty, but it should be called if there is
- * a hole. */
+ * a hole.
+ *
+ * Returns zero on success, negative on error. */
int pa_stream_peek(
pa_stream *p /**< The stream to use */,
const void **data /**< Pointer to pointer that will point to data */,
size_t *nbytes /**< The length of the data read in bytes */);
/** Remove the current fragment on record streams. It is invalid to do this without first
- * calling pa_stream_peek(). */
+ * calling pa_stream_peek(). Returns zero on success. */
int pa_stream_drop(pa_stream *p);
/** Return the number of bytes requested by the server that have not yet
@@ -595,10 +611,14 @@ int pa_stream_drop(pa_stream *p);
* buffer_attr.maxlength bytes. This is usually not desirable, though, as
* it would increase stream latency to be higher than requested
* (buffer_attr.tlength).
+ *
+ * (size_t) -1 is returned on error.
*/
size_t pa_stream_writable_size(pa_stream *p);
-/** Return the number of bytes that may be read using pa_stream_peek(). */
+/** Return the number of bytes that may be read using pa_stream_peek().
+ *
+ * (size_t) -1 is returned on error. */
size_t pa_stream_readable_size(pa_stream *p);
/** Drain a playback stream. Use this for notification when the
@@ -635,7 +655,7 @@ int64_t pa_stream_get_underflow_index(pa_stream *p);
/** Set the callback function that is called when a buffer underflow happens. (Only for playback streams) */
void pa_stream_set_underflow_callback(pa_stream *p, pa_stream_notify_cb_t cb, void *userdata);
-/** Set the callback function that is called when a the server starts
+/** Set the callback function that is called when the server starts
* playback after an underrun or on initial startup. This only informs
* that audio is flowing again, it is no indication that audio started
* to reach the speakers already. (Only for playback streams) \since
@@ -736,7 +756,9 @@ pa_operation* pa_stream_set_name(pa_stream *s, const char *name, pa_stream_succe
*
* If no timing information has been
* received yet this call will return -PA_ERR_NODATA. For more details
- * see pa_stream_get_timing_info(). */
+ * see pa_stream_get_timing_info().
+ *
+ * Returns zero on success, negative on error. */
int pa_stream_get_time(pa_stream *s, pa_usec_t *r_usec);
/** Determine the total stream latency. This function is based on
@@ -757,14 +779,13 @@ int pa_stream_get_latency(pa_stream *s, pa_usec_t *r_usec, int *negative);
/** Return the latest raw timing data structure. The returned pointer
* refers to an internal read-only instance of the timing
- * structure. The user should make a copy of this structure if he
- * wants to modify it. An in-place update to this data structure may
- * be requested using pa_stream_update_timing_info().
+ * structure. The user should make a copy of this structure if
+ * wanting to modify it. An in-place update to this data structure
+ * may be requested using pa_stream_update_timing_info().
*
* If no timing information has been received before (i.e. by
* requesting pa_stream_update_timing_info() or by using
- * PA_STREAM_AUTO_TIMING_UPDATE), this function will fail with
- * -PA_ERR_NODATA.
+ * PA_STREAM_AUTO_TIMING_UPDATE), this function will return NULL.
*
* Please note that the write_index member field (and only this field)
* is updated on each pa_stream_write() call, not just when a timing
@@ -791,7 +812,7 @@ const pa_format_info* pa_stream_get_format_info(pa_stream *s);
const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
/** Change the buffer metrics of the stream during playback. The
- * server might have chosen different buffer metrics then
+ * server might have chosen different buffer metrics than
* requested. The selected metrics may be queried with
* pa_stream_get_buffer_attr() as soon as the callback is called. Only
* valid after the stream has been connected successfully and if the
@@ -821,13 +842,13 @@ pa_operation *pa_stream_proplist_remove(pa_stream *s, const char *const keys[],
/** For record streams connected to a monitor source: monitor only a
* very specific sink input of the sink. This function needs to be
- * called before pa_stream_connect_record() is called. \since
- * 0.9.11 */
+ * called before pa_stream_connect_record() is called.
+ * Returns zero on success, negative on error. \since 0.9.11 */
int pa_stream_set_monitor_stream(pa_stream *s, uint32_t sink_input_idx);
/** Return the sink input index previously set with
- * pa_stream_set_monitor_stream().
- * \since 0.9.11 */
+ * pa_stream_set_monitor_stream(). Returns PA_INVALID_INDEX
+ * on failure. \since 0.9.11 */
uint32_t pa_stream_get_monitor_stream(pa_stream *s);
PA_C_DECL_END
diff --git a/src/pulse/thread-mainloop.h b/src/pulse/thread-mainloop.h
index e69298aa..79c91eff 100644
--- a/src/pulse/thread-mainloop.h
+++ b/src/pulse/thread-mainloop.h
@@ -37,7 +37,7 @@ PA_C_DECL_BEGIN
*
* The added feature in the threaded main loop is that it spawns a new thread
* that runs the real main loop. This allows a synchronous application to use
- * the asynchronous API without risking to stall the PulseAudio library.
+ * the asynchronous API without risking stalling the PulseAudio library.
*
* \section creat_sec Creation
*
@@ -247,7 +247,7 @@ typedef struct pa_threaded_mainloop pa_threaded_mainloop;
/** Allocate a new threaded main loop object. You have to call
* pa_threaded_mainloop_start() before the event loop thread starts
- * running. */
+ * running. Free with pa_threaded_mainloop_free. */
pa_threaded_mainloop *pa_threaded_mainloop_new(void);
/** Free a threaded main loop object. If the event loop thread is
@@ -255,7 +255,7 @@ pa_threaded_mainloop *pa_threaded_mainloop_new(void);
* first. */
void pa_threaded_mainloop_free(pa_threaded_mainloop* m);
-/** Start the event loop thread. */
+/** Start the event loop thread. Returns zero on success, negative on error. */
int pa_threaded_mainloop_start(pa_threaded_mainloop *m);
/** Terminate the event loop thread cleanly. Make sure to unlock the
diff --git a/src/pulse/utf8.c b/src/pulse/utf8.c
index 31a61a02..3262eed5 100644
--- a/src/pulse/utf8.c
+++ b/src/pulse/utf8.c
@@ -33,7 +33,7 @@
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
- * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
diff --git a/src/pulse/volume.h b/src/pulse/volume.h
index 08db7cfe..2503c3f6 100644
--- a/src/pulse/volume.h
+++ b/src/pulse/volume.h
@@ -147,7 +147,9 @@ typedef struct pa_cvolume {
pa_volume_t values[PA_CHANNELS_MAX]; /**< Per-channel volume */
} pa_cvolume;
-/** Return non-zero when *a == *b */
+/** Return non-zero when *a == *b, checking that both a and b
+ * have the same number of channels and that the volumes of
+ * channels in a equal those in b. */
int pa_cvolume_equal(const pa_cvolume *a, const pa_cvolume *b) PA_GCC_PURE;
/** Initialize the specified volume and return a pointer to
@@ -171,7 +173,7 @@ pa_cvolume* pa_cvolume_set(pa_cvolume *a, unsigned channels, pa_volume_t v);
* might become part of an ABI.*/
#define PA_CVOLUME_SNPRINT_MAX 320
-/** Pretty print a volume structure */
+/** Pretty print a volume structure. Returns \a s. */
char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
/** Maximum length of the strings returned by
@@ -181,7 +183,7 @@ char *pa_cvolume_snprint(char *s, size_t l, const pa_cvolume *c);
* might become part of an ABI. \since 0.9.13 */
#define PA_SW_CVOLUME_SNPRINT_DB_MAX 448
-/** Pretty print a volume structure but show dB values. \since 0.9.13 */
+/** Pretty print a volume structure, showing dB values. Returns \a s. \since 0.9.13 */
char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
/** Maximum length of the strings returned by pa_cvolume_snprint_verbose().
@@ -193,7 +195,7 @@ char *pa_sw_cvolume_snprint_dB(char *s, size_t l, const pa_cvolume *c);
/** Pretty print a volume structure in a verbose way. The volume for each
* channel is printed in several formats: the raw pa_volume_t value,
* percentage, and if print_dB is non-zero, also the dB value. If map is not
- * NULL, the channel names will be printed. \since 5.0 */
+ * NULL, the channel names will be printed. Returns \a s. \since 5.0 */
char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const pa_channel_map *map, int print_dB);
/** Maximum length of the strings returned by
@@ -203,7 +205,7 @@ char *pa_cvolume_snprint_verbose(char *s, size_t l, const pa_cvolume *c, const p
* might become part of an ABI. \since 0.9.15 */
#define PA_VOLUME_SNPRINT_MAX 10
-/** Pretty print a volume \since 0.9.15 */
+/** Pretty print a volume. Returns \a s. \since 0.9.15 */
char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
/** Maximum length of the strings returned by
@@ -213,7 +215,7 @@ char *pa_volume_snprint(char *s, size_t l, pa_volume_t v);
* might become part of an ABI. \since 0.9.15 */
#define PA_SW_VOLUME_SNPRINT_DB_MAX 11
-/** Pretty print a volume but show dB values. \since 0.9.15 */
+/** Pretty print a volume but show dB values. Returns \a s. \since 0.9.15 */
char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
/** Maximum length of the strings returned by pa_volume_snprint_verbose().
@@ -224,7 +226,7 @@ char *pa_sw_volume_snprint_dB(char *s, size_t l, pa_volume_t v);
/** Pretty print a volume in a verbose way. The volume is printed in several
* formats: the raw pa_volume_t value, percentage, and if print_dB is non-zero,
- * also the dB value. \since 5.0 */
+ * also the dB value. Returns \a s. \since 5.0 */
char *pa_volume_snprint_verbose(char *s, size_t l, pa_volume_t v, int print_dB);
/** Return the average volume of all channels */
@@ -276,13 +278,13 @@ pa_volume_t pa_sw_volume_multiply(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
/** Multiply two per-channel volumes and return the result in
* *dest. This is only valid for software volumes! a, b and dest may
- * point to the same structure. */
+ * point to the same structure. Returns dest, or NULL on error. */
pa_cvolume *pa_sw_cvolume_multiply(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
/** Multiply a per-channel volume with a scalar volume and return the
* result in *dest. This is only valid for software volumes! a
- * and dest may point to the same structure. \since
- * 0.9.16 */
+ * and dest may point to the same structure. Returns dest, or NULL on error.
+ * \since 0.9.16 */
pa_cvolume *pa_sw_cvolume_multiply_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
/** Divide two volume specifications, return the result. This uses
@@ -293,13 +295,14 @@ pa_volume_t pa_sw_volume_divide(pa_volume_t a, pa_volume_t b) PA_GCC_CONST;
/** Divide two per-channel volumes and return the result in
* *dest. This is only valid for software volumes! a, b
- * and dest may point to the same structure. \since 0.9.13 */
+ * and dest may point to the same structure. Returns dest,
+ * or NULL on error. \since 0.9.13 */
pa_cvolume *pa_sw_cvolume_divide(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
/** Divide a per-channel volume by a scalar volume and return the
* result in *dest. This is only valid for software volumes! a
- * and dest may point to the same structure. \since
- * 0.9.16 */
+ * and dest may point to the same structure. Returns dest,
+ * or NULL on error. \since 0.9.16 */
pa_cvolume *pa_sw_cvolume_divide_scalar(pa_cvolume *dest, const pa_cvolume *a, pa_volume_t b);
/** Convert a decibel value to a volume (amplitude, not power). This is only valid for software volumes! */
@@ -308,8 +311,8 @@ pa_volume_t pa_sw_volume_from_dB(double f) PA_GCC_CONST;
/** Convert a volume to a decibel value (amplitude, not power). This is only valid for software volumes! */
double pa_sw_volume_to_dB(pa_volume_t v) PA_GCC_CONST;
-/** Convert a linear factor to a volume. 0.0 and less is muted while
- * 1.0 is PA_VOLUME_NORM. This is only valid for software volumes! */
+/** Convert a linear factor to a volume. 0.0 and less is muted while
+ * 1.0 is PA_VOLUME_NORM. This is only valid for software volumes! */
pa_volume_t pa_sw_volume_from_linear(double v) PA_GCC_CONST;
/** Convert a volume to a linear factor. This is only valid for software volumes! */
@@ -322,7 +325,8 @@ double pa_sw_volume_to_linear(pa_volume_t v) PA_GCC_CONST;
#define PA_DECIBEL_MININFTY ((double) -200.0)
#endif
-/** Remap a volume from one channel mapping to a different channel mapping. \since 0.9.12 */
+/** Remap a volume from one channel mapping to a different channel mapping.
+ * Returns \a v. \since 0.9.12 */
pa_cvolume *pa_cvolume_remap(pa_cvolume *v, const pa_channel_map *from, const pa_channel_map *to);
/** Return non-zero if the specified volume is compatible with the
@@ -348,7 +352,7 @@ float pa_cvolume_get_balance(const pa_cvolume *v, const pa_channel_map *map) PA_
* requested balance value (e.g. when the input volume was zero anyway for
* all channels). If no balance value is applicable to
* this channel map the volume will not be modified. See
- * pa_channel_map_can_balance(). \since 0.9.15 */
+ * pa_channel_map_can_balance(). Will return NULL on error. \since 0.9.15 */
pa_cvolume* pa_cvolume_set_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
/** Calculate a 'fade' value (i.e.\ 'balance' between front and rear)
@@ -366,7 +370,7 @@ float pa_cvolume_get_fade(const pa_cvolume *v, const pa_channel_map *map) PA_GCC
* return the requested fade value (e.g. when the input volume was
* zero anyway for all channels). If no fade value is applicable to
* this channel map the volume will not be modified. See
- * pa_channel_map_can_fade(). \since 0.9.15 */
+ * pa_channel_map_can_fade(). Will return NULL on error. \since 0.9.15 */
pa_cvolume* pa_cvolume_set_fade(pa_cvolume *v, const pa_channel_map *map, float new_fade);
/** Calculate a 'lfe balance' value for the specified volume with
@@ -384,25 +388,28 @@ float pa_cvolume_get_lfe_balance(const pa_cvolume *v, const pa_channel_map *map)
* return the requested value (e.g. when the input volume was
* zero anyway for all channels). If no lfe balance value is applicable to
* this channel map the volume will not be modified. See
- * pa_channel_map_can_lfe_balance(). \since 8.0 */
+ * pa_channel_map_can_lfe_balance(). Will return NULL on error. \since 8.0 */
pa_cvolume* pa_cvolume_set_lfe_balance(pa_cvolume *v, const pa_channel_map *map, float new_balance);
/** Scale the passed pa_cvolume structure so that the maximum volume
* of all channels equals max. The proportions between the channel
- * volumes are kept. \since 0.9.15 */
+ * volumes are kept. Returns \a v, or NULL on error. \since 0.9.15 */
pa_cvolume* pa_cvolume_scale(pa_cvolume *v, pa_volume_t max);
/** Scale the passed pa_cvolume structure so that the maximum volume
* of all channels selected via cm/mask equals max. This also modifies
* the volume of those channels that are unmasked. The proportions
- * between the channel volumes are kept. \since 0.9.16 */
+ * between the channel volumes are kept. If cm is NULL this call is
+ * identical to pa_cvolume_scale(). Returns \a v, or NULL on error.
+ * \since 0.9.16 */
pa_cvolume* pa_cvolume_scale_mask(pa_cvolume *v, pa_volume_t max, const pa_channel_map *cm, pa_channel_position_mask_t mask);
/** Set the passed volume to all channels at the specified channel
* position. Will return the updated volume struct, or NULL if there
* is no channel at the position specified. You can check if a channel
* map includes a specific position by calling
- * pa_channel_map_has_position(). \since 0.9.16 */
+ * pa_channel_map_has_position(). Returns \a cv, or NULL on error.
+ * \since 0.9.16 */
pa_cvolume* pa_cvolume_set_position(pa_cvolume *cv, const pa_channel_map *map, pa_channel_position_t t, pa_volume_t v);
/** Get the maximum volume of all channels at the specified channel
@@ -413,19 +420,21 @@ pa_volume_t pa_cvolume_get_position(pa_cvolume *cv, const pa_channel_map *map, p
/** This goes through all channels in a and b and sets the
* corresponding channel in dest to the greater volume of both. a, b
- * and dest may point to the same structure. \since 0.9.16 */
+ * and dest may point to the same structure. Returns \a dest, or NULL
+ * on error. \since 0.9.16 */
pa_cvolume* pa_cvolume_merge(pa_cvolume *dest, const pa_cvolume *a, const pa_cvolume *b);
/** Increase the volume passed in by 'inc', but not exceeding 'limit'.
- * The proportions between the channels are kept. \since 0.9.19 */
+ * The proportions between the channels are kept.
+ * Returns \a v, or NULL on error. \since 0.9.19 */
pa_cvolume* pa_cvolume_inc_clamp(pa_cvolume *v, pa_volume_t inc, pa_volume_t limit);
/** Increase the volume passed in by 'inc'. The proportions between
- * the channels are kept. \since 0.9.16 */
+ * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */
pa_cvolume* pa_cvolume_inc(pa_cvolume *v, pa_volume_t inc);
/** Decrease the volume passed in by 'dec'. The proportions between
- * the channels are kept. \since 0.9.16 */
+ * the channels are kept. Returns \a v, or NULL on error. \since 0.9.16 */
pa_cvolume* pa_cvolume_dec(pa_cvolume *v, pa_volume_t dec);
PA_C_DECL_END
From a745f61cdb607365d3478e3fdfbcb7706e8f9787 Mon Sep 17 00:00:00 2001
From: jnqnfe <jnq...@gmail.com>
Date: Fri, 8 Sep 2017 04:31:42 +0100
Subject: doc: merge and deduplicate some pa_buffer_attr documentation
diff --git a/src/pulse/def.h b/src/pulse/def.h
index 7211b60e..100df5b5 100644
--- a/src/pulse/def.h
+++ b/src/pulse/def.h
@@ -401,13 +401,18 @@ typedef struct pa_buffer_attr {
uint32_t tlength;
/**< Playback only: target length of the buffer. The server tries
* to assure that at least tlength bytes are always available in
- * the per-stream server-side playback buffer. It is recommended
- * to set this to (uint32_t) -1, which will initialize this to a
- * value that is deemed sensible by the server. However, this
- * value will default to something like 2s, i.e. for applications
- * that have specific latency requirements this value should be
- * set to the maximum latency that the application can deal
- * with. When PA_STREAM_ADJUST_LATENCY is not set this value will
+ * the per-stream server-side playback buffer. The server will
+ * only send requests for more data as long as the buffer has
+ * less than this number of bytes of data.
+ *
+ * It is recommended to set this to (uint32_t) -1, which will
+ * initialize this to a value that is deemed sensible by the
+ * server. However, this value will default to something like 2s;
+ * for applications that have specific latency requirements
+ * this value should be set to the maximum latency that the
+ * application can deal with.
+ *
+ * When PA_STREAM_ADJUST_LATENCY is not set this value will
* influence only the per-stream playback buffer size. When
* PA_STREAM_ADJUST_LATENCY is set the overall latency of the sink
* plus the playback buffer size is configured to this value. Set
@@ -421,11 +426,19 @@ typedef struct pa_buffer_attr {
* playback before at least prebuf bytes are available in the
* buffer. It is recommended to set this to (uint32_t) -1, which
* will initialize this to the same value as tlength, whatever
- * that may be. Initialize to 0 to enable manual start/stop
- * control of the stream. This means that playback will not stop
- * on underrun and playback will not start automatically. Instead
- * pa_stream_cork() needs to be called explicitly. If you set
- * this value to 0 you should also set PA_STREAM_START_CORKED. */
+ * that may be.
+ *
+ * Initialize to 0 to enable manual start/stop control of the stream.
+ * This means that playback will not stop on underrun and playback
+ * will not start automatically, instead pa_stream_cork() needs to
+ * be called explicitly. If you set this value to 0 you should also
+ * set PA_STREAM_START_CORKED. Should underrun occur, the read index
+ * of the output buffer overtakes the write index, and hence the
+ * fill level of the buffer is negative.
+ *
+ * Start of playback can be forced using pa_stream_trigger() even
+ * though the prebuffer size hasn't been reached. If a buffer
+ * underrun occurs, this prebuffering will be again enabled. */
uint32_t minreq;
/**< Playback only: minimum request. The server does not request
@@ -444,11 +457,12 @@ typedef struct pa_buffer_attr {
* but decrease control overhead. It is recommended to set this to
* (uint32_t) -1, which will initialize this to a value that is
* deemed sensible by the server. However, this value will default
- * to something like 2s, i.e. for applications that have specific
+ * to something like 2s; For applications that have specific
* latency requirements this value should be set to the maximum
- * latency that the application can deal with. If
- * PA_STREAM_ADJUST_LATENCY is set the overall source latency will
- * be adjusted according to this value. If it is not set the
+ * latency that the application can deal with.
+ *
+ * If PA_STREAM_ADJUST_LATENCY is set the overall source latency
+ * will be adjusted according to this value. If it is not set the
* source latency is left unmodified. */
} pa_buffer_attr;
diff --git a/src/pulse/stream.h b/src/pulse/stream.h
index 68627984..4efba934 100644
--- a/src/pulse/stream.h
+++ b/src/pulse/stream.h
@@ -92,68 +92,20 @@
* overflows/underruns.
*
* The buffer metrics may be controlled by the application. They are
- * described with a pa_buffer_attr structure which contains a number
- * of fields:
- *
- * \li maxlength - The absolute maximum number of bytes that can be
- * stored in the buffer. If this value is exceeded
- * then data will be lost. It is recommended to pass
- * (uint32_t) -1 here which will cause the server to
- * fill in the maximum possible value.
- *
- * \li tlength - The target fill level of the playback buffer. The
- * server will only send requests for more data as long
- * as the buffer has less than this number of bytes of
- * data. If you pass (uint32_t) -1 (which is
- * recommended) here the server will choose the longest
- * target buffer fill level possible to minimize the
- * number of necessary wakeups and maximize drop-out
- * safety. This can exceed 2s of buffering. For
- * low-latency applications or applications where
- * latency matters you should pass a proper value here.
- *
- * \li prebuf - Number of bytes that need to be in the buffer before
- * playback will commence. Start of playback can be
- * forced using pa_stream_trigger() even though the
- * prebuffer size hasn't been reached. If a buffer
- * underrun occurs, this prebuffering will be again
- * enabled. If the playback shall never stop in case of a
- * buffer underrun, this value should be set to 0. In
- * that case the read index of the output buffer
- * overtakes the write index, and hence the fill level of
- * the buffer is negative. If you pass (uint32_t) -1 here
- * (which is recommended) the server will choose the same
- * value as tlength here.
- *
- * \li minreq - Minimum number of free bytes in the playback
- * buffer before the server will request more data. It is
- * recommended to fill in (uint32_t) -1 here. This value
- * influences how much time the sound server has to move
- * data from the per-stream server-side playback buffer
- * to the hardware playback buffer.
- *
- * \li fragsize - Maximum number of bytes that the server will push in
- * one chunk for record streams. If you pass (uint32_t)
- * -1 (which is recommended) here, the server will
- * choose the longest fragment setting possible to
- * minimize the number of necessary wakeups and
- * maximize drop-out safety. This can exceed 2s of
- * buffering. For low-latency applications or
- * applications where latency matters you should pass a
- * proper value here.
+ * described with a pa_buffer_attr structure.
*
* If PA_STREAM_ADJUST_LATENCY is set, then the tlength/fragsize
- * parameters will be interpreted slightly differently than described
- * above when passed to pa_stream_connect_record() and
- * pa_stream_connect_playback(): the overall latency that is comprised
- * of both the server side playback buffer length, the hardware
- * playback buffer length and additional latencies will be adjusted in
- * a way that it matches tlength resp. fragsize. Set
- * PA_STREAM_ADJUST_LATENCY if you want to control the overall
- * playback latency for your stream. Unset it if you want to control
- * only the latency induced by the server-side, rewritable playback
- * buffer. The server will try to fulfill the client's latency requests
- * as good as possible. However if the underlying hardware cannot
+ * parameters of the pa_buffer_attr structure will be interpreted
+ * slightly differently than otherwise when passed to
+ * pa_stream_connect_record() and pa_stream_connect_playback(): the
+ * overall latency that is comprised of both the server side playback
+ * buffer length, the hardware playback buffer length and additional
+ * latencies will be adjusted in a way that it matches tlength resp.
+ * fragsize. Set PA_STREAM_ADJUST_LATENCY if you want to control the
+ * overall playback latency for your stream. Unset it if you want to
+ * control only the latency induced by the server-side, rewritable
+ * playback buffer. The server will try to fulfill the client's latency
+ * requests as good as possible. However if the underlying hardware cannot
* change the hardware buffer length or only in a limited range, the
* actually resulting latency might be different from what the client
* requested. Thus, for synchronization clients always need to check
@@ -164,8 +116,8 @@
* tlength/fragsize, regardless whether PA_STREAM_ADJUST_LATENCY is
* set or not.
*
- * The server-side per-stream playback buffers are indexed by a write and a read
- * index. The application writes to the write index and the sound
+ * The server-side per-stream playback buffers are indexed by a write and
+ * a read index. The application writes to the write index and the sound
* device reads from the read index. The read index is increased
* monotonically, while the write index may be freely controlled by
* the application. Subtracting the read index from the write index
_______________________________________________
pulseaudio-discuss mailing list
pulseaudio-discuss@lists.freedesktop.org
https://lists.freedesktop.org/mailman/listinfo/pulseaudio-discuss
