mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-11-26 11:41:09 +00:00
docs/pwg/advanced_types.xml: Add notes on creating your own types.
Original commit message from CVS: 2004-01-28 Ronald Bultje <rbultje@ronald.bitfreak.net> * docs/pwg/advanced_types.xml: Add notes on creating your own types. * docs/pwg/building_boiler.xml: * docs/pwg/building_pads.xml: * docs/pwg/building_state.xml: Add some stuff about how to retrieve values from structures, how that relates to types and change layout slightly again to be almost perfect.
This commit is contained in:
Ronald S. Bultje
parent
1cd5fa3b07
commit
671d5229b9
5 changed files with 88 additions and 16 deletions
11
ChangeLog
11
ChangeLog
|
|
@ -1,3 +1,14 @@
|
|||
2004-01-28 Ronald Bultje <rbultje@ronald.bitfreak.net>
|
||||
|
||||
* docs/pwg/advanced_types.xml:
|
||||
Add notes on creating your own types.
|
||||
* docs/pwg/building_boiler.xml:
|
||||
* docs/pwg/building_pads.xml:
|
||||
* docs/pwg/building_state.xml:
|
||||
Add some stuff about how to retrieve values from structures, how
|
||||
that relates to types and change layout slightly again to be almost
|
||||
perfect.
|
||||
|
||||
2004-01-28 Ronald Bultje <rbultje@ronald.bitfreak.net>
|
||||
|
||||
* docs/pwg/advanced_dparams.xml:
|
||||
|
|
|
|||
|
|
@ -59,22 +59,25 @@
|
|||
<sect1 id="sect1-types-test" xreflabel="Building a Simple Format for Testing">
|
||||
<title>Building a Simple Format for Testing</title>
|
||||
<para>
|
||||
If you need a new format that has not yet been defined in our <xref
|
||||
linkend="sect1-types-definitions"/>, you will want to have some general
|
||||
guidelines on mimetype naming, properties and such. A mimetype would
|
||||
ideally be one defined by IANA; else, it should be in the form
|
||||
type/x-name, where type is the sort of data this mimetype handles (audio,
|
||||
video, ...) and name should be something specific for this specific type.
|
||||
Audio and video mimetypes should try to support the general audio/video
|
||||
properties (see the list), and can use their own properties, too. To get
|
||||
an idea of what properties we think are useful, see (again) the list.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<!-- ############ sect1 ############# -->
|
||||
|
||||
<sect1 id="sect1-types-mime" xreflabel="A Simple Mime Type">
|
||||
<title>A Simple Mime Type</title>
|
||||
<para>
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<!-- ############ sect1 ############# -->
|
||||
|
||||
<sect1 id="sect1-types-properties" xreflabel="Type Properties">
|
||||
<title>Type Properties</title>
|
||||
<para>
|
||||
Take your time to find the right set of properties for your type. There
|
||||
is no reason to hurry. Also, experimenting with this is generally a good
|
||||
idea. Experience learns that theoretically thought-out types are good,
|
||||
but they still need practical use to assure that they serve their needs.
|
||||
Make sure that your property names do not clash with similar properties
|
||||
used in other types. If they match, make sure they mean the same thing;
|
||||
properties with different types but the same names are
|
||||
<emphasis>not</emphasis> allowed.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
|
@ -83,6 +86,7 @@
|
|||
<sect1 id="sect1-types-typefind" xreflabel="Typefind Functions and Autoplugging">
|
||||
<title>Typefind Functions and Autoplugging</title>
|
||||
<para>
|
||||
WRITEME
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
|
|
|
|||
|
|
@ -313,6 +313,40 @@ gst_my_filter_base_init (GstMyFilterClass *klass)
|
|||
[..]
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
The last argument in a template is its type
|
||||
or list of supported types. In this example, we use 'ANY', which means
|
||||
that this element will accept all input. In real-life situations, you
|
||||
would set a mimetype and optionally a set of properties to make sure
|
||||
that only supported input will come in. This representation should be
|
||||
a string that starts with a mimetype, then a set of comma-separates
|
||||
properties with their supported values. In case of an audio filter that
|
||||
supports raw integer 16-bit audio, mono or stereo at any samplerate, the
|
||||
correct template would look like this:
|
||||
</para>
|
||||
<programlisting>
|
||||
static GstStaticPadTemplate sink_factory =
|
||||
GST_STATIC_PAD_TEMPLATE (
|
||||
"sink",
|
||||
GST_PAD_SINK,
|
||||
GST_PAD_ALWAYS,
|
||||
GST_STATIC_CAPS (
|
||||
"audio/x-raw-int, "
|
||||
"width = (int) 16, "
|
||||
"depth = (int) 16, "
|
||||
"endianness = (int) BYTE_ORDER, "
|
||||
"channels = (int) { 1, 2 }, "
|
||||
"rate = (int) [ 8000, 96000 ]"
|
||||
)
|
||||
);
|
||||
</programlisting>
|
||||
<para>
|
||||
Values surrounded by {} are lists, values surrounded by [] are ranges.
|
||||
Multiple sets of types are supported too, and should be separated by
|
||||
a semicolon (<quote>;</quote>). Later, in the chapter on pads, we will
|
||||
see how to use types to know the exact format of a stream:
|
||||
<xref linkend="cha-building-pads"/>.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<!-- ############ sect1 ############# -->
|
||||
|
|
|
|||
|
|
@ -55,6 +55,9 @@ gst_my_filter_init (GstMyFilter *filter)
|
|||
[..]
|
||||
}
|
||||
</programlisting>
|
||||
|
||||
<sect1 id="sect-pads-linkfn" xreflabel="The link function">
|
||||
<title>The link function</title>
|
||||
<para>
|
||||
The <function>_link ()</function> is called during caps negotiation. This
|
||||
is the process where the linked pads decide on the streamtype that will
|
||||
|
|
@ -108,6 +111,16 @@ gst_my_filter_link (GstPad *pad,
|
|||
return ret;
|
||||
}
|
||||
</programlisting>
|
||||
<para>
|
||||
In here, we check the mimetype of the provided caps. Normally, you don't
|
||||
need to do that in your own plugin/element, because the core does that
|
||||
for you. We simply use it to show how to retrieve the mimetype from a
|
||||
provided set of caps. Types are stored in <classname>GstStructure</classname>
|
||||
internally. A <classname>GstCaps</classname> is nothing more than a small
|
||||
wrapper for 0 or more structures/types. From the structure, you can also
|
||||
retrieve properties, as is shown above with the function
|
||||
<function>gst_structure_get_int ()</function>.
|
||||
</para>
|
||||
<para>
|
||||
If your <function>_link ()</function> function does not need to perform
|
||||
any specific operation (i.e. it will only forward caps), you can set it
|
||||
|
|
@ -115,6 +128,10 @@ gst_my_filter_link (GstPad *pad,
|
|||
function implementation provided by the core. It is useful for elements
|
||||
such as <classname>identity</classname>.
|
||||
</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="sect-pads-getcapsfn" xreflabel="The getcaps function">
|
||||
<title>The getcaps function</title>
|
||||
<para>
|
||||
The <function>_getcaps ()</function> funtion is used to request the list
|
||||
of supported formats and properties from the element. In some cases, this
|
||||
|
|
@ -158,6 +175,10 @@ gst_my_filter_getcaps (GstPad *pad)
|
|||
return caps;
|
||||
}
|
||||
</programlisting>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="sect-pads-explicitcaps" xreflabel="Explicit caps">
|
||||
<title>Explicit caps</title>
|
||||
<para>
|
||||
Obviously, many elements will not need this complex mechanism, because they
|
||||
are much simpler than that. They only support one format, or their format
|
||||
|
|
@ -191,5 +212,6 @@ gst_my_filter_somefunction (GstMyFilter *filter)
|
|||
[..]
|
||||
}
|
||||
</programlisting>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
||||
|
|
|
|||
|
|
@ -53,8 +53,8 @@
|
|||
as possible and would ideally cause no delay at all. The same goes for the
|
||||
reverse transition (<classname>GST_STATE_PLAYING_TO_PAUSED</classname>).
|
||||
</para>
|
||||
</chapter>
|
||||
<chapter id="cha-statemanage-filters">
|
||||
|
||||
<sect1 id="sect1-statemanage-filters">
|
||||
<title>
|
||||
Mangaging filter state
|
||||
</title>
|
||||
|
|
@ -99,4 +99,5 @@ gst_my_filter_change_state (GstElement *element)
|
|||
return GST_STATE_SUCCESS;
|
||||
}
|
||||
</programlisting>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue