mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2025-12-14 08:56:37 -05:00
doc: reorganize Doxygen groups/modules to make more sense
The Doxygen "Modules" page is not very illuminative, as different parts of the API are mixed together and not all parts are included. Try to address this: Put all parts of the public API to some Doxygen group, usually one group per header file. Use short, systematic names. Make these groups sub-groups of a few top-level groups, roughly corresponding to the different logical parts of the API (core, impl, stream, filter, spa, utilities).
This commit is contained in:
Pauli Virtanen
parent
43a84c4a2c
commit
8159797f89
95 changed files with 588 additions and 154 deletions
|
|
@ -9,6 +9,7 @@ EXTRACT_ALL = YES
|
|||
EXTRACT_STATIC = YES
|
||||
FULL_PATH_NAMES = YES
|
||||
STRIP_FROM_PATH = @path_prefixes@
|
||||
STRIP_FROM_INC_PATH = @path_prefixes@
|
||||
SHOW_INCLUDE_FILES = NO
|
||||
GENERATE_TODOLIST = NO
|
||||
GENERATE_TESTLIST = NO
|
||||
|
|
|
|||
127
doc/api-tree.dox
Normal file
127
doc/api-tree.dox
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
/**
|
||||
|
||||
\defgroup api_pw_core Core API
|
||||
\brief PipeWire Core API
|
||||
\{
|
||||
\addtogroup pw_pipewire
|
||||
\addtogroup pw_context
|
||||
\addtogroup pw_client
|
||||
\addtogroup pw_core
|
||||
\addtogroup pw_device
|
||||
\addtogroup pw_factory
|
||||
\addtogroup pw_link
|
||||
\addtogroup pw_loop
|
||||
\addtogroup pw_module
|
||||
\addtogroup pw_node
|
||||
\addtogroup pw_permission
|
||||
\addtogroup pw_port
|
||||
\addtogroup pw_proxy
|
||||
\addtogroup pw_registry
|
||||
\addtogroup pw_type
|
||||
\addtogroup pw_keys
|
||||
\}
|
||||
|
||||
\defgroup api_pw_impl Implementation API
|
||||
\brief PipeWire Object Implementation API
|
||||
\{
|
||||
\addtogroup pw_impl_client
|
||||
\addtogroup pw_impl_core
|
||||
\addtogroup pw_impl_device
|
||||
\addtogroup pw_impl_factory
|
||||
\addtogroup pw_impl_link
|
||||
\addtogroup pw_impl_metadata
|
||||
\addtogroup pw_impl_module
|
||||
\addtogroup pw_impl_node
|
||||
\addtogroup pw_impl_port
|
||||
\addtogroup pw_buffers
|
||||
\addtogroup pw_control
|
||||
\addtogroup pw_data_loop
|
||||
\addtogroup pw_global
|
||||
\addtogroup pw_protocol
|
||||
\addtogroup pw_resource
|
||||
\addtogroup pw_thread_loop
|
||||
\addtogroup pw_work_queue
|
||||
\}
|
||||
|
||||
\defgroup api_pw_util Utilities
|
||||
\brief PipeWire Utilities
|
||||
\{
|
||||
\addtogroup pw_array
|
||||
\addtogroup pw_conf
|
||||
\addtogroup pw_gettext
|
||||
\addtogroup pw_log
|
||||
\addtogroup pw_main_loop
|
||||
\addtogroup pw_map
|
||||
\addtogroup pw_memblock
|
||||
\addtogroup pw_properties
|
||||
\addtogroup pw_thread
|
||||
\addtogroup pw_utils
|
||||
\}
|
||||
|
||||
\defgroup api_pw_ext Extensions
|
||||
\brief PipeWire Extensions
|
||||
\{
|
||||
\addtogroup pw_client_node
|
||||
\addtogroup pw_metadata
|
||||
\addtogroup pw_profiler
|
||||
\addtogroup pw_protocol_native
|
||||
\addtogroup pw_session_manager
|
||||
\{
|
||||
\addtogroup pw_session_manager_impl
|
||||
\}
|
||||
\}
|
||||
|
||||
\defgroup api_spa SPA
|
||||
\brief Simple Plugin API
|
||||
\{
|
||||
\addtogroup spa_buffer
|
||||
\addtogroup spa_control
|
||||
\addtogroup spa_debug
|
||||
\addtogroup spa_device
|
||||
\addtogroup spa_graph
|
||||
\addtogroup spa_node
|
||||
\addtogroup spa_param
|
||||
\addtogroup spa_pod
|
||||
\defgroup spa_utils Utilities
|
||||
\{
|
||||
\addtogroup spa_ansi
|
||||
\addtogroup spa_utils_defs
|
||||
\addtogroup spa_dict
|
||||
\addtogroup spa_list
|
||||
\addtogroup spa_hooks
|
||||
\addtogroup spa_interfaces
|
||||
\addtogroup spa_json
|
||||
\addtogroup spa_keys
|
||||
\addtogroup spa_names
|
||||
\addtogroup spa_result
|
||||
\addtogroup spa_ringbuffer
|
||||
\addtogroup spa_string
|
||||
\addtogroup spa_types
|
||||
\}
|
||||
\defgroup spa_support Support
|
||||
\{
|
||||
\addtogroup spa_cpu
|
||||
\addtogroup spa_dbus
|
||||
\addtogroup spa_i18n
|
||||
\addtogroup spa_log
|
||||
\addtogroup spa_loop
|
||||
\addtogroup spa_handle
|
||||
\addtogroup spa_plugin_loader
|
||||
\addtogroup spa_system
|
||||
\addtogroup spa_thread
|
||||
\}
|
||||
\}
|
||||
|
||||
\defgroup pw_stream Stream API
|
||||
\{
|
||||
\}
|
||||
|
||||
\defgroup pw_filter Filter API
|
||||
\{
|
||||
\}
|
||||
|
||||
\defgroup pwtest Test Suite
|
||||
\{
|
||||
\}
|
||||
|
||||
*/
|
||||
61
doc/api.dox
61
doc/api.dox
|
|
@ -1,15 +1,23 @@
|
|||
/** \page page_api API Documentation
|
||||
/** \page page_api PipeWire API
|
||||
|
||||
The API consists of two parts:
|
||||
The PipeWire API consists of several parts:
|
||||
|
||||
- The \ref page_core_api to access a PipeWire instance. This API is used
|
||||
- The \ref pw_stream for a convenient way to send and receive data streams from/to PipeWire.
|
||||
|
||||
- The \ref pw_filter for a convenient way to implement processing filters.
|
||||
|
||||
- The \ref api_pw_core to access a PipeWire instance. This API is used
|
||||
by all clients that need to communicate with the \ref page_daemon and provides
|
||||
the necessary structs to interface with the daemon.
|
||||
- The \ref page_implementation_api and tools to build new objects and modules.
|
||||
This API is primarily used by the \ref page_daemon itself but also by the
|
||||
|
||||
- The \ref api_pw_impl is primarily used by the \ref page_daemon itself but also by the
|
||||
\ref page_session_manager and modules/extensions that need to build objects in
|
||||
the graph.
|
||||
|
||||
- The \ref api_pw_util containing various utility functions and structures.
|
||||
|
||||
- The \ref api_pw_ext for interfacing with certain extension modules.
|
||||
|
||||
The APIs work through proxy objects, so that calling a method on an object
|
||||
invokes that same method on the remote side. Marshalling and de-marshalling is
|
||||
handled transparently by the \ref page_module_protocol_native.
|
||||
|
|
@ -48,47 +56,32 @@ digraph API {
|
|||
}
|
||||
\enddot
|
||||
|
||||
It is common for clients to use both the Core API and the Implementation API
|
||||
It is common for clients to use both the \ref api_pw_core and the \ref api_pw_impl
|
||||
and both APIs are provided by the same library.
|
||||
|
||||
\section page_core_api Core API
|
||||
|
||||
The Core API serves to access a PipeWire instance. This API is used by all
|
||||
clients to communicate with the \ref page_daemon. It consists of the
|
||||
following object-specific APIs:
|
||||
|
||||
- \ref pw_core
|
||||
- \ref pw_context
|
||||
- \ref pw_global
|
||||
- \ref pw_client
|
||||
- \ref pw_resource
|
||||
- \ref pw_node
|
||||
- \ref pw_port
|
||||
- \ref pw_link
|
||||
|
||||
|
||||
\addtogroup api_pw_core Core API
|
||||
|
||||
The Core API to access a PipeWire instance. This API is used by all
|
||||
clients to communicate with the \ref page_daemon.
|
||||
|
||||
If you are familiar with Wayland implementation, the Core API is
|
||||
roughly equivalent to libwayland-client.
|
||||
|
||||
\section page_implementation_api Implementation API
|
||||
See: \ref page_api
|
||||
|
||||
|
||||
\addtogroup api_pw_impl Implementation API
|
||||
|
||||
The implementation API provides the tools to build new objects and
|
||||
modules. It consists of the following object-specific APIs:
|
||||
|
||||
- \ref pw_impl_core
|
||||
- \ref pw_impl_client
|
||||
- \ref pw_impl_device
|
||||
- \ref pw_impl_factory
|
||||
- \ref pw_impl_link
|
||||
- \ref pw_impl_metadata
|
||||
- \ref pw_impl_module
|
||||
- \ref pw_impl_node
|
||||
- \ref pw_impl_port
|
||||
- \ref pw_control
|
||||
- \ref pw_global
|
||||
- \ref pw_resource
|
||||
- \ref pw_work_queue
|
||||
modules.
|
||||
|
||||
If you are familiar with Wayland implementation, the Implementation API is
|
||||
roughly equivalent to libwayland-server.
|
||||
|
||||
See: \ref page_api
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -35,5 +35,4 @@ More information on how to configure and use PipeWire.
|
|||
|
||||
- [LAC 2020 Paper](https://lac2020.sciencesconf.org/307881/document)
|
||||
- [PipeWire Under The Hood](https://venam.nixers.net/blog/unix/2021/06/23/pipewire-under-the-hood.html)
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -12,10 +12,55 @@ else
|
|||
doxyfile_conf.set('HAVE_DOT', 'NO')
|
||||
endif
|
||||
|
||||
# Note: order here is how doxygen will expose the pages in the sidebar
|
||||
# api-tree.dox should be first to determine ordering of Modules.
|
||||
extra_docs = [
|
||||
'api-tree.dox',
|
||||
'index.dox',
|
||||
'overview.dox',
|
||||
'pipewire.dox',
|
||||
'pipewire-design.dox',
|
||||
'pipewire-access.dox',
|
||||
'pipewire-midi.dox',
|
||||
'pipewire-portal.dox',
|
||||
'pipewire-daemon.dox',
|
||||
'pipewire-library.dox',
|
||||
'pipewire-modules.dox',
|
||||
'pipewire-tools.dox',
|
||||
'pipewire-session-manager.dox',
|
||||
'pipewire-objects-design.dox',
|
||||
'pipewire-audio.dox',
|
||||
'media-session.dox',
|
||||
'tutorial.dox',
|
||||
'tutorial1.dox',
|
||||
'tutorial2.dox',
|
||||
'tutorial3.dox',
|
||||
'tutorial4.dox',
|
||||
'tutorial5.dox',
|
||||
'tutorial6.dox',
|
||||
'api.dox',
|
||||
'spa-index.dox',
|
||||
'spa-plugins.dox',
|
||||
'spa-design.dox',
|
||||
'spa-pod.dox',
|
||||
'spa-buffer.dox',
|
||||
'pulseaudio.dox',
|
||||
'dma-buf.dox',
|
||||
]
|
||||
|
||||
inputs = []
|
||||
foreach extra : extra_docs
|
||||
inputs += meson.source_root() / 'doc' / extra
|
||||
endforeach
|
||||
foreach h : pipewire_headers
|
||||
inputs += meson.source_root() / 'src' / 'pipewire' / h
|
||||
endforeach
|
||||
foreach h : pipewire_ext_headers
|
||||
inputs += meson.source_root() / 'src' / 'pipewire' / 'extensions' / h
|
||||
endforeach
|
||||
foreach h : pipewire_ext_sm_headers
|
||||
inputs += meson.source_root() / 'src' / 'pipewire' / 'extensions' / h
|
||||
endforeach
|
||||
foreach h : pipewire_sources
|
||||
inputs += meson.source_root() / 'src' / 'pipewire' / h
|
||||
endforeach
|
||||
|
|
@ -34,44 +79,6 @@ path_prefixes = [
|
|||
meson.source_root(),
|
||||
]
|
||||
|
||||
# Note: order here is how doxygen will expose the pages in the sidebar
|
||||
extra_docs = [
|
||||
'index.dox',
|
||||
'overview.dox',
|
||||
'pipewire.dox',
|
||||
'pipewire-design.dox',
|
||||
'pipewire-access.dox',
|
||||
'pipewire-midi.dox',
|
||||
'pipewire-portal.dox',
|
||||
'pipewire-daemon.dox',
|
||||
'pipewire-library.dox',
|
||||
'pipewire-modules.dox',
|
||||
'pipewire-tools.dox',
|
||||
'pipewire-session-manager.dox',
|
||||
'pipewire-objects-design.dox',
|
||||
'pipewire-audio.dox',
|
||||
'media-session.dox',
|
||||
'api.dox',
|
||||
'tutorial.dox',
|
||||
'tutorial1.dox',
|
||||
'tutorial2.dox',
|
||||
'tutorial3.dox',
|
||||
'tutorial4.dox',
|
||||
'tutorial5.dox',
|
||||
'tutorial6.dox',
|
||||
'spa-index.dox',
|
||||
'spa-plugins.dox',
|
||||
'spa-design.dox',
|
||||
'spa-pod.dox',
|
||||
'spa-buffer.dox',
|
||||
'pulseaudio.dox',
|
||||
'dma-buf.dox',
|
||||
]
|
||||
|
||||
foreach extra : extra_docs
|
||||
inputs += meson.source_root() / 'doc' / extra
|
||||
endforeach
|
||||
|
||||
cssfiles = [
|
||||
meson.source_root() / 'doc' / 'doxygen-awesome.css',
|
||||
meson.source_root() / 'doc' / 'custom.css'
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
|
||||
> What is the array of `spa_data` in `spa_buffer`?
|
||||
|
||||
A buffer contains metadata and data. There can be many metadata items (headers, color info, cursor position, etc) in the buffer. The metadata items are stored in the metas array. In the same way, the buffer can contain multiple data blocks in the datas array. Each data block is, for example, a video plane or an audio channel. There are `n_datas` of those blocks.
|
||||
A \ref spa_buffer "SPA Buffer" contains metadata and data. There can be many metadata items (headers, color info, cursor position, etc) in the buffer. The metadata items are stored in the metas array. In the same way, the buffer can contain multiple data blocks in the datas array. Each data block is, for example, a video plane or an audio channel. There are `n_datas` of those blocks.
|
||||
|
||||
> What is the `void*` data pointer in `spa_data`?
|
||||
|
||||
|
|
@ -62,4 +62,10 @@ The reason why is this set up like this is that the metadata memory, the data an
|
|||
|
||||
Taken from [here](https://gitlab.freedesktop.org/pipewire/pipewire/-/blob/11f95fe11e07192cec19fddb4fafc708e023e49c/spa/include/spa/buffer/alloc.h).
|
||||
|
||||
|
||||
|
||||
\addtogroup spa_buffer
|
||||
|
||||
See: \ref page_spa_buffer
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/** \page page_spa SPA (Simple Plugin API)
|
||||
|
||||
SPA (Simple Plugin API) is an extensible API to implement all kinds of
|
||||
\ref api_spa (Simple Plugin API) is an extensible API to implement all kinds of
|
||||
plugins.
|
||||
|
||||
It is inspired by many other plugin APIs, mostly LV2 and
|
||||
|
|
@ -70,9 +70,15 @@ Please see \ref page_spa_plugins for the details on how to use SPA plugins.
|
|||
|
||||
## Further details
|
||||
|
||||
- \ref api_spa
|
||||
- \subpage page_spa_design
|
||||
- \subpage page_spa_plugins
|
||||
- \subpage page_spa_pod
|
||||
- \subpage page_spa_buffer
|
||||
|
||||
|
||||
\addtogroup api_spa
|
||||
|
||||
See: \ref page_spa, \ref page_spa_design
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/** \page page_spa_plugins SPA Plugins
|
||||
|
||||
Plugins are dynamically loadable objects that contain objects and interfaces that
|
||||
\ref spa_handle "SPA plugins" are dynamically loadable objects that contain objects and interfaces that
|
||||
can be introspected and used at runtime in any application. This document
|
||||
introduces the basic concepts of SPA plugins. It first covers using the API
|
||||
and then talks about implementing new Plugins.
|
||||
|
|
@ -346,4 +346,10 @@ expected_seq = SPA_RESULT_ASYNC_SEQ(res);
|
|||
|
||||
FIXME
|
||||
|
||||
|
||||
|
||||
\addtogroup spa_handle
|
||||
|
||||
See: \ref page_spa_plugins
|
||||
|
||||
*/
|
||||
|
|
|
|||
|
|
@ -1,6 +1,6 @@
|
|||
/** \page page_spa_pod SPA POD
|
||||
|
||||
POD (plain old data) is a sort of data container. It is comparable to
|
||||
\ref spa_pod (plain old data) is a sort of data container. It is comparable to
|
||||
DBus Variant or LV2 Atom.
|
||||
|
||||
A POD can express nested structures of Objects (with properties), Vectors,
|
||||
|
|
@ -519,4 +519,8 @@ field specifies the size following the type field.
|
|||
Each POD is aligned to an 8 byte boundary.
|
||||
|
||||
|
||||
\addtogroup spa_pod
|
||||
|
||||
See: \ref page_spa_pod
|
||||
|
||||
*/
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue