PipeWire 1.6.5

Loading...
Searching...
No Matches
io.h
Go to the documentation of this file.
1/* Simple Plugin API */
2/* SPDX-FileCopyrightText: Copyright © 2018 Wim Taymans */
3/* SPDX-License-Identifier: MIT */
4
5#ifndef SPA_IO_H
6#define SPA_IO_H
7
8#include <spa/utils/defs.h>
9#include <spa/pod/pod.h>
10
11#ifdef __cplusplus
12 extern "C" {
13#endif
14
19
29
31 enum spa_io_type {
32 SPA_IO_Invalid,
33 SPA_IO_Buffers,
34 SPA_IO_Range,
35 SPA_IO_Clock,
36 SPA_IO_Latency,
38 SPA_IO_Control,
39 SPA_IO_Notify,
40 SPA_IO_Position,
41 SPA_IO_RateMatch,
42 SPA_IO_Memory,
43 SPA_IO_AsyncBuffers,
44};
45
50
75 struct spa_io_buffers {
76#define SPA_STATUS_OK 0
77#define SPA_STATUS_NEED_DATA (1<<0)
78#define SPA_STATUS_HAVE_DATA (1<<1)
79#define SPA_STATUS_STOPPED (1<<2)
80#define SPA_STATUS_DRAINED (1<<3)
81 int32_t status;
82 uint32_t buffer_id;
83};
84
85#define SPA_IO_BUFFERS_INIT ((struct spa_io_buffers) { SPA_STATUS_OK, SPA_ID_INVALID, })
86
90 struct spa_io_memory {
91 int32_t status;
92 uint32_t size;
93 void *data;
94};
95#define SPA_IO_MEMORY_INIT ((struct spa_io_memory) { SPA_STATUS_OK, 0, NULL, })
96
98 struct spa_io_range {
99 uint64_t offset;
100 uint32_t min_size;
101 uint32_t max_size;
102};
103
106
110 *
111 * The clock counts the elapsed time according to the clock provider
112 * since the provider was last started.
113 *
114 * Driver nodes are supposed to update the contents of \ref SPA_IO_Clock before
115 * signaling the start of a graph cycle. These updated clock values become
116 * visible to other nodes in \ref SPA_IO_Position. Non-driver nodes do
117 * not need to update the contents of their \ref SPA_IO_Clock. Also
118 * see \ref page_driver for further details.
119 *
120 * The host generally gives each node a separate \ref spa_io_clock in \ref
121 * SPA_IO_Clock, so that updates made by the driver are not visible in the
122 * contents of \ref SPA_IO_Clock of other nodes. Instead, \ref SPA_IO_Position
123 * is used to look up the current graph time.
124 *
125 * A node is a driver when \ref spa_io_clock::id and the ID in
126 * \ref spa_io_position.clock in \ref SPA_IO_Position are the same.
127 *
128 * The flags are set by the graph driver at the start of each cycle.
129 */
130 struct spa_io_clock {
131#define SPA_IO_CLOCK_FLAG_FREEWHEEL (1u<<0)
136#define SPA_IO_CLOCK_FLAG_XRUN_RECOVER (1u<<1)
142 * flag is cleared again. That way, the node knows that
143 * during the last cycle it experienced an xrun. They
144 * can use this information for example to resynchronize
145 * or clear custom stale states. */
146#define SPA_IO_CLOCK_FLAG_LAZY (1u<<2)
148#define SPA_IO_CLOCK_FLAG_NO_RATE (1u<<3)
151#define SPA_IO_CLOCK_FLAG_DISCONT (1u<<4)
165 uint32_t flags;
166 uint32_t id;
167 char name[64];
170 uint64_t nsec;
174 struct spa_fraction rate;
175 uint64_t position;
176 uint64_t duration;
177 int64_t delay;
178 double rate_diff;
182 uint64_t next_nsec;
186
187 struct spa_fraction target_rate;
188 uint64_t target_duration;
189 uint32_t target_seq;
191 uint32_t cycle;
192 uint64_t xrun;
193};
194
195/* the size of the video in this cycle */
196 struct spa_io_video_size {
197#define SPA_IO_VIDEO_SIZE_VALID (1<<0)
198 uint32_t flags;
199 uint32_t stride;
200 struct spa_rectangle size;
201 struct spa_fraction framerate;
204 uint32_t padding[4];
205};
206
211
212 struct spa_io_latency {
213 struct spa_fraction rate;
214 uint64_t min;
215 uint64_t max;
216};
217
219 struct spa_io_sequence {
220 struct spa_pod_sequence sequence;
221};
222
224 struct spa_io_segment_bar {
225#define SPA_IO_SEGMENT_BAR_FLAG_VALID (1<<0)
226 uint32_t flags;
227 uint32_t offset;
228 float signature_num;
229 float signature_denom;
230 double bpm;
231 double beat;
232 double bar_start_tick;
233 double ticks_per_beat;
234 uint32_t padding[4];
235};
236
237/** video frame segment */
238 struct spa_io_segment_video {
239#define SPA_IO_SEGMENT_VIDEO_FLAG_VALID (1<<0)
240#define SPA_IO_SEGMENT_VIDEO_FLAG_DROP_FRAME (1<<1)
241#define SPA_IO_SEGMENT_VIDEO_FLAG_PULL_DOWN (1<<2)
242#define SPA_IO_SEGMENT_VIDEO_FLAG_INTERLACED (1<<3)
243 uint32_t flags;
244 uint32_t offset;
245 struct spa_fraction framerate;
246 uint32_t hours;
247 uint32_t minutes;
248 uint32_t seconds;
249 uint32_t frames;
250 uint32_t field_count;
251 uint32_t padding[11];
252};
253
255
257 * The segment position is valid when the current running time is between
258 * start and start + duration. The position is then
259 * calculated as:
260 *
261 * (running time - start) * rate + position;
262 *
263 * Support for looping is done by specifying the LOOPING flags with a
264 * non-zero duration. When the running time reaches start + duration,
265 * duration is added to start and the loop repeats.
266 *
267 * Care has to be taken when the running time + clock.duration extends
268 * past the start + duration from the segment; the user should correctly
269 * wrap around and partially repeat the loop in the current cycle.
270 *
271 * Extra information can be placed in the segment by setting the valid flags
272 * and filling up the corresponding structures.
273 */
274 struct spa_io_segment {
275 uint32_t version;
276#define SPA_IO_SEGMENT_FLAG_LOOPING (1<<0)
277#define SPA_IO_SEGMENT_FLAG_NO_POSITION (1<<1)
281 uint32_t flags;
282 uint64_t start;
286 uint64_t duration;
291 double rate;
293 uint64_t position;
296
297 struct spa_io_segment_bar bar;
298 struct spa_io_segment_video video;
299};
300
301 enum spa_io_position_state {
302 SPA_IO_POSITION_STATE_STOPPED,
303 SPA_IO_POSITION_STATE_STARTING,
304 SPA_IO_POSITION_STATE_RUNNING,
305};
306
308#define SPA_IO_POSITION_MAX_SEGMENTS 8
309
325
326 */
327 struct spa_io_position {
328 struct spa_io_clock clock;
330 struct spa_io_video_size video;
331 int64_t offset;
336 uint32_t state;
337
338 uint32_t n_segments;
339 struct spa_io_segment segments[SPA_IO_POSITION_MAX_SEGMENTS];
340};
341
353 *
354 * When resampling to (graph->node) direction, the number of samples produced
355 * by the resampler varies on each cycle, as the rates are not commensurate.
356 *
357 * When resampling to (node->graph) direction, the number of samples consumed by the
358 * resampler varies. Node output ports in process() should produce \a size number of
359 * samples to match what the resampler needs to produce one graph quantum of output
360 * samples.
361 *
362 * Resampling filters introduce processing delay, given by \a delay and \a delay_frac, in
363 * samples at node rate. The delay varies on each cycle e.g. when resampling between
364 * noncommensurate rates.
365 *
366 * The first sample output (graph->node) or consumed (node->graph) by the resampler is
367 * offset by \a delay + \a delay_frac / 1e9 node samples relative to the nominal graph
368 * cycle start position:
369 *
370 * \code{.unparsed}
371 * first_resampled_sample_nsec =
372 * first_original_sample_nsec
373 * - (rate_match->delay * SPA_NSEC_PER_SEC + rate_match->delay_frac) / node_rate
374 * \endcode
375 */
376 struct spa_io_rate_match {
377 uint32_t delay;
379 uint32_t size;
380 double rate;
381#define SPA_IO_RATE_MATCH_FLAG_ACTIVE (1 << 0)
382 uint32_t flags;
383 int32_t delay_frac;
385 uint32_t padding[6];
386};
387
389 struct spa_io_async_buffers {
390 struct spa_io_buffers buffers[2];
392};
393
397
398#ifdef __cplusplus
399} /* extern "C" */
400#endif
401
402#endif /* SPA_IO_H */
defs.h
spa/utils/defs.h
id
uint32_t id
Definition core.h:432
spa_io_position_state
spa_io_position_state
Definition io.h:326
spa_io_type
spa_io_type
IO areas.
Definition io.h:36
SPA_IO_POSITION_MAX_SEGMENTS
#define SPA_IO_POSITION_MAX_SEGMENTS
the maximum number of segments visible in the future
Definition io.h:334
SPA_IO_POSITION_STATE_RUNNING
@ SPA_IO_POSITION_STATE_RUNNING
Definition io.h:329
SPA_IO_POSITION_STATE_STOPPED
@ SPA_IO_POSITION_STATE_STOPPED
Definition io.h:327
SPA_IO_POSITION_STATE_STARTING
@ SPA_IO_POSITION_STATE_STARTING
Definition io.h:328
SPA_IO_AsyncBuffers
@ SPA_IO_AsyncBuffers
async area to exchange buffers, struct spa_io_async_buffers
Definition io.h:48
SPA_IO_Notify
@ SPA_IO_Notify
area for notify messages, struct spa_io_sequence
Definition io.h:44
SPA_IO_Memory
@ SPA_IO_Memory
memory pointer, struct spa_io_memory (currently not used in PipeWire)
Definition io.h:47
SPA_IO_Clock
@ SPA_IO_Clock
area to update clock information, struct spa_io_clock
Definition io.h:40
SPA_IO_Control
@ SPA_IO_Control
area for control messages, struct spa_io_sequence
Definition io.h:43
SPA_IO_Latency
@ SPA_IO_Latency
latency reporting, struct spa_io_latency (currently not used in PipeWire).
Definition io.h:41
SPA_IO_Range
@ SPA_IO_Range
expected byte range, struct spa_io_range (currently not used in PipeWire)
Definition io.h:39
SPA_IO_Invalid
@ SPA_IO_Invalid
Definition io.h:37
SPA_IO_Position
@ SPA_IO_Position
position information in the graph, struct spa_io_position
Definition io.h:45
SPA_IO_Buffers
@ SPA_IO_Buffers
area to exchange buffers, struct spa_io_buffers
Definition io.h:38
SPA_IO_RateMatch
@ SPA_IO_RateMatch
rate matching between nodes, struct spa_io_rate_match
Definition io.h:46
pod.h
spa/pod/pod.h
spa_fraction
Definition defs.h:137
spa_io_async_buffers
async buffers
Definition io.h:416
spa_io_async_buffers::buffers
struct spa_io_buffers buffers[2]
async buffers, writers write to current (cycle+1)&1, readers read from (cycle)&1
Definition io.h:417
spa_io_buffers
IO area to exchange buffers.
Definition io.h:80
spa_io_buffers::status
int32_t status
the status code
Definition io.h:91
spa_io_buffers::buffer_id
uint32_t buffer_id
a buffer id
Definition io.h:92
spa_io_clock
Absolute time reporting.
Definition io.h:142
spa_io_clock::target_rate
struct spa_fraction target_rate
Target rate of next cycle.
Definition io.h:204
spa_io_clock::next_nsec
uint64_t next_nsec
Estimated next wakeup time in nanoseconds.
Definition io.h:199
spa_io_clock::xrun
uint64_t xrun
Estimated accumulated xrun duration.
Definition io.h:209
spa_io_clock::position
uint64_t position
Current position, in samples @ rate.
Definition io.h:192
spa_io_clock::cycle
uint32_t cycle
incremented each time the graph is started
Definition io.h:208
spa_io_clock::nsec
uint64_t nsec
Time in nanoseconds against monotonic clock (CLOCK_MONOTONIC).
Definition io.h:187
spa_io_clock::rate
struct spa_fraction rate
Rate for position/duration/delay/xrun.
Definition io.h:191
spa_io_clock::rate_diff
double rate_diff
Rate difference between clock and monotonic time, as a ratio of clock speeds.
Definition io.h:195
spa_io_clock::flags
uint32_t flags
Clock flags.
Definition io.h:182
spa_io_clock::target_duration
uint64_t target_duration
Target duration of next cycle.
Definition io.h:205
spa_io_clock::duration
uint64_t duration
Duration of current cycle, in samples @ rate.
Definition io.h:193
spa_io_clock::delay
int64_t delay
Delay between position and hardware, in samples @ rate.
Definition io.h:194
spa_io_clock::target_seq
uint32_t target_seq
Seq counter.
Definition io.h:206
spa_io_latency
Latency reporting.
Definition io.h:230
spa_io_latency::min
uint64_t min
min latency
Definition io.h:232
spa_io_latency::max
uint64_t max
max latency
Definition io.h:233
spa_io_latency::rate
struct spa_fraction rate
rate for min/max
Definition io.h:231
spa_io_memory
IO area to exchange a memory region.
Definition io.h:101
spa_io_memory::size
uint32_t size
the size of data
Definition io.h:103
spa_io_position
The position information adds extra meaning to the raw clock times.
Definition io.h:353
spa_io_position::clock
struct spa_io_clock clock
clock position of driver, always valid and read only
Definition io.h:354
spa_io_position::video
struct spa_io_video_size video
size of the video in the current cycle
Definition io.h:356
spa_io_position::state
uint32_t state
one of enum spa_io_position_state
Definition io.h:362
spa_io_position::n_segments
uint32_t n_segments
number of segments
Definition io.h:364
spa_io_position::segments
struct spa_io_segment segments[SPA_IO_POSITION_MAX_SEGMENTS]
segments
Definition io.h:365
spa_io_position::offset
int64_t offset
an offset to subtract from the clock position to get a running time.
Definition io.h:357
spa_io_range
A range, suitable for input ports that can suggest a range to output ports.
Definition io.h:110
spa_io_range::offset
uint64_t offset
offset in range
Definition io.h:111
spa_io_range::max_size
uint32_t max_size
maximum size of data
Definition io.h:113
spa_io_range::min_size
uint32_t min_size
minimum size of data
Definition io.h:112
spa_io_rate_match
Rate matching.
Definition io.h:402
spa_io_rate_match::delay_frac
int32_t delay_frac
resampling delay fractional part, in units of nanosamples (1/10^9 sample) at node rate
Definition io.h:410
spa_io_rate_match::padding
uint32_t padding[6]
Definition io.h:412
spa_io_rate_match::flags
uint32_t flags
extra flags (set by node)
Definition io.h:409
spa_io_rate_match::rate
double rate
rate for resampler (set by node)
Definition io.h:406
spa_io_rate_match::delay
uint32_t delay
resampling delay, in samples at node rate
Definition io.h:403
spa_io_rate_match::size
uint32_t size
requested input size for resampler
Definition io.h:405
spa_io_segment_bar
bar and beat segment
Definition io.h:242
spa_io_segment_bar::beat
double beat
current beat in segment
Definition io.h:250
spa_io_segment_bar::padding
uint32_t padding[4]
Definition io.h:253
spa_io_segment_bar::bpm
double bpm
beats per minute
Definition io.h:249
spa_io_segment_bar::signature_denom
float signature_denom
time signature denominator
Definition io.h:248
spa_io_segment_bar::ticks_per_beat
double ticks_per_beat
Definition io.h:252
spa_io_segment_bar::bar_start_tick
double bar_start_tick
Definition io.h:251
spa_io_segment_bar::offset
uint32_t offset
offset in segment of this beat
Definition io.h:246
spa_io_segment_bar::signature_num
float signature_num
time signature numerator
Definition io.h:247
spa_io_segment_bar::flags
uint32_t flags
extra flags
Definition io.h:245
spa_io_segment_video
video frame segment
Definition io.h:257
spa_io_segment_video::seconds
uint32_t seconds
Definition io.h:271
spa_io_segment_video::framerate
struct spa_fraction framerate
Definition io.h:268
spa_io_segment_video::field_count
uint32_t field_count
0 for progressive, 1 and 2 for interlaced
Definition io.h:273
spa_io_segment_video::flags
uint32_t flags
flags
Definition io.h:266
spa_io_segment_video::hours
uint32_t hours
Definition io.h:269
spa_io_segment_video::minutes
uint32_t minutes
Definition io.h:270
spa_io_segment_video::frames
uint32_t frames
Definition io.h:272
spa_io_segment_video::offset
uint32_t offset
offset in segment
Definition io.h:267
spa_io_segment
A segment converts a running time to a segment (stream) position.
Definition io.h:297
spa_io_segment::duration
uint64_t duration
duration when this info becomes invalid expressed in running time.
Definition io.h:311
spa_io_segment::position
uint64_t position
The position when the running time == start.
Definition io.h:318
spa_io_segment::rate
double rate
overall rate of the segment, can be negative for backwards time reporting.
Definition io.h:316
spa_io_segment::video
struct spa_io_segment_video video
Definition io.h:323
spa_io_segment::bar
struct spa_io_segment_bar bar
Definition io.h:322
spa_io_segment::version
uint32_t version
Definition io.h:298
spa_io_sequence
control stream, io area for SPA_IO_Control and SPA_IO_Notify
Definition io.h:237
spa_io_sequence::sequence
struct spa_pod_sequence sequence
sequence of timed events
Definition io.h:238
spa_io_video_size
Definition io.h:213
spa_io_video_size::framerate
struct spa_fraction framerate
the minimum framerate, the cycle duration is always smaller to ensure there is only one video frame p...
Definition io.h:219
spa_io_video_size::padding
uint32_t padding[4]
Definition io.h:222
spa_io_video_size::stride
uint32_t stride
video stride in bytes
Definition io.h:217
spa_io_video_size::flags
uint32_t flags
optional flags
Definition io.h:216
spa_io_video_size::size
struct spa_rectangle size
the video size
Definition io.h:218
spa_pod_sequence
a sequence of timed controls
Definition pod.h:271
spa_rectangle
Definition defs.h:116