mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-05-18 08:22:51 +00:00
Code Issues Projects Releases Wiki Activity

update docs

Browse source 
Original commit message from CVS:
update docs
This commit is contained in:
Benjamin Otte 2003-10-27 16:09:57 +00:00
parent 95343b9d13
commit f2f01efb75
7 changed files with 242 additions and 252 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

10
docs/gst/gstreamer-docs.sgml
View file

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

53
docs/gst/gstreamer-sections.txt
View file

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

2
docs/gst/gstreamer.types
View file

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

108
docs/gst/tmpl/gsttype.sgml
View file

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

101
docs/gst/tmpl/gsttypefactory.sgml
View file

@ -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 (&amp;data[0], "RIFF", 4)) return NULL;
if (strncmp (&amp;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 (&amp;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:

103
docs/gst/tmpl/gsttypefind.sgml
View file

@ -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 &amp;&amp; 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
View 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 &gt;= 0 &amp;&amp; offset + size &lt;= find->size) {
return find->data + offset;
}
return NULL;
}
static void
my_suggest (gpointer data, guint probability, GstCaps *caps)
{
MyTypeFind *find = (MyTypeFind *) data;
if (probability &gt; find->probability) {
find->probability = probability;
gst_caps_replace (&amp;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, &amp;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, &amp;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: