diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml
index c3e6a2a388..9cc12a4462 100644
--- a/docs/gst/gstreamer-docs.sgml
+++ b/docs/gst/gstreamer-docs.sgml
@@ -29,8 +29,8 @@
-
-
+
+
@@ -40,7 +40,6 @@
@@ -118,9 +117,8 @@ with some more specialized elements.
&GstScheduler;
&GstSystemClock;
&GstThread;
- &GstType;
-
+ &GstTypeFind;
+ &GstTypeFindFactory;
&GstUri;
&GstUtils;
&GstXML;
diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index 04a0f5b9bd..f641d0a2ef 100644
--- a/docs/gst/gstreamer-sections.txt
+++ b/docs/gst/gstreamer-sections.txt
@@ -1254,38 +1254,33 @@ gst_alloc_trace_flags_get_type
-gsttype
-GstType
-GstType
-gst_type_register
-gst_type_find_by_mime
-gst_type_find_by_ext
-gst_type_find_by_id
-gst_type_get_list
-
+gsttypefind
+Writing typefind functions
+GstTypeFind
+GstTypeFindFunction
+gst_type_find_peek
+gst_type_find_suggest
+gst_type_find_get_length
+gst_type_find_factory_register
-gsttypefactory
-GstTypeFactory
-GstTypeFactory
-GstTypeDefinition
-GstTypeFindFunc
-gst_type_factory_new
-gst_type_factory_find
+gsttypefindfactory
+GstTypeFindFactory
+GstTypeFindFactory
+GstTypeFindFactoryClass
+gst_type_find_factory_get_list
+gst_type_find_factory_get_extensions
+gst_type_find_factory_get_caps
+gst_type_find_factory_call_function
-GstTypeFind
-GstTypeFindClass
-GST_TYPE_FACTORY
-GST_IS_TYPE_FACTORY
-GST_TYPE_TYPE_FACTORY
-gst_type_factory_get_type
-GST_TYPE_FACTORY_CLASS
-GST_IS_TYPE_FACTORY_CLASS
-GST_IS_TYPE_FIND
-GST_IS_TYPE_FIND_CLASS
-GST_TYPE_FACTORY_GET_CLASS
-GstTypeFactoryClass
+GST_TYPE_FIND_FACTORY
+GST_IS_TYPE_FIND_FACTORY
+GST_TYPE_TYPE_FIND_FACTORY
+gst_type_find_factory_get_type
+GST_TYPE_FIND_FACTORY_CLASS
+GST_IS_TYPE_FIND_FACTORY_CLASS
+GST_TYPE_FIND_FACTORY_GET_CLASS
@@ -1325,8 +1320,6 @@ gst_caps_replace_sink
gst_caps_sink
gst_caps_set_name
gst_caps_get_name
-gst_caps_set_type_id
-gst_caps_get_type_id
gst_caps_set_mime
gst_caps_get_mime
gst_caps_set_props
diff --git a/docs/gst/gstreamer.types b/docs/gst/gstreamer.types
index bca68fcce3..d561d86f1e 100644
--- a/docs/gst/gstreamer.types
+++ b/docs/gst/gstreamer.types
@@ -13,7 +13,7 @@ gst_thread_get_type
gst_plugin_feature_get_type
gst_autoplug_get_type
gst_autoplug_factory_get_type
-gst_type_factory_get_type
+gst_type_find_factory_get_type
gst_element_factory_get_type
gst_scheduler_factory_get_type
gst_scheduler_get_type
diff --git a/docs/gst/tmpl/gsttype.sgml b/docs/gst/tmpl/gsttype.sgml
deleted file mode 100644
index fbd9b8cbe8..0000000000
--- a/docs/gst/tmpl/gsttype.sgml
+++ /dev/null
@@ -1,108 +0,0 @@
-
-GstType
-
-
-Identifies the data
-
-
-
-GstTypes exist to try to make sure data eveyrone is talking about the
-right kind of data. They aid quite a bit in autoplugging, in fact make it
-possible. Each well-formed type includes a function (typefind) that will
-take one or more buffers and determine whether or not it is indeed a
-stream of that type, and possible a metadata to go with it. It may
-provide related metadata structure IDs (and must if it provides metadata
-from the typefind function).
-
-
-
-Because multiple elements and plugins are very likely to be using the same
-types, the process of creating/finding types is designed to be done with a
-single function call. All operations on GstTypes occur via their guint16
-ID numbers, with the GstType structure "private" to the GST library. A
-plugin wishing to use a give type would contain a static struct of type
-GstTypeFactory, which lists the MIME type, possible extensions (which may
-overlap the mime-types file), a typefind function, and any other cruft I
-decide to add.
-
-
-
-A plugin init function would take this typefactory and hand it to the
-gst_type_new() (FIXME: badly named) function, which would first search for
-that same MIME type in the current list. If it found one, it would
-compare the two to see if the new one is "better". Better is defined as
-having more extentions (to be merged) or a typefind function verses none.
-
-
-
-The point of returning an existing MIME type is a result of the goal of
-unifying types enough to guarantee that, for instance, all MP3 decoders
-will work interchangably. If MP3 decoder A says "MIME type 'audio/mpeg'
-with extensions 'mpeg3'" and decoder B says "MIME type 'audio/mpeg' with
-extensions 'mp3'", we don't want to have two types defined, possibly with
-two typefind functions. If we did, it's not obvious which of the two would
-be tried first (luck) and if both would really identify streams as mp3
-correctly in all cases. And whichever wins, we're stuck using the
-associated decoder to play that stream. We lose the choice between any
-valid mp3 decoder, and thus the whole point of the type system.
-
-
-
-
-#GstTypeFactory
-
-
-
-
-A type.
-
-
-@id:
-@mime:
-@exts:
-@factories:
-
-
-
-
-
-
-@factory:
-@Returns:
-
-
-
-
-
-
-
-@mime:
-@Returns:
-
-
-
-
-
-
-
-@ext:
-@Returns:
-
-
-
-
-
-
-
-@id:
-@Returns:
-
-
-
-
-
-
-
-@Returns:
-
-
diff --git a/docs/gst/tmpl/gsttypefactory.sgml b/docs/gst/tmpl/gsttypefactory.sgml
deleted file mode 100644
index 5b65c24c35..0000000000
--- a/docs/gst/tmpl/gsttypefactory.sgml
+++ /dev/null
@@ -1,101 +0,0 @@
-
-GstTypeFactory
-
-
-Add types to plugins.
-
-
-
-A GstTypeFactory is used to add a new type and a typedetection function
-to a plugin. Typefactories are named so they can be found with
-gst_type_factory_find().
-
-
-gst_type_factory_new() is used to create a new typefactory from the given
-#GstTypeDefinition. A typefactory is added to a #GstPlugin with
-gst_plugin_add_feature() as shown in the example:
-
- static GstCaps*
- avi_type_find (GstBuffer *buf, gpointer private)
- {
- gchar *data = GST_BUFFER_DATA (buf);
-
- if (strncmp (&data[0], "RIFF", 4)) return NULL;
- if (strncmp (&data[8], "AVI ", 4)) return NULL;
-
- return gst_caps_new ("avi_type_find","video/avi", NULL);
- }
-
- /* typedefinition for 'avi' */
- static GstTypeDefinition avidefinition = {
- "avidecoder_video/avi", /* the name of this definition */
- "video/avi", /* the mime type */
- ".avi", /* the file extensions */
- avi_type_find, /* a pointer to a GstTypeFindFunc function */
- };
-
- static gboolean
- plugin_init (GModule *module, GstPlugin *plugin)
- {
- GstTypeFactory *type;
- ...
- type = gst_type_factory_new (&avidefinition);
- gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (type));
- ...
- }
-
-
-
-
-
-#GstPluginFeature, #GstPlugin
-
-
-
-
-The struct with the typefactory information.
-
-
-
-
-
-The typedefinition structure.
-
-
-@name: The name of this factory
-@mime: The mime type of the new type.
-@exts: The extensions of this type.
-@typefindfunc: An optional typefind function.
-
-
-
-This is the function that will be called when a typefind has to be
-performed by a plugin.
-
-
-@bs:
-@priv: private; don't touch
-@Returns: A #GstCaps structure describing the type or NULL if the
- type was not recognized by this function;
-
-@buf: the buffer with media on which to perform the typefind
-
-
-
-
-
-
-
-@definition:
-@Returns:
-
-
-
-
-
-
-
-@name:
-@Returns:
-
-
diff --git a/docs/gst/tmpl/gsttypefind.sgml b/docs/gst/tmpl/gsttypefind.sgml
index ad3f5ae74f..10ae8f64bd 100644
--- a/docs/gst/tmpl/gsttypefind.sgml
+++ b/docs/gst/tmpl/gsttypefind.sgml
@@ -1,23 +1,114 @@
-GstTypeFind
+Writing typefind functions
-Detect the mime type of a media stream
+Using the type finding subsystem from plugins
-This element can be added to the pipeline and will notify the listener of
-the detected mime type of the stream. It is used in autoplugging.
+The typefinding subsystem in GStreamer is used to find the matching #GstCaps
+for an unidentified stream. This works similar to the unix file
+ command.
+
+
+There are a number of elements which output unidentified data streams, such as
+a file source. Some other elements such as an autoplugger require a proper
+identification of the data, so they can create the right pipeline. To find the
+right type, they use typefinding elements, the most notable being the typefind
+element. These elements take a list of all registered typefind functions and
+try them on the data to see if any of these functions can identify the data.
+
+
+The functions in this section provide the simple framework for writing these
+typefind functions. The job of a typefind function is to identify the type of
+the data good enough so that plugins using this type can understand them while
+make sure no other type is misidentified.
+
+a typefind function for Ogg data
+
+static void
+ogg_type_find (GstTypeFind *tf, gpointer unused)
+{
+ guint8 *data = gst_type_find_peek (tf, 0, 4);
+
+ if (data && memcmp (data, "OggS", 4) == 0) {
+ gst_type_find_suggest (tf, GST_TYPE_FIND_MAXIMUM,
+ gst_caps_new ("ogg_type_find", "application/ogg", NULL));
+ }
+};
+
+
-
+GstTypeFactory - querying registered typefind
+functions
-
+
+
+This structure is filled by the caller of the typefind function. Typefind
+functions must treat this as an opaque structure.
+
+
+@peek: function called to get data. See gst_type_find_peek()
+@suggest: function called to suggest a caps. See gst_type_find_suggest()
+@data: caller defined data, that is passed when calling the functions
+@get_length: function called to query the length of the stream. See
+gst_type_find_get_length(). Providing this function is optional.
+
+
+
+This is the prototype for a typefind function.
+
+
+@find: The #GstTypeFind data
+@data: the user defined data that was provided on
+gst_type_find_factory_register()
+
+
+
+@find:
+@offset:
+@size:
+@Returns:
+
+
+
+
+
+
+
+@find:
+@probability:
+@caps:
+
+
+
+
+
+
+
+@find:
+@Returns:
+
+
+
+
+
+
+
+@plugin:
+@name:
+@rank:
+@func:
+@extensions:
+@possible_caps:
+@data:
+
diff --git a/docs/gst/tmpl/gsttypefindfactory.sgml b/docs/gst/tmpl/gsttypefindfactory.sgml
new file mode 100644
index 0000000000..118cf5a508
--- /dev/null
+++ b/docs/gst/tmpl/gsttypefindfactory.sgml
@@ -0,0 +1,117 @@
+
+GstTypeFindFactory
+
+
+information about registered typefind functions
+
+
+
+These functions allow querying informations about registered typefind
+functions. How to create and register these functions is described in
+the section
+"Writing typefind functions".
+
+
+how to write a simple typefinder
+
+/* FIXME: compile this? ;) */
+typedef struct {
+ guint8 *data;
+ guint size;
+ guint probability;
+ GstCaps *data;
+} MyTypeFind;
+static void
+my_peek (gpointer data, gint64 offset, guint size)
+{
+ MyTypeFind *find = (MyTypeFind *) data;
+ if (offset >= 0 && offset + size <= find->size) {
+ return find->data + offset;
+ }
+ return NULL;
+}
+static void
+my_suggest (gpointer data, guint probability, GstCaps *caps)
+{
+ MyTypeFind *find = (MyTypeFind *) data;
+ if (probability > find->probability) {
+ find->probability = probability;
+ gst_caps_replace (&find->caps, caps);
+ }
+}
+static GstCaps *
+find_type (guint8 *data, guint size)
+{
+ GList *walk, *type_list;
+ MyTypeFind find = {data, size, 0, NULL};
+ GstTypeFind gst_find = {my_peek, my_suggest, &find, };
+
+ walk = type_list = gst_type_find_factory_get_list ();
+ while (walk) {
+ GstTypeFindFactory *factory = GST_TYPE_FIND_FACTORY (walk->data);
+ walk = g_list_next (walk)
+ gst_type_find_factory_call_function (factory, &gst_find);
+ }
+ g_list_free (type_list);
+ return find.caps;
+};
+
+
+
+The above example shows how to write a very simple typefinder that identifies
+the given data. You can get quite a bit more complicated than that though.
+
+
+
+
+Writing typefind functions
+
+
+
+
+Object that stores information about a typefind function
+
+
+
+
+
+Class belonging to #GstTypeFindFactory.
+
+
+@parent:
+
+
+
+
+
+
+@Returns:
+
+
+
+
+
+
+
+@factory:
+@Returns:
+
+
+
+
+
+
+
+@factory:
+@Returns:
+
+
+
+
+
+
+
+@factory:
+@find:
+
+