&GstScheduler;
&GstThread;
&GstTimeCache;
- &GstTrace;
&GstType;
&GstTypeFactory;
&GstTypeFind;
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
<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>
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
<SECTION>
<FILE>gstlog</FILE>
-gst_info
<SUBSECTION Standard>
+gst_info
GST_SHOW_INFO
</SECTION>
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
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
gst_plugin_get_feature_list
gst_plugin_load_plugin
gst_plugin_unload_all
-
<SUBSECTION Standard>
</SECTION>
<SECTION>
<FILE>gsttrace</FILE>
<TITLE>GstTrace</TITLE>
+<SUBSECTION Standard>
gst_trace_read_tsc
GstTrace
GstTraceEntry
gst_trace_set_default
TRACE_ENABLE
gst_trace_add_entry
-<SUBSECTION Standard>
</SECTION>
<SECTION>
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 (&argc, &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
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
</para>
@srcbuf: the src buffer
-@Returns:
-<!-- # Unused Parameters # -->
-@dstbuf: the destination buffer
+@Returns: The copied buffer
<!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
@buffer:
-<!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
-<para>
-
-</para>
-
-@buffer:
-@count:
-
-
<!-- ##### FUNCTION gst_buffer_unref ##### -->
<para>
</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(), optional cleanup of the bufferpool can
+be triggered in the GstBufferPoolDestroyHook which you can install with
+gst_buffer_pool_set_destroy_hook().
</para>
<para>
-Destroy the bufferpool with gst_buffer_pool_destroy().
+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>
-A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function.
+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 ##### -->
<!-- ##### 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 ##### -->
<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
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 >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>
<!-- ##### MACRO gst_element_destroy ##### -->
<para>
-
+Destroy the element. This is potentially dangerous, use gst_object_unref
+instead.
</para>
@element: the element to destroy
The event classes are used to construct and query events.
</para>
-<!-- ##### SECTION See_Also ##### -->
<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 ##### -->
<!-- ##### MACRO gst_event_new_flush ##### -->
<para>
-
+Create a new flush event.
</para>
@string:
-<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
-<para>
-
-</para>
-
-
-
<!-- ##### USER_FUNCTION GstInfoHandler ##### -->
<para>
</para>
-<!-- ##### MACRO gst_info ##### -->
-<para>
-
-</para>
-
-@format:
-@args...:
-
-
<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 ##### -->
<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 ##### -->
@Returns:
-<!-- ##### FUNCTION gst_pad_event ##### -->
-<para>
-
-</para>
-
-@pad:
-@event:
-@timestamp:
-@data:
-@Returns:
-
-
<!-- ##### FUNCTION gst_pad_ghost_save_thyself ##### -->
<para>
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 ##### -->
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>
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 ##### -->
@init: The init function of this plugin.
-<!-- ##### FUNCTION gst_plugin_new ##### -->
-<para>
-
-</para>
-
-@name:
-@major:
-@minor:
-@Returns:
-
-
<!-- ##### FUNCTION gst_plugin_set_name ##### -->
<para>
</para>
@feature:
+@Returns:
<!-- ##### FUNCTION gst_plugin_feature_unload_thyself ##### -->
</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
</para>
+<!-- ##### MACRO TRACE_ENABLE ##### -->
+<para>
+must be defined to activate the tracing functionality.
+</para>
+
+
<!-- ##### FUNCTION g2g_object_class_find_property ##### -->
<para>
@destroy:
@user_data:
+<!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
+<para>
+
+</para>
+
+@buffer:
+@count:
+
<!-- ##### FUNCTION gst_buffer_remove_meta ##### -->
<para>
@connection:
+<!-- ##### FUNCTION gst_debug_print_stack_trace ##### -->
+<para>
+
+</para>
+
+
<!-- ##### FUNCTION gst_disksrc_get_type ##### -->
<para>
@name:
@Returns:
+<!-- ##### MACRO gst_info ##### -->
+<para>
+
+</para>
+
+@format:
+@args...:
+
<!-- ##### MACRO gst_marshal_VOID__BOOLEAN ##### -->
<para>
@pad:
@Returns:
+<!-- ##### FUNCTION gst_pad_event ##### -->
+<para>
+
+</para>
+
+@pad:
+@event:
+@timestamp:
+@data:
+@Returns:
+
<!-- ##### FUNCTION gst_pad_get_caps_by_name ##### -->
<para>
@mime:
+<!-- ##### FUNCTION gst_plugin_new ##### -->
+<para>
+
+</para>
+
+@name:
+@major:
+@minor:
+@Returns:
+
<!-- ##### FUNCTION gst_props_register ##### -->
<para>
@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>
</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:
-
-
<!-- ##### 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 (&avidefinition);
+ gst_plugin_add_feature (plugin, GST_PLUGIN_FEATURE (type));
+ ...
+ }
+</programlisting>
</para>
<!-- ##### SECTION See_Also ##### -->
<para>
-#GstPluginFeature
+#GstPluginFeature, #GstPlugin
</para>
<!-- ##### STRUCT GstTypeFactory ##### -->