mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-06-25 17:30:43 +00:00
Added an unfinished capsnego doc.
Original commit message from CVS: Added an unfinished capsnego doc.
This commit is contained in:
parent
4031c2f252
commit
0a0598f97a
178
docs/random/wtay/capsnego2-docs
Normal file
178
docs/random/wtay/capsnego2-docs
Normal file
|
@ -0,0 +1,178 @@
|
|||
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
|
||||
-----------------
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
Loading…
Reference in a new issue