PipeWire 1.1.0
Loading...
Searching...
No Matches
Filter

PipeWire filter object class. More...

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 unconneced 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.
 
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.
 
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

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 unconneced 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, and video-dsp-play.c.

◆ pw_filter_destroy()

void pw_filter_destroy ( struct pw_filter filter)

Destroy a filter

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

◆ 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, 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, 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

◆ 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_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
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
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

◆ 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_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