mirrors/pulseaudio
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pulseaudio/pulseaudio.git synced 2025-10-29 05:40:23 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

prepare doxygen docs for 0.9.11

Browse source
This commit is contained in:
Lennart Poettering 2008-07-21 18:55:17 +02:00
parent d0530b0359
commit c1f9f95fa2
8 changed files with 174 additions and 78 deletions
Download patch file Download diff file Expand all files Collapse all files

6
src/pulse/channelmap.h
View file

@ -47,8 +47,10 @@
*
* \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 up to
* six 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 noone
* predefined one is known for the specified number of channels.
*
* \section conv_sec Convenience Functions
*

5
src/pulse/context.h
View file

@ -35,7 +35,7 @@
* \section overv_sec Overview
*
* The asynchronous API is the native interface to the PulseAudio library.
* It allows full access to all available functions. This also means that
* It allows full access to all available functionality. This however means that
* it is rather complex and can take some time to fully master.
*
* \section mainloop_sec Main Loop Abstraction
@ -64,8 +64,7 @@
* implementation where all of PulseAudio's
* internal handling runs in a separate
* thread.
* \li \subpage glib-mainloop - A wrapper around GLIB's main loop. Available
* for both GLIB 1.2 and GLIB 2.x.
* \li \subpage glib-mainloop - A wrapper around GLib's main loop.
*
* UNIX signals may be hooked to a main loop using the functions from
* \ref mainloop-signal.h. These rely only on the main loop abstraction

72
src/pulse/def.h
View file

@ -233,12 +233,11 @@ typedef enum pa_stream_flags {
PA_STREAM_START_MUTED = 4096, /**< Create in muted state. \since 0.9.11 */
PA_STREAM_ADJUST_LATENCY = 8192, /**< Try to adjust the latency of
* the sink/source based on the
* requested buffer metrics and
* adjust buffer metrics
* accordingly. \since 0.9.11 */
* accordingly. See pa_buffer_attr \since 0.9.11 */
} pa_stream_flags_t;
@ -248,53 +247,86 @@ typedef enum pa_stream_flags {
/** Playback and record buffer metrics */
typedef struct pa_buffer_attr {
uint32_t maxlength; /**< Maximum length of the
* buffer. Setting this to 0 will
* buffer. Setting this to (uint32_t) -1 will
* initialize this to the maximum value
* supported by server, which is
* recommended. */
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 buffer. It is
* recommended to set this to 0, which
* will initialize this to a value that
* is deemed sensible by the
* 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. */
* 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
* PA_STREAM_ADJUST_LATENCY if you are
* interested in adjusting the overall
* latency. Don't set it if you are
* interested in configuring the
* server-sider per-stream playback
* buffer size. */
uint32_t prebuf; /**< Playback only: pre-buffering. The
* server does not start with playback
* before at least prebug bytes are
* available in the buffer. It is
* recommended to set this to 0, which
* will initialize this to the same value
* as tlength, whatever that may be. */
* 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_corked() needs to be called
* explicitly. If you set this value to 0
* you should also set
* PA_STREAM_START_CORKED. */
uint32_t minreq; /**< Playback only: minimum request. The
* server does not request less than
* minreq bytes from the client, instead
* waits until the buffer is free enough
* to request more bytes at once. It is
* recommended to set this to 0, which
* will initialize this to a value that
* is deemed sensible by the server. */
* recommended to set this to (uint32_t)
* -1, which will initialize this to a
* value that is deemed sensible by the
* server. This should be set to a value
* that gives PulseAudio enough time to
* move the data from the per-stream
* playback buffer into the hardware
* playback buffer. */
uint32_t fragsize; /**< Recording only: fragment size. The
* server sends data in blocks of
* fragsize bytes size. Large values
* deminish interactivity with other
* operations on the connection context
* but decrease control overhead. It is
* recommended to set this to 0, which
* will initialize this to a value that
* is deemed sensible by the
* 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. */
* 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;
/** Error values as used by pa_context_errno(). Use pa_strerror() to convert these values to human readable strings */
@ -431,9 +463,9 @@ typedef struct pa_timing_info {
* PA_SEEK_RELATIVE_ON_READ
* instead. */
pa_usec_t configured_sink_usec; /**< The static configured latency for
pa_usec_t configured_sink_usec; /**< The configured latency for
* the sink. \since 0.9.11 */
pa_usec_t configured_source_usec; /**< The static configured latency for
pa_usec_t configured_source_usec; /**< The configured latency for
* the source. \since 0.9.11 */
int64_t since_underrun; /**< Bytes that were handed to the sink

10
src/pulse/introspect.h
View file

@ -130,8 +130,10 @@
*
* \subsection autoload_subsec Autoload Entries
*
* Modules can be autoloaded as a result of a client requesting a certain
* sink or source. This mapping between sink/source names and modules can be
* Modules can be autoloaded as a result of a client requesting a
* certain sink or source. Please note that autoloading is deprecated
* in 0.9.11. and is likely to be removed from the API in a later
* version. This mapping between sink/source names and modules can be
* queried from the server:
*
* \li By index - pa_context_get_autoload_info_by_index()
@ -191,7 +193,9 @@
*
* New module autoloading rules can be added, and existing can be removed
* using pa_context_add_autoload() and pa_context_remove_autoload_by_index()
* / pa_context_remove_autoload_by_name().
* / pa_context_remove_autoload_by_name(). Please note that autoloading is deprecated
* in 0.9.11. and is likely to be removed from the API in a later
* version.
*
* \subsection client_subsec Clients
*

34
src/pulse/proplist.h
View file

@ -36,19 +36,20 @@ PA_C_DECL_BEGIN
* media.artist "Guns'N'Roses"
* media.language "de_DE"
* media.filename
* media.icon
* media.icon_name
* media.icon Binary blob containing PNG icon data
* media.icon_name Name from XDG icon naming spec
* media.role video, music, game, event, phone, production, filter, abstract, stream
* event.id button-click, session-login
* event.id Name from XDG sound naming spec
* event.description "Button blabla clicked" for a11y
* event.mouse.x
* event.mouse.y
* event.mouse.hpos
* event.mouse.vpos
* event.mouse.button
* event.mouse.hpos Float formatted as string in range 0..1
* event.mouse.vpos Float formatted as string in range 0..1
* event.mouse.button Button number following X11 ordering
* window.name
* window.id
* window.icon
* window.icon_name
* window.id "org.gnome.rhytmbox.MainWindow"
* window.icon Binary blob containing PNG icon data
* window.icon_name Name from XDG icon naming spec
* window.x11.display
* window.x11.screen
* window.x11.monitor
@ -56,23 +57,23 @@ PA_C_DECL_BEGIN
* application.name "Rhythmbox Media Player"
* application.id "org.gnome.rhythmbox"
* application.version
* application.icon
* application.icon_name
* application.icon Binary blob containing PNG icon data
* application.icon_name Name from XDG icon naming spec
* application.language
* application.process.id
* application.process.binary
* application.process.user
* application.process.host
* device.string
* device.api oss, alsa, sunaudio
* device.api oss, alsa, sunaudio
* device.description
* device.bus_path
* device.serial
* device.vendor_product_id
* device.class sound, modem, monitor, filter, abstract
* device.form_factor laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset
* device.connector isa, pci, usb, firewire, bluetooth
* device.access_mode mmap, mmap_rewrite, serial
* device.class sound, modem, monitor, filter, abstract
* device.form_factor laptop-speakers, external-speakers, telephone, tv-capture, webcam-capture, microphone-capture, headset
* device.connector isa, pci, usb, firewire, bluetooth
* device.access_mode mmap, mmap_rewrite, serial
* device.master_device
* device.bufferin.buffer_size
* device.bufferin.fragment_size
@ -86,6 +87,7 @@ PA_C_DECL_BEGIN
#define PA_PROP_MEDIA_ICON_NAME "media.icon_name"
#define PA_PROP_MEDIA_ROLE "media.role"
#define PA_PROP_EVENT_ID "event.id"
#define PA_PROP_EVENT_DESCRIPTION "event.description"
#define PA_PROP_EVENT_MOUSE_X "event.mouse.x"
#define PA_PROP_EVENT_MOUSE_Y "event.mouse.y"
#define PA_PROP_EVENT_MOUSE_HPOS "event.mouse.hpos"

10
src/pulse/pulseaudio.h
View file

@ -89,17 +89,17 @@
*
* \section thread_sec Threads
*
* The PulseAudio client libraries are not designed to be used in a
* heavily threaded environment. They are however designed to be reentrant
* safe.
* The PulseAudio client libraries are not designed to be directly
* thread-safe. They are however designed to be reentrant and
* threads-aware.
*
* To use a the libraries in a threaded environment, you must assure that
* To use the libraries in a threaded environment, you must assure that
* all objects are only used in one thread at a time. Normally, this means
* that all objects belonging to a single context must be accessed from the
* same thread.
*
* The included main loop implementation is also not thread safe. Take care
* to make sure event lists are not manipulated when any other code is
* to make sure event objects are not manipulated when any other code is
* using the main loop.
*
* \section pkgconfig pkg-config

2
src/pulse/sample.h
View file

@ -52,7 +52,7 @@
* \li PA_SAMPLE_S32LE - Signed 32 bit integer PCM, little endian.
* \li PA_SAMPLE_S32BE - Signed 32 bit integer PCM, big endian.
*
* The floating point sample formats have the range from -1 to 1.
* The floating point sample formats have the range from -1.0 to 1.0.
*
* The sample formats that are sensitive to endianness have convenience
* macros for native endian (NE), and reverse endian (RE).

113
src/pulse/stream.h
View file

@ -70,35 +70,85 @@
*
* \subsection bufattr_subsec Buffer Attributes
*
* Playback and record streams always have a server side buffer as
* part of the data flow. The size of this buffer strikes a
* compromise between low latency and sensitivity for buffer
* Playback and record streams always have a server-side buffer as
* part of the data flow. The size of this buffer needs to be chosen
* in a compromise between low latency and sensitivity for buffer
* 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.
* \li tlength - The target length of a 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.
* \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.
* \li minreq - Minimum free number of the bytes in the playback buffer before
* the server will request more data.
* \li fragsize - Maximum number of bytes that the server will push in one
* chunk for record streams.
* \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.
*
* The server side playback buffers are indexed by a write and a read
* \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 free number of the 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.
*
* 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 clients 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
* the actual measured latency via pa_stream_get_latency() or a
* similar call, and not make any assumptions. about the latency
* available. The function pa_stream_get_buffer_attr() will always
* return the actual size of the server-side per-stream buffer in
* 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
* device reads from the read index. The read index is increased
* monotonically, while the write index may be freely controlled by
@ -196,10 +246,10 @@
* accordingly.
*
* The raw timing data in the pa_timing_info structure is usually hard
* to deal with. Therefore a more simplistic interface is available:
* to deal with. Therefore a simpler interface is available:
* you can call pa_stream_get_time() or pa_stream_get_latency(). The
* former will return the current playback time of the hardware since
* the stream has been started. The latter returns the time a sample
* the stream has been started. The latter returns the overall time a sample
* that you write now takes to be played by the hardware. These two
* functions base their calculations on the same data that is returned
* by pa_stream_get_timing_info(). Hence the same rules for keeping
@ -512,9 +562,14 @@ const pa_sample_spec* pa_stream_get_sample_spec(pa_stream *s);
/** Return a pointer to the stream's channel map. */
const pa_channel_map* pa_stream_get_channel_map(pa_stream *s);
/** Return the buffer metrics of the stream. Only valid after the
* stream has been connected successfuly and if the server is at least
* PulseAudio 0.9. \since 0.9.0 */
/** Return the per-stream server-side buffer metrics of the
* stream. Only valid after the stream has been connected successfuly
* and if the server is at least PulseAudio 0.9. This will return the
* actual configured buffering metrics, which may differ from what was
* requested during pa_stream_connect_record() or
* pa_stream_connect_playback(). This call will always return the
* actually per-stream server-side buffer metrics, regardless whether
* PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.0 */
const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
/** Change the buffer metrics of the stream during playback. The
@ -522,7 +577,9 @@ const pa_buffer_attr* pa_stream_get_buffer_attr(pa_stream *s);
* 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
* server is at least PulseAudio 0.9.8. \since 0.9.8 */
* server is at least PulseAudio 0.9.8. Please be aware of the
* slightly different semantics of the call depending whether
* PA_STREAM_ADJUST_LATENCY is set or not. \since 0.9.8 */
pa_operation *pa_stream_set_buffer_attr(pa_stream *s, const pa_buffer_attr *attr, pa_stream_success_cb_t cb, void *userdata);
/** Change the stream sampling rate during playback. You need to pass