Removed the last bits of Metadata.

Original commit message from CVS:
Removed the last bits of Metadata.
Updated the bufferpool docs.
This commit is contained in:
Wim Taymans 2001-07-07 10:55:58 +00:00
parent ef64fa0d04
commit 5d2a56cd7c
11 changed files with 463 additions and 69 deletions

View file

@ -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>

View file

@ -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>

View file

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

View file

@ -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

View file

@ -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:

View file

@ -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.

View file

@ -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

View file

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

View file

@ -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

View file

@ -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>

View file

@ -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: