mirror of
https://gitlab.freedesktop.org/pipewire/pipewire
synced 2024-10-14 11:53:16 +00:00
0f0565175e
Add more info to the main SPA page and split the design vs plugin pages up, together with some more documentation to ideally lower make this easier to understand on a glance. Most of the actual plugin loading documentation are unmodified.
79 lines
2.6 KiB
Plaintext
79 lines
2.6 KiB
Plaintext
/** \page page_spa SPA (Simple Plugin 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
|
|
GStreamer. SPA provides two parts:
|
|
- a header-only API with no external dependencies
|
|
- a set of support libraries ("plugins") for commonly used functionality
|
|
|
|
The usual approach is that PipeWire and PipeWire clients can use the
|
|
header-only functions to interact with the plugins. Those plugins are
|
|
usually loaded at runtime (through `dlopen(3)`.
|
|
|
|
## Motivation
|
|
|
|
SPA was designed with the following goals in mind:
|
|
- No dependencies, SPA is shipped as a set of header files that have no dependencies except for the standard c library.
|
|
- Very efficient both in space and in time.
|
|
- Very configurable and usable in many different environments. All aspects
|
|
of the plugin environment can be configured and changed, like logging,
|
|
poll loops, system calls etc.
|
|
- Consistent API
|
|
- Extensible, new API can be added with minimal effort, existing API can be updated and versioned.
|
|
|
|
The original user of SPA is PipeWire, which uses SPA to implement the
|
|
low-level multimedia processing plugins, device detection, mainloops, CPU
|
|
detection and logging, among other things. SPA however can be used outside
|
|
of PipeWire with minimal problems.
|
|
|
|
## The SPA header-only API
|
|
|
|
A very simple example on how SPA headers work are the \ref spa_utils, a set
|
|
of utilities commonly required by C projects. SPA functions use the `spa_`
|
|
namespace and are easy to identify.
|
|
|
|
\code
|
|
/* cc $(pkg-config --cflags libspa-0.2) -o spa-test spa-test.c */
|
|
|
|
#include <stdint.h>
|
|
#include <spa/utils/string.h>
|
|
|
|
int main(int argc, char **argv) {
|
|
uint32_t val;
|
|
|
|
if (spa_atoi32(argv[1], &val, 16))
|
|
printf("argv[1] is hex %#x\n", val);
|
|
else
|
|
printf("argv[1] is not a hex number\n");
|
|
|
|
return 0;
|
|
}
|
|
\endcode
|
|
|
|
|
|
## SPA Plugins
|
|
|
|
SPA plugins are shared libraries (`.so` files) that can be loaded at
|
|
runtime. Each library provides one or more "factories", each of which may
|
|
implement several "interfaces". Code that uses SPA plugins then uses those
|
|
interfaces (through SPA header files) to interact with the plugin.
|
|
|
|
For example, the PipeWire daemon can load the normal `printf`-based logger
|
|
or a systemd journal-based logger. Both of those provide the \ref spa_log
|
|
interface and once instantiated, PipeWire no longer has to differentiate
|
|
between the two logging facilities.
|
|
|
|
Please see \ref page_spa_plugins for the details on how to use SPA plugins.
|
|
|
|
|
|
## Further details
|
|
|
|
- \subpage page_spa_design
|
|
- \subpage page_spa_plugins
|
|
- \subpage page_spa_pod
|
|
- \subpage page_spa_buffer
|
|
|
|
*/
|