From 9ee943b38999291f497b6e2121ea9e1dd349e73b Mon Sep 17 00:00:00 2001 From: Wim Taymans Date: Wed, 18 Apr 2001 20:16:53 +0000 Subject: [PATCH] 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 --- docs/gst/tmpl/gstbin.sgml | 26 +++ docs/gst/tmpl/gstbuffer.sgml | 47 ++++- docs/gst/tmpl/gstbufferpool.sgml | 27 ++- docs/gst/tmpl/gstcaps.sgml | 2 +- docs/gst/tmpl/gstreamer-unused.sgml | 264 ++++++++++++++-------------- 5 files changed, 228 insertions(+), 138 deletions(-) diff --git a/docs/gst/tmpl/gstbin.sgml b/docs/gst/tmpl/gstbin.sgml index 4669eb4ee0..780ad46c77 100644 --- 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. + +A new GstBin is created with gst_bin_new() + + +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(). + + +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. + + +The list of elements in a bin can be retrieved with gst_bin_get_list(). + + +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. + + +The "object_added" signal is fired whenever a new object is added to the bin. + + +gst_bin_destroy() is used to destroy the bin. + diff --git a/docs/gst/tmpl/gstbuffer.sgml b/docs/gst/tmpl/gstbuffer.sgml index 288a588dba..aae17fee17 100644 --- 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. + +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. + + 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); + ... + + + + +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(). + + +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. + + +To efficiently create a smaller buffer out of an existing one, you can +use gst_buffer_create_sub(). + + +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. + + +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). + - +#GstBufferPool, #GstPad @@ -88,7 +129,7 @@ Get the offset in the source file of this buffer. - +Gets the maximun size of this buffer. @buf: GstBuffer diff --git a/docs/gst/tmpl/gstbufferpool.sgml b/docs/gst/tmpl/gstbufferpool.sgml index 24243edbae..075f996f9a 100644 --- 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. - 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. + +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(). + + +To create a buffer from the bufferpool use gst_buffer_pool_new_buffer(), which is +functionally equivalent to gst_buffer_new_from_pool(). + + +When the buffer is unreffed and has reached a refcount of 0, the bufferpools destroy +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. + + +Destroy the bufferpool with gst_buffer_pool_destroy(). + + +A bufferpool can be requested from a pad with the gst_pad_get_bufferpool() function. + - +#GstBuffer, #GstPad diff --git a/docs/gst/tmpl/gstcaps.sgml b/docs/gst/tmpl/gstcaps.sgml index 6f8a9e5a12..38ae27e70c 100644 --- a/docs/gst/tmpl/gstcaps.sgml +++ b/docs/gst/tmpl/gstcaps.sgml @@ -12,7 +12,7 @@ a mime-type and a set of properties. - +#GstProps, #GstPad diff --git a/docs/gst/tmpl/gstreamer-unused.sgml b/docs/gst/tmpl/gstreamer-unused.sgml index 5fa58aa49d..29a890b92d 100644 --- a/docs/gst/tmpl/gstreamer-unused.sgml +++ b/docs/gst/tmpl/gstreamer-unused.sgml @@ -67,14 +67,6 @@ Query the element for the current mime type - - - - - -@pad: -@parent: - @@ -83,6 +75,14 @@ Query the element for the current mime type @pad: @buf: + + + + + +@pad: +@parent: + Specify the location of the file. The location must be a fully qualified URL. @@ -97,13 +97,6 @@ Specify the location of the file. The location must be a fully qualified URL. @pad: @buf: - - - - - -@Returns: - @@ -112,6 +105,13 @@ Specify the location of the file. The location must be a fully qualified URL. @pad: @buf: + + + + + +@Returns: + @@ -206,12 +206,6 @@ the stream. @gstsrc: the object which received the signal. @arg1: the object which received the signal - - - - - - @@ -219,6 +213,12 @@ the stream. @Returns: + + + + + + @@ -372,16 +372,16 @@ subclass use this to start their flag enumeration @audiosink: @channels: - -Generic connection between elements. - - + +Generic connection between elements. + + @@ -661,13 +661,13 @@ Specify the current offset in the file. @sheight: @bytes_per_line: - + - + @@ -701,24 +701,17 @@ Specify the current offset in the file. @name: @Returns: - - - - - - - + -@src: @@ -728,6 +721,13 @@ Specify the current offset in the file. @id: @sink: + + + + + +@src: + @@ -1141,13 +1141,6 @@ GstFilter @obj: - - - - - -@obj: - @@ -1155,6 +1148,13 @@ GstFilter @Returns: + + + + + +@obj: + @@ -1163,13 +1163,6 @@ GstFilter @pad: @Returns: - - - - - -@thread: - @@ -1180,6 +1173,13 @@ GstFilter @y1: @y2: + + + + + +@thread: + Flags for the GstSrc element @@ -1255,13 +1255,6 @@ Defines an entry for a padfactory. @obj: - - - - - -@Returns: - @@ -1269,6 +1262,13 @@ Defines an entry for a padfactory. @klass: + + + + + +@Returns: + Indicates a sinkpad for the padfactory. @@ -1304,12 +1304,6 @@ Indicates a sinkpad for the padfactory. @pad: @Returns: - - - - - - @@ -1318,6 +1312,12 @@ Indicates a sinkpad for the padfactory. @name: @Returns: + + + + + + @@ -1427,6 +1427,12 @@ This macro sets the given flags. @flag: Flag to set, can by any number of bits in guint32. @obj: GstSrc to set flag in. + + + + + + @@ -1434,12 +1440,6 @@ This macro sets the given flags. @a: - - - - - - @@ -1461,16 +1461,16 @@ This macro sets the given flags. - -GstSink - - A flag indicating that MMX instructions are supported. + +GstSink + + @@ -1784,13 +1784,6 @@ or a video card. - - - - - -@obj: - @@ -1798,6 +1791,13 @@ or a video card. @Returns: + + + + + +@obj: + @@ -1818,12 +1818,6 @@ Query whether this object has multiple input pads. @obj: Element to query for multiple input pads. - - - - - - @@ -1832,6 +1826,12 @@ Query whether this object has multiple input pads. @format: @args...: + + + + + + @@ -2249,13 +2249,6 @@ this in the factory definition. @audiosink: - - - - - -@obj: - 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. + + + + + +@obj: + @@ -2336,6 +2336,13 @@ The number of bytes per read. @obj: + + + + + +@Returns: + @@ -2346,13 +2353,6 @@ The number of bytes per read. @format: @args...: - - - - - -@Returns: - @@ -2457,17 +2457,6 @@ This macro sets the given state on the element. @obj: - -Information about video buffers. - - - - - - - -@Returns: - @@ -2477,6 +2466,17 @@ Information about video buffers. @offset: @size: + + + + + +@Returns: + + +Information about video buffers. + + @@ -2579,13 +2579,13 @@ A flag indicating that SSE instructions are supported. @obj: - + - + @@ -2666,12 +2666,6 @@ Information about audio buffers. - - - - - - @@ -2680,6 +2674,12 @@ Information about audio buffers. @factory: @Returns: + + + + + + Specify the location of the file to read. @@ -2743,6 +2743,13 @@ the offset. + + + + + +@obj: + @@ -2751,13 +2758,6 @@ the offset. @name: @Returns: - - - - - -@obj: - Get the current number of bytes read. @@ -2806,13 +2806,6 @@ plugin @klass: - - - - - -@klass: - @@ -2820,6 +2813,13 @@ plugin @obj: + + + + + +@klass: + Indicates this pad is active