PipeWire: node.h Source File

PipeWire 0.3.37

build/doc/spa/node/node.h
Go to the documentation of this file.
1/* Simple Plugin API
2 *
3 * Copyright © 2018 Wim Taymans
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice (including the next
13 * paragraph) shall be included in all copies or substantial portions of the
14 * Software.
15 *
16 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
19 * THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22 * DEALINGS IN THE SOFTWARE.
23 */
24
25#ifndef SPA_NODE_H
26#define SPA_NODE_H
27
28#ifdef __cplusplus
29extern "C" {
30#endif
31
41#include <errno.h>
42#include <spa/utils/defs.h>
43#include <spa/utils/type.h>
44#include <spa/utils/hook.h>
45#include <spa/buffer/buffer.h>
46#include <spa/node/event.h>
47#include <spa/node/command.h>
48
49
50#define SPA_TYPE_INTERFACE_Node SPA_TYPE_INFO_INTERFACE_BASE "Node"
51
52#define SPA_VERSION_NODE 0
53 struct spa_node { struct spa_interface iface; };
54
60 struct spa_node_info {
61 uint32_t max_input_ports;
62 uint32_t max_output_ports;
63#define SPA_NODE_CHANGE_MASK_FLAGS (1u<<0)
64#define SPA_NODE_CHANGE_MASK_PROPS (1u<<1)
65#define SPA_NODE_CHANGE_MASK_PARAMS (1u<<2)
66 uint64_t change_mask;
67
68#define SPA_NODE_FLAG_RT (1u<<0)
69#define SPA_NODE_FLAG_IN_DYNAMIC_PORTS (1u<<1)
70#define SPA_NODE_FLAG_OUT_DYNAMIC_PORTS (1u<<2)
71#define SPA_NODE_FLAG_IN_PORT_CONFIG (1u<<3)
73#define SPA_NODE_FLAG_OUT_PORT_CONFIG (1u<<4)
75#define SPA_NODE_FLAG_NEED_CONFIGURE (1u<<5)
77#define SPA_NODE_FLAG_ASYNC (1u<<6)
81 uint64_t flags;
82 struct spa_dict *props;
83 struct spa_param_info *params;
84 uint32_t n_params;
85};
86
87#define SPA_NODE_INFO_INIT() (struct spa_node_info) { 0, }
88
94 struct spa_port_info {
95#define SPA_PORT_CHANGE_MASK_FLAGS (1u<<0)
96#define SPA_PORT_CHANGE_MASK_RATE (1u<<1)
97#define SPA_PORT_CHANGE_MASK_PROPS (1u<<2)
98#define SPA_PORT_CHANGE_MASK_PARAMS (1u<<3)
99 uint64_t change_mask;
100
101#define SPA_PORT_FLAG_REMOVABLE (1u<<0)
102#define SPA_PORT_FLAG_OPTIONAL (1u<<1)
103#define SPA_PORT_FLAG_CAN_ALLOC_BUFFERS (1u<<2)
104#define SPA_PORT_FLAG_IN_PLACE (1u<<3)
106#define SPA_PORT_FLAG_NO_REF (1u<<4)
110#define SPA_PORT_FLAG_LIVE (1u<<5)
112#define SPA_PORT_FLAG_PHYSICAL (1u<<6)
113#define SPA_PORT_FLAG_TERMINAL (1u<<7)
116#define SPA_PORT_FLAG_DYNAMIC_DATA (1u<<8)
119 uint64_t flags;
120 struct spa_fraction rate;
121 const struct spa_dict *props;
122 struct spa_param_info *params;
123 uint32_t n_params;
124};
125
126#define SPA_PORT_INFO_INIT() (struct spa_port_info) { 0, }
127
128#define SPA_RESULT_TYPE_NODE_ERROR 1
129#define SPA_RESULT_TYPE_NODE_PARAMS 2
130
132 struct spa_result_node_error {
133 const char *message;
134};
135
137 struct spa_result_node_params {
138 uint32_t id;
139 uint32_t index;
140 uint32_t next;
141 struct spa_pod *param;
142};
143
144#define SPA_NODE_EVENT_INFO 0
145#define SPA_NODE_EVENT_PORT_INFO 1
146#define SPA_NODE_EVENT_RESULT 2
147#define SPA_NODE_EVENT_EVENT 3
148#define SPA_NODE_EVENT_NUM 4
149
156 struct spa_node_events {
157#define SPA_VERSION_NODE_EVENTS 0
158 uint32_t version;
161 void (*info) (void *data, const struct spa_node_info *info);
162
164 void (*port_info) (void *data,
165 enum spa_direction direction, uint32_t port,
166 const struct spa_port_info *info);
167
184 void (*result) (void *data, int seq, int res,
185 uint32_t type, const void *result);
186
194 void (*event) (void *data, const struct spa_event *event);
195};
196
197#define SPA_NODE_CALLBACK_READY 0
198#define SPA_NODE_CALLBACK_REUSE_BUFFER 1
199#define SPA_NODE_CALLBACK_XRUN 2
200#define SPA_NODE_CALLBACK_NUM 3
201
207 struct spa_node_callbacks {
208#define SPA_VERSION_NODE_CALLBACKS 0
209 uint32_t version;
218 int (*ready) (void *data, int state);
219
230 int (*reuse_buffer) (void *data,
231 uint32_t port_id,
232 uint32_t buffer_id);
233
244 int (*xrun) (void *data, uint64_t trigger, uint64_t delay,
245 struct spa_pod *info);
246};
247
248
250#define SPA_NODE_PARAM_FLAG_TEST_ONLY (1 << 0)
251#define SPA_NODE_PARAM_FLAG_FIXATE (1 << 1)
252#define SPA_NODE_PARAM_FLAG_NEAREST (1 << 2)
256#define SPA_NODE_BUFFERS_FLAG_ALLOC (1 << 0)
261#define SPA_NODE_METHOD_ADD_LISTENER 0
262#define SPA_NODE_METHOD_SET_CALLBACKS 1
263#define SPA_NODE_METHOD_SYNC 2
264#define SPA_NODE_METHOD_ENUM_PARAMS 3
265#define SPA_NODE_METHOD_SET_PARAM 4
266#define SPA_NODE_METHOD_SET_IO 5
267#define SPA_NODE_METHOD_SEND_COMMAND 6
268#define SPA_NODE_METHOD_ADD_PORT 7
269#define SPA_NODE_METHOD_REMOVE_PORT 8
270#define SPA_NODE_METHOD_PORT_ENUM_PARAMS 9
271#define SPA_NODE_METHOD_PORT_SET_PARAM 10
272#define SPA_NODE_METHOD_PORT_USE_BUFFERS 11
273#define SPA_NODE_METHOD_PORT_SET_IO 12
274#define SPA_NODE_METHOD_PORT_REUSE_BUFFER 13
275#define SPA_NODE_METHOD_PROCESS 14
276#define SPA_NODE_METHOD_NUM 15
277
281 struct spa_node_methods {
282 /* the version of the node methods. This can be used to expand this
283 * structure in the future */
284#define SPA_VERSION_NODE_METHODS 0
285 uint32_t version;
286
301 int (*add_listener) (void *object,
302 struct spa_hook *listener,
303 const struct spa_node_events *events,
304 void *data);
318 int (*set_callbacks) (void *object,
319 const struct spa_node_callbacks *callbacks,
320 void *data);
336 int (*sync) (void *object, int seq);
337
369 int (*enum_params) (void *object, int seq,
370 uint32_t id, uint32_t start, uint32_t max,
371 const struct spa_pod *filter);
372
394 int (*set_param) (void *object,
395 uint32_t id, uint32_t flags,
396 const struct spa_pod *param);
397
416 int (*set_io) (void *object,
417 uint32_t id, void *data, size_t size);
418
433 int (*send_command) (void *object, const struct spa_command *command);
434
451 int (*add_port) (void *object,
452 enum spa_direction direction, uint32_t port_id,
453 const struct spa_dict *props);
454
465 int (*remove_port) (void *object,
466 enum spa_direction direction, uint32_t port_id);
467
498 int (*port_enum_params) (void *object, int seq,
499 enum spa_direction direction, uint32_t port_id,
500 uint32_t id, uint32_t start, uint32_t max,
501 const struct spa_pod *filter);
526 int (*port_set_param) (void *object,
527 enum spa_direction direction,
528 uint32_t port_id,
529 uint32_t id, uint32_t flags,
530 const struct spa_pod *param);
531
572 int (*port_use_buffers) (void *object,
573 enum spa_direction direction,
574 uint32_t port_id,
575 uint32_t flags,
576 struct spa_buffer **buffers,
577 uint32_t n_buffers);
578
599 int (*port_set_io) (void *object,
600 enum spa_direction direction,
601 uint32_t port_id,
602 uint32_t id,
603 void *data, size_t size);
604
616 int (*port_reuse_buffer) (void *object, uint32_t port_id, uint32_t buffer_id);
617
635 int (*process) (void *object);
636};
637
638#define spa_node_method(o,method,version,...) \
639({ \
640 int _res = -ENOTSUP; \
641 struct spa_node *_n = o; \
642 spa_interface_call_res(&_n->iface, \
643 struct spa_node_methods, _res, \
644 method, version, ##__VA_ARGS__); \
645 _res; \
646})
647
648#define spa_node_add_listener(n,...) spa_node_method(n, add_listener, 0, __VA_ARGS__)
649#define spa_node_set_callbacks(n,...) spa_node_method(n, set_callbacks, 0, __VA_ARGS__)
650#define spa_node_sync(n,...) spa_node_method(n, sync, 0, __VA_ARGS__)
651#define spa_node_enum_params(n,...) spa_node_method(n, enum_params, 0, __VA_ARGS__)
652#define spa_node_set_param(n,...) spa_node_method(n, set_param, 0, __VA_ARGS__)
653#define spa_node_set_io(n,...) spa_node_method(n, set_io, 0, __VA_ARGS__)
654#define spa_node_send_command(n,...) spa_node_method(n, send_command, 0, __VA_ARGS__)
655#define spa_node_add_port(n,...) spa_node_method(n, add_port, 0, __VA_ARGS__)
656#define spa_node_remove_port(n,...) spa_node_method(n, remove_port, 0, __VA_ARGS__)
657#define spa_node_port_enum_params(n,...) spa_node_method(n, port_enum_params, 0, __VA_ARGS__)
658#define spa_node_port_set_param(n,...) spa_node_method(n, port_set_param, 0, __VA_ARGS__)
659#define spa_node_port_use_buffers(n,...) spa_node_method(n, port_use_buffers, 0, __VA_ARGS__)
660#define spa_node_port_set_io(n,...) spa_node_method(n, port_set_io, 0, __VA_ARGS__)
661
662#define spa_node_port_reuse_buffer(n,...) spa_node_method(n, port_reuse_buffer, 0, __VA_ARGS__)
663#define spa_node_process(n) spa_node_method(n, process, 0)
664
669#ifdef __cplusplus
670} /* extern "C" */
671#endif
672
673#endif /* SPA_NODE_H */
buffer.h
type.h
defs.h
spa_direction
spa_direction
Definition: defs.h:78
hook.h
props
const char * props
Definition: media-session.c:2383
start
int(* start)(struct sm_media_session *sess)
Definition: media-session.c:2382
command.h
event.h
data
user data to add to an object
Definition: media-session.c:110
filter
Definition: filter.c:126
param
Definition: media-session.c:116
port
Definition: module-filter-chain.c:144
spa_buffer
A Buffer.
Definition: buffer/buffer.h:93
spa_command
Definition: pod/command.h:44
spa_dict
Definition: utils/dict.h:48
spa_event
Definition: pod/event.h:43
spa_fraction
Definition: defs.h:104
spa_hook
A hook, contains the structure with functions and the data passed to the functions.
Definition: hook.h:295
spa_interface
Definition: hook.h:146
spa_node_callbacks
Node callbacks.
Definition: build/doc/spa/node/node.h:207
spa_node_callbacks::version
uint32_t version
Definition: build/doc/spa/node/node.h:209
spa_node_callbacks::ready
int(* ready)(void *data, int state)
Definition: build/doc/spa/node/node.h:218
spa_node_callbacks::reuse_buffer
int(* reuse_buffer)(void *data, uint32_t port_id, uint32_t buffer_id)
Definition: build/doc/spa/node/node.h:230
spa_node_callbacks::xrun
int(* xrun)(void *data, uint64_t trigger, uint64_t delay, struct spa_pod *info)
Definition: build/doc/spa/node/node.h:244
spa_node_events
events from the spa_node.
Definition: build/doc/spa/node/node.h:156
spa_node_events::version
uint32_t version
version of this structure
Definition: build/doc/spa/node/node.h:158
spa_node_events::event
void(* event)(void *data, const struct spa_event *event)
Definition: build/doc/spa/node/node.h:194
spa_node_events::result
void(* result)(void *data, int seq, int res, uint32_t type, const void *result)
notify a result.
Definition: build/doc/spa/node/node.h:184
spa_node_events::info
void(* info)(void *data, const struct spa_node_info *info)
Emitted when info changes.
Definition: build/doc/spa/node/node.h:161
spa_node_events::port_info
void(* port_info)(void *data, enum spa_direction direction, uint32_t port, const struct spa_port_info *info)
Emitted when port info changes, NULL when port is removed.
Definition: build/doc/spa/node/node.h:164
spa_node_info
Node information structure.
Definition: build/doc/spa/node/node.h:60
spa_node_info::params
struct spa_param_info * params
parameter information
Definition: build/doc/spa/node/node.h:83
spa_node_info::flags
uint64_t flags
Definition: build/doc/spa/node/node.h:81
spa_node_info::n_params
uint32_t n_params
number of items in params
Definition: build/doc/spa/node/node.h:84
spa_node_info::max_output_ports
uint32_t max_output_ports
Definition: build/doc/spa/node/node.h:62
spa_node_info::change_mask
uint64_t change_mask
Definition: build/doc/spa/node/node.h:66
spa_node_info::props
struct spa_dict * props
extra node properties
Definition: build/doc/spa/node/node.h:82
spa_node_info::max_input_ports
uint32_t max_input_ports
Definition: build/doc/spa/node/node.h:61
spa_node_methods
Node methods.
Definition: build/doc/spa/node/node.h:281
spa_node_methods::set_param
int(* set_param)(void *object, uint32_t id, uint32_t flags, const struct spa_pod *param)
Set the configurable parameter in node.
Definition: build/doc/spa/node/node.h:394
spa_node_methods::port_enum_params
int(* port_enum_params)(void *object, int seq, enum spa_direction direction, uint32_t port_id, uint32_t id, uint32_t start, uint32_t max, const struct spa_pod *filter)
Enumerate all possible parameters of id on port_id of node that are compatible with filter.
Definition: build/doc/spa/node/node.h:498
spa_node_methods::port_set_io
int(* port_set_io)(void *object, enum spa_direction direction, uint32_t port_id, uint32_t id, void *data, size_t size)
Configure the given memory area with id on port_id.
Definition: build/doc/spa/node/node.h:599
spa_node_methods::process
int(* process)(void *object)
Process the node.
Definition: build/doc/spa/node/node.h:635
spa_node_methods::port_use_buffers
int(* port_use_buffers)(void *object, enum spa_direction direction, uint32_t port_id, uint32_t flags, struct spa_buffer **buffers, uint32_t n_buffers)
Tell the port to use the given buffers.
Definition: build/doc/spa/node/node.h:572
spa_node_methods::add_listener
int(* add_listener)(void *object, struct spa_hook *listener, const struct spa_node_events *events, void *data)
Adds an event listener on node.
Definition: build/doc/spa/node/node.h:301
spa_node_methods::add_port
int(* add_port)(void *object, enum spa_direction direction, uint32_t port_id, const struct spa_dict *props)
Make a new port with port_id.
Definition: build/doc/spa/node/node.h:451
spa_node_methods::enum_params
int(* enum_params)(void *object, int seq, uint32_t id, uint32_t start, uint32_t max, const struct spa_pod *filter)
Enumerate the parameters of a node.
Definition: build/doc/spa/node/node.h:369
spa_node_methods::set_callbacks
int(* set_callbacks)(void *object, const struct spa_node_callbacks *callbacks, void *data)
Set callbacks to on node.
Definition: build/doc/spa/node/node.h:318
spa_node_methods::version
uint32_t version
Definition: build/doc/spa/node/node.h:285
spa_node_methods::set_io
int(* set_io)(void *object, uint32_t id, void *data, size_t size)
Configure the given memory area with id on node.
Definition: build/doc/spa/node/node.h:416
spa_node_methods::port_reuse_buffer
int(* port_reuse_buffer)(void *object, uint32_t port_id, uint32_t buffer_id)
Tell an output port to reuse a buffer.
Definition: build/doc/spa/node/node.h:616
spa_node_methods::remove_port
int(* remove_port)(void *object, enum spa_direction direction, uint32_t port_id)
Remove a port with port_id.
Definition: build/doc/spa/node/node.h:465
spa_node_methods::send_command
int(* send_command)(void *object, const struct spa_command *command)
Send a command to a node.
Definition: build/doc/spa/node/node.h:433
spa_node_methods::port_set_param
int(* port_set_param)(void *object, enum spa_direction direction, uint32_t port_id, uint32_t id, uint32_t flags, const struct spa_pod *param)
Set a parameter on port_id of node.
Definition: build/doc/spa/node/node.h:526
spa_node
Definition: build/doc/spa/node/node.h:53
spa_node::iface
struct spa_interface iface
Definition: build/doc/spa/node/node.h:53
spa_param_info
information about a parameter
Definition: param.h:64
spa_pod
Definition: pod/pod.h:50
spa_pod::size
uint32_t size
Definition: pod/pod.h:51
spa_port_info
Port information structure.
Definition: build/doc/spa/node/node.h:94
spa_port_info::flags
uint64_t flags
port flags
Definition: build/doc/spa/node/node.h:119
spa_port_info::rate
struct spa_fraction rate
rate of sequence numbers on port
Definition: build/doc/spa/node/node.h:120
spa_port_info::params
struct spa_param_info * params
parameter information
Definition: build/doc/spa/node/node.h:122
spa_port_info::change_mask
uint64_t change_mask
Definition: build/doc/spa/node/node.h:99
spa_port_info::n_params
uint32_t n_params
number of items in params
Definition: build/doc/spa/node/node.h:123
spa_port_info::props
const struct spa_dict * props
extra port properties
Definition: build/doc/spa/node/node.h:121
spa_result_node_error
an error result
Definition: build/doc/spa/node/node.h:132
spa_result_node_error::message
const char * message
Definition: build/doc/spa/node/node.h:133
spa_result_node_params
the result of enum_params or port_enum_params.
Definition: build/doc/spa/node/node.h:137
spa_result_node_params::param
struct spa_pod * param
the result param
Definition: build/doc/spa/node/node.h:141
spa_result_node_params::next
uint32_t next
next index of iteration
Definition: build/doc/spa/node/node.h:140
spa_result_node_params::index
uint32_t index
index of parameter
Definition: build/doc/spa/node/node.h:139
spa_result_node_params::id
uint32_t id
id of parameter
Definition: build/doc/spa/node/node.h:138
sync
Definition: media-session.c:120