mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-14 20:02:38 +00:00
doc: document the core/implementation API split a bit better
Still missing a proper review of the linked objects, but at least this now explains why those two are split.
This commit is contained in:
parent
3370a56e3e
commit
5561531751
90
doc/api.dox
90
doc/api.dox
|
@ -2,7 +2,93 @@
|
|||
|
||||
The API consists of two parts:
|
||||
|
||||
- The \subpage page_core_api to access a PipeWire instance.
|
||||
- The \subpage page_implementation_api and tools to build new objects and modules
|
||||
- The \ref page_core_api 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
|
||||
\ref page_session_manager and modules/extensions that need to build objects in
|
||||
the graph.
|
||||
|
||||
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.
|
||||
The below graph illustrates this approach:
|
||||
|
||||
@dot
|
||||
digraph API {
|
||||
compound=true;
|
||||
node [shape="box"];
|
||||
rankdir="RL";
|
||||
|
||||
subgraph cluster_daemon {
|
||||
rankdir="TB";
|
||||
label="PipeWire daemon";
|
||||
style="dashed";
|
||||
|
||||
impl_core [label="Core Impl. Object"];
|
||||
impl_device [label="Device Impl. Object"];
|
||||
impl_node [label="Node Impl. Object"];
|
||||
}
|
||||
|
||||
subgraph cluster_client {
|
||||
rankdir="TB";
|
||||
label="PipeWire client";
|
||||
style="dashed";
|
||||
|
||||
obj_core [label="Core Object"];
|
||||
obj_device [label="Device Object"];
|
||||
obj_node [label="Node Object"];
|
||||
}
|
||||
|
||||
obj_core -> impl_core;
|
||||
obj_device -> impl_device;
|
||||
obj_node -> impl_node;
|
||||
|
||||
}
|
||||
@enddot
|
||||
|
||||
It is common for clients to use both the Core API and the Implementation API
|
||||
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
|
||||
|
||||
If you are familiar with Wayland implementation, the Core API is
|
||||
roughly equivalent to libwayland-client.
|
||||
|
||||
\section page_implementation_api 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
|
||||
|
||||
If you are familiar with Wayland implementation, the Implementation API is
|
||||
roughly equivalent to libwayland-server.
|
||||
|
||||
*/
|
||||
|
|
|
@ -32,21 +32,6 @@ extern "C" {
|
|||
#include <spa/utils/defs.h>
|
||||
#include <spa/utils/hook.h>
|
||||
|
||||
/** \page page_core_api Core API
|
||||
*
|
||||
* The Core API serves to access a PipeWire instance. It consists of the
|
||||
* following object-specific APIs:
|
||||
*
|
||||
* - \ref pw_context
|
||||
* - \ref pw_global
|
||||
* - \ref pw_client
|
||||
* - \ref pw_resource
|
||||
* - \ref pw_node
|
||||
* - \ref pw_port
|
||||
* - \ref pw_link
|
||||
*
|
||||
*/
|
||||
|
||||
/** \defgroup pw_context PipeWire Context
|
||||
*
|
||||
* \brief The PipeWire context object manages all locally available
|
||||
|
|
|
@ -34,7 +34,7 @@ extern "C" {
|
|||
|
||||
#include <spa/utils/hook.h>
|
||||
|
||||
/** \defgroup pw_core The Core Global Object
|
||||
/** \defgroup pw_core The PipeWire Core Global Object
|
||||
*
|
||||
* \brief The core global object.
|
||||
*
|
||||
|
|
|
@ -29,7 +29,7 @@
|
|||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** \defgroup pw_global Global Object
|
||||
/** \defgroup pw_global PipeWire Global Object
|
||||
*
|
||||
* \brief A global object visible to remote clients
|
||||
*
|
||||
|
|
|
@ -29,28 +29,6 @@
|
|||
extern "C" {
|
||||
#endif
|
||||
|
||||
/** \page page_implementation_api 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
|
||||
*
|
||||
*/
|
||||
|
||||
|
||||
struct pw_impl_client;
|
||||
struct pw_impl_module;
|
||||
struct pw_global;
|
||||
|
|
|
@ -31,7 +31,7 @@ extern "C" {
|
|||
|
||||
#include <spa/utils/hook.h>
|
||||
|
||||
/** \defgroup pw_resource Resources
|
||||
/** \defgroup pw_resource PipeWire Resources
|
||||
*
|
||||
* \brief Client owned objects
|
||||
*
|
||||
|
|
Loading…
Reference in a new issue