Pad

The point where two elements meet. More...

Files
file	mpipe_pad.h
	Pad: the point where two elements meet.

Data Structures
struct	mpipe_pad
	Pad structure. More...

Enumerations
enum	mpipe_pad_direction { MPIPE_PAD_UNKNOWN , MPIPE_PAD_SRC , MPIPE_PAD_SINK }
	The direction of a pad. More...
enum	mpipe_pad_mode { MPIPE_PAD_MODE_NONE , MPIPE_PAD_MODE_PUSH , MPIPE_PAD_MODE_PULL }
	The operating mode of a Pad. More...
enum	mpipe_pad_presence { MPIPE_PAD_ALWAYS , MPIPE_PAD_SOMETIMES , MPIPE_PAD_REQUEST }
	The presence of a pad. More...

Functions
int	mpipe_pad_enum_caps (struct mpipe_pad *pad, uint32_t index, const struct mpipe_structure *filter, struct mpipe_structure *out)
	Produce one of the pad's supported caps.
int	mpipe_pad_enum_first (struct mpipe_pad *pad, const struct mpipe_structure *filter, struct mpipe_structure *out)
	Produce the pad's first supported capability that a filter accepts.
int	mpipe_pad_answer_caps_query (struct mpipe_pad *pad, struct mpipe_dispatch *query)
	Answer a caps query with the first capability its filter accepts.
int	mpipe_pad_enum_filter (const struct mpipe_structure *candidate, const struct mpipe_structure *filter, struct mpipe_structure *out)
	Narrow one enumerated capability by an enumeration filter.
void	mpipe_pad_init (struct mpipe_pad *pad, uint8_t id, enum mpipe_pad_direction direction, enum mpipe_pad_presence presence)
	Initialize a pad.
int	mpipe_pad_set_caps (struct mpipe_pad *pad, const struct mpipe_structure *caps)
	Set the pad's capability.
int	mpipe_pad_link (struct mpipe_pad *src_pad, struct mpipe_pad *sink_pad)
	Link two pads together.
int	mpipe_pad_send_event (struct mpipe_pad *pad, struct mpipe_dispatch *event)
	Send an event to a pad.
int	mpipe_pad_send_event_default (struct mpipe_pad *pad, struct mpipe_dispatch *event)
	Default event handler for pads.
int	mpipe_pad_query (struct mpipe_pad *pad, struct mpipe_dispatch *query)
	Send a query to a pad.

Detailed Description

The point where two elements meet.

A pad is an element's input or output connector. It has a direction - a source pad (MPIPE_PAD_SRC) emits data, a sink pad (MPIPE_PAD_SINK) receives it - and mpipe_pad_link joins one of each. The link is recorded on both sides through their peer pointers, and that pair of pointers is the path every buffer, event and query travels.

A pad also holds the capability it settled on, one Capability Structure by value. Until a negotiation has run it constrains nothing, and mpipe_pad_set_caps with NULL puts it back that way, which is what the PAUSED to READY transition does.

Buffers, events and queries

Three kinds of traffic cross a link, each with its own hook:

• a buffer arrives at a sink pad's chain_fn. The chain function owns the buffer it is given and must release it even when it fails; the caller never touches it again either way.
• an event announces something and is sent with mpipe_pad_send_event - a format to apply, or the end of the stream. The default handler forwards it across the element to the peers on the other side.
• a query asks something and is sent with mpipe_pad_query. The answer is written into storage the asker owns, so a query allocates nothing.

Events and queries are both carried by Dispatches; what decides whether a dispatch asks or announces is the function it is passed to, not anything in the dispatch itself.

Enumerating capabilities

An element that supports several formats does not describe them as one capability holding a list - there is no list type, because there is no allocation. It answers enum_caps_fn once per index, producing one capability at a time, and negotiation walks those indices. See mpipe_pad_enum_caps for the three-way return that drives the walk.

Presence

A pad records a presence describing when it is meant to exist - MPIPE_PAD_ALWAYS as soon as the element is built, MPIPE_PAD_SOMETIMES coming and going with the stream, MPIPE_PAD_REQUEST only once asked for. Only MPIPE_PAD_ALWAYS is implemented today: the field is stored and nothing acts on it, so treat the other two as reserved.

Enumeration Type Documentation

mpipe_pad_direction

enum mpipe_pad_direction

#include <mpipe_pad.h>

The direction of a pad.

Enumerator
MPIPE_PAD_UNKNOWN	Direction is unknown.
MPIPE_PAD_SRC	The pad is a source pad.
MPIPE_PAD_SINK	The pad is a sink pad.

mpipe_pad_mode

enum mpipe_pad_mode

#include <mpipe_pad.h>

The operating mode of a Pad.

Defines if the pad operates in push or pull mode or none of them.

Enumerator
MPIPE_PAD_MODE_NONE	Pad will not handle dataflow.
MPIPE_PAD_MODE_PUSH	Pad handles dataflow in push mode.
MPIPE_PAD_MODE_PULL	Pad handles dataflow in pull mode.

mpipe_pad_presence

enum mpipe_pad_presence

#include <mpipe_pad.h>

The presence of a pad.

Enumerator
MPIPE_PAD_ALWAYS	The pad is always present.
MPIPE_PAD_SOMETIMES	The pad will be present depending on the media stream.
MPIPE_PAD_REQUEST	The pad is only available on request.

Function Documentation

mpipe_pad_answer_caps_query()

int mpipe_pad_answer_caps_query	(	struct mpipe_pad *	pad,
		struct mpipe_dispatch *	query )

#include <mpipe_pad.h>

Answer a caps query with the first capability its filter accepts.

Enumerates the pad and writes the capability the negotiation would settle on back into query. This is what an element with nothing to transform, a source or a sink, installs as its query handler.

Parameters

pad	Pad to enumerate.
query	Caps query to answer, carrying the filter on entry.

Returns

0 on success, negative errno on other failures

Return values

-ENODATA

The pad has no capability the filter accepts

mpipe_pad_enum_caps()

int mpipe_pad_enum_caps	(	struct mpipe_pad *	pad,
		uint32_t	index,
		const struct mpipe_structure *	filter,
		struct mpipe_structure *	out )

#include <mpipe_pad.h>

Produce one of the pad's supported caps.

Parameters

	pad	Pad to enumerate.
	index	Zero-based index of the capability.
	filter	Optional structure to narrow the capability by, may be NULL.
[out]	out	Storage for the capability, released with mpipe_structure_clear.

Return values

0	on success
-EAGAIN	This index cannot satisfy filter
-ENOENT	Past the last capability

mpipe_pad_enum_filter()

int mpipe_pad_enum_filter	(	const struct mpipe_structure *	candidate,
		const struct mpipe_structure *	filter,
		struct mpipe_structure *	out )

#include <mpipe_pad.h>

Narrow one enumerated capability by an enumeration filter.

The epilogue every Pad enum_caps_fn shares: hand back candidate when there is no filter, otherwise narrow it and report that this index cannot satisfy the filter so the caller moves on to the next one.

Parameters

	candidate	Pointer to the capability this index produced.
	filter	Capability to narrow by, may be NULL.
[out]	out	Pointer to storage for the result.

Return values

0	Success.
-EAGAIN	candidate cannot satisfy filter

mpipe_pad_enum_first()

int mpipe_pad_enum_first	(	struct mpipe_pad *	pad,
		const struct mpipe_structure *	filter,
		struct mpipe_structure *	out )

#include <mpipe_pad.h>

Produce the pad's first supported capability that a filter accepts.

Parameters

	pad	Pad to enumerate.
	filter	Capability to narrow by, may be NULL or ANY.
[out]	out	Storage for the capability, released with mpipe_structure_clear.

Return values

0	on success
-ENODATA	No capability is accepted

mpipe_pad_init()

void mpipe_pad_init	(	struct mpipe_pad *	pad,
		uint8_t	id,
		enum mpipe_pad_direction	direction,
		enum mpipe_pad_presence	presence )

#include <mpipe_pad.h>

Initialize a pad.

Initializes an existing Pad structure with the specified parameters.

Parameters

pad	Pointer to the Pad to initialize
id	Unique ID of the pad instance in the element
direction	Direction of the pad (mpipe_pad_direction)
presence	Presence of the pad (Presence)

mpipe_pad_link()

int mpipe_pad_link	(	struct mpipe_pad *	src_pad,
		struct mpipe_pad *	sink_pad )

#include <mpipe_pad.h>

Link two pads together.

Links a source pad to a sink pad, establishing a connection for data flow. Both pads will have their peer pointers set to each other.

Parameters

src_pad	Source pad to link
sink_pad	Sink pad to link

Returns

0 on success, negative errno on failure

mpipe_pad_query()

int mpipe_pad_query	(	struct mpipe_pad *	pad,
		struct mpipe_dispatch *	query )

#include <mpipe_pad.h>

Send a query to a pad.

Sends a query to the pad using the pad's query function.

A caps query is answered into the storage it carries, so one that carries none is refused before the pad's query function is called. That is what lets a query function dereference mpipe_dispatch::caps without checking it.

Parameters

pad	Pointer to the Pad to send query to, must not be NULL
query	Pointer to the Dispatches to send, must not be NULL. A caps query must carry the capability storage to answer into.

Return values

0	Success.
-EINVAL	a caps query carries no capability storage to answer into
-ENOTSUP	the pad has no query function
-ENODATA	a caps query was answered with an empty capability

Returns

Any negative errno the pad's query function returns

mpipe_pad_send_event()

int mpipe_pad_send_event	(	struct mpipe_pad *	pad,
		struct mpipe_dispatch *	event )

#include <mpipe_pad.h>

Send an event to a pad.

Sends an event to the specified pad using the pad's event function.

Parameters

pad	Pointer to the Pad where the event should be sent
event	Pointer to the Dispatches to send

Returns

0 on success, negative errno on failure

mpipe_pad_send_event_default()

int mpipe_pad_send_event_default	(	struct mpipe_pad *	pad,
		struct mpipe_dispatch *	event )

#include <mpipe_pad.h>

Default event handler for pads.

Forwards an event received on pad to the peers of all opposite-side pads in the same element. If pad is a sink pad, the event is forwarded to the peer of each source pad; if pad is a source pad, it is forwarded to the peer of each sink pad.

If the element has only source pads or only sink pads, there are no opposite-side pads to send the event to, so the function returns -ENOTSUP.

Parameters

pad	Pointer to the Pad that received the event
event	Pointer to the Dispatches to send

Return values

0	The event reached at least one peer.
-ENOTSUP	No opposite-side pad has a peer, or every peer refused the event. A peer's own error is logged and not propagated.

mpipe_pad_set_caps()

int mpipe_pad_set_caps	(	struct mpipe_pad *	pad,
		const struct mpipe_structure *	caps )

#include <mpipe_pad.h>

Set the pad's capability.

Copies caps into the pad. Passing NULL resets the pad to constraining nothing, which is what a re-negotiation starts from.

Parameters

pad	Pad to set the capability on.
caps	Capability to copy in, or NULL to reset to ANY.

Returns

0 on success, negative errno on failure