PipeWire 1.2.7
Loading...
Searching...
No Matches
Filter

Files

file  filter.h
 pipewire/filter.h
 

Data Structures

struct  pw_filter_events
 Events for a filter. More...
 
struct  pw_filter
 

Enumerations

enum  pw_filter_state {
  PW_FILTER_STATE_ERROR = -1 , PW_FILTER_STATE_UNCONNECTED = 0 , PW_FILTER_STATE_CONNECTING = 1 , PW_FILTER_STATE_PAUSED = 2 ,
  PW_FILTER_STATE_STREAMING = 3
}
 The state of a filter
More...
 
enum  pw_filter_flags {
  PW_FILTER_FLAG_NONE = 0 , PW_FILTER_FLAG_INACTIVE = (1 << 0) , PW_FILTER_FLAG_DRIVER = (1 << 1) , PW_FILTER_FLAG_RT_PROCESS = (1 << 2) ,
  PW_FILTER_FLAG_CUSTOM_LATENCY = (1 << 3) , PW_FILTER_FLAG_TRIGGER = (1 << 4) , PW_FILTER_FLAG_ASYNC = (1 << 5)
}
 Extra flags that can be used in pw_filter_connect()
More...
 
enum  pw_filter_port_flags { PW_FILTER_PORT_FLAG_NONE = 0 , PW_FILTER_PORT_FLAG_MAP_BUFFERS = (1 << 0) , PW_FILTER_PORT_FLAG_ALLOC_BUFFERS = (1 << 1) }
 

Macros

#define PW_VERSION_FILTER_EVENTS   1
 

Functions

const char * pw_filter_state_as_string (enum pw_filter_state state)
 Convert a filter state to a readable string

 
struct pw_filterpw_filter_new (struct pw_core *core, const char *name, struct pw_properties *props)
 Create a new unconnected Filter.
 
struct pw_filterpw_filter_new_simple (struct pw_loop *loop, const char *name, struct pw_properties *props, const struct pw_filter_events *events, void *data)
 
void pw_filter_destroy (struct pw_filter *filter)
 Destroy a filter

 
void pw_filter_add_listener (struct pw_filter *filter, struct spa_hook *listener, const struct pw_filter_events *events, void *data)
 
enum pw_filter_state pw_filter_get_state (struct pw_filter *filter, const char **error)
 
const char * pw_filter_get_name (struct pw_filter *filter)
 
struct pw_corepw_filter_get_core (struct pw_filter *filter)
 
int pw_filter_connect (struct pw_filter *filter, enum pw_filter_flags flags, const struct spa_pod **params, uint32_t n_params)
 Connect a filter for processing.
 
uint32_t pw_filter_get_node_id (struct pw_filter *filter)
 Get the node ID of the filter.
 
int pw_filter_disconnect (struct pw_filter *filter)
 Disconnect filter

 
void * pw_filter_add_port (struct pw_filter *filter, enum pw_direction direction, enum pw_filter_port_flags flags, size_t port_data_size, struct pw_properties *props, const struct spa_pod **params, uint32_t n_params)
 add a port to the filter, returns user data of port_data_size.
 
int pw_filter_remove_port (void *port_data)
 remove a port from the filter
 
const struct pw_propertiespw_filter_get_properties (struct pw_filter *filter, void *port_data)
 get properties, port_data of NULL will give global properties
 
int pw_filter_update_properties (struct pw_filter *filter, void *port_data, const struct spa_dict *dict)
 Update properties, use NULL port_data for global filter properties.
 
int pw_filter_set_error (struct pw_filter *filter, int res, const char *error,...)
 Set the filter in error state.
 
int pw_filter_update_params (struct pw_filter *filter, void *port_data, const struct spa_pod **params, uint32_t n_params)
 Update params, use NULL port_data for global filter params.
 
int pw_filter_get_time (struct pw_filter *filter, struct pw_time *time)
 Query the time on the filter, deprecated, use the spa_io_position in the process() method for timing information.
 
uint64_t pw_filter_get_nsec (struct pw_filter *filter)
 Get the current time in nanoseconds.
 
struct pw_looppw_filter_get_data_loop (struct pw_filter *filter)
 Get the data loop that is doing the processing of this filter.
 
struct pw_bufferpw_filter_dequeue_buffer (void *port_data)
 Get a buffer that can be filled for output ports or consumed for input ports.
 
int pw_filter_queue_buffer (void *port_data, struct pw_buffer *buffer)
 Submit a buffer for playback or recycle a buffer for capture.
 
void * pw_filter_get_dsp_buffer (void *port_data, uint32_t n_samples)
 Get a data pointer to the buffer data.
 
int pw_filter_set_active (struct pw_filter *filter, bool active)
 Activate or deactivate the filter

 
int pw_filter_flush (struct pw_filter *filter, bool drain)
 Flush a filter.
 
bool pw_filter_is_driving (struct pw_filter *filter)
 Check if the filter is driving.
 
bool pw_filter_is_lazy (struct pw_filter *filter)
 Check if the graph is using lazy scheduling.
 
int pw_filter_trigger_process (struct pw_filter *filter)
 Trigger a push/pull on the filter.
 

Detailed Description

PipeWire filter object class

The filter object provides a convenient way to implement processing filters.

See also Core API

Enumeration Type Documentation

◆ pw_filter_state

The state of a filter

Enumerator
PW_FILTER_STATE_ERROR 

the stream is in error

PW_FILTER_STATE_UNCONNECTED 

unconnected

PW_FILTER_STATE_CONNECTING 

connection is in progress

PW_FILTER_STATE_PAUSED 

filter is connected and paused

PW_FILTER_STATE_STREAMING 

filter is streaming

◆ pw_filter_flags

Extra flags that can be used in pw_filter_connect()

Enumerator
PW_FILTER_FLAG_NONE 

no flags

PW_FILTER_FLAG_INACTIVE 

start the filter inactive, pw_filter_set_active() needs to be called explicitly

PW_FILTER_FLAG_DRIVER 

be a driver

PW_FILTER_FLAG_RT_PROCESS 

call process from the realtime thread

PW_FILTER_FLAG_CUSTOM_LATENCY 

don't call the default latency algorithm but emit the param_changed event for the ports when Latency params are received.

PW_FILTER_FLAG_TRIGGER 

the filter will not be scheduled automatically but _trigger_process() needs to be called.

This can be used when the filter depends on processing of other filters.

PW_FILTER_FLAG_ASYNC 

Buffers will not be dequeued/queued from the realtime process() function.

This is assumed when RT_PROCESS is unset but can also be the case when the process() function does a trigger_process() that will then dequeue/queue a buffer from another process() function. since 0.3.73

◆ pw_filter_port_flags

Enumerator
PW_FILTER_PORT_FLAG_NONE 

no flags

PW_FILTER_PORT_FLAG_MAP_BUFFERS 

mmap the buffers except DmaBuf that is not explicitly marked as mappable.

PW_FILTER_PORT_FLAG_ALLOC_BUFFERS 

the application will allocate buffer memory.

In the add_buffer event, the data of the buffer should be set

Macro Definition Documentation

◆ PW_VERSION_FILTER_EVENTS

#define PW_VERSION_FILTER_EVENTS   1

Function Documentation

◆ pw_filter_state_as_string()

const char * pw_filter_state_as_string ( enum pw_filter_state state)

Convert a filter state to a readable string

Examples
video-dsp-play.c.

◆ pw_filter_new()

struct pw_filter * pw_filter_new ( struct pw_core * core,
const char * name,
struct pw_properties * props )

Create a new unconnected Filter.

Returns
a newly allocated Filter
Parameters
corea Core
namea filter media name
propsfilter properties, ownership is taken

◆ pw_filter_new_simple()

struct pw_filter * pw_filter_new_simple ( struct pw_loop * loop,
const char * name,
struct pw_properties * props,
const struct pw_filter_events * events,
void * data )
Parameters
loopa Loop to use
namea filter media name
propsfilter properties, ownership is taken
eventsfilter events
datadata passed to events
Examples
audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

◆ pw_filter_destroy()

void pw_filter_destroy ( struct pw_filter * filter)

◆ pw_filter_add_listener()

void pw_filter_add_listener ( struct pw_filter * filter,
struct spa_hook * listener,
const struct pw_filter_events * events,
void * data )

◆ pw_filter_get_state()

enum pw_filter_state pw_filter_get_state ( struct pw_filter * filter,
const char ** error )

◆ pw_filter_get_name()

const char * pw_filter_get_name ( struct pw_filter * filter)

◆ pw_filter_get_core()

struct pw_core * pw_filter_get_core ( struct pw_filter * filter)

◆ pw_filter_connect()

int pw_filter_connect ( struct pw_filter * filter,
enum pw_filter_flags flags,
const struct spa_pod ** params,
uint32_t n_params )

Connect a filter for processing.

Returns
0 on success < 0 on error.

You should connect to the process event and use pw_filter_dequeue_buffer() to get the latest metadata and data.

Parameters
filtera Filter
flagsfilter flags
paramsan array with params.
n_paramsnumber of items in params
Examples
audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

◆ pw_filter_get_node_id()

uint32_t pw_filter_get_node_id ( struct pw_filter * filter)

Get the node ID of the filter.

Returns
node ID.

◆ pw_filter_disconnect()

int pw_filter_disconnect ( struct pw_filter * filter)

Disconnect filter

◆ pw_filter_add_port()

void * pw_filter_add_port ( struct pw_filter * filter,
enum pw_direction direction,
enum pw_filter_port_flags flags,
size_t port_data_size,
struct pw_properties * props,
const struct spa_pod ** params,
uint32_t n_params )

add a port to the filter, returns user data of port_data_size.

Parameters
filtera Filter
directionport direction
flagsport flags
port_data_sizeallocated and given to the user as port_data
propsport properties, ownership is taken
paramsan array of params. The params should ideally contain the supported formats
n_paramsnumber of elements in params
Examples
audio-dsp-filter.c, audio-dsp-src.c, midi-src.c, and video-dsp-play.c.

◆ pw_filter_remove_port()

int pw_filter_remove_port ( void * port_data)

remove a port from the filter

Parameters
port_datadata associated with port

◆ pw_filter_get_properties()

const struct pw_properties * pw_filter_get_properties ( struct pw_filter * filter,
void * port_data )

get properties, port_data of NULL will give global properties

◆ pw_filter_update_properties()

int pw_filter_update_properties ( struct pw_filter * filter,
void * port_data,
const struct spa_dict * dict )

Update properties, use NULL port_data for global filter properties.

◆ pw_filter_set_error()

int pw_filter_set_error ( struct pw_filter * filter,
int res,
const char * error,
... )

Set the filter in error state.

Parameters
filtera Filter
resa result code
erroran error message
Examples
video-dsp-play.c.

◆ pw_filter_update_params()

int pw_filter_update_params ( struct pw_filter * filter,
void * port_data,
const struct spa_pod ** params,
uint32_t n_params )

Update params, use NULL port_data for global filter params.

Parameters
filtera Filter
port_datadata associated with port
paramsan array of params.
n_paramsnumber of elements in params
Examples
midi-src.c.

◆ pw_filter_get_time()

int pw_filter_get_time ( struct pw_filter * filter,
struct pw_time * time )

Query the time on the filter, deprecated, use the spa_io_position in the process() method for timing information.

◆ pw_filter_get_nsec()

uint64_t pw_filter_get_nsec ( struct pw_filter * filter)

Get the current time in nanoseconds.

This value can be compared with the nsec value in the spa_io_position. Since 1.1.0

◆ pw_filter_get_data_loop()

struct pw_loop * pw_filter_get_data_loop ( struct pw_filter * filter)

Get the data loop that is doing the processing of this filter.

This loop is assigned after pw_filter_connect(). * Since 1.1.0

◆ pw_filter_dequeue_buffer()

struct pw_buffer * pw_filter_dequeue_buffer ( void * port_data)

Get a buffer that can be filled for output ports or consumed for input ports.


Examples
midi-src.c, and video-dsp-play.c.

◆ pw_filter_queue_buffer()

int pw_filter_queue_buffer ( void * port_data,
struct pw_buffer * buffer )

Submit a buffer for playback or recycle a buffer for capture.

Examples
midi-src.c, and video-dsp-play.c.

◆ pw_filter_get_dsp_buffer()

void * pw_filter_get_dsp_buffer ( void * port_data,
uint32_t n_samples )

Get a data pointer to the buffer data.

Examples
audio-dsp-filter.c, and audio-dsp-src.c.

◆ pw_filter_set_active()

int pw_filter_set_active ( struct pw_filter * filter,
bool active )

Activate or deactivate the filter

◆ pw_filter_flush()

int pw_filter_flush ( struct pw_filter * filter,
bool drain )

Flush a filter.

When drain is true, the drained callback will be called when all data is played or recorded. The filter can be resumed after the drain by setting it active again with pw_filter_set_active(). A flush without a drain is mostly useful afer a state change to PAUSED, to flush any remaining data from the queues.

◆ pw_filter_is_driving()

bool pw_filter_is_driving ( struct pw_filter * filter)

Check if the filter is driving.

The filter needs to have the PW_FILTER_FLAG_DRIVER set. When the filter is driving, pw_filter_trigger_process() needs to be called when data is available (output) or needed (input). Since 0.3.66

◆ pw_filter_is_lazy()

bool pw_filter_is_lazy ( struct pw_filter * filter)

Check if the graph is using lazy scheduling.

Since 1.2.7

◆ pw_filter_trigger_process()

int pw_filter_trigger_process ( struct pw_filter * filter)

Trigger a push/pull on the filter.

One iteration of the graph will be scheduled and process() will be called. Since 0.3.66