mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2025-02-17 11:45:25 +00:00
178 lines
5.6 KiB
Text
178 lines
5.6 KiB
Text
purpose
|
|
-------
|
|
|
|
GStreamer has a very flexible mechanism to describe media types using
|
|
mime types and key/value pairs (GstCaps). The definition of media types
|
|
is entirely done by the plugins which can set the media type to one or
|
|
more of the plugins GstPads.
|
|
|
|
Pads with the same mime type and 'compatible' properties are allowed to
|
|
connect. It is possible that a pad can accept or produce many different
|
|
media types.
|
|
|
|
The purpose of caps negotiation is to provide a framework for plugins so
|
|
that they can agree on a common media type for their pads.
|
|
|
|
|
|
Capabilities (GstCaps)
|
|
----------------------
|
|
|
|
The core component in the caps negotiation system are GstCaps. They consist
|
|
of:
|
|
|
|
- a name (ex. "my_audio_capabilities")
|
|
- a mime-type (ex. audio/raw, audio/mp3, ...)
|
|
- a list of key/value pairs (ex. channels=2, rate=44100, ...)
|
|
|
|
The list of key/value pairs is maintained by the GstProps object.
|
|
|
|
The GstProps object maintains a GList of GstPropsEntries. An entry has
|
|
a key, which is always a string constant (internally converted to a GQuark)
|
|
and a value, which can be one of the following:
|
|
|
|
- an integer constant (ex. 5)
|
|
- a float contant (ex. 1.0)
|
|
- a string constant (ex. "int")
|
|
- a boolean constant (ex. FALSE)
|
|
- a fourcc constant (ex. I420)
|
|
* fourcc codes are usually used to describe a video format
|
|
|
|
In addition to these constant values, the following variable values are
|
|
supported too:
|
|
|
|
- an integer range (ex. 0-200)
|
|
- a float range (ex. 1.0-3.0)
|
|
- a list of values (ex. 1, 2, 5).
|
|
* A List cannot contain another list and the
|
|
entries in the list should all have the
|
|
same type (int, float, string, fourcc). It is
|
|
allowed to mix integers/floats and
|
|
integer/float ranges in a list.
|
|
|
|
A capability is usually described as follows:
|
|
|
|
GST_CAPS_NEW (
|
|
capability name ---> "my_audio_capabilities",
|
|
mime-type ---------> "audio/raw",
|
|
( "format", GST_PROPS_STRING ("int"),
|
|
GstProps ---------> ( "channels", GST_PROPS_INT_RANGE (1, 2),
|
|
(list of entries) ( "rate", GST_PROPS_INT (44100)
|
|
)
|
|
|
|
(-----------) (--------------------------)
|
|
entry key entry value
|
|
|
|
Two capabilities can be chained together to form a larger capability:
|
|
|
|
( GST_CAPS_NEW (
|
|
( "my_mp3_capability",
|
|
( "audio/mp3",
|
|
one capability ----> ( NULL
|
|
created by chaining ( ),
|
|
two capabilities. ( GST_CAPS_NEW (
|
|
( "my_vorbis_capability",
|
|
( "audio/vorbis",
|
|
( NULL
|
|
( )
|
|
|
|
Capabilities always work as constraints, this means that they constrain the
|
|
media type tp the given mime-type and properties. By this definition a NULL
|
|
GstCaps or a NULL GstProps means: no constraints.
|
|
|
|
|
|
Variable capabilities vs. fixed capabilities
|
|
--------------------------------------------
|
|
|
|
A GstProps structure is said to be fixed if it doesn't contain lists or
|
|
ranges, otherwise it is a variable GstProps. A variable GstProps, by definitin
|
|
does not constrain the media type to a set of fixed properties.
|
|
|
|
A GstCaps is said to be fixed if it is not chained and it doesn't contain
|
|
a variable GstProps component.
|
|
|
|
|
|
GstCaps compatibility
|
|
---------------------
|
|
|
|
<write me>
|
|
|
|
|
|
GstCaps usage
|
|
-------------
|
|
|
|
GstCaps are used in the following data structures:
|
|
|
|
- padtemplates.
|
|
* padtemplates are added to elementfactory to describe the possible
|
|
pads that an element created from said factory can have.
|
|
* padtemplates contain the name, direction and presence of the pads.
|
|
* padtemplates also describe the media types that this element can
|
|
accept/produce using GstCaps.
|
|
* padtemplates can provide fixed or variable GstCaps for the pads.
|
|
* padtemplates can be used by the element to create its pads and is
|
|
highly recommended.
|
|
* the padtemplate GstCaps are saved into the registry so that the
|
|
media types an element can operate on, are known without having to
|
|
bring the element into memory.
|
|
|
|
- pad caps
|
|
* pad caps are _fixed_ caps attached to a pad to describe the exact media
|
|
type this pad is handling. A pad with caps is said to be a "tainted" pad.
|
|
|
|
- connection filters
|
|
* a connection filter is created when two pads are connected. It describes
|
|
the media type(s) that _can_ flow through this connection.
|
|
|
|
- application connection filters
|
|
* When the application connects two pads, it can specify an application
|
|
connection filter that will act as additional constraints on the media types
|
|
that can flow through the connection.
|
|
|
|
Connection filters are cleared when two connected pads are disconnected.
|
|
|
|
|
|
|
|
Purpose of caps negotiation
|
|
---------------------------
|
|
|
|
The purpose of the caps negotiation procedure is to set "pad caps" on a pad
|
|
so that it is compatible with the "connection filter". This has to be done
|
|
_before_ any data passing happens through the connection. Data passing between two
|
|
pads is _not_ allowed when the pad caps are not compatible with the connection
|
|
filter or when the pad caps of two pads participating in the connection are not
|
|
equal.
|
|
|
|
Caps negotiation starts as early as possible.
|
|
|
|
|
|
Pad connect functions
|
|
---------------------
|
|
|
|
A Pad can be notified when another pad is connected or reconnected to it with
|
|
fixed or variable caps. This notification will be done with the optional
|
|
GstPadConnect callback that an element can provide for a pad.
|
|
|
|
The pad connection
|
|
|
|
|
|
|
|
GstPad connection
|
|
-----------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|