docs/gst/tmpl/gstpad.sgml

<!-- ##### SECTION Title ##### -->
GstPad

<!-- ##### SECTION Short_Description ##### -->
The connection between Elements

<!-- ##### SECTION Long_Description ##### -->
<para>
#GstElement are connected to each other via "pads", which are extremely light-weight generic 
connections. After two pad are retrieved from an element with gst_element_get_pad(), the pads
can be connected with gst_pad_connect().
</para>
<para>
PedTemplates are use to describe the runtime behaviour of an element and what pads it
will have during its lifetime. Pads are typically created from a padtemplate with 
GST_PADTEMPLATE_NEW() or with the factory macro GST_PADTEMPLATE_FACTORY().
</para>
<para>
Pad and PadTemplates have #GstCaps attached to it to describe the media type they
are capable of dealing with. gst_pad_get_caps() and gst_pad_set_caps() are used to
manipulate the caps of the pads. gst_padtemplate_get_caps() is used to get the
caps of a padtemplate. It's not possible to modify the caps of a padtemplate after
creation. The following code example shows the code to create a pad from a padtemplate.
<programlisting>
GST_PADTEMPLATE_FACTORY (my_factory,
  "sink",		/* the name of the pad */
  GST_PAD_SINK,		/* the direction of the pad */
  GST_PAD_ALWAYS, 	/* when this pad will be present */
  GST_CAPS_NEW (	/* the capabilities of the padtemplate */
    "my_caps",
    "audio/raw",
      "format",		GST_PROPS_STRING ("int"),
      "channels",	GST_PROPS_INT_RANGE (1, 6)
  )
)

void
my_method (void) 
{
  GstPad *pad;
  
  pad = gst_pad_new_from_template (GST_PADTEMPLATE_GET (my_factory), "sink");
  ...
}
</programlisting>
Pads created from a padtemplate cannot set capabilities that are incompatible with
the padtemplates capabilities.
</para>
<para>
Pads without padtemplates can be created with gst_pad_new() which takes a direction and
a name as an argument.
</para>
<para>
gst_pad_get_parent() will retrieve the GstElement that owns the pad.
</para>
<para>
GstElements creating a pad will typicilally use the various gst_pad_set_*_function() calls
to register callbacks for various events on the pads.
</para>
<para>
GstElements will use gst_pad_push() and gst_pad_pull() to push out or pull a buffer in. The
gst_pad_pullregion() function can be used to request for a buffer with a specific offset (in
time or in bytes).
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GstCaps, #GstElement
</para>

<!-- ##### MACRO GST_PAD_NAME ##### -->
<para>
Get the name of the pad.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_ELEMENT_PRIVATE ##### -->
<para>
Get the private data set by the element that owns the pad.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_PARENT ##### -->
<para>
Get the parent element of this pad.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_PADTEMPLATE ##### -->
<para>
Get the padtemplate that was used to create this pad. NULL if no padtemplate
was used.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_REALIZE ##### -->
<para>
Return the real pad of this pad.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_DIRECTION ##### -->
<para>
Get the pad direction.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_CAPS ##### -->
<para>
Get the capabilities of a pad.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_PEER ##### -->
<para>
Get the peerpad of this pad.
</para>

@pad: the pad to query


<!-- ##### MACRO GST_PAD_CONNECTED ##### -->
<para>
Is this pad connected.
</para>

@pad: the pad to check


<!-- ##### MACRO GST_PAD_CAN_PULL ##### -->
<para>
Can this pad be used to pull a buffer.
</para>

@pad: the pad to check


<!-- ##### STRUCT GstPad ##### -->
<para>

</para>


<!-- ##### USER_FUNCTION GstPadChainFunction ##### -->
<para>
The function that will be called when chaining buffers.
</para>

@pad: the pad that performed the chain
@buf: the buffer that is chained


<!-- ##### USER_FUNCTION GstPadGetFunction ##### -->
<para>
The function that will be called when pulling a buffer.
</para>

@pad: the pad to get a buffer from
@Returns: a #GstBuffer


<!-- ##### USER_FUNCTION GstPadGetRegionFunction ##### -->
<para>
The function that will be called when pulling a region buffer.
You can specify which buffer to get using an offset/length pair or
a start/stop timecode pair.
</para>

@pad: the pad to get a buffer from
@type: the type of region to get (time or offset based)
@offset: the offset of the region to get
@len: the length of the region to get
@Returns: a #GstBuffer
<!-- # Unused Parameters # -->
@size: the size of the region to get


<!-- ##### USER_FUNCTION GstPadNewCapsFunction ##### -->
<para>
The function that will be called when the caps of the pad has
changed.
</para>

@pad: The pad that has its caps changed
@caps: the new caps of the pad


<!-- ##### USER_FUNCTION GstPadBufferPoolFunction ##### -->
<para>
The function that will be called when a bufferpool is requested
from this pad.
</para>

@pad: the pad with the bufferpool
@Returns: the GstBufferPool associated with this pad.


<!-- ##### ENUM GstPadNegotiateReturn ##### -->
<para>
The possible results from padnegotiation.
</para>

@GST_PAD_NEGOTIATE_FAIL: The pads could not agree about the media type.
@GST_PAD_NEGOTIATE_AGREE: The pads agreed about the media type.
@GST_PAD_NEGOTIATE_TRY: The pad did not agree and suggests another media type.

<!-- ##### USER_FUNCTION GstPadNegotiateFunction ##### -->
<para>
The function that will be called when negotiating.
</para>

@pad: The pad that is being negotiated
@caps: The current caps that are being negotiated
@data: A generic gpointer that can be used to store user_data
@Returns: The result of the negotiation process


<!-- ##### ENUM GstRegionType ##### -->
<para>
the region types for #gst_pad_pullregion.
</para>

@GST_REGION_VOID: 
@GST_REGION_OFFSET_LEN: an offet/length pair
@GST_REGION_TIME_LEN: a time start/length pair

<!-- ##### USER_FUNCTION GstPadPullRegionFunction ##### -->
<para>
The function that will be called when pulling a region buffer.
You can specify which buffer to get using an offset/length pair or
a start/stop timecode pair.
</para>

@pad: the pad to get a buffer from
@type: the type of region to get (time or offset based)
@offset: the offset of the region to get
@len: the length of the region to get
@Returns: a #GstBuffer
</para>


<!-- ##### ENUM GstPadDirection ##### -->
<para>
The direction this pad is.
</para>

@GST_PAD_UNKNOWN: direction is unknown
@GST_PAD_SRC: this is a source pad
@GST_PAD_SINK: this is a sink pad

<!-- ##### ENUM GstPadFlags ##### -->
<para>
Flags for the pad.
</para>

@GST_PAD_DISABLED: the pad is disabled
@GST_PAD_EOS: the pad is in end of stream state
@GST_PAD_FLAG_LAST: subclasses can use this number to enumerate their flags

<!-- ##### FUNCTION gst_pad_new ##### -->
<para>

</para>

@name: 
@direction: 
@Returns: 


<!-- ##### MACRO gst_pad_destroy ##### -->
<para>
Destroy the pad.
</para>

@pad: the pad to destroy


<!-- ##### FUNCTION gst_pad_new_from_template ##### -->
<para>

</para>

@templ: 
@name: 
@Returns: 
<!-- # Unused Parameters # -->
@temp: 


<!-- ##### FUNCTION gst_pad_get_direction ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_chain_function ##### -->
<para>

</para>

@pad: 
@chain: 


<!-- ##### FUNCTION gst_pad_set_get_function ##### -->
<para>

</para>

@pad: 
@get: 


<!-- ##### FUNCTION gst_pad_set_getregion_function ##### -->
<para>

</para>

@pad: 
@getregion: 


<!-- ##### FUNCTION gst_pad_set_negotiate_function ##### -->
<para>

</para>

@pad: 
@nego: 


<!-- ##### FUNCTION gst_pad_set_newcaps_function ##### -->
<para>

</para>

@pad: 
@newcaps: 


<!-- ##### FUNCTION gst_pad_set_bufferpool_function ##### -->
<para>

</para>

@pad: 
@bufpool: 


<!-- ##### FUNCTION gst_pad_set_caps ##### -->
<para>

</para>

@pad: 
@caps: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_caps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_check_compatibility ##### -->
<para>

</para>

@srcpad: 
@sinkpad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_name ##### -->
<para>

</para>

@pad: 
@name: 


<!-- ##### FUNCTION gst_pad_get_name ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_element_private ##### -->
<para>

</para>

@pad: 
@priv: 


<!-- ##### FUNCTION gst_pad_get_element_private ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_parent ##### -->
<para>

</para>

@pad: 
@parent: 


<!-- ##### FUNCTION gst_pad_get_parent ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_sched ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_set_sched ##### -->
<para>

</para>

@pad: 
@sched: 


<!-- ##### FUNCTION gst_pad_get_real_parent ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_add_ghost_pad ##### -->
<para>

</para>

@pad: 
@ghostpad: 


<!-- ##### FUNCTION gst_pad_remove_ghost_pad ##### -->
<para>

</para>

@pad: 
@ghostpad: 


<!-- ##### FUNCTION gst_pad_get_ghost_pad_list ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_peer ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_connect ##### -->
<para>

</para>

@srcpad: 
@sinkpad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_disconnect ##### -->
<para>

</para>

@srcpad: 
@sinkpad: 


<!-- ##### FUNCTION gst_pad_push ##### -->
<para>

</para>

@pad: 
@buf: 
<!-- # Unused Parameters # -->
@buffer: 


<!-- ##### FUNCTION gst_pad_pull ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_pullregion ##### -->
<para>

</para>

@pad: 
@type: 
@offset: 
@len: 
@Returns: 
<!-- # Unused Parameters # -->
@size: 


<!-- ##### FUNCTION gst_pad_get_bufferpool ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_load_and_connect ##### -->
<para>

</para>

@self: 
@parent: 
<!-- # Unused Parameters # -->
@element: 
@elements: 


<!-- ##### FUNCTION gst_pad_negotiate_proxy ##### -->
<para>

</para>

@srcpad: 
@destpad: 
@caps: 
@Returns: 
<!-- # Unused Parameters # -->
@counter: 
@count: 


<!-- ##### FUNCTION gst_pad_renegotiate ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_padtemplate ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### FUNCTION gst_pad_get_padtemplate_caps ##### -->
<para>

</para>

@pad: 
@Returns: 


<!-- ##### STRUCT GstRealPad ##### -->
<para>

</para>

@pad: 
@caps: 
@direction: 
@threadstate: 
@peer: 
@bufpen: 
@regiontype: 
@offset: 
@len: 
@sched: 
@chainfunc: 
@chainhandler: 
@getfunc: 
@gethandler: 
@eventfunc: 
@eventhandler: 
@getregionfunc: 
@pullregionfunc: 
@negotiatefunc: 
@newcapsfunc: 
@bufferpoolfunc: 
@ghostpads: 

<!-- ##### MACRO GST_RPAD_LEN ##### -->
<para>
Get the length of the region that is being pulled.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_OFFSET ##### -->
<para>
Get the offset of the region that is being pulled.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_SCHED ##### -->
<para>

</para>

@pad: 


<!-- ##### MACRO GST_RPAD_REGIONTYPE ##### -->
<para>
Get the type of the region that is being pulled.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_DIRECTION ##### -->
<para>
Get the direction of the real pad.
</para>

@pad: the realpad to query.


<!-- ##### MACRO GST_RPAD_CAPS ##### -->
<para>
Get the caps of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_PEER ##### -->
<para>
Get the peer element of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_BUFPEN ##### -->
<para>
Get the bufpen of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_CHAINFUNC ##### -->
<para>
Get the chain function of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_GETFUNC ##### -->
<para>
Get get getfunction of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_GETREGIONFUNC ##### -->
<para>
Get the getregion function of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_PULLREGIONFUNC ##### -->
<para>
Get the pullregion function of the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_NEGOTIATEFUNC ##### -->
<para>
Get the negotiate function from the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_NEWCAPSFUNC ##### -->
<para>
Get the newcaps function from the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_RPAD_BUFFERPOOLFUNC ##### -->
<para>
Get the bufferpoolfunction from the real pad.
</para>

@pad: the real pad to query.


<!-- ##### MACRO GST_GPAD_REALPAD ##### -->
<para>
Get the real pad of this ghost pad.
</para>

@pad: the real pad to query.


<!-- ##### STRUCT GstGhostPad ##### -->
<para>

</para>

@pad: 
@realpad: 

<!-- ##### FUNCTION gst_ghost_pad_new ##### -->
<para>

</para>

@name: 
@pad: 
@Returns: 


<!-- ##### ENUM GstPadPresence ##### -->
<para>
Indicates when this pad will become available.
</para>

@GST_PAD_ALWAYS: the pad is always available
@GST_PAD_SOMETIMES: the pad will become available depending on the media stream
@GST_PAD_REQUEST: th pad is only available on request with 
gst_element_request_pad_by_name() or gst_element_request_compatible_pad().

<!-- ##### STRUCT GstPadTemplate ##### -->
<para>

</para>

@object: 
@name_template: 
@direction: 
@presence: 
@caps: 

<!-- ##### MACRO GST_PADTEMPLATE_CAPS ##### -->
<para>
Get a handle to the padtemplate #GstCaps
</para>

@templ: the template to query


<!-- ##### MACRO GST_PADTEMPLATE_DIRECTION ##### -->
<para>
Get the direction of the padtemplate.
</para>

@templ: the template to query


<!-- ##### MACRO GST_PADTEMPLATE_NAME_TEMPLATE ##### -->
<para>
Get the nametemplate of the padtemplate.
</para>

@templ: the template to query


<!-- ##### MACRO GST_PADTEMPLATE_PRESENCE ##### -->
<para>
Get the presence of the padtemplate.
</para>

@templ: the template to query


<!-- ##### MACRO GST_PADTEMPLATE_NEW ##### -->
<para>
Create a new padtemplate.
</para>

@padname: the nametemplate for the pads that will be created with this template
@dir: the direction of the pads.
@pres: the presence of the pads.
@a...: the capabilities of this padtemplate usually created with GST_CAPS_NEW()


<!-- ##### MACRO GST_PADTEMPLATE_FACTORY ##### -->
<para>
Create a factory for a padtemplate. This can be used if you only want one instance
of the padtemplate. Use GST_PADTEMPLATE_GET() to get the unique padtemplate.
</para>

@name: th name of the factory
@padname: the nametemplate of the pads
@dir: the direction of the pads.
@pres: the presence of the pads.
@a...: the capabilities of this padtemplate, usually created with GST_CAPS_NEW()


<!-- ##### MACRO GST_PADTEMPLATE_GET ##### -->
<para>
Get the padtemplate of the factory created with GST_PADTEMPLATE_FACTORY()
</para>

@fact: the factory name to get the padtemplate from.


<!-- ##### FUNCTION gst_padtemplate_new ##### -->
<para>

</para>

@name_template: 
@direction: 
@presence: 
@caps: 
@Varargs: 
@Returns: 


<!-- ##### FUNCTION gst_padtemplate_load_thyself ##### -->
<para>

</para>

@parent: 
@Returns: 


<!-- ##### FUNCTION gst_padtemplate_save_thyself ##### -->
<para>

</para>

@templ: 
@parent: 
@Returns: 


<!-- ##### FUNCTION gst_padtemplate_get_caps ##### -->
<para>

</para>

@templ: 
@Returns: 


<!-- ##### FUNCTION gst_padtemplate_get_caps_by_name ##### -->
<para>

</para>

@templ: 
@name: 
@Returns: