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).
Add an input filter that tries to link e.g.
#define pw_core_add_listener(...) pw_core_method(c,add_listener,...)
to the corresponding declaration in struct pw_core_methods.
Make Doxygen data structure etc. lists less cluttered by hiding
non-public stuff.
Add a Doxygen input filter that marks symbols declared in C files
private, so that they won't appear in the output unless the symbol is
also declared in a header.
The "spa static inline" hack is then also not needed any more.
Media-session itself uses ms.core, there are only two files that could
have a sub-topic but right now they don't use it (match-rules and
metadata).
The modules use the ms.mod.* namespace, so it's trivial to filter on
those.
pw_log_log/logv now go through the topic-based logger using the
"default" topic. Log topics themselves can be allocated by the call
sites. The simplest way to use a topic from e.g. a module:
PW_LOG_TOPIC_STATIC(mod_topic, "mod.foo");
#define PW_LOG_TOPIC_DEFAULT mod_topic
...
void pipewire__module_init() {
PW_LOG_TOPIC_INIT(mod_topic);
...
}
With the #define all pw_log_foo() are now routed through the custom
topic. For the cases where the log topic must be specified, a
pw_logt_foo() set of macros is available.
Log topics are enabled through the PIPEWIRE_DEBUG environment variable
which now supports globs, e.g. PIPEWIRE_DEBUG="*:I;mod.access:D"
to enable global INFO but DEBUG for the access module.
Namespaces documented are "pw", "mod" and "conn", for pipewire-internal
stuff, modules and connection dumping. The latter is special-cased to
avoid spamming the log files, it requires an expcit "conn.<glob>"
pattern to enable.
The "default" topic always exists and is the fallback for any
pw_log_foo() invocation that does not use a topic.
Allow one of "XEWIDT" to refer to none, errors, warnings, info, debug
and trace, respectively because they're immediately recognizable. Well,
except maybe the X.
PIPEWIRE_DEBUG="I" is equivalent to PIPEWIRE_DEBUG="3" for example.
This is a multi-step process involving 4 processes and two modules.
Let's add some graphs to make this slightly easier to comprehend for
those not familiar with how portals work.
A list of reasons why DMA-BUFs have to be treated specially. This
should make it clearer why mmaping DMA-BUFs should be avoided and hint
clients on how treat them correctly
Co-authored-by: columbarius <co1umbarius@protonmail.com>
Describing different behaviour for modifier-less and modifier-aware case
and how a EnumFormat with modifier should be fixated. Also adding a Note
about `SPA_PARAM_BUFFERS_blocks`, which is important for multiplane
DMA-BUFS.
Add module that switches bluez device profile to HFP/HSP if an input
stream (non-monitor, autoconnect) appears, and the current default
output device is bluez one that does not have input route.
When all input streams are gone, switch all changed profiles back.
Pending restore state is saved to session manager state files, in order
to restore it if e.g. devices get disconnected. This usually is not
currently necessary since the bluez5 plugin prefers to connect to A2DP
over HFP, but might matter in future with backchannel-enabled A2DP
codecs.
This adds a new top-level documentation entry for pipewire-media-session
with a list of modules (currently only one). Similar setup to the
pipewire modules, it allows us to document all modules in-place.
This is a good first (top) page to have in the docs, let's move it out
from the pipewire heading.
This doesn't change any of the links and the renaming isn't required
(subpage controls whether it's a top-level item and the meson.build
order decides its spot in he list). Still, better to have the filenames
represent the layout.
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.
