From 710d1ae0d245cbc282e9732560ee56eb9edffa91 Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Sun, 21 Oct 2001 15:47:23 +0000 Subject: [PATCH] More updates to the API docs. Original commit message from CVS: More updates to the API docs. --- docs/gst/gstreamer-docs.sgml | 1 - docs/gst/gstreamer-sections.txt | 13 ++-- docs/gst/tmpl/gst.sgml | 23 ++++++ docs/gst/tmpl/gstbin.sgml | 4 +- docs/gst/tmpl/gstbuffer.sgml | 13 +--- docs/gst/tmpl/gstbufferpool.sgml | 53 ++++++++----- docs/gst/tmpl/gstcaps.sgml | 30 +++++++- docs/gst/tmpl/gstelement.sgml | 3 +- docs/gst/tmpl/gstevent.sgml | 17 ++++- docs/gst/tmpl/gstinfo.sgml | 7 -- docs/gst/tmpl/gstlog.sgml | 9 --- docs/gst/tmpl/gstobject.sgml | 15 ++-- docs/gst/tmpl/gstpad.sgml | 20 ++--- docs/gst/tmpl/gstpipeline.sgml | 6 +- docs/gst/tmpl/gstplugin.sgml | 21 +----- docs/gst/tmpl/gstpluginfeature.sgml | 1 + docs/gst/tmpl/gstreamer-unused.sgml | 145 ++++++++++++++++++++++++++++++++++++ docs/gst/tmpl/gsttrace.sgml | 113 ---------------------------- docs/gst/tmpl/gsttypefactory.sgml | 40 +++++++++- 19 files changed, 323 insertions(+), 211 deletions(-) diff --git a/docs/gst/gstreamer-docs.sgml b/docs/gst/gstreamer-docs.sgml index b387539..fb3c81e 100644 --- a/docs/gst/gstreamer-docs.sgml +++ b/docs/gst/gstreamer-docs.sgml @@ -86,7 +86,6 @@ with some more specialized elements. &GstScheduler; &GstThread; &GstTimeCache; - &GstTrace; &GstType; &GstTypeFactory; &GstTypeFind; diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt index 5ab19ef..1d0dfb8 100644 --- a/docs/gst/gstreamer-sections.txt +++ b/docs/gst/gstreamer-sections.txt @@ -261,10 +261,10 @@ GST_ERROR_OBJECT GstDebugHandler gst_default_debug_handler gst_default_error_handler -gst_debug_print_stack_trace GstInfoHandler GstErrorHandler +gst_debug_print_stack_trace GST_DEBUG_CHAR_MODE GST_DEBUG_ENABLED GST_DEBUG_ENABLE_CATEGORIES @@ -307,10 +307,12 @@ gst_schedule_show 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 @@ -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
gstlog -gst_info +gst_info GST_SHOW_INFO
@@ -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 - @@ -896,6 +897,7 @@ gst_thread_details
gsttrace GstTrace + gst_trace_read_tsc GstTrace GstTraceEntry @@ -909,7 +911,6 @@ gst_trace_get_remaining gst_trace_set_default TRACE_ENABLE gst_trace_add_entry -
diff --git a/docs/gst/tmpl/gst.sgml b/docs/gst/tmpl/gst.sgml index 3e31202..de74f0a 100644 --- a/docs/gst/tmpl/gst.sgml +++ b/docs/gst/tmpl/gst.sgml @@ -24,6 +24,29 @@ metadata handling twice already), and thus can be changed to increase the sanity/noise ratio. + +The GStreamer 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. + + + int + main (int argc, char *argv[]) + { + // initialize the GStreamer library + gst_init (&argc, &argv); + ... + } + + + + Use gst_version() to query the library version at runtime or use the GST_VERSION_* macros + to find the version at compile time. + + +gst_main() and gst_main_quit() enter and exit the main loop. + + Check out both OGI's diff --git a/docs/gst/tmpl/gstbin.sgml b/docs/gst/tmpl/gstbin.sgml index a89dbbf..1f6e0f5 100644 --- a/docs/gst/tmpl/gstbin.sgml +++ b/docs/gst/tmpl/gstbin.sgml @@ -12,7 +12,9 @@ the bin, making the bin itself look transparently like any other element, allowing for deep nesting of predefined sub-pipelines. -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. After the bin has been created you will typically add elements to it with diff --git a/docs/gst/tmpl/gstbuffer.sgml b/docs/gst/tmpl/gstbuffer.sgml index b06c50c..5ba20a3f 100644 --- a/docs/gst/tmpl/gstbuffer.sgml +++ b/docs/gst/tmpl/gstbuffer.sgml @@ -234,9 +234,7 @@ This function is used to copy the buffer contents. @srcbuf: the src buffer -@Returns: - -@dstbuf: the destination buffer +@Returns: The copied buffer @@ -340,15 +338,6 @@ used when data in a stream has been skipped @buffer: - - - - - -@buffer: -@count: - - diff --git a/docs/gst/tmpl/gstbufferpool.sgml b/docs/gst/tmpl/gstbufferpool.sgml index c9b4569..2178525 100644 --- a/docs/gst/tmpl/gstbufferpool.sgml +++ b/docs/gst/tmpl/gstbufferpool.sgml @@ -18,27 +18,45 @@ the number of memcpy operations. 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. -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(). -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(). + + +When the buffer is unreffed and has reached a refcount of 0, the bufferpools free function is called with the buffer as an argument. 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. + + +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(). -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(). -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. + + + +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. @@ -59,23 +77,24 @@ A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() funct - +The function will be called when a buffer must be allocated from the pool. -@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. - +Will be called when the bufferpool is destroyed so that the owner of the pool +can perform necessary cleanup. -@pool: -@user_data: +@pool: The pool that is being destroyed +@user_data: user data as set on th bufferpool diff --git a/docs/gst/tmpl/gstcaps.sgml b/docs/gst/tmpl/gstcaps.sgml index 961ad6c..95b9263 100644 --- a/docs/gst/tmpl/gstcaps.sgml +++ b/docs/gst/tmpl/gstcaps.sgml @@ -50,7 +50,7 @@ structure from a chained list. 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. 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 >1. + +If you need a unique instance of a GstCaps you can use the convenient +GST_CAPS_FACTORY() macro as shown below. + + 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); + + ... + } + + diff --git a/docs/gst/tmpl/gstelement.sgml b/docs/gst/tmpl/gstelement.sgml index 4f5e8da..4370578 100644 --- a/docs/gst/tmpl/gstelement.sgml +++ b/docs/gst/tmpl/gstelement.sgml @@ -255,7 +255,8 @@ circumstances. - +Destroy the element. This is potentially dangerous, use gst_object_unref +instead. @element: the element to destroy diff --git a/docs/gst/tmpl/gstevent.sgml b/docs/gst/tmpl/gstevent.sgml index a2e5865..94caeeb 100644 --- a/docs/gst/tmpl/gstevent.sgml +++ b/docs/gst/tmpl/gstevent.sgml @@ -9,9 +9,22 @@ Event definitions. The event classes are used to construct and query events. - +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(). + + +gst_event_new_seek() is a usually used to create a seek event and it takes the +needed parameters for a seek event. + + +gst_event_new_flush() creates a new flush event. + + + +#GstPad @@ -114,7 +127,7 @@ The event data structure. - +Create a new flush event. diff --git a/docs/gst/tmpl/gstinfo.sgml b/docs/gst/tmpl/gstinfo.sgml index d0fa8de..c108ccd 100644 --- a/docs/gst/tmpl/gstinfo.sgml +++ b/docs/gst/tmpl/gstinfo.sgml @@ -293,13 +293,6 @@ Print out an error condition and abort the application. @string: - - - - - - - diff --git a/docs/gst/tmpl/gstlog.sgml b/docs/gst/tmpl/gstlog.sgml index f4af303..7605b29 100644 --- a/docs/gst/tmpl/gstlog.sgml +++ b/docs/gst/tmpl/gstlog.sgml @@ -14,12 +14,3 @@ gstlog - - - - - -@format: -@args...: - - diff --git a/docs/gst/tmpl/gstobject.sgml b/docs/gst/tmpl/gstobject.sgml index e0b652b..cf50e92 100644 --- a/docs/gst/tmpl/gstobject.sgml +++ b/docs/gst/tmpl/gstobject.sgml @@ -8,16 +8,17 @@ Basis for the GST object hierarchy. GstObject provides a root for the object hierarchy tree filed in by the GST library. It is currently a thin wrapper on top of -GtkObject, 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. +GObject 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. -GstObject gives us basic refcounting and parenting functionality, though -it is possible that we could use GtkObject's -equivalent functions. I'll probably use what I have now until I strip -down GtkObject to re-parent the hierarchy. +GstObject gives us basic refcounting, parenting functionality and locking. + + +gst_object_set_name() and gst_object_get_name() are used to set/get the name of the +object. diff --git a/docs/gst/tmpl/gstpad.sgml b/docs/gst/tmpl/gstpad.sgml index cb105fe..0083f07 100644 --- a/docs/gst/tmpl/gstpad.sgml +++ b/docs/gst/tmpl/gstpad.sgml @@ -60,12 +60,16 @@ to register callbacks for various events on the pads. 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. + + +To send an event on a pad, use gst_pad_send_event(). -#GstCaps, #GstElement +#GstCaps, #GstElement, #GstEvent @@ -643,18 +647,6 @@ Destroy the pad. @Returns: - - - - - -@pad: -@event: -@timestamp: -@data: -@Returns: - - diff --git a/docs/gst/tmpl/gstpipeline.sgml b/docs/gst/tmpl/gstpipeline.sgml index 2e241a3..d47ff73 100644 --- a/docs/gst/tmpl/gstpipeline.sgml +++ b/docs/gst/tmpl/gstpipeline.sgml @@ -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'. + +gst_pipeline_new() is used to create a pipeline. when you are done with +the pipeline, use gst_element_unref() to free its resources. + - +#GstBin diff --git a/docs/gst/tmpl/gstplugin.sgml b/docs/gst/tmpl/gstplugin.sgml index 3e2fad1..b04e7d7 100644 --- a/docs/gst/tmpl/gstplugin.sgml +++ b/docs/gst/tmpl/gstplugin.sgml @@ -17,10 +17,6 @@ and will create a new #GstPlugin. It will then call the #GstPluginInitFunc funct that was provided in the plugin_desc. -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. - - Once you have a handle to a #GstPlugin, you can add any object that subclasses #GstPluginFeature. @@ -28,8 +24,10 @@ use gst_plugin_find(), gst_plugin_get_list() and gst_plugin_get_feature_list() to query the plugin repository. -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. @@ -105,17 +103,6 @@ A macro used to define a statically linked plugin. @init: The init function of this plugin. - - - - - -@name: -@major: -@minor: -@Returns: - - diff --git a/docs/gst/tmpl/gstpluginfeature.sgml b/docs/gst/tmpl/gstpluginfeature.sgml index 3211c20..03da9d3 100644 --- a/docs/gst/tmpl/gstpluginfeature.sgml +++ b/docs/gst/tmpl/gstpluginfeature.sgml @@ -20,6 +20,7 @@ This is a base class for anything that can be added to a #GstPlugin. @feature: +@Returns: diff --git a/docs/gst/tmpl/gstreamer-unused.sgml b/docs/gst/tmpl/gstreamer-unused.sgml index c9df884..e57b294 100644 --- a/docs/gst/tmpl/gstreamer-unused.sgml +++ b/docs/gst/tmpl/gstreamer-unused.sgml @@ -2806,6 +2806,27 @@ Flags for the GstSrc element + + + + + +@filename: +@fd: +@buf: +@bufsize: +@bufoffset: + + + + + + +@timestamp: +@sequence: +@data: +@message: + Query the element for the current mime type @@ -2917,6 +2938,12 @@ Is trigered whenever the state of an element changes + + +must be defined to activate the tracing functionality. + + + @@ -3928,6 +3955,14 @@ Is trigered whenever the state of an element changes @destroy: @user_data: + + + + + +@buffer: +@count: + @@ -3995,6 +4030,12 @@ Is trigered whenever the state of an element changes @connection: + + + + + + @@ -4317,6 +4358,14 @@ Is trigered whenever the state of an element changes @name: @Returns: + + + + + +@format: +@args...: + @@ -4431,6 +4480,17 @@ Call the EOS function of the pad @pad: @Returns: + + + + + +@pad: +@event: +@timestamp: +@data: +@Returns: + @@ -4671,6 +4731,16 @@ Call the EOS function of the pad @mime: + + + + + +@name: +@major: +@minor: +@Returns: + @@ -4837,6 +4907,81 @@ Call the EOS function of the pad @arg: + + + + + +@trace: +@seq: +@data: +@msg: + + + + + + +@trace: + + + + + + +@trace: + + + + + + +@trace: + + + + + + +@trace: + + + + + + +@trace: + + + + + + +@filename: +@size: +@Returns: + + + + + + +@dst: + + + + + + +@trace: + + + + + + +@trace: + diff --git a/docs/gst/tmpl/gsttrace.sgml b/docs/gst/tmpl/gsttrace.sgml index 2221681..3ed6fe9 100644 --- a/docs/gst/tmpl/gsttrace.sgml +++ b/docs/gst/tmpl/gsttrace.sgml @@ -14,116 +14,3 @@ Tracing functionality - - - - - -@dst: - - - - - - - -@filename: -@fd: -@buf: -@bufsize: -@bufoffset: - - - - - - -@timestamp: -@sequence: -@data: -@message: - - - - - - -@filename: -@size: -@Returns: - - - - - - - -@trace: - - - - - - - -@trace: - - - - - - - -@trace: - - - - - - - -@trace: - - - - - - - -@trace: - - - - - - - -@trace: - - - - - - - -@trace: - - - - -must be defined to activate the tracing functionality. - - - - - - - - - -@trace: -@seq: -@data: -@msg: - - diff --git a/docs/gst/tmpl/gsttypefactory.sgml b/docs/gst/tmpl/gsttypefactory.sgml index d0cb554..0ac10c4 100644 --- a/docs/gst/tmpl/gsttypefactory.sgml +++ b/docs/gst/tmpl/gsttypefactory.sgml @@ -7,12 +7,48 @@ Add types to plugins. 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(). + + +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: + + 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)); + ... + } + -#GstPluginFeature +#GstPluginFeature, #GstPlugin -- 2.7.4