Commit 671d5229 authored by Ronald S. Bultje's avatar Ronald S. Bultje
Browse files

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.
parent 1cd5fa3b
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>
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment