Reorganize the docs a little. First a short intro, then list the use
cases, then the responsabilities of the various components, then
the implementation in various places.
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.
This way doxygen will pick up the #defines for spa_log_error, etc. Without
this define it uses the else part of the condition which uses macros to
construct function names.
Heavily inspired by libinput's litest framework (built around check), this is
a from-scratch framework that simplifies adding tests for various parts of
pipewire. See the pwtest.h documentation for details but the basics are:
- PW_TEST() and PWTEST_SUITE() specify the tests to be run
- Test are run in forked processes, any errors/signals are caught and printed
to the log
- Tests have a custom pipewire daemon started on demand to talk to [1]. The
daemon's log is available in the test output.
- Output is YAML to be processed into whatever format needed
[1] There are limits here, since we can't emulate devices yet there is only
so much we can rely on with the daemon.
This is an attempt of breaking up the documentation, currently spread across
several pages. We're left with a few high-level topics with various things
grouped underneath those.
Further refinement is necessary, but this can now be done in incremental steps
over massive reworks.
While doxygen can handle markdown pages, support for it is very limited:
markdown pages can only be included as a whole page, they get an automatic
title (custom titles are possible but aren't standard markdown) and it's not
possible to use \subpage without messing with the markdown again. Any markdown
page will thus end up as separate item in the doxygen output, not really
suitable for generating a good page hiearchy.
Let's switch the tutorial to use doxygen directly instead of markdown, short
of using code/endcode instead of markdown's ``` there isn't that much
difference anyway but it allows us to structure things nicer in the online
docs.
This requires a helper script: doxygen doesn't differ between static methods
and static inline methods. EXTRACT_STATIC defines whether it parses *any*
static method but we're currently using all C files as input files as well. We
cannot convince doxygen to just parse static inline functions in header files
so for SPA we hack around this: meson passes the spa headers to a shell script
with simply copies those changed to `/* static */ inline void (foo)` and doxygen
then runs on those header files.
The result: we get all spa functions added to your doxygen output at the cost
of a few sed calls.
Theme from doxygen-awesome-css with custom modifications based on the
pipewire.org website to use the same type of blue, grey, etc.
doxygen-awesome-css is MIT licensed, see
https://github.com/jothepro/doxygen-awesome-css
Note that the order of the includes matters - that's how doxygen will sort
them. There is no specific structure other than the include order - one reason
why the headers are being changed. Without polluting the markdown files with
doxygen commands we cannot use \subpage, so all files convert to a regular
\page and are listed as flat hierarchy in the sidebar (and in Related Pages).
Changing the headers at least provides some visual grouping with comon
prefixes.
Keep all files as strings in an array so we can add them to the custom command
input list - this way meson will correctly rebuild documentation on changes.
This tool detects and fixes common English spelling mistakes, with
generally very few mistakes.
Here is the command I used to generate this commit. There were a few
changes that had to be done manually, and of course adding the ignore
file:
```shell
codespell -I .codespell-ignore -x .codespell-ignore -w
```
I didn’t add it to the CI, but this would be a good place for it.
Fix docs
Add some more versions to interfaces
Make types for the various proxy object + inline methods that does type
checking and create proxys etc.
Set owner client of client-nodes in the properties
Pass type to bind to in create-node
Don't place global id in the info structs
Improve registration of marshal functions
Pass more types around as ids
Implements the basics of the PORT_UPDATE control message
Add the ports to the proxy node with whe PORT_UPDATE control message.
Let the proxy node check the events and create dbus objects based on
added/removed ports.
Rework things so that we negotiate buffer pools beforehand and only pass
buffer ids around We can then remove the refcount of buffers, events and
commands.
More work on buffer reuse
Use the node state changes to trigger the next step in the configuration
sequence.
Move most of the client-node to a plugin
Do buffer allocation in the port link.
We now only allow per port preallocated buffers. We exchange the index
into the array instead of passing the buffers around. We still use the
refcount to track when a buffer can be reused.
Improve API a little, allow passing the node as the first argument of
the interface call.
Implement alloc_buffer in v4l2 and improve the test.
Remove the old PinosBuffer object and replace it with SpaControl, this
communication protocol is designed to make it possible to implement
remote nodes and so it is moved to Spa.
Move SpaBuffer into to API
Work on easier API to make formats, implement enumeration and support
for all formats in v4l2.
Improve format output in -inspect
Bring back the channel object. Making a node and port on the client side
was rather awkward because of the async nature of many methods. It feels
better to have a specific communication channel object to interface with
a server side port.
Use port activate/deactivate to start/stop streams
Remove links from the ports. We let other objects install a callback on
the port to receive and route buffers.
Add buffer flags. The idea is to make it possible to easily check when a
buffer contains control information that we need to parse to update the
port fields.
Make the client create remote nodes and ports and set up proxies for
them.
Make a port base class implementing most of the logic to pass buffers
locally and remotely.
Remove most code from stream.c, it's now in the port.
Make a portsink and portsrc that can write and read to/from any port. We
use these in the server to send and receive data.
Rework format negotiation. The final format is now sent in-line before
the data. The server will select a format on output ports.
Make an object for a processing node.
Implement a sink node. Make it possible to implement Sink and Source
interfaces to provide input/output from the node.
Improve pinosdepay to track fds and handle format changes.
Add a new refresh message to request a keyframe from the pinos server.
pinospay: pass the refresh-request message upstream
pinossink: turn refresh-request messages into events
pinossrc: turn a keyframe event into a refresh-request message
Make separate payload for the header.
Make release-fd payloads
capture_buffer -> peek_buffer to avoid a copy
remove release-buffer, we really need to release each fd in the buffer
separately.
provide_buffer -> send_buffer so that we can also use this to send the
release-fd messages.
in pinossrc, send back release-fd messages when the fd is no longer in
use.
Use BufferIter and BufferBuilder instead of Packet*
Make separate method to set the header so you can set it later and not
only at builder init time.
Add method to clear the builder if you want to abort.
Add method to add fd to builder instead of in _add_fd_payload. This
would make it easier to add multiple fd-payloads using data from the
same fd.
Pass PinosPacketFDPayload to add_fd_payload to make it symetric with the
parsing code. We should be able to get the size from the VERSION passed
when the builder was made.
Add ideas about releasing the fds back to the server.
Send a command stream over the socket.
Implement a new buffer object that holds the data and commands.
Make iterator and builders to parse and construct buffers.
Rework gstreamer elements to use new API for creating and parsing
buffers.
Add _release_buffer to notify a stream when we are done processing the
buffer. This will eventually go all the way to the server and will allow
us to do more complicated buffer management.