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),
  /* 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 {
  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
} GstFlowReturn;

The result of passing data to a linked pad.

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 "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 returns 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 *srcpad);

Gets the capabilities of the allowed media types that can flow through srcpad and its peer. The pad must be a source pad. The caller must free 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 blocked at this point.

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

You need to check the caps of the buffer after performing this function and renegotiate to the format if needed.

A new, empty GstBuffer will be put in the buf argument.

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.

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.

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.

GstPadChainFunction ()

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

A function that will be called on sinkpads when chaining buffers.

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);

Calls the getrange function of pad.

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. Getrange functions cannot return NULL.

GstPadGetRangeFunction ()

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

This function will be called on sourcepads 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.

gst_pad_set_event_function ()

void        gst_pad_set_event_function      (GstPad *pad,
                                             GstPadEventFunction event);

Sets the given event handler for the pad.

GstPadEventFunction ()

gboolean    (*GstPadEventFunction)          (GstPad *pad,
                                             GstEvent *event);

Function signature to handle an event for the pad.

gst_pad_set_link_function ()

void        gst_pad_set_link_function       (GstPad *pad,
                                             GstPadLinkFunction link);

Sets the given link function for the pad. It will be called when the pad is linked with another pad.

The return value GST_PAD_LINK_OK should be used when the connection can be made.

The return value GST_PAD_LINK_REFUSED should be used when the connection cannot be made for some reason.

If link is installed on a source pad, it should call the GstPadLinkFunction of the peer sink pad, if present.

GstPadLinkFunction ()

GstPadLinkReturn (*GstPadLinkFunction)      (GstPad *pad,
                                             GstPad *peer);

Function signature to handle a new link on the pad.

gst_pad_set_unlink_function ()

void        gst_pad_set_unlink_function     (GstPad *pad,
                                             GstPadUnlinkFunction unlink);

Sets the given unlink function for the pad. It will be called when the pad is unlinked.

GstPadUnlinkFunction ()

void        (*GstPadUnlinkFunction)         (GstPad *pad);

Function signature to handle a unlinking the pad prom its peer.

gst_pad_accept_caps ()

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

Check if the given pad accepts the caps.

gst_pad_set_acceptcaps_function ()

void        gst_pad_set_acceptcaps_function (GstPad *pad,
                                             GstPadAcceptCapsFunction acceptcaps);

Sets the given acceptcaps function for the pad. The acceptcaps function will be called to check if the pad can accept the given caps.

GstPadAcceptCapsFunction ()

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

Check if pad can accept caps. By default this function will see if caps intersect with the result from gst_pad_get_caps() by can be overridden to perform extra checks.

gst_pad_set_getcaps_function ()

void        gst_pad_set_getcaps_function    (GstPad *pad,
                                             GstPadGetCapsFunction getcaps);

Sets the given getcaps function for the pad. getcaps should return the allowable caps for a pad in the context of the element's state, its link to other elements, and the devices or files it has opened. These caps must be a subset of the pad template caps. In the NULL state with no links, getcaps should ideally return the same caps as the pad template. In rare circumstances, an object property can affect the caps returned by getcaps, but this is discouraged.

You do not need to call this function if pad's allowed caps are always the same as the pad template caps. This can only be true if the padtemplate has fixed simple caps.

For most filters, the caps returned by getcaps is directly affected by the allowed caps on other pads. For demuxers and decoders, the caps returned by the srcpad's getcaps function is directly related to the stream data. Again, getcaps should return the most specific caps it reasonably can, since this helps with autoplugging.

Note that the return value from getcaps is owned by the caller, so the caller should unref the caps after usage.

GstPadGetCapsFunction ()

GstCaps*    (*GstPadGetCapsFunction)        (GstPad *pad);

Returns a copy of the capabilities of the specified pad. By default this function will return the pad template capabilities, but can optionally be overridden by elements.

gst_pad_proxy_getcaps ()

GstCaps*    gst_pad_proxy_getcaps           (GstPad *pad);

Calls gst_pad_get_allowed_caps() for every other pad belonging to the same element as pad, and returns the intersection of the results.

This function is useful as a default getcaps function for an element that can handle any stream format, but requires all its pads to have the same caps. Two such elements are tee and aggregator.

gst_pad_set_setcaps_function ()</