mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-27 18:50:48 +00:00
Code Issues 1 Projects Releases Wiki Activity

More updates to the API docs.

Browse source 
Original commit message from CVS:
More updates to the API docs.
This commit is contained in:
Wim Taymans 2001-10-21 15:47:23 +00:00
parent de48822104
commit 710d1ae0d2
19 changed files with 323 additions and 211 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

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

@ -86,7 +86,6 @@ with some more specialized elements.</para>
&GstScheduler;
&GstThread;
&GstTimeCache;
&GstTrace;
&GstType;
&GstTypeFactory;
&GstTypeFind;

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

@ -261,10 +261,10 @@ GST_ERROR_OBJECT
GstDebugHandler
gst_default_debug_handler
gst_default_error_handler
gst_debug_print_stack_trace
GstInfoHandler
GstErrorHandler
<SUBSECTION Standard>
gst_debug_print_stack_trace
GST_DEBUG_CHAR_MODE
GST_DEBUG_ENABLED
GST_DEBUG_ENABLE_CATEGORIES
@ -307,10 +307,12 @@ gst_schedule_show
<SUBSECTION Standard>
GstSchedule
GST_SCHEDULE
GST_SCHEDULE_FAST
GST_IS_SCHEDULE
GST_TYPE_SCHEDULE
gst_schedule_get_type
GST_SCHEDULE_CLASS
GST_SCHEDULE_CLASS_FAST
GST_IS_SCHEDULE_CLASS
</SECTION>
@ -334,6 +336,8 @@ gst_bin_get_type
GST_TYPE_BIN
GST_BIN
GST_BIN_CLASS
GST_BIN_FAST
GST_BIN_CLASS_FAST
GST_IS_BIN
GST_IS_BIN_CLASS
gst_bin_details
@ -584,8 +588,8 @@ gst_clock_current_diff
<SECTION>
<FILE>gstlog</FILE>
gst_info
<SUBSECTION Standard>
gst_info
GST_SHOW_INFO
</SECTION>
@ -701,7 +705,6 @@ gst_pad_negotiate_proxy
gst_pad_renegotiate
gst_pad_get_padtemplate
gst_pad_get_padtemplate_caps
gst_pad_event
gst_pad_ghost_save_thyself
gst_pad_peek
gst_pad_select
@ -821,7 +824,6 @@ GstPluginDesc
GST_PLUGIN_DESC
GST_PLUGIN_DESC_DYNAMIC
GST_PLUGIN_DESC_STATIC
gst_plugin_new
gst_plugin_set_name
gst_plugin_get_name
gst_plugin_get_longname
@ -841,7 +843,6 @@ gst_plugin_add_feature
gst_plugin_get_feature_list
gst_plugin_load_plugin
gst_plugin_unload_all
<SUBSECTION Standard>
</SECTION>
@ -896,6 +897,7 @@ gst_thread_details
<SECTION>
<FILE>gsttrace</FILE>
<TITLE>GstTrace</TITLE>
<SUBSECTION Standard>
gst_trace_read_tsc
GstTrace
GstTraceEntry
@ -909,7 +911,6 @@ gst_trace_get_remaining
gst_trace_set_default
TRACE_ENABLE
gst_trace_add_entry
<SUBSECTION Standard>
</SECTION>
<SECTION>

23
docs/gst/tmpl/gst.sgml
View file

@ -24,6 +24,29 @@ metadata handling twice already), and thus can be changed to increase the
sanity/noise ratio.
</para>
<para>
The <application>GStreamer</application> library should be initialized with gst_init() before
it can be used. You should pass a pointer to the main argc and argv variables so that GStreamer can
process its own command line options, as shown in the following example.
<programlisting>
int
main (int argc, char *argv[])
{
// initialize the GStreamer library
gst_init (&amp;argc, &amp;argv);
...
}
</programlisting>
</para>
<para>
Use gst_version() to query the library version at runtime or use the GST_VERSION_* macros
to find the version at compile time.
</para>
<para>
gst_main() and gst_main_quit() enter and exit the main loop.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
Check out both <ulink url="http://www.cse.ogi.edu/sysl/">OGI's

4
docs/gst/tmpl/gstbin.sgml
View file

@ -12,7 +12,9 @@ the bin, making the bin itself look transparently like any other element,
allowing for deep nesting of predefined sub-pipelines.
</para>
<para>
A new GstBin is created with gst_bin_new()
A new GstBin is created with gst_bin_new(). Use a #GstPipeline instead if you want
to create a toplevel bin because a normal bin doesn't have a scheduler of its
own.
</para>
<para>
After the bin has been created you will typically add elements to it with

13
docs/gst/tmpl/gstbuffer.sgml
View file

@ -234,9 +234,7 @@ This function is used to copy the buffer contents.
</para>
@srcbuf: the src buffer
@Returns:
<!-- # Unused Parameters # -->
@dstbuf: the destination buffer
@Returns: The copied buffer
<!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
@ -340,15 +338,6 @@ used when data in a stream has been skipped
@buffer:
<!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
<para>
</para>
@buffer:
@count:
<!-- ##### FUNCTION gst_buffer_unref ##### -->
<para>

53
docs/gst/tmpl/gstbufferpool.sgml
View file

@ -18,27 +18,45 @@ the number of memcpy operations.
</para>
<para>
A bufferpool is created with gst_buffer_pool_new(). You'll have to set the
buffer allocation and destroy function afterwards with gst_buffer_pool_set_create_function() and
gst_buffer_pool_set_destroy_function().
buffer new and free function afterwards with gst_buffer_pool_set_buffer_new_function() and
gst_buffer_pool_set_buffer_free_function() so that all buffers created
from this pool will be allocated/freed with these functions.
</para>
<para>
To create a buffer from the bufferpool use gst_buffer_pool_new_buffer(), which is
functionally equivalent to gst_buffer_new_from_pool().
Optionally the default buffer copy function of the buffers allocated from this pool
can be overridden with gst_buffer_pool_set_buffer_copy_function().
</para>
<para>
When the buffer is unreffed and has reached a refcount of 0, the bufferpools destroy
To create a buffer from the bufferpool use gst_buffer_new_from_pool().
</para>
<para>
When the buffer is unreffed and has reached a refcount of 0, the bufferpools free
function is called with the buffer as an argument.
</para>
<para>
A bufferpool can store private data in the buffer it creates with the GST_BUFFER_POOL_PRIVATE()
macro. To check it a buffer was made by a specific bufferpool, use the GST_BUFFER_BUFFERPOOL()
macro to get it's bufferpool.
macro to get its bufferpool.
</para>
<para>
Destroy the bufferpool with gst_buffer_pool_destroy().
Destroy the bufferpool with gst_buffer_pool_destroy(), optional cleanup of the bufferpool can
be triggered in the GstBufferPoolDestroyHook which you can install with
gst_buffer_pool_set_destroy_hook().
</para>
<para>
A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function.
The owner of the bufferpool can add user data to the pool with
gst_buffer_pool_set_user_data() and gst_buffer_pool_get_user_data().
</para>
<para>
If your plugin is going to need a lot of equally sized memory areas you can use
gst_buffer_pool_get_default() to request a pool that will create buffers of that size.
These bufferpools will be shared with all plugins needing the same size of buffers so it's
quite efficient since it reduces the number of memory allocations.
</para>
<para>
A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function. This function
is typically used when a plugin wants to write into a memory area provided by another plugin.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -59,23 +77,24 @@ A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() funct
<!-- ##### USER_FUNCTION GstBufferPoolBufferNewFunction ##### -->
<para>
The function will be called when a buffer must be allocated from the pool.
</para>
@pool:
@location:
@size:
@user_data:
@Returns:
@pool: The pool allocating the buffer
@location: the location (offset) of the buffer to allocate
@size: The size of the allocated buffer
@user_data: user data as set on the bufferpool
@Returns: A new buffer with the given parameters.
<!-- ##### USER_FUNCTION GstBufferPoolDestroyHook ##### -->
<para>
Will be called when the bufferpool is destroyed so that the owner of the pool
can perform necessary cleanup.
</para>
@pool:
@user_data:
@pool: The pool that is being destroyed
@user_data: user data as set on th bufferpool
<!-- ##### MACRO GST_BUFFER_POOL_UNLOCK ##### -->

30
docs/gst/tmpl/gstcaps.sgml
View file

@ -50,7 +50,7 @@ structure from a chained list.
<para>
To get the properties of a caps structure the functions
gst_caps_get_boolean(), gst_caps_get_fourcc_int(), gst_caps_get_int(),
gst_caps_get_string(), which all take a property name as an argument.
gst_caps_get_string(), gst_caps_get_float(), which all take a property name as an argument.
</para>
<para>
The properties of the caps structure can be modified with gst_caps_set, which
@ -69,6 +69,34 @@ takes a list of key value pairs in the #GstProps syntax as shown by this example
before modifying a GstCaps, it is a good idea to make a copy if it first with
gst_caps_copy_on_write(). This will copy the GstCaps if the refcount is &gt;1.
</para>
<para>
If you need a unique instance of a GstCaps you can use the convenient
GST_CAPS_FACTORY() macro as shown below.
<programlisting>
GST_CAPS_FACTORY (my_caps,
GST_CAPS_NEW (
"caps1",
"audio/raw",
"format", GST_PROPS_STRING ("float"),
"channels", GST_PROPS_INT (5)
),
GST_CAPS_NEW (
"caps2",
"audio/raw",
"format", GST_PROPS_STRING ("int"),
"channels", GST_PROPS_INT (5)
)
)
void
some_function (void)
{
GstCaps *caps = GST_CAPS_GET (my_caps);
...
}
</programlisting>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>

3
docs/gst/tmpl/gstelement.sgml
View file

@ -255,7 +255,8 @@ circumstances.
<!-- ##### MACRO gst_element_destroy ##### -->
<para>
Destroy the element. This is potentially dangerous, use gst_object_unref
instead.
</para>
@element: the element to destroy

17
docs/gst/tmpl/gstevent.sgml
View file

@ -9,9 +9,22 @@ Event definitions.
The event classes are used to construct and query events.
</para>
<para>
Events are usually created with gst_event_new() which takes the event type as an argument.
properties specific to the event can be set afterwards with the provided macros.
The event is freed with gst_event_free().
</para>
<para>
gst_event_new_seek() is a usually used to create a seek event and it takes the
needed parameters for a seek event.
</para>
<para>
gst_event_new_flush() creates a new flush event.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstPad
</para>
<!-- ##### ENUM GstEventType ##### -->
@ -114,7 +127,7 @@ The event data structure.
<!-- ##### MACRO gst_event_new_flush ##### -->
<para>
Create a new flush event.
</para>

7
docs/gst/tmpl/gstinfo.sgml
View file

@ -293,13 +293,6 @@ Print out an error condition and abort the application.
@string:
<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
<para>
</para>
<!-- ##### USER_FUNCTION GstInfoHandler ##### -->
<para>

9
docs/gst/tmpl/gstlog.sgml
View file

@ -14,12 +14,3 @@ gstlog
</para>
<!-- ##### MACRO gst_info ##### -->
<para>
</para>
@format:
@args...:

15
docs/gst/tmpl/gstobject.sgml
View file

@ -8,16 +8,17 @@ Basis for the GST object hierarchy.
<para>
GstObject provides a root for the object hierarchy tree filed in by the
GST library. It is currently a thin wrapper on top of
<classname>GtkObject</classname>, but eventually will be replaced by a
stripped down version of it. This will remove all the X dependencies from
the GST library, making it much more portably and generally useful.
<classname>GObject</classname> but it can be compiled against GTK+ with
a shim provided by the GStreamer library. It is an abstract class that is not
very usable on its own.
</para>
<para>
GstObject gives us basic refcounting and parenting functionality, though
it is possible that we could use <classname>GtkObject</classname>'s
equivalent functions. I'll probably use what I have now until I strip
down <classname>GtkObject</classname> to re-parent the hierarchy.
GstObject gives us basic refcounting, parenting functionality and locking.
</para>
<para>
gst_object_set_name() and gst_object_get_name() are used to set/get the name of the
object.
</para>
<!-- ##### SECTION See_Also ##### -->

20
docs/gst/tmpl/gstpad.sgml
View file

@ -60,12 +60,16 @@ to register callbacks for various events on the pads.
<para>
GstElements will use gst_pad_push() and gst_pad_pull() to push out or pull a buffer in. The
gst_pad_pullregion() function can be used to request for a buffer with a specific offset (in
time or in bytes).
time or in bytes). gst_pad_select() and gst_pad_selectv() are use by plugins to wait on a set
of pads for a new GstBuffer or GstEvent.
</para>
<para>
To send an event on a pad, use gst_pad_send_event().
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstCaps, #GstElement
#GstCaps, #GstElement, #GstEvent
</para>
<!-- ##### MACRO GST_PAD_NAME ##### -->
@ -643,18 +647,6 @@ Destroy the pad.
@Returns:
<!-- ##### FUNCTION gst_pad_event ##### -->
<para>
</para>
@pad:
@event:
@timestamp:
@data:
@Returns:
<!-- ##### FUNCTION gst_pad_ghost_save_thyself ##### -->
<para>

6
docs/gst/tmpl/gstpipeline.sgml
View file

@ -11,10 +11,14 @@ filter graph. The GstPipeline will manage all the scheduling issues,
including threading, as well as provide simple interfaces to common
functions, like 'Play'.
</para>
<para>
gst_pipeline_new() is used to create a pipeline. when you are done with
the pipeline, use gst_element_unref() to free its resources.
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstBin
</para>
<!-- ##### STRUCT GstPipeline ##### -->

21
docs/gst/tmpl/gstplugin.sgml
View file

@ -17,10 +17,6 @@ and will create a new #GstPlugin. It will then call the #GstPluginInitFunc funct
that was provided in the plugin_desc.
</para>
<para>
Optionally a new plugin is created with gst_plugin_new(). this function will return a handle
to the GstPlugin or NULL if the plugin could not be created.
</para>
<para>
Once you have a handle to a #GstPlugin, you can add any object that subclasses #GstPluginFeature.
</para>
<para>
@ -28,8 +24,10 @@ use gst_plugin_find(), gst_plugin_get_list() and gst_plugin_get_feature_list()
to query the plugin repository.
</para>
<para>
Plugins are always automaticlly loaded so you don't need to call gst_plugin_load() explicitly
to bring it into memory.
Usually plugins are always automaticlly loaded so you don't need to call gst_plugin_load() explicitly
to bring it into memory. There are options to statically link plugins to an app or even
use GStreamer without a plugin repository in which case gst_plugin_load() can be needed
to bring the plugin into memory.
</para>
<!-- ##### SECTION See_Also ##### -->
@ -105,17 +103,6 @@ A macro used to define a statically linked plugin.
@init: The init function of this plugin.
<!-- ##### FUNCTION gst_plugin_new ##### -->
<para>
</para>
@name:
@major:
@minor:
@Returns:
<!-- ##### FUNCTION gst_plugin_set_name ##### -->
<para>

1
docs/gst/tmpl/gstpluginfeature.sgml
View file

@ -20,6 +20,7 @@ This is a base class for anything that can be added to a #GstPlugin.
</para>
@feature:
@Returns:
<!-- ##### FUNCTION gst_plugin_feature_unload_thyself ##### -->

145
docs/gst/tmpl/gstreamer-unused.sgml
View file

@ -2806,6 +2806,27 @@ Flags for the GstSrc element
</para>
<!-- ##### STRUCT GstTrace ##### -->
<para>
</para>
@filename:
@fd:
@buf:
@bufsize:
@bufoffset:
<!-- ##### STRUCT GstTraceEntry ##### -->
<para>
</para>
@timestamp:
@sequence:
@data:
@message:
<!-- ##### ARG GstTypeFind:type ##### -->
<para>
Query the element for the current mime type
@ -2917,6 +2938,12 @@ Is trigered whenever the state of an element changes
</para>
<!-- ##### MACRO TRACE_ENABLE ##### -->
<para>
must be defined to activate the tracing functionality.
</para>
<!-- ##### FUNCTION g2g_object_class_find_property ##### -->
<para>
@ -3928,6 +3955,14 @@ Is trigered whenever the state of an element changes
@destroy:
@user_data:
<!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
<para>
</para>
@buffer:
@count:
<!-- ##### FUNCTION gst_buffer_remove_meta ##### -->
<para>
@ -3995,6 +4030,12 @@ Is trigered whenever the state of an element changes
@connection:
<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
<para>
</para>
<!-- ##### FUNCTION gst_disksrc_get_type ##### -->
<para>
@ -4317,6 +4358,14 @@ Is trigered whenever the state of an element changes
@name:
@Returns:
<!-- ##### MACRO gst_info ##### -->
<para>
</para>
@format:
@args...:
<!-- ##### MACRO gst_marshal_VOID__BOOLEAN ##### -->
<para>
@ -4431,6 +4480,17 @@ Call the EOS function of the pad
@pad:
@Returns:
<!-- ##### FUNCTION gst_pad_event ##### -->
<para>
</para>
@pad:
@event:
@timestamp:
@data:
@Returns:
<!-- ##### FUNCTION gst_pad_get_caps_by_name ##### -->
<para>
@ -4671,6 +4731,16 @@ Call the EOS function of the pad
@mime:
<!-- ##### FUNCTION gst_plugin_new ##### -->
<para>
</para>
@name:
@major:
@minor:
@Returns:
<!-- ##### FUNCTION gst_props_register ##### -->
<para>
@ -4837,6 +4907,81 @@ Call the EOS function of the pad
@arg:
<!-- ##### MACRO gst_trace_add_entry ##### -->
<para>
</para>
@trace:
@seq:
@data:
@msg:
<!-- ##### FUNCTION gst_trace_destroy ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_trace_flush ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO gst_trace_get_offset ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO gst_trace_get_remaining ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO gst_trace_get_size ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_trace_new ##### -->
<para>
</para>
@filename:
@size:
@Returns:
<!-- ##### FUNCTION gst_trace_read_tsc ##### -->
<para>
</para>
@dst:
<!-- ##### FUNCTION gst_trace_set_default ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_trace_text_flush ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_type_add_sink ##### -->
<para>

113
docs/gst/tmpl/gsttrace.sgml
View file

@ -14,116 +14,3 @@ Tracing functionality
</para>
<!-- ##### FUNCTION gst_trace_read_tsc ##### -->
<para>
</para>
@dst:
<!-- ##### STRUCT GstTrace ##### -->
<para>
</para>
@filename:
@fd:
@buf:
@bufsize:
@bufoffset:
<!-- ##### STRUCT GstTraceEntry ##### -->
<para>
</para>
@timestamp:
@sequence:
@data:
@message:
<!-- ##### FUNCTION gst_trace_new ##### -->
<para>
</para>
@filename:
@size:
@Returns:
<!-- ##### FUNCTION gst_trace_destroy ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_trace_flush ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_trace_text_flush ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO gst_trace_get_size ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO gst_trace_get_offset ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO gst_trace_get_remaining ##### -->
<para>
</para>
@trace:
<!-- ##### FUNCTION gst_trace_set_default ##### -->
<para>
</para>
@trace:
<!-- ##### MACRO TRACE_ENABLE ##### -->
<para>
must be defined to activate the tracing functionality.
</para>
<!-- ##### MACRO gst_trace_add_entry ##### -->
<para>
</para>
@trace:
@seq:
@data:
@msg:

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

@ -7,12 +7,48 @@ Add types to plugins.
<!-- ##### SECTION Long_Description ##### -->
<para>
A GstTypeFactory is used to add a new type and a typedetection function
to a plugin.
to a plugin. Typefactories are named so they can be found with
gst_typefactory_find().
</para>
<para>
gst_typefactory_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_typefind (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_typefind","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_typefind, /* a pointer to a GstTypeFindFunc function */
};
static gboolean
plugin_init (GModule *module, GstPlugin *plugin)
{
GstTypeFactory *type;
...
type = gst_typefactory_new (&amp;avidefinition);
gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (type));
...
}
</programlisting>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
#GstPluginFeature
#GstPluginFeature, #GstPlugin
</para>
<!-- ##### STRUCT GstTypeFactory ##### -->