Added more API docs to Autoplug, Buffer, Bin, BufferPool.

Original commit message from CVS:
Added more API docs to Autoplug, Buffer, Bin, BufferPool.
Fixed some compile problems with videosink

diff --git a/docs/gst/tmpl/gstbin.sgml b/docs/gst/tmpl/gstbin.sgml
index 4669eb4..780ad46 100644 (file)
--- a/docs/gst/tmpl/gstbin.sgml
+++ b/docs/gst/tmpl/gstbin.sgml
@@ -11,6 +11,32 @@ become children of itself.  Pads from the child elements can be ghosted to
 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()
+</para>
+<para>
+After the bin has been created you will typically add elements to it with
+gst_bin_add(). You can remove elements with gst_bin_remove().
+</para>
+<para>
+An element can be retrieved from a bin with gst_bin_get_by_name(), using the
+elements name. gst_bin_get_by_name_recurse_up() is mainly used for internal
+purposes and will query the parent bins when the element is not found in the
+current bin.
+</para>
+<para>
+The list of elements in a bin can be retrieved with gst_bin_get_list().
+</para>
+<para>
+After the bin has been set to the PLAYING state (with gst_element_set_state()), 
+gst_bin_iterate() is used to process the elements in the bin.
+</para>
+<para>
+The "object_added" signal is fired whenever a new object is added to the bin.
+</para>
+<para>
+gst_bin_destroy() is used to destroy the bin. 
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>

diff --git a/docs/gst/tmpl/gstbuffer.sgml b/docs/gst/tmpl/gstbuffer.sgml
index 288a588..aae17fe 100644 (file)
--- a/docs/gst/tmpl/gstbuffer.sgml
+++ b/docs/gst/tmpl/gstbuffer.sgml
@@ -10,13 +10,54 @@ Buffers are the basic unit of data transfer in GST.  The GstBuffer type
 provides all the state necessary to define a region of memory as part of a
 stream.  Sub-buffer are also supported, allowing a smaller region of a
 buffer to become its own buffer, with mechanisms in place to ensure that
-nither memory space goes away.  Metadata is supported as a list of
+neither memory space goes away.  Metadata is supported as a list of
 pointers to arbitrary metadata.
 </para>
+<para>
+Buffers are usually created with gst_buffer_new(). After a buffer has been 
+created one will typically allocate memory for it and set the size of the 
+buffer data.
+<programlisting>
+  GstBuffer *buffer;
+  gint size, widht, height, bpp;
+
+  size = width * height * bpp;
+
+  buffer = gst_buffer_new ();
+  GST_BUFFER_SIZE (buffer) = size;
+  GST_BUFFER_DATA (buffer) = g_alloc (size);
+  ...
+  
+</programlisting>
+</para>
+<para>
+GstBuffers can also be created from a GstBufferPool with 
+gst_buffer_new_from_pool(). The bufferpool can be obtained from a
+peer element with gst_pad_get_bufferpool().
+</para>
+<para>
+gst_buffer_ref() is used to increase the refcount of a buffer. This must be
+done when you want to keep a handle to the buffer after pushing it to the
+next element.
+</para>
+<para>
+To efficiently create a smaller buffer out of an existing one, you can
+use gst_buffer_create_sub().
+</para>
+<para>
+Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET()
+and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
+a certain flag is set.
+</para>
+<para>
+Buffers usually are freed by unreffing them with gst_buffer_unref().
+gst_buffer_destroy() can also be used to effectively destroy the buffer
+regardless of the refcount (dangerous).
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GstBufferPool, #GstPad
 </para>
 
 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
@@ -88,7 +129,7 @@ Get the offset in the source file of this buffer.
 
 <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
 <para>
-
+Gets the maximun size of this buffer.
 </para>
 
 @buf: GstBuffer

diff --git a/docs/gst/tmpl/gstbufferpool.sgml b/docs/gst/tmpl/gstbufferpool.sgml
index 24243ed..075f996 100644 (file)
--- a/docs/gst/tmpl/gstbufferpool.sgml
+++ b/docs/gst/tmpl/gstbufferpool.sgml
@@ -10,17 +10,40 @@ A bufferpool is used to create buffers in an efficient way. En element
 can maintain a bufferpool with a fixed number of buffers. This will reduce
 the g_malloc and g_free overhead.
 </para>
-
 <para>
 A bufferpool can also be used to implement direct access. A bufferpool can be
 sent from one element to another so that the latter can directly write into
 the memory of the element that maintains the bufferpool. This can greatly reduce
 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().
+</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().
+</para>
+<para>
+When the buffer is unreffed and has reached a refcount of 0, the bufferpools destroy
+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.
+</para>
+<para>
+Destroy the bufferpool with gst_buffer_pool_destroy().
+</para>
+<para>
+A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function.
+</para>
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GstBuffer, #GstPad
 </para>
 
 <!-- ##### STRUCT GstBufferPool ##### -->

diff --git a/docs/gst/tmpl/gstcaps.sgml b/docs/gst/tmpl/gstcaps.sgml
index 6f8a9e5..38ae27e 100644 (file)
--- a/docs/gst/tmpl/gstcaps.sgml
+++ b/docs/gst/tmpl/gstcaps.sgml
@@ -12,7 +12,7 @@ a mime-type and a set of properties.
 
 <!-- ##### SECTION See_Also ##### -->
 <para>
-
+#GstProps, #GstPad
 </para>
 
 <!-- ##### MACRO GST_CAPS_LOCK ##### -->

diff --git a/docs/gst/tmpl/gstreamer-unused.sgml b/docs/gst/tmpl/gstreamer-unused.sgml
index 5fa58aa..29a890b 100644 (file)
--- a/docs/gst/tmpl/gstreamer-unused.sgml
+++ b/docs/gst/tmpl/gstreamer-unused.sgml
@@ -67,21 +67,21 @@ Query the element for the current mime type
 </para>
 
 
-<!-- ##### FUNCTION gst_pad_remove_ghost_parent ##### -->
+<!-- ##### FUNCTION gst_fdsink_chain ##### -->
 <para>
 
 </para>
 
 @pad: 
-@parent: 
+@buf: 
 
-<!-- ##### FUNCTION gst_fdsink_chain ##### -->
+<!-- ##### FUNCTION gst_pad_remove_ghost_parent ##### -->
 <para>
 
 </para>
 
 @pad: 
-@buf: 
+@parent: 
 
 <!-- ##### ARG GstHttpSrc:location ##### -->
 <para>
@@ -97,20 +97,20 @@ Specify the location of the file. The location must be a fully qualified URL.
 @pad: 
 @buf: 
 
-<!-- ##### FUNCTION gst_connection_get_type ##### -->
+<!-- ##### FUNCTION gst_audiosink_chain ##### -->
 <para>
 
 </para>
 
-@Returns: 
+@pad: 
+@buf: 
 
-<!-- ##### FUNCTION gst_audiosink_chain ##### -->
+<!-- ##### FUNCTION gst_connection_get_type ##### -->
 <para>
 
 </para>
 
-@pad: 
-@buf: 
+@Returns: 
 
 <!-- ##### MACRO GST_PIPELINE_CLASS ##### -->
 <para>
@@ -206,18 +206,18 @@ the stream.
 @gstsrc: the object which received the signal.
 @arg1: the object which received the signal
 
-<!-- ##### TYPEDEF GstCapsFactoryEntry ##### -->
+<!-- ##### FUNCTION gst_disksrc_get_type ##### -->
 <para>
 
 </para>
 
+@Returns: 
 
-<!-- ##### FUNCTION gst_disksrc_get_type ##### -->
+<!-- ##### TYPEDEF GstCapsFactoryEntry ##### -->
 <para>
 
 </para>
 
-@Returns: 
 
 <!-- ##### MACRO GST_IS_DISKSRC_CLASS ##### -->
 <para>
@@ -372,16 +372,16 @@ subclass use this to start their flag enumeration
 @audiosink: 
 @channels: 
 
-<!-- ##### SECTION ./tmpl/gstconnection.sgml:Short_Description ##### -->
-Generic connection between elements.
-
-
 <!-- ##### STRUCT GstSinkClass ##### -->
 <para>
 
 </para>
 
 
+<!-- ##### SECTION ./tmpl/gstconnection.sgml:Short_Description ##### -->
+Generic connection between elements.
+
+
 <!-- ##### STRUCT GstFilterClass ##### -->
 <para>
 
@@ -661,13 +661,13 @@ Specify the current offset in the file.
 @sheight: 
 @bytes_per_line: 
 
-<!-- ##### SECTION ./tmpl/GstElement.sgml:Long_Description ##### -->
+<!-- ##### ARG GstAudioSink:format ##### -->
 <para>
 
 </para>
 
 
-<!-- ##### ARG GstAudioSink:format ##### -->
+<!-- ##### SECTION ./tmpl/GstElement.sgml:Long_Description ##### -->
 <para>
 
 </para>
@@ -701,32 +701,32 @@ Specify the current offset in the file.
 @name: 
 @Returns: 
 
-<!-- ##### STRUCT GstConnection ##### -->
+<!-- ##### STRUCT GstQueueClass ##### -->
 <para>
 
 </para>
 
 
-<!-- ##### STRUCT GstQueueClass ##### -->
+<!-- ##### STRUCT GstConnection ##### -->
 <para>
 
 </para>
 
 
-<!-- ##### FUNCTION gst_fakesrc_push ##### -->
+<!-- ##### FUNCTION gst_type_add_sink ##### -->
 <para>
 
 </para>
 
-@src: 
+@id: 
+@sink: 
 
-<!-- ##### FUNCTION gst_type_add_sink ##### -->
+<!-- ##### FUNCTION gst_fakesrc_push ##### -->
 <para>
 
 </para>
 
-@id: 
-@sink: 
+@src: 
 
 <!-- ##### MACRO GST_IS_IDENTITY_CLASS ##### -->
 <para>
@@ -1141,19 +1141,19 @@ GstFilter
 
 @obj: 
 
-<!-- ##### MACRO GST_IS_QUEUE_CLASS ##### -->
+<!-- ##### FUNCTION gst_fdsrc_get_type ##### -->
 <para>
 
 </para>
 
-@obj: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_fdsrc_get_type ##### -->
+<!-- ##### MACRO GST_IS_QUEUE_CLASS ##### -->
 <para>
 
 </para>
 
-@Returns: 
+@obj: 
 
 <!-- ##### FUNCTION gst_pad_get_type_id ##### -->
 <para>
@@ -1163,13 +1163,6 @@ GstFilter
 @pad: 
 @Returns: 
 
-<!-- ##### FUNCTION gst_thread_iterate ##### -->
-<para>
-
-</para>
-
-@thread: 
-
 <!-- ##### STRUCT OverlayClip ##### -->
 <para>
 
@@ -1180,6 +1173,13 @@ GstFilter
 @y1: 
 @y2: 
 
+<!-- ##### FUNCTION gst_thread_iterate ##### -->
+<para>
+
+</para>
+
+@thread: 
+
 <!-- ##### ENUM GstSrcFlags ##### -->
 <para>
 Flags for the GstSrc element
@@ -1255,19 +1255,19 @@ Defines an entry for a padfactory.
 
 @obj: 
 
-<!-- ##### FUNCTION gst_asyncdisksrc_get_type ##### -->
+<!-- ##### MACRO GST_AUDIOSINK_CLASS ##### -->
 <para>
 
 </para>
 
-@Returns: 
+@klass: 
 
-<!-- ##### MACRO GST_AUDIOSINK_CLASS ##### -->
+<!-- ##### FUNCTION gst_asyncdisksrc_get_type ##### -->
 <para>
 
 </para>
 
-@klass: 
+@Returns: 
 
 <!-- ##### MACRO GST_PAD_FACTORY_SINK ##### -->
 <para>
@@ -1304,19 +1304,19 @@ Indicates a sinkpad for the padfactory.
 @pad: 
 @Returns: 
 
-<!-- ##### MACRO GST_PROPS_FOURCC_ID ##### -->
+<!-- ##### FUNCTION gst_esdsink_new ##### -->
 <para>
 
 </para>
 
+@name: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_esdsink_new ##### -->
+<!-- ##### MACRO GST_PROPS_FOURCC_ID ##### -->
 <para>
 
 </para>
 
-@name: 
-@Returns: 
 
 <!-- ##### FUNCTION gst_element_request_pad ##### -->
 <para>
@@ -1427,18 +1427,18 @@ This macro sets the given flags.
 @flag: Flag to set, can by any number of bits in guint32.
 @obj: GstSrc to set flag in.
 
-<!-- ##### MACRO GST_PROPS_FLOAT_STRING ##### -->
+<!-- ##### MACRO DEBUG_LEAVE_STRING ##### -->
 <para>
 
 </para>
 
-@a: 
 
-<!-- ##### MACRO DEBUG_LEAVE_STRING ##### -->
+<!-- ##### MACRO GST_PROPS_FLOAT_STRING ##### -->
 <para>
 
 </para>
 
+@a: 
 
 <!-- ##### FUNCTION gst_filter_get_type ##### -->
 <para>
@@ -1461,16 +1461,16 @@ This macro sets the given flags.
 </para>
 
 
-<!-- ##### SECTION ./tmpl/gstsink.sgml:Title ##### -->
-GstSink
-
-
 <!-- ##### MACRO GST_CPU_FLAG_MMX ##### -->
 <para>
 A flag indicating that MMX instructions are supported.
 </para>
 
 
+<!-- ##### SECTION ./tmpl/gstsink.sgml:Title ##### -->
+GstSink
+
+
 <!-- ##### FUNCTION gst_object_get_type ##### -->
 <para>
 
@@ -1784,19 +1784,19 @@ or a video card.
 </para>
 
 
-<!-- ##### MACRO GST_IS_BIN_CLASS ##### -->
+<!-- ##### FUNCTION gst_esdsink_get_type ##### -->
 <para>
 
 </para>
 
-@obj: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_esdsink_get_type ##### -->
+<!-- ##### MACRO GST_IS_BIN_CLASS ##### -->
 <para>
 
 </para>
 
-@Returns: 
+@obj: 
 
 <!-- ##### SECTION ./tmpl/GstElement.sgml:See_Also ##### -->
 <para>
@@ -1818,19 +1818,19 @@ Query whether this object has multiple input pads.
 
 @obj: Element to query for multiple input pads.
 
-<!-- ##### SECTION ./tmpl/gstfilter.sgml:See_Also ##### -->
+<!-- ##### MACRO DEBUG_NOPREFIX ##### -->
 <para>
 
 </para>
 
+@format: 
+@args...: 
 
-<!-- ##### MACRO DEBUG_NOPREFIX ##### -->
+<!-- ##### SECTION ./tmpl/gstfilter.sgml:See_Also ##### -->
 <para>
 
 </para>
 
-@format: 
-@args...: 
 
 <!-- ##### ARG GstAudioSink:frequency ##### -->
 <para>
@@ -2249,13 +2249,6 @@ this in the factory definition.
 
 @audiosink: 
 
-<!-- ##### MACRO GST_IS_FAKESINK ##### -->
-<para>
-
-</para>
-
-@obj: 
-
 <!-- ##### MACRO GST_STATE_UNSET ##### -->
 <para>
 This macro unsets the given state on the element.
@@ -2264,6 +2257,13 @@ This macro unsets the given state on the element.
 @obj: Element to unset state of.
 @flag: State to unset, can be any number of bits in guint32.
 
+<!-- ##### MACRO GST_IS_FAKESINK ##### -->
+<para>
+
+</para>
+
+@obj: 
+
 <!-- ##### MACRO GST_QUEUE_CLASS ##### -->
 <para>
 
@@ -2336,22 +2336,22 @@ The number of bytes per read.
 
 @obj: 
 
-<!-- ##### MACRO ERROR_OBJECT ##### -->
+<!-- ##### FUNCTION gst_sinesrc_get_type ##### -->
 <para>
 
 </para>
 
-@element: 
-@object: 
-@format: 
-@args...: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_sinesrc_get_type ##### -->
+<!-- ##### MACRO ERROR_OBJECT ##### -->
 <para>
 
 </para>
 
-@Returns: 
+@element: 
+@object: 
+@format: 
+@args...: 
 
 <!-- ##### MACRO GST_IS_IDENTITY ##### -->
 <para>
@@ -2457,9 +2457,14 @@ This macro sets the given state on the element.
 
 @obj: 
 
-<!-- ##### SECTION ./tmpl/videoraw.sgml:Short_Description ##### -->
-Information about video buffers.
+<!-- ##### FUNCTION gst_src_push_region ##### -->
+<para>
+
+</para>
 
+@src: 
+@offset: 
+@size: 
 
 <!-- ##### FUNCTION gst_fdsink_get_type ##### -->
 <para>
@@ -2468,14 +2473,9 @@ Information about video buffers.
 
 @Returns: 
 
-<!-- ##### FUNCTION gst_src_push_region ##### -->
-<para>
-
-</para>
+<!-- ##### SECTION ./tmpl/videoraw.sgml:Short_Description ##### -->
+Information about video buffers.
 
-@src: 
-@offset: 
-@size: 
 
 <!-- ##### STRUCT GstPipelineClass ##### -->
 <para>
@@ -2579,13 +2579,13 @@ A flag indicating that SSE instructions are supported.
 
 @obj: 
 
-<!-- ##### ARG GstAsyncDiskSrc:size ##### -->
+<!-- ##### STRUCT GstDiskSrcClass ##### -->
 <para>
 
 </para>
 
 
-<!-- ##### STRUCT GstDiskSrcClass ##### -->
+<!-- ##### ARG GstAsyncDiskSrc:size ##### -->
 <para>
 
 </para>
@@ -2666,19 +2666,19 @@ Information about audio buffers.
 </para>
 
 
-<!-- ##### FUNCTION plugin_initialize ##### -->
+<!-- ##### FUNCTION gst_caps_register ##### -->
 <para>
 
 </para>
 
+@factory: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_caps_register ##### -->
+<!-- ##### FUNCTION plugin_initialize ##### -->
 <para>
 
 </para>
 
-@factory: 
-@Returns: 
 
 <!-- ##### ARG GstAsyncDiskSrc:location ##### -->
 <para>
@@ -2743,20 +2743,20 @@ the offset.
 </para>
 
 
-<!-- ##### FUNCTION gst_sinesrc_new ##### -->
+<!-- ##### MACRO GST_IS_ASYNCDISKSRC_CLASS ##### -->
 <para>
 
 </para>
 
-@name: 
-@Returns: 
+@obj: 
 
-<!-- ##### MACRO GST_IS_ASYNCDISKSRC_CLASS ##### -->
+<!-- ##### FUNCTION gst_sinesrc_new ##### -->
 <para>
 
 </para>
 
-@obj: 
+@name: 
+@Returns: 
 
 <!-- ##### ARG GstAudioSrc:curoffset ##### -->
 <para>
@@ -2806,19 +2806,19 @@ plugin
 
 @klass: 
 
-<!-- ##### MACRO GST_HTTPSRC_CLASS ##### -->
+<!-- ##### MACRO GST_ASYNCDISKSRC ##### -->
 <para>
 
 </para>
 
-@klass: 
+@obj: 
 
-<!-- ##### MACRO GST_ASYNCDISKSRC ##### -->
+<!-- ##### MACRO GST_HTTPSRC_CLASS ##### -->
 <para>
 
 </para>
 
-@obj: 
+@klass: 
 
 <!-- ##### ARG GstPad:active ##### -->
 <para>