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.

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:

docs/pwg/advanced-types.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>
 

docs/pwg/building-boiler.xml

@@ -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 ############# -->

docs/pwg/building-pads.xml

@@ -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>
 

docs/pwg/building-state.xml

@@ -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>