mirror of
https://gitlab.freedesktop.org/gstreamer/gstreamer.git
synced 2024-09-26 14:00:29 +00:00
update docs
Original commit message from CVS: update docs
This commit is contained in:
parent
95343b9d13
commit
f2f01efb75
7 changed files with 242 additions and 252 deletions
|
@ -29,8 +29,8 @@
|
|||
<!ENTITY GstRegistryPool SYSTEM "xml/gstregistrypool.xml">
|
||||
<!ENTITY GstScheduler SYSTEM "xml/gstscheduler.xml">
|
||||
<!ENTITY GstTrace SYSTEM "xml/gsttrace.xml">
|
||||
<!ENTITY GstType SYSTEM "xml/gsttype.xml">
|
||||
<!ENTITY GstTypeFactory SYSTEM "xml/gsttype.xml">
|
||||
<!ENTITY GstTypeFind SYSTEM "xml/gsttypefind.xml">
|
||||
<!ENTITY GstTypeFindFactory SYSTEM "xml/gsttypefindfactory.xml">
|
||||
<!ENTITY GstCaps SYSTEM "xml/gstcaps.xml">
|
||||
<!ENTITY GstProps SYSTEM "xml/gstprops.xml">
|
||||
<!ENTITY GstClock SYSTEM "xml/gstclock.xml">
|
||||
|
@ -40,7 +40,6 @@
|
|||
<!ENTITY GstXML SYSTEM "xml/gstxml.xml">
|
||||
<!-- these are elements without API docs
|
||||
<!ENTITY GstQueue SYSTEM "xml/gstqueue.xml">
|
||||
<!ENTITY GstTypeFind SYSTEM "xml/gsttypefind.xml">
|
||||
-->
|
||||
<!ENTITY GstIndex SYSTEM "xml/gstindex.xml">
|
||||
<!ENTITY cothreads SYSTEM "xml/cothreads.xml">
|
||||
|
@ -118,9 +117,8 @@ with some more specialized elements.</para>
|
|||
&GstScheduler;
|
||||
&GstSystemClock;
|
||||
&GstThread;
|
||||
&GstType;
|
||||
<!-- no API docs
|
||||
&GstTypeFind; -->
|
||||
&GstTypeFind;
|
||||
&GstTypeFindFactory;
|
||||
&GstUri;
|
||||
&GstUtils;
|
||||
&GstXML;
|
||||
|
|
|
@ -1254,38 +1254,33 @@ gst_alloc_trace_flags_get_type
|
|||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
<FILE>gsttype</FILE>
|
||||
<TITLE>GstType</TITLE>
|
||||
GstType
|
||||
gst_type_register
|
||||
gst_type_find_by_mime
|
||||
gst_type_find_by_ext
|
||||
gst_type_find_by_id
|
||||
gst_type_get_list
|
||||
<SUBSECTION Standard>
|
||||
<FILE>gsttypefind</FILE>
|
||||
<TITLE>Writing typefind functions</TITLE>
|
||||
GstTypeFind
|
||||
GstTypeFindFunction
|
||||
gst_type_find_peek
|
||||
gst_type_find_suggest
|
||||
gst_type_find_get_length
|
||||
gst_type_find_factory_register
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
<FILE>gsttypefactory</FILE>
|
||||
<TITLE>GstTypeFactory</TITLE>
|
||||
GstTypeFactory
|
||||
GstTypeDefinition
|
||||
GstTypeFindFunc
|
||||
gst_type_factory_new
|
||||
gst_type_factory_find
|
||||
<FILE>gsttypefindfactory</FILE>
|
||||
<TITLE>GstTypeFindFactory</TITLE>
|
||||
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
|
||||
<SUBSECTION Standard>
|
||||
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
|
||||
</SECTION>
|
||||
|
||||
<SECTION>
|
||||
|
@ -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
|
||||
|
|
|
@ -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
|
||||
|
|
|
@ -1,108 +0,0 @@
|
|||
<!-- ##### SECTION Title ##### -->
|
||||
GstType
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
Identifies the data
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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).
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GstTypeFactory
|
||||
</para>
|
||||
|
||||
<!-- ##### STRUCT GstType ##### -->
|
||||
<para>
|
||||
A type.
|
||||
</para>
|
||||
|
||||
@id:
|
||||
@mime:
|
||||
@exts:
|
||||
@factories:
|
||||
|
||||
<!-- ##### FUNCTION gst_type_register ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@factory:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_by_mime ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@mime:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_by_ext ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@ext:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_by_id ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@id:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_get_list ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@Returns:
|
||||
|
||||
|
|
@ -1,101 +0,0 @@
|
|||
<!-- ##### SECTION Title ##### -->
|
||||
GstTypeFactory
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
Add types to plugins.
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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().
|
||||
</para>
|
||||
<para>
|
||||
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:
|
||||
<programlisting>
|
||||
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));
|
||||
...
|
||||
}
|
||||
</programlisting>
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
#GstPluginFeature, #GstPlugin
|
||||
</para>
|
||||
|
||||
<!-- ##### STRUCT GstTypeFactory ##### -->
|
||||
<para>
|
||||
The struct with the typefactory information.
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### STRUCT GstTypeDefinition ##### -->
|
||||
<para>
|
||||
The typedefinition structure.
|
||||
</para>
|
||||
|
||||
@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.
|
||||
|
||||
<!-- ##### USER_FUNCTION GstTypeFindFunc ##### -->
|
||||
<para>
|
||||
This is the function that will be called when a typefind has to be
|
||||
performed by a plugin.
|
||||
</para>
|
||||
|
||||
@bs:
|
||||
@priv: private; don't touch
|
||||
@Returns: A #GstCaps structure describing the type or NULL if the
|
||||
type was not recognized by this function;
|
||||
<!-- # Unused Parameters # -->
|
||||
@buf: the buffer with media on which to perform the typefind
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_factory_new ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@definition:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_factory_find ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@name:
|
||||
@Returns:
|
||||
|
||||
|
|
@ -1,23 +1,114 @@
|
|||
<!-- ##### SECTION Title ##### -->
|
||||
GstTypeFind
|
||||
Writing typefind functions
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
Detect the mime type of a media stream
|
||||
Using the type finding subsystem from plugins
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
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 <emphasis>file
|
||||
</emphasis> command.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
<para>
|
||||
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.
|
||||
<example>
|
||||
<title>a typefind function for Ogg data</title>
|
||||
<programlisting>
|
||||
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));
|
||||
}
|
||||
};
|
||||
</programlisting>
|
||||
</example>
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
|
||||
<link linkend="GstTypeFindFactory">GstTypeFactory - querying registered typefind
|
||||
functions</link>
|
||||
</para>
|
||||
|
||||
<!-- ##### VARIABLE gst_type_find_details ##### -->
|
||||
<!-- ##### STRUCT GstTypeFind ##### -->
|
||||
<para>
|
||||
This structure is filled by the caller of the typefind function. Typefind
|
||||
functions must treat this as an opaque structure.
|
||||
</para>
|
||||
|
||||
@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.
|
||||
|
||||
<!-- ##### USER_FUNCTION GstTypeFindFunction ##### -->
|
||||
<para>
|
||||
This is the prototype for a typefind function.
|
||||
</para>
|
||||
|
||||
@find: The #GstTypeFind data
|
||||
@data: the user defined data that was provided on
|
||||
gst_type_find_factory_register()
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_peek ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@find:
|
||||
@offset:
|
||||
@size:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_suggest ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@find:
|
||||
@probability:
|
||||
@caps:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_get_length ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@find:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_factory_register ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@plugin:
|
||||
@name:
|
||||
@rank:
|
||||
@func:
|
||||
@extensions:
|
||||
@possible_caps:
|
||||
@data:
|
||||
|
||||
|
||||
|
|
117
docs/gst/tmpl/gsttypefindfactory.sgml
Normal file
117
docs/gst/tmpl/gsttypefindfactory.sgml
Normal file
|
@ -0,0 +1,117 @@
|
|||
<!-- ##### SECTION Title ##### -->
|
||||
GstTypeFindFactory
|
||||
|
||||
<!-- ##### SECTION Short_Description ##### -->
|
||||
information about registered typefind functions
|
||||
|
||||
<!-- ##### SECTION Long_Description ##### -->
|
||||
<para>
|
||||
These functions allow querying informations about registered typefind
|
||||
functions. How to create and register these functions is described in
|
||||
the section <link linkend="gstreamer-Writing-typefind-functions">
|
||||
"Writing typefind functions"</link>.
|
||||
</para>
|
||||
<example>
|
||||
<title>how to write a simple typefinder</title>
|
||||
<programlisting>
|
||||
/* 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;
|
||||
};
|
||||
</programlisting>
|
||||
</example>
|
||||
<para>
|
||||
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.
|
||||
</para>
|
||||
|
||||
<!-- ##### SECTION See_Also ##### -->
|
||||
<para>
|
||||
<link linkend="gstreamer-Writing-typefind-functions">Writing typefind functions</link>
|
||||
</para>
|
||||
|
||||
<!-- ##### STRUCT GstTypeFindFactory ##### -->
|
||||
<para>
|
||||
Object that stores information about a typefind function
|
||||
</para>
|
||||
|
||||
|
||||
<!-- ##### STRUCT GstTypeFindFactoryClass ##### -->
|
||||
<para>
|
||||
Class belonging to #GstTypeFindFactory.
|
||||
</para>
|
||||
|
||||
@parent:
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_factory_get_list ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_factory_get_extensions ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@factory:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_factory_get_caps ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@factory:
|
||||
@Returns:
|
||||
|
||||
|
||||
<!-- ##### FUNCTION gst_type_find_factory_call_function ##### -->
|
||||
<para>
|
||||
|
||||
</para>
|
||||
|
||||
@factory:
|
||||
@find:
|
||||
|
||||
|
Loading…
Reference in a new issue