mirrors/pipewire
1
0
Fork 0
mirror of https://gitlab.freedesktop.org/pipewire/pipewire.git synced 2025-10-29 05:40:27 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions

doc: spa: Fix offset in driver documentation

Browse source
This commit is contained in:
Carlos Rafael Giani 2025-08-03 19:01:11 +02:00 • committed by Wim Taymans
parent e6f767d41d
commit 6c4cd0f1b2
1 changed files with 9 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

18
doc/dox/internals/driver.dox
View file

@ -62,10 +62,10 @@ data loop assigned to the driver node.
As mentioned above, the \ref spa_io_clock::position field is the _ideal_ position As mentioned above, the \ref spa_io_clock::position field is the _ideal_ position
of the graph cycle, in samples. This contrasts with \ref spa_io_clock::nsec, which of the graph cycle, in samples. This contrasts with \ref spa_io_clock::nsec, which
is the moment in monotonic clock time when the cycle _actually_ happens. This is is the moment in monotonic clock time when the cycle _actually_ happens. This is an
an important distinction when driver is run by a clock that is different to the monotonic important distinction when driver is run by a clock that is different to the monotonic
cloc. In that case, the \ref spa_io_clock::nsec timestamps are adjusted to match the pace clock. In that case, the \ref spa_io_clock::nsec timestamps are adjusted to match the
of that different clock (explained in the section below). In such a case, pace of that different clock (explained in the section below). In such a case,
\ref spa_io_clock::position still is incremented by the duration in samples. This \ref spa_io_clock::position still is incremented by the duration in samples. This
is important, since nodes and modules may use this field as an offset within their own is important, since nodes and modules may use this field as an offset within their own
internal ring buffers or similar structures, using the position field as an offset within internal ring buffers or similar structures, using the position field as an offset within
@ -77,15 +77,15 @@ By incrementing by the duration, this requirement is met.
As mentioned earlier, the driver may be run by an internal clock that is different As mentioned earlier, the driver may be run by an internal clock that is different
to the monotonic clock. If that other clock can be directly used for scheduling to the monotonic clock. If that other clock can be directly used for scheduling
graph cycle initiations, then it is sufficient to compute the offset between that graph cycle initiations, then it is sufficient to compute the offset between that
clock and the monotonic clock (that is, offset = other_clock_time - monotonic_clock_time) clock and the monotonic clock (that is, offset = monotonic_clock_time - other_clock_time)
at each cycle and use that offset to translate that other clock's time to the monotonic at each cycle and use that offset to translate that other clock's time to the monotonic
clock time. This is accomplished by adding that offset to the \ref spa_io_clock::nsec clock time. This is accomplished by adding that offset to the \ref spa_io_clock::nsec
and \ref spa_io_clock::next_nsec fields. For example, when the driver uses the realtime and \ref spa_io_clock::next_nsec fields. For example, when the driver uses the realtime
system clock instead of the monotonic system clock, then that realtime clock can still system clock instead of the monotonic system clock, then that realtime clock can still
be used with \c timerfd to schedule callback invocations within the data loop. Then, computing be used with \c timerfd to schedule callback invocations within the data loop. Then,
the (realtime_clock_time - monotonic_clock_time) offset is sufficient, as mentioned, computing the (monotonic_clock_time - realtime_clock_time) offset is sufficient, as
to fulfill the requirements of the \ref spa_io_clock::nsec and \ref spa_io_clock::next_nsec mentioned, to be able to translate clock's time to monotonic time for \ref spa_io_clock::nsec
fields that their timestamps must be given in monotonic clock time. and \ref spa_io_clock::next_nsec (which require monotonic clock timestamps).
If however that other clock cannot be used for scheduling graph cycle initiations directly If however that other clock cannot be used for scheduling graph cycle initiations directly
(for example, because the API of that clock has no functionality to trigger callbacks), (for example, because the API of that clock has no functionality to trigger callbacks),