GstPad

typedef struct {
  gpointer			element_private;

  GstPadTemplate		*padtemplate;

  GstPadDirection		 direction;

  /* streaming rec_lock */
  GStaticRecMutex		*stream_rec_lock;
  GstTask			*task;
  GMutex			*preroll_lock;
  GCond				*preroll_cond;

  /* block cond, mutex is from the object */
  GCond				*block_cond;
  GstPadBlockCallback		 block_callback;
  gpointer			 block_data;

  /* the pad capabilities */
  GstCaps			*caps;
  GstPadGetCapsFunction		getcapsfunc;
  GstPadSetCapsFunction		setcapsfunc;
  GstPadAcceptCapsFunction	 acceptcapsfunc;
  GstPadFixateCapsFunction	 fixatecapsfunc;

  GstPadActivateFunction	 activatefunc;
  GstPadActivateModeFunction	 activatepushfunc;
  GstPadActivateModeFunction	 activatepullfunc;

  /* pad link */
  GstPadLinkFunction		 linkfunc;
  GstPadUnlinkFunction		 unlinkfunc;
  GstPad			*peer;

  gpointer			 sched_private;

  /* data transport functions */
  GstPadChainFunction		 chainfunc;
  GstPadCheckGetRangeFunction	 checkgetrangefunc;
  GstPadGetRangeFunction	 getrangefunc;
  GstPadEventFunction		 eventfunc;

  GstActivateMode		 mode;

  /* generic query method */
  GstPadQueryTypeFunction	 querytypefunc;
  GstPadQueryFunction		 queryfunc;

  /* internal links */
  GstPadIntLinkFunction		 intlinkfunc;

  GstPadBufferAllocFunction      bufferallocfunc;

  /* whether to emit signals for have-data. counts number
   * of handlers attached. */
  gint				 do_buffer_signals;
  gint				 do_event_signals;
} GstPad;

The GstPad structure. Use the functions to update the variables.

enum GstPadDirection

typedef enum {
  GST_PAD_UNKNOWN,
  GST_PAD_SRC,
  GST_PAD_SINK
} GstPadDirection;

The direction of a pad.

enum GstPadFlags

typedef enum {
  GST_PAD_BLOCKED       = (GST_OBJECT_FLAG_LAST << 0),
  GST_PAD_FLUSHING      = (GST_OBJECT_FLAG_LAST << 1),
  GST_PAD_IN_GETCAPS    = (GST_OBJECT_FLAG_LAST << 2),
  GST_PAD_IN_SETCAPS    = (GST_OBJECT_FLAG_LAST << 3),
  GST_PAD_BLOCKING	= (GST_OBJECT_FLAG_LAST << 4),
  /* padding */
  GST_PAD_FLAG_LAST     = (GST_OBJECT_FLAG_LAST << 8)
} GstPadFlags;

Pad state flags

enum GstPadLinkReturn

typedef enum {
  GST_PAD_LINK_OK               =  0,
  GST_PAD_LINK_WRONG_HIERARCHY  = -1,
  GST_PAD_LINK_WAS_LINKED       = -2,
  GST_PAD_LINK_WRONG_DIRECTION  = -3,
  GST_PAD_LINK_NOFORMAT         = -4,
  GST_PAD_LINK_NOSCHED          = -5,
  GST_PAD_LINK_REFUSED          = -6
} GstPadLinkReturn;

Result values from gst_pad_link and friends.

GST_PAD_LINK_FAILED()

#define GST_PAD_LINK_FAILED(ret) ((ret) < GST_PAD_LINK_OK)

Macro to test if the given GstPadLinkReturn value indicates a failed link step.

GST_PAD_LINK_SUCCESSFUL()

#define GST_PAD_LINK_SUCCESSFUL(ret) ((ret) >= GST_PAD_LINK_OK)

Macro to test if the given GstPadLinkReturn value indicates a successful link step.

enum GstFlowReturn

typedef enum {
  /* custom success starts here */
  GST_FLOW_CUSTOM_SUCCESS = 100,

  /* core predefined */
  GST_FLOW_RESEND	  =  1,
  GST_FLOW_OK		  =  0,
  /* expected failures */
  GST_FLOW_NOT_LINKED     = -1,
  GST_FLOW_WRONG_STATE    = -2,
  /* error cases */
  GST_FLOW_UNEXPECTED     = -3,
  GST_FLOW_NOT_NEGOTIATED = -4,
  GST_FLOW_ERROR	  = -5,
  GST_FLOW_NOT_SUPPORTED  = -6,

  /* custom error starts here */
  GST_FLOW_CUSTOM_ERROR   = -100
} GstFlowReturn;

The result of passing data to a pad.

Note that the custom return values should not be exposed outside of the element scope and are available since 0.10.7.

enum GstActivateMode

typedef enum {
  GST_ACTIVATE_NONE,
  GST_ACTIVATE_PUSH,
  GST_ACTIVATE_PULL
} GstActivateMode;

The status of a GstPad. After activating a pad, which usually happens when the parent element goes from READY to PAUSED, the GstActivateMode defines if the pad operates in push or pull mode.

gst_pad_get_name()

#define gst_pad_get_name(pad) gst_object_get_name (GST_OBJECT_CAST (pad))

Get a copy of the name of the pad. g_free() after usage.

MT safe.

gst_pad_get_direction ()

GstPadDirection     gst_pad_get_direction               (GstPad *pad);

Gets the direction of the pad. The direction of the pad is decided at construction time so this function does not take the LOCK.

gst_pad_get_parent()

#define gst_pad_get_parent(pad) gst_object_get_parent (GST_OBJECT_CAST (pad))

Get the parent of pad. This function increases the refcount of the parent object so you should gst_object_unref() it after usage. Can return NULL if the pad did not have a parent.

MT safe.

gst_pad_get_parent_element ()

GstElement*         gst_pad_get_parent_element          (GstPad *pad);

Gets the parent of pad, cast to a GstElement. If a pad has no parent or its parent is not an element, return NULL.

gst_pad_get_pad_template ()

GstPadTemplate*     gst_pad_get_pad_template            (GstPad *pad);

Gets the template for pad.

gst_pad_link ()

GstPadLinkReturn    gst_pad_link                        (GstPad *srcpad,
                                                         GstPad *sinkpad);

Links the source pad and the sink pad.

gst_pad_unlink ()

gboolean            gst_pad_unlink                      (GstPad *srcpad,
                                                         GstPad *sinkpad);

Unlinks the source pad from the sink pad. Will emit the GstPad::unlinked signal on both pads.

gst_pad_is_linked ()

gboolean            gst_pad_is_linked                   (GstPad *pad);

Checks if a pad is linked to another pad or not.

gst_pad_can_link ()

gboolean            gst_pad_can_link                    (GstPad *srcpad,
                                                         GstPad *sinkpad);

Checks if the source pad and the sink pad can be linked. Both srcpad and sinkpad must be unlinked.

gst_pad_get_caps ()

GstCaps*            gst_pad_get_caps                    (GstPad *pad);

Gets the capabilities this pad can produce or consume. Note that this method doesn't necessarily return the caps set by gst_pad_set_caps() - use GST_PAD_CAPS() for that instead. gst_pad_get_caps returns all possible caps a pad can operate with, using the pad's get_caps function; this returns the pad template caps if not explicitly set.

gst_pad_get_allowed_caps ()

GstCaps*            gst_pad_get_allowed_caps            (GstPad *pad);

Gets the capabilities of the allowed media types that can flow through pad and its peer.

The allowed capabilities is calculated as the intersection of the results of calling gst_pad_get_caps() on pad and its peer. The caller owns a reference on the resulting caps.

gst_pad_get_negotiated_caps ()

GstCaps*            gst_pad_get_negotiated_caps         (GstPad *pad);

Gets the capabilities of the media type that currently flows through pad and its peer.

This function can be used on both src and sinkpads. Note that srcpads are always negotiated before sinkpads so it is possible that the negotiated caps on the srcpad do not match the negotiated caps of the peer.

gst_pad_get_pad_template_caps ()

const GstCaps*      gst_pad_get_pad_template_caps       (GstPad *pad);

Gets the capabilities for pad's template.

gst_pad_set_caps ()

gboolean            gst_pad_set_caps                    (GstPad *pad,
                                                         GstCaps *caps);

Sets the capabilities of this pad. The caps must be fixed. Any previous caps on the pad will be unreffed. This function refs the caps so you should unref if as soon as you don't need it anymore. It is possible to set NULL caps, which will make the pad unnegotiated again.

gst_pad_get_peer ()

GstPad*             gst_pad_get_peer                    (GstPad *pad);

Gets the peer of pad. This function refs the peer pad so you need to unref it after use.

gst_pad_peer_get_caps ()

GstCaps*            gst_pad_peer_get_caps               (GstPad *pad);

Gets the capabilities of the peer connected to this pad.

gst_pad_use_fixed_caps ()

void                gst_pad_use_fixed_caps              (GstPad *pad);

A helper function you can use that sets the gst_pad_get_fixed_caps_func as the getcaps function for the pad. This way the function will always return the negotiated caps or in case the pad is not negotiated, the padtemplate caps.

Use this function on a pad that, once _set_caps() has been called on it, cannot be renegotiated to something else.

gst_pad_is_active ()

gboolean            gst_pad_is_active                   (GstPad *pad);

Query if a pad is active

gst_pad_set_blocked ()

gboolean            gst_pad_set_blocked                 (GstPad *pad,
                                                         gboolean blocked);

Blocks or unblocks the dataflow on a pad. This function is a shortcut for gst_pad_set_blocked_async() with a NULL callback.

gst_pad_set_blocked_async ()

gboolean            gst_pad_set_blocked_async           (GstPad *pad,
                                                         gboolean blocked,
                                                         GstPadBlockCallback callback,
                                                         gpointer user_data);

Blocks or unblocks the dataflow on a pad. The provided callback is called when the operation succeeds; this happens right before the next attempt at pushing a buffer on the pad.

This can take a while as the pad can only become blocked when real dataflow is happening. When the pipeline is stalled, for example in PAUSED, this can take an indeterminate amount of time. You can pass NULL as the callback to make this call block. Be careful with this blocking call as it might not return for reasons stated above.

GstPadBlockCallback ()

void                (*GstPadBlockCallback)              (GstPad *pad,
                                                         gboolean blocked,
                                                         gpointer user_data);

Callback used by gst_pad_set_blocked_async(). Gets called when the blocking operation succeeds.

gst_pad_is_blocked ()

gboolean            gst_pad_is_blocked                  (GstPad *pad);

Checks if the pad is blocked or not. This function returns the last requested state of the pad. It is not certain that the pad is actually blocking at this point (see gst_pad_is_blocking()).

gst_pad_is_blocking ()

gboolean            gst_pad_is_blocking                 (GstPad *pad);

Checks if the pad is blocking or not. This is a guaranteed state of whether the pad is actually blocking on a GstBuffer or a GstEvent.

Since 0.10.11

gst_pad_add_data_probe ()

gulong              gst_pad_add_data_probe              (GstPad *pad,
                                                         GCallback handler,
                                                         gpointer data);

Adds a "data probe" to a pad. This function will be called whenever data passes through a pad. In this case data means both events and buffers. The probe will be called with the data as an argument, meaning handler should have the same callback signature as the GstPad::have-data signal. Note that the data will have a reference count greater than 1, so it will be immutable -- you must not change it.

For source pads, the probe will be called after the blocking function, if any (see gst_pad_set_blocked_async()), but before looking up the peer to chain to. For sink pads, the probe function will be called before configuring the sink with new caps, if any, and before calling the pad's chain function.

Your data probe should return TRUE to let the data continue to flow, or FALSE to drop it. Dropping data is rarely useful, but occasionally comes in handy with events.

Although probes are implemented internally by connecting handler to the have-data signal on the pad, if you want to remove a probe it is insufficient to only call g_signal_handler_disconnect on the returned handler id. To remove a probe, use the appropriate function, such as gst_pad_remove_data_probe().

gst_pad_add_data_probe_full ()

gulong              gst_pad_add_data_probe_full         (GstPad *pad,
                                                         GCallback handler,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Adds a "data probe" to a pad. This function will be called whenever data passes through a pad. In this case data means both events and buffers. The probe will be called with the data as an argument, meaning handler should have the same callback signature as the GstPad::have-data signal. Note that the data will have a reference count greater than 1, so it will be immutable -- you must not change it.

For source pads, the probe will be called after the blocking function, if any (see gst_pad_set_blocked_async()), but before looking up the peer to chain to. For sink pads, the probe function will be called before configuring the sink with new caps, if any, and before calling the pad's chain function.

Your data probe should return TRUE to let the data continue to flow, or FALSE to drop it. Dropping data is rarely useful, but occasionally comes in handy with events.

Although probes are implemented internally by connecting handler to the have-data signal on the pad, if you want to remove a probe it is insufficient to only call g_signal_handler_disconnect on the returned handler id. To remove a probe, use the appropriate function, such as gst_pad_remove_data_probe().

The notify function is called when the probe is disconnected and usually used to free data.

Since 0.10.20

gst_pad_add_buffer_probe ()

gulong              gst_pad_add_buffer_probe            (GstPad *pad,
                                                         GCallback handler,
                                                         gpointer data);

Adds a probe that will be called for all buffers passing through a pad. See gst_pad_add_data_probe() for more information.

gst_pad_add_buffer_probe_full ()

gulong              gst_pad_add_buffer_probe_full       (GstPad *pad,
                                                         GCallback handler,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Adds a probe that will be called for all buffers passing through a pad. See gst_pad_add_data_probe() for more information.

The notify function is called when the probe is disconnected and usually used to free data.

Since 0.10.20

gst_pad_add_event_probe ()

gulong              gst_pad_add_event_probe             (GstPad *pad,
                                                         GCallback handler,
                                                         gpointer data);

Adds a probe that will be called for all events passing through a pad. See gst_pad_add_data_probe() for more information.

gst_pad_add_event_probe_full ()

gulong              gst_pad_add_event_probe_full        (GstPad *pad,
                                                         GCallback handler,
                                                         gpointer data,
                                                         GDestroyNotify notify);

Adds a probe that will be called for all events passing through a pad. See gst_pad_add_data_probe() for more information.

The notify function is called when the probe is disconnected and usually used to free data.

Since 0.10.20

gst_pad_remove_data_probe ()

void                gst_pad_remove_data_probe           (GstPad *pad,
                                                         guint handler_id);

Removes a data probe from pad.

gst_pad_remove_buffer_probe ()

void                gst_pad_remove_buffer_probe         (GstPad *pad,
                                                         guint handler_id);

Removes a buffer probe from pad.

gst_pad_remove_event_probe ()

void                gst_pad_remove_event_probe          (GstPad *pad,
                                                         guint handler_id);

Removes an event probe from pad.

gst_pad_new ()

GstPad*             gst_pad_new                         (const gchar *name,
                                                         GstPadDirection direction);

Creates a new pad with the given name in the given direction. If name is NULL, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name.

gst_pad_new_from_template ()

GstPad*             gst_pad_new_from_template           (GstPadTemplate *templ,
                                                         const gchar *name);

Creates a new pad with the given name from the given template. If name is NULL, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name.

gst_pad_new_from_static_template ()

GstPad*             gst_pad_new_from_static_template    (GstStaticPadTemplate *templ,
                                                         const gchar *name);

Creates a new pad with the given name from the given static template. If name is NULL, a guaranteed unique name (across all pads) will be assigned. This function makes a copy of the name so you can safely free the name.

gst_pad_alloc_buffer ()

GstFlowReturn       gst_pad_alloc_buffer                (GstPad *pad,
                                                         guint64 offset,
                                                         gint size,
                                                         GstCaps *caps,
                                                         GstBuffer **buf);

Allocates a new, empty buffer optimized to push to pad pad. This function only works if pad is a source pad and has a peer.

A new, empty GstBuffer will be put in the buf argument. You need to check the caps of the buffer after performing this function and renegotiate to the format if needed.

gst_pad_alloc_buffer_and_set_caps ()

GstFlowReturn       gst_pad_alloc_buffer_and_set_caps   (GstPad *pad,
                                                         guint64 offset,
                                                         gint size,
                                                         GstCaps *caps,
                                                         GstBuffer **buf);

In addition to the function gst_pad_alloc_buffer(), this function automatically calls gst_pad_set_caps() when the caps of the newly allocated buffer are different from the pad caps.

gst_pad_set_bufferalloc_function ()

void                gst_pad_set_bufferalloc_function    (GstPad *pad,
                                                         GstPadBufferAllocFunction bufalloc);

Sets the given bufferalloc function for the pad. Note that the bufferalloc function can only be set on sinkpads.

GstPadBufferAllocFunction ()

GstFlowReturn       (*GstPadBufferAllocFunction)        (GstPad *pad,
                                                         guint64 offset,
                                                         guint size,
                                                         GstCaps *caps,
                                                         GstBuffer **buf);

Ask the sinkpad pad to allocate a buffer with offset, size and caps. The result will be stored in buf.

The purpose of this function is to allocate a buffer that is optimal to be processed by pad. The function is mostly overridden by elements that can provide a hardware buffer in order to avoid additional memcpy operations.

The function can return a buffer that does not have caps, in which case the upstream element requests a format change. If a format change was requested, the returned buffer will be one to hold the data of said new caps, so its size might be different from size.

When this function returns anything else than GST_FLOW_OK, the buffer allocation failed and buf does not contain valid data.

By default this function returns a new buffer of size and with caps containing purely malloced data. The buffer should be freed with gst_buffer_unref() after usage.

gst_pad_set_chain_function ()

void                gst_pad_set_chain_function          (GstPad *pad,
                                                         GstPadChainFunction chain);

Sets the given chain function for the pad. The chain function is called to process a GstBuffer input buffer. see GstPadChainFunction for more details.

GstPadChainFunction ()

GstFlowReturn       (*GstPadChainFunction)              (GstPad *pad,
                                                         GstBuffer *buffer);

A function that will be called on sinkpads when chaining buffers. The function typically processes the data contained in the buffer and either consumes the data or passes it on to the internally linked pad(s).

The implementer of this function receives a refcount to buffer and should gst_buffer_unref() when the buffer is no longer needed.

When a chain function detects an error in the data stream, it must post an error on the buffer and return an appropriate GstFlowReturn value.

gst_pad_set_checkgetrange_function ()

void                gst_pad_set_checkgetrange_function  (GstPad *pad,
                                                         GstPadCheckGetRangeFunction check);

Sets the given checkgetrange function for the pad. Implement this function on a pad if you dynamically support getrange based scheduling on the pad.

GstPadCheckGetRangeFunction ()

gboolean            (*GstPadCheckGetRangeFunction)      (GstPad *pad);

Check if pad can be activated in pull mode.

This function will be deprecated after 0.10; use the seeking query to check if a pad can support random access.

gst_pad_get_range ()

GstFlowReturn       gst_pad_get_range                   (GstPad *pad,
                                                         guint64 offset,
                                                         guint size,
                                                         GstBuffer **buffer);

When pad is flushing this function returns GST_FLOW_WRONG_STATE immediatly.

Calls the getrange function of pad, see GstPadGetRangeFunction for a description of a getrange function. If pad has no getrange function installed (see gst_pad_set_getrange_function()) this function returns GST_FLOW_NOT_SUPPORTED.

buffer's caps must either be unset or the same as what is already configured on pad. Renegotiation within a running pull-mode pipeline is not supported.

This is a lowlevel function. Usualy gst_pad_pull_range() is used.

gst_pad_set_getrange_function ()

void                gst_pad_set_getrange_function       (GstPad *pad,
                                                         GstPadGetRangeFunction get);

Sets the given getrange function for the pad. The getrange function is called to produce a new GstBuffer to start the processing pipeline. see GstPadGetRangeFunction for a description of the getrange function.

GstPadGetRangeFunction ()

GstFlowReturn       (*GstPadGetRangeFunction)           (GstPad *pad,
                                                         guint64 offset,
                                                         guint length,
                                                         GstBuffer **buffer);

This function will be called on source pads when a peer element request a buffer at the specified offset and length. If this function returns GST_FLOW_OK, the result buffer will be stored in buffer. The contents of buffer is invalid for any other return value.

This function is installed on a source pad with gst_pad_set_getrange_function() and can only be called on source pads after they are successfully activated with gst_pad_activate_pull().

offset and length are always given in byte units. offset must normally be a value between 0 and the length in bytes of the data available on pad. The length (duration in bytes) can be retrieved with a GST_QUERY_DURATION or with a GST_QUERY_SEEKING.

Any offset larger or equal than the length will make the function return GST_FLOW_UNEXPECTED, which corresponds to EOS. In this case buffer does not contain a valid buffer.

The buffer size of buffer might be smaller than length when offset is near the end of the stream.

It is allowed to call this function with a 0 length and valid offset, in which case buffer will contain a 0-sized buffer and the function returns GST_FLOW_OK.

When this function is called with a -1 offset, the sequentially next buffer of length length in the stream is returned.

When this function is called with a -1 length, a buffer with a default optimal length is returned in buffer. The length might depend on the value of offset.

gst_pad_set_event_function ()

void                gst_pad_set_event_function          (GstPad *pad,
                                                         GstPadEventFunction event);

Sets the given event handler for the pad.