Removed the last bits of Metadata.

Original commit message from CVS:
Removed the last bits of Metadata.
Updated the bufferpool docs.

docs/gst/gstreamer-docs.sgml

@@ -9,7 +9,6 @@
 <!entity GstCpu SYSTEM "sgml/gstcpu.sgml">
 <!entity GstElement SYSTEM "sgml/gstelement.sgml">
 <!entity GstLog SYSTEM "sgml/gstlog.sgml">
-<!entity GstMeta SYSTEM "sgml/gstmeta.sgml">
 <!entity GstObject SYSTEM "sgml/gstobject.sgml">
 <!entity GstPad SYSTEM "sgml/gstpad.sgml">
 <!entity GstPipeline SYSTEM "sgml/gstpipeline.sgml">
@@ -56,7 +55,7 @@
     <title>GStreamer Core Library</title>
 
     <para>libgst.la provides all the core GStreamer services,
-including initialization, plugin management, types and metadata, as 
+including initialization, plugin management and types, as 
 well as the object hiarchy that defines elements and bins, along
 with some more specialized elements.</para>
 
@@ -69,7 +68,6 @@ with some more specialized elements.</para>
     &GstCpu;
     &GstElement;
     &GstInfo;
-    &GstMeta;
     &GstObject;
     &GstPad;
     &GstParse;
@@ -140,14 +138,6 @@ with some more specialized elements.</para>
     &GstTee;
   </chapter>
 
-  <chapter id="metatdata-types">
-    <title>GStreamer MetaData Types</title>
-
-    <para>MetaData is used to specify the content of buffers. See <classname>GstMeta</classname>. </para>
-
-    &spectrum;
-  </chapter>
-
   <chapter id="autopluggers">
     <title>GStreamer Autoppluggers</title>
 

docs/gst/gstreamer-sections.txt

@@ -1,5 +1,152 @@
 <INCLUDE>gst/gst.h</INCLUDE>
 
+<SECTION>
+<FILE>gobject2gtk</FILE>
+GObject
+G_MAXUINT
+G_MAXULONG
+g_object_ref
+g_object_unref
+G_TYPE_CHECK_INSTANCE_CAST
+G_TYPE_CHECK_INSTANCE_TYPE
+G_TYPE_CHECK_CLASS_CAST
+G_TYPE_CHECK_CLASS_TYPE
+G_TYPE_FROM_CLASS
+G_OBJECT_TYPE
+G_OBJECT_CLASS_TYPE
+G_TYPE_NONE
+G_TYPE_CHAR
+G_TYPE_UCHAR
+G_TYPE_BOOLEAN
+G_TYPE_INT
+G_TYPE_UINT
+G_TYPE_LONG
+G_TYPE_ULONG
+G_TYPE_ENUM
+G_TYPE_FLAGS
+G_TYPE_FLOAT
+G_TYPE_DOUBLE
+G_TYPE_STRING
+G_TYPE_POINTER
+G_TYPE_BOXED
+G_TYPE_PARAM
+g_cclosure_marshal_VOID__VOID
+g_cclosure_marshal_VOID__BOOLEAN
+g_cclosure_marshal_VOID__CHAR
+g_cclosure_marshal_VOID__UCHAR
+g_cclosure_marshal_VOID__INT
+g_cclosure_marshal_VOID__UINT
+g_cclosure_marshal_VOID__LONG
+g_cclosure_marshal_VOID__ULONG
+g_cclosure_marshal_VOID__ENUM
+g_cclosure_marshal_VOID__FLAGS
+g_cclosure_marshal_VOID__FLOAT
+g_cclosure_marshal_VOID__DOUBLE
+g_cclosure_marshal_VOID__STRING
+g_cclosure_marshal_VOID__PARAM
+g_cclosure_marshal_VOID__BOXED
+g_cclosure_marshal_VOID__POINTER
+g_cclosure_marshal_STRING__OBJECT_POINTER
+g_cclosure_marshal_VOID__UINT_POINTER
+gst_marshal_VOID__OBJECT_POINTER
+gst_marshal_VOID__INT_INT
+g_object_get_property
+g_object_set
+GType
+GTypeFlags
+GClassInitFunc
+GBaseInitFunc
+GInstanceInitFunc
+g_type_class_ref
+g_type_class_unref
+g_type_name
+g_type_from_name
+GEnumValue
+g_enum_register_static
+GTypeInfo
+G_TYPE_FLAG_ABSTRACT
+g_type_register_static
+g2g_type_register_static
+g_object_new
+g2g_object_new
+G_SIGNAL_RUN_LAST
+G_SIGNAL_RUN_FIRST
+GCallback
+G_CALLBACK
+g_signal_newc
+g2g_signal_newc
+g_signal_lookup
+g_signal_handler_block
+g_signal_handler_unblock
+GValue
+GParamFlags
+G_VALUE_TYPE
+G_PARAM_READWRITE
+G_PARAM_READABLE
+G_PARAM_WRITABLE
+G_OBJECT_WARN_INVALID_PROPERTY_ID
+GParamSpec
+g_value_init
+g_object_class_install_property
+g2g_object_class_install_property
+g_object_class_find_property
+g2g_object_class_find_property
+g_object_class_list_properties
+g2g_object_class_list_properties
+G_IS_PARAM_SPEC_ENUM
+g_param_spec_boolean
+g2g_param_spec_boolean
+g_param_spec_int
+g2g_param_spec_int
+g_param_spec_uint
+g2g_param_spec_uint
+g_param_spec_long
+g2g_param_spec_long
+g_param_spec_ulong
+g2g_param_spec_ulong
+g_param_spec_float
+g2g_param_spec_float
+g_param_spec_double
+g2g_param_spec_double
+g_param_spec_enum
+g2g_param_spec_enum
+g_param_spec_pointer
+g2g_param_spec_pointer
+g_param_spec_string
+g2g_param_spec_string
+g_value_get_boolean
+g_value_set_boolean
+g_value_get_enum
+g_value_set_enum
+g_value_get_int
+g_value_set_int
+g_value_get_uint
+g_value_set_uint
+g_value_get_long
+g_value_set_long
+g_value_get_ulong
+g_value_set_ulong
+g_value_get_float
+g_value_set_float
+g_value_get_double
+g_value_set_double
+g_value_get_string
+g_value_set_string
+g_value_get_pointer
+g_value_set_pointer
+G_OBJECT
+<TITLE>GObject</TITLE>
+g_object_get_type
+<SUBSECTION Standard>
+g_cclosure_marshal_VOID__OBJECT
+G_IS_OBJECT
+G_TYPE_OBJECT
+g2g_object_get_type
+G_OBJECT_CLASS
+G_IS_OBJECT_CLASS
+G_OBJECT_GET_CLASS
+</SECTION>
+
 <SECTION>
 <FILE>cothreads</FILE>
 CURRENT_STACK_FRAME
@@ -167,6 +314,7 @@ GST_BUFFER_MAXSIZE
 GST_BUFFER_TIMESTAMP
 GST_BUFFER_BUFFERPOOL
 GST_BUFFER_POOL_PRIVATE
+GST_BUFFER_POOL_LOCK
 GST_BUFFER_LOCK
 GST_BUFFER_TRYLOCK
 GST_BUFFER_UNLOCK
@@ -334,22 +482,6 @@ gst_info
 <SUBSECTION Standard>
 </SECTION>
 
-<SECTION>
-<FILE>gstmeta</FILE>
-GST_META_FLAGS
-GST_META_FLAG_IS_SET
-GST_META_FLAG_SET
-GST_META_FLAG_UNSET
-GstMetaFlags
-GstMeta
-gst_meta_new_size
-gst_meta_new
-gst_meta_ref
-gst_meta_unref
-<SUBSECTION Standard>
-GST_META
-</SECTION>
-
 <SECTION>
 <FILE>gstobject</FILE>
 <TITLE>GstObject</TITLE>
@@ -755,7 +887,6 @@ gst_util_get_float_arg
 gst_util_get_double_arg
 gst_util_get_string_arg
 gst_util_get_pointer_arg
-gst_util_get_widget_arg
 gst_util_dump_mem
 <SUBSECTION Standard>
 </SECTION>
@@ -1003,9 +1134,3 @@ GST_MULTIDISKSRC_CLASS
 GST_IS_MULTIDISKSRC_CLASS
 </SECTION>
 
-<SECTION>
-<INCLUDE>gst/meta/spectrum.h</INCLUDE>
-<FILE>spectrum</FILE>
-MetaAudioSpectrum
-</SECTION>
-

docs/gst/gstreamer.hierarchy

@@ -2,23 +2,23 @@ GtkObject
   GtkWidget
     GtkRange
     GtkContainer
-  GstObject
+  GObject
-    GstXML
+    GstObject
-    GstElement
+      GstXml
-      GstBin
+      GstElement
-        GstPipeline
+        GstBin
-        GstThread
+          GstPipeline
-      GstTee
+          GstThread
-      GstFakeSrc
+        GstTee
-      GstFakeSink
+        GstFakeSrc
-      GstDiskSrc
+        GstFakeSink
-      GstHttpSrc
+        GstDiskSrc
-      GstFdSrc
+        GstHttpSrc
-      GstSineSrc
+        GstFdSrc
-      GstFdSink
+        GstSineSrc
-      GstPipefilter
+        GstFdSink
-      GstIdentity
+        GstPipefilter
-      GstQueue
+        GstIdentity
-      GstTypeFind
+        GstQueue
-    GstPad
+        GstTypeFind
-  GstSignalObject
+      GstPad

docs/gst/tmpl/gstbuffer.sgml

@@ -151,6 +151,14 @@ Get the bufferpool private data.
 @buf: GstBuffer
 
 
+<!-- ##### MACRO GST_BUFFER_POOL_LOCK ##### -->
+<para>
+
+</para>
+
+@pool: 
+
+
 <!-- ##### MACRO GST_BUFFER_LOCK ##### -->
 <para>
 This macro will obtain a lock on the object, making serialization

docs/gst/tmpl/gstbufferpool.sgml

@@ -51,7 +51,7 @@ A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() funct
 
 </para>
 
-@new_buffer: 
+@lock: 
 @new_user_data: 
 @destroy_user_data: 
 @destroy_buffer: 
@@ -103,6 +103,33 @@ the pool.
 @buffer: 
 
 
+<!-- ##### FUNCTION gst_buffer_pool_ref ##### -->
+<para>
+
+</para>
+
+@pool: 
+
+
+<!-- ##### FUNCTION gst_buffer_pool_ref_by_count ##### -->
+<para>
+
+</para>
+
+@pool: 
+@count: 
+
+
+<!-- ##### FUNCTION gst_buffer_pool_unref ##### -->
+<para>
+
+</para>
+
+@pool: 
+<!-- # Unused Parameters # -->
+@buffer: 
+
+
 <!-- ##### FUNCTION gst_buffer_pool_set_create_function ##### -->
 <para>
 
@@ -131,3 +158,14 @@ the pool.
 @pool: 
 
 
+<!-- ##### FUNCTION gst_buffer_pool_get_default ##### -->
+<para>
+
+</para>
+
+@oldpool: 
+@buffer_size: 
+@pool_size: 
+@Returns: 
+
+

docs/gst/tmpl/gstelement.sgml

@@ -35,7 +35,7 @@ use gst_element_set_state() to change the state of an element.
 
 </para>
 
-@GST_STATE_NONE_PENDING: The element is in the desired state.
+@GST_STATE_VOID_PENDING: 
 @GST_STATE_NULL: Reset the state of an element.
 @GST_STATE_READY: will make the element ready to start processing data. some
 elements might have a non trivial way to initialize themselves.

docs/gst/tmpl/gstpad.sgml

@@ -271,7 +271,7 @@ The function that will be called when pulling buffers.
 the region types for #gst_pad_pullregion.
 </para>
 
-@GST_REGION_NONE: no type specified
+@GST_REGION_VOID: 
 @GST_REGION_OFFSET_LEN: an offet/length pair
 @GST_REGION_TIME_LEN: a time start/length pair
 

docs/gst/tmpl/gstplugin.sgml

@@ -67,9 +67,7 @@ to bring it into memory.
 @numtypes: 
 @elements: 
 @numelements: 
-@autopluggers: 
 @numautopluggers: 
-@loaded: 
 
 <!-- ##### USER_FUNCTION GstPluginInitFunc ##### -->
 <para>

docs/gst/tmpl/gstreamer-unused.sgml

@@ -220,6 +220,10 @@ the stream.
 
 @obj: 
 
+<!-- ##### SECTION ./tmpl/gstmeta.sgml:Short_Description ##### -->
+Provide context for buffers
+
+
 <!-- ##### MACRO DEBUG_ENTER_STRING ##### -->
 <para>
 
@@ -424,6 +428,13 @@ Generic connection between elements.
 @overlay_info: 
 @dga_info: 
 
+<!-- ##### FUNCTION gst_meta_ref ##### -->
+<para>
+
+</para>
+
+@meta: 
+
 <!-- ##### SECTION ./tmpl/gstaudiosink.sgml:See_Also ##### -->
 <para>
 
@@ -670,6 +681,13 @@ Specify the current offset in the file.
 </para>
 
 
+<!-- ##### FUNCTION gst_meta_unref ##### -->
+<para>
+
+</para>
+
+@meta: 
+
 <!-- ##### STRUCT GstSineSrc ##### -->
 <para>
 
@@ -686,6 +704,10 @@ Specify the current offset in the file.
 @sheight: 
 @bytes_per_line: 
 
+<!-- ##### SECTION ./tmpl/spectrum.sgml:Title ##### -->
+spectrum
+
+
 <!-- ##### SECTION ./tmpl/GstElement.sgml:Long_Description ##### -->
 <para>
 
@@ -1325,6 +1347,10 @@ subclasses can use this value to start the enumeration of their flags
 </para>
 
 
+<!-- ##### SECTION ./tmpl/spectrum.sgml:Short_Description ##### -->
+Frequencies of a spectrum analysis.
+
+
 <!-- ##### FUNCTION gst_asyncdisksrc_get_type ##### -->
 <para>
 
@@ -1388,6 +1414,13 @@ Indicates a sinkpad for the padfactory.
 @name: 
 @Returns: 
 
+<!-- ##### MACRO GST_META_FLAGS ##### -->
+<para>
+Retrieve the flags of the given meta information.
+</para>
+
+@meta: the meta information
+
 <!-- ##### FUNCTION gst_element_request_pad ##### -->
 <para>
 
@@ -1440,6 +1473,16 @@ This macro checks to see if the given state is set.
 @obj: Element to check for state.
 @flag: State to check for, must be a single bit in guint32.
 
+<!-- ##### STRUCT GstMeta ##### -->
+<para>
+
+</para>
+
+@lock: for locking purposes
+@flags: the flags of the meta data
+@data: the meta data
+@size: the size of the meta data
+
 <!-- ##### FUNCTION gst_xml_new_from_memory ##### -->
 <para>
 
@@ -1784,6 +1827,12 @@ The Element is going from the READY state to the PLAYING state.
 </para>
 
 
+<!-- ##### SECTION ./tmpl/gstmeta.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### MACRO GST_IS_TEE_CLASS ##### -->
 <para>
 
@@ -1798,6 +1847,105 @@ The Element is going from the READY state to the PLAYING state.
 
 @arg: 
 
+<!-- ##### SECTION ./tmpl/gstmeta.sgml:Long_Description ##### -->
+<para>
+The point of the metadata is to provide some context for each buffer.  In
+the case of audio data, for instance, it would provide the samplerate, bit
+depth, and channel count.
+</para>
+
+<para>
+The trick is that there may be multiple types of metadata ganged onto a
+single buffer.  This is why they're going to be a GList.  This does mean
+extra overhead in all cases, but I think it's minimal.  The GList type
+uses a chunk allocater so we're not wasting too much memory or time when
+adding to the list.
+</para>
+
+<para>
+The trick is dealing with these structs as they pass through a pipeline,
+since they have potentially different mutability properties.  For
+instance, if you've got a mp3 decoder connected to a tee, which sends the
+buffers off to both the decoder and a spectrum analyzer (and then a
+visualization element).  The preferred setup would be where every time a
+audio/raw metadata comes down the pipe (indicating a potential change in
+audio format), the audiosink and spectrum would just save off pointers.
+</para>
+
+<para>
+So when exactly does this metadata go away (deallocated)?  Well, that
+means metadata has to be refcounted.  But that gets rather hairy.  OK, in
+the simple case you create a metadata struct, it comes with refcount set
+to 1.  You pass it through, it stays one, eventually someone drops the
+last reference on the buffer it's tied to, you free the metadata too.
+Easy.  What if you tee?  You could go through and for every metadata in
+the buffer, increment the refcount by the same as the buffer.  So in the
+above case (tee'd), the audiosink and spectrum would get the buffer with a
+refcount of 2, and it'd have a metadata with refcount 2.  Do they ref it
+each themselves, then unref the buffer?  Or do they remove the metadata?
+Removing the metadata would require a buffer CoW, which would suck, so
+yes, they'd just ref the metadata.
+</para>
+
+<para>
+But....  what if they're all in different threads?  Then we're off into
+the magical world of mutexes.  Everything with a refcount in a threaded
+world must be mutexed, else you can do atomic increment and atomic
+dec and test.  Can this be done from C easily?  Perhaps it needs to be found
+from kernel includes via autoconf?
+</para>
+
+<para>
+The goal in designing the way metadata will be defined and used is to keep
+it as simple as possible.  The basis for accomplishing this is the fact
+that in order to actually use (rather than just pass) the metadata, you
+have to know what the fields are, which means you have to have compiled in
+support for that metadata at build time.  Therefore, if you're using
+metadata, you must have build-time access to the necessary include file
+that defines it.
+</para>
+
+<para>
+So, given that you've got an include file, it would be nice if the whole
+thing could be contained there.  This would limit the need to be linked
+against something, or have load-time requirements as to that has to be
+loaded before you are.
+</para>
+
+<para>
+Given that really all metadata is is a region of memory of a given size
+with a certain signature, this isn't all that hard.  First you lay out the
+struct that defines the metadata.  Then you set up #defines that expand to
+the size of the struct in question, as well as the four-cc code that
+defines the type.
+</para>
+
+<para>
+The work is done by a few #defines, a la the #defines used in all Gtk
+objects.  The first is a NEW() method that allocates the memory for the
+metadata and fills in all the normal fields (type, size, utility
+functions).  Because of the way it's defined (as a #define, no less),
+you'll have to invoke it as META_NEW(meta), since it can't return()
+anything.
+</para>
+
+<para>
+Another #define will check to make sure a meta is indeed that type by
+verifying the type code and size.  Theoretically, meta types can overlap
+with the same fourcc code, as long as they have different sizes.  But I
+probably ought to have a global public registry so people writing things
+don't conflict.  MSFT got that right, at least.
+</para>
+
+<para>
+So, a hairy problem is what to do when there are utility functions
+associated with one of these things.  One option is to not bother with
+them.  This is very likely a possible solution, since metadata is supposed
+to be flat memory of a given size.  Not much to do to either free or copy
+it, is there?
+</para>
+
+
 <!-- ##### SECTION ./tmpl/gstconnection.sgml:Title ##### -->
 GstConnection
 
@@ -1868,6 +2016,14 @@ GstElement
 </para>
 
 
+<!-- ##### MACRO GST_META_FLAG_UNSET ##### -->
+<para>
+Clear a flag in the meta data.
+</para>
+
+@meta: the meta data
+@flag: the flag to clear
+
 <!-- ##### MACRO GST_IS_FAKESRC ##### -->
 <para>
 
@@ -2484,6 +2640,14 @@ The number of bytes per read.
 
 @obj: 
 
+<!-- ##### FUNCTION gst_meta_new_size ##### -->
+<para>
+
+</para>
+
+@size: 
+@Returns: 
+
 <!-- ##### MACRO ERROR_OBJECT ##### -->
 <para>
 
@@ -2598,6 +2762,19 @@ This macro sets the given state on the element.
 </para>
 
 
+<!-- ##### ENUM GstMetaFlags ##### -->
+<para>
+Flags indicating properties about the meta data.
+</para>
+
+@GST_META_FREEABLE: the meta data can be freed
+
+<!-- ##### SECTION ./tmpl/spectrum.sgml:See_Also ##### -->
+<para>
+
+</para>
+
+
 <!-- ##### MACRO GST_CONNECTION ##### -->
 <para>
 
@@ -2708,6 +2885,10 @@ This macro checks to see if the GST_SRC_ASYNC flag is set.
 </para>
 
 
+<!-- ##### SECTION ./tmpl/gstmeta.sgml:Title ##### -->
+GstMeta
+
+
 <!-- ##### TYPEDEF GstCapsFactory ##### -->
 <para>
 
@@ -2733,6 +2914,15 @@ A flag indicating that SSE instructions are supported.
 
 @obj: 
 
+<!-- ##### FUNCTION gst_util_get_widget_arg ##### -->
+<para>
+
+</para>
+
+@object: 
+@argname: 
+@Returns: 
+
 <!-- ##### ARG GstAsyncDiskSrc:size ##### -->
 <para>
 
@@ -2775,6 +2965,14 @@ to the current function, i.e. "('element')"
 </para>
 
 
+<!-- ##### MACRO GST_META_FLAG_SET ##### -->
+<para>
+Set a flag in the meta data.
+</para>
+
+@meta: the meta data
+@flag: the flag to set
+
 <!-- ##### MACRO GST_IS_SRC ##### -->
 <para>
 
@@ -2808,6 +3006,14 @@ Information about audio buffers.
 @GST_CAPS_ALWAYS: 
 @GST_CAPS_MAYBE: 
 
+<!-- ##### MACRO GST_META_FLAG_IS_SET ##### -->
+<para>
+Check if a given flag is set.
+</para>
+
+@meta: the meta data to test
+@flag: the flag to test
+
 <!-- ##### STRUCT GstPadClass ##### -->
 <para>
 
@@ -2837,6 +3043,13 @@ Information about audio buffers.
 </para>
 
 
+<!-- ##### MACRO gst_meta_new ##### -->
+<para>
+Create new meta data.
+</para>
+
+@type: the type of the meta data to create
+
 <!-- ##### FUNCTION plugin_initialize ##### -->
 <para>
 
@@ -2887,6 +3100,13 @@ Specify the location of the file to read.
 @audiosink: 
 @format: 
 
+<!-- ##### SECTION ./tmpl/spectrum.sgml:Long_Description ##### -->
+<para>
+Frequencies of a spectrum analysis.
+
+</para>
+
+
 <!-- ##### SECTION ./tmpl/gstaudiosrc.sgml:Title ##### -->
 GstAudioSrc
 
@@ -2949,6 +3169,19 @@ Get the current number of bytes read.
 </para>
 
 
+<!-- ##### STRUCT MetaAudioSpectrum ##### -->
+<para>
+
+</para>
+
+@meta: 
+@bands: 
+@channels: 
+@interleaved: 
+@lowfreq: 
+@highfreq: 
+@steps: 
+
 <!-- ##### SECTION ./tmpl/plugin.sgml:Title ##### -->
 plugin
 

docs/gst/tmpl/gstutils.sgml

@@ -94,16 +94,6 @@ Some convenience functions
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_util_get_widget_arg ##### -->
-<para>
-
-</para>
-
-@object: 
-@argname: 
-@Returns: 
-
-
 <!-- ##### FUNCTION gst_util_dump_mem ##### -->
 <para>
 

docs/gst/tmpl/gstxml.sgml

@@ -20,6 +20,9 @@ All GstElements can be serialized to an XML presentation and subsequently loaded
 
 </para>
 
+@object: 
+@topelements: 
+@ns: 
 
 <!-- ##### FUNCTION gst_xml_new ##### -->
 <para>
@@ -91,3 +94,12 @@ All GstElements can be serialized to an XML presentation and subsequently loaded
 @Returns: 
 
 
+<!-- ##### SIGNAL GstXml::object-loaded ##### -->
+<para>
+
+</para>
+
+@gstxml: the object which received the signal.
+@arg1: 
+@arg2: 
+