+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:
<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>
<sect1 id="sect1-types-typefind" xreflabel="Typefind Functions and Autoplugging">
<title>Typefind Functions and Autoplugging</title>
<para>
+ WRITEME
</para>
</sect1>
[..]
}
</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 ############# -->
[..]
}
</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
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
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
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
[..]
}
</programlisting>
+ </sect1>
</chapter>
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>
return GST_STATE_SUCCESS;
}
</programlisting>
+ </sect1>
</chapter>
projects / platform / upstream / gstreamer.git / commitdiff