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:
* docs/pwg/advanced_scheduling.xml:
Change index layout slightly.
<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
}
</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
to <function>gst_pad_proxy_link</function>. This is a link forwarding
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