add flag, reorder GstBuffer docs

Original commit message from CVS:
add flag, reorder GstBuffer docs

diff --git a/ChangeLog b/ChangeLog
index 6dfa45a..d598c31 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,14 @@
+2004-08-12  Thomas Vander Stichele  <thomas at apestaart dot org>
+
+       * docs/gst/gstreamer-sections.txt:
+       * docs/gst/tmpl/gstbuffer.sgml:
+       * docs/gst/tmpl/gstschedulerfactory.sgml:
+         reorder docs a little, make GstBuffer's more sensible.
+       * gst/gstbuffer.h:
+         API: added GST_BUFFER_FLAG_DELTA_UNIT
+       * gst/gstscheduler.c:
+         comment API addition
+
 2004-08-12  Benjamin Otte  <in7y118@public.uni-hamburg.de>
 
        * gst/elements/gstfilesrc.c: (gst_filesrc_get_mmap):
@@ -32,6 +43,7 @@
        * docs/gst/gstreamer-sections.txt:
        * gst/gstscheduler.c: (gst_scheduler_register):
        * gst/gstscheduler.h:
+         API:
          add gst_scheduler_register shortcut similar to gst_element_register
        * gst/schedulers/entryscheduler.c: (plugin_init):
        * gst/schedulers/gstbasicscheduler.c: (plugin_init):
@@ -68,7 +80,7 @@
        * win32/gst-register.vcproj:
        * win32/gstspider.vcproj:
          update the include and lib dirs to fit standard libraries as
-      described in the Win32 manual
+         described in the Win32 manual
 
 2004-08-09  Steve Lhomme  <steve.lhomme@free.fr>
 
@@ -412,7 +424,7 @@
        * win32/config.h:
        * win32/README.txt:
        * docs/manual/win32.xml:
-       Fixed the plugin and GSTreamer location
+       Fixed the plugin and GStreamer location
 
 2004-07-24  Steve Lhomme  <steve.lhomme@free.fr>
 
@@ -512,7 +524,9 @@
        * testsuite/states/.cvsignore:
        * testsuite/threads/.cvsignore:
          keep this up to date, since I seem to be the only one who cares
-         about not missing files on commits
+         about not missing files on commits (editor's note: no you don't,
+         but feel free to change them at the time you add stuff instead
+         of later on)
 
 2004-07-21  Benjamin Otte  <otte@gnome.org>
 

diff --git a/docs/gst/gstreamer-sections.txt b/docs/gst/gstreamer-sections.txt
index 2b7b67f..98fe204 100644 (file)
--- a/docs/gst/gstreamer-sections.txt
+++ b/docs/gst/gstreamer-sections.txt
@@ -73,16 +73,16 @@ gst_bin_get_type
 <FILE>gstbuffer</FILE>
 <TITLE>GstBuffer</TITLE>
 GstBuffer
-GstBufferFreeDataFunc
-GST_BUFFER_TRACE_NAME
-GST_BUFFER_REFCOUNT
-GST_BUFFER_REFCOUNT_VALUE
-GST_BUFFER_COPY_FUNC
-GST_BUFFER_FREE_FUNC
+gst_buffer_new
+gst_buffer_new_and_alloc
+
+GstBufferFlag
 GST_BUFFER_FLAGS
 GST_BUFFER_FLAG_IS_SET
 GST_BUFFER_FLAG_SET
 GST_BUFFER_FLAG_UNSET
+
+gst_buffer_set_data
 GST_BUFFER_DATA
 GST_BUFFER_SIZE
 GST_BUFFER_MAXSIZE
@@ -90,19 +90,7 @@ GST_BUFFER_TIMESTAMP
 GST_BUFFER_DURATION
 GST_BUFFER_OFFSET
 GST_BUFFER_OFFSET_END
-GST_BUFFER_FREE_DATA_FUNC
-GST_BUFFER_PRIVATE
-GST_BUFFER_OFFSET_NONE
-GST_BUFFER_MAXSIZE_NONE
-GST_BUFFER_DURATION_IS_VALID
-GST_BUFFER_TIMESTAMP_IS_VALID
-GST_BUFFER_OFFSET_IS_VALID
-GST_BUFFER_OFFSET_END_IS_VALID
-GST_BUFFER_MAXSIZE_IS_VALID
-GstBufferFlag
-gst_buffer_new
-gst_buffer_new_and_alloc
-gst_buffer_set_data
+
 gst_buffer_ref
 gst_buffer_ref_by_count
 gst_buffer_unref
@@ -113,10 +101,27 @@ gst_buffer_copy_on_write
 gst_buffer_create_sub
 gst_buffer_join
 gst_buffer_merge
-gst_buffer_is_span_fast
 gst_buffer_span
+gst_buffer_is_span_fast
 gst_buffer_default_free
 gst_buffer_default_copy
+
+GST_BUFFER_TRACE_NAME
+GST_BUFFER_REFCOUNT
+GST_BUFFER_REFCOUNT_VALUE
+GST_BUFFER_COPY_FUNC
+GST_BUFFER_FREE_FUNC
+GST_BUFFER_FREE_DATA_FUNC
+GstBufferFreeDataFunc
+GST_BUFFER_PRIVATE
+GST_BUFFER_OFFSET_NONE
+GST_BUFFER_MAXSIZE_NONE
+GST_BUFFER_DURATION_IS_VALID
+GST_BUFFER_TIMESTAMP_IS_VALID
+GST_BUFFER_OFFSET_IS_VALID
+GST_BUFFER_OFFSET_END_IS_VALID
+GST_BUFFER_MAXSIZE_IS_VALID
+
 <SUBSECTION Standard>
 GST_BUFFER
 GST_IS_BUFFER

diff --git a/docs/gst/tmpl/gstbuffer.sgml b/docs/gst/tmpl/gstbuffer.sgml
index 3424556..a528bb1 100644 (file)
--- a/docs/gst/tmpl/gstbuffer.sgml
+++ b/docs/gst/tmpl/gstbuffer.sgml
@@ -36,8 +36,12 @@ video frame with a given width, height and bits per plane.
 </para>
 <para>
 Alternatively, use gst_buffer_new_and_alloc() 
-to create a buffer with preallocated
-data of a given size.
+to create a buffer with preallocated data of a given size.
+</para>
+<para>
+If an element knows what pad you will push the buffer out on, it should use
+gst_pad_alloc_buffer() instead to create a buffer.  This allows downstream
+elements to provide special buffers to write in, like hardware buffers.
 </para>
 <para>
 gst_buffer_ref() is used to increase the refcount of a buffer. This must be
@@ -72,7 +76,7 @@ regardless of the refcount, which is dangerous.
 </para>
 
 <para>
-Last reviewed on August 30th, 2002 (0.4.0.1)
+Last reviewed on August 12th, 2004 (0.8.5)
 </para>
 
 <!-- ##### SECTION See_Also ##### -->
@@ -97,52 +101,37 @@ The basic structure of a buffer.
 @buffer_private: 
 @_gst_reserved: 
 
-<!-- ##### USER_FUNCTION GstBufferFreeDataFunc ##### -->
+<!-- ##### FUNCTION gst_buffer_new ##### -->
 <para>
 
 </para>
 
-@buffer: 
+@Returns: 
 
 
-<!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
+<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
 <para>
-The name used for tracing memory allocations
-</para>
-
-
 
-<!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
-<para>
-Gets a handle to the refcount structure of the buffer.
 </para>
 
-@buf: a #GstBuffer to get the refcount structure of.
-
-
-<!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
-<para>
-Gets the current refcount value of the buffer.
-</para>
-
-@buf: a #GstBuffer to get the refcount value of.
+@size: 
+@Returns: 
 
 
-<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
+<!-- ##### ENUM GstBufferFlag ##### -->
 <para>
-Calls the buffer-specific copy function on the given buffer.
-</para>
-
-@buf: a #GstBuffer to copy.
-
 
-<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
-<para>
-Calls the buffer-specific free function on the given buffer.
 </para>
 
-@buf: a #GstBuffer to free.
-
+@GST_BUFFER_READONLY: 
+@GST_BUFFER_SUBBUFFER: 
+@GST_BUFFER_ORIGINAL: 
+@GST_BUFFER_DONTFREE: 
+@GST_BUFFER_KEY_UNIT: 
+@GST_BUFFER_DONTKEEP: 
+@GST_BUFFER_IN_CAPS: 
+@GST_BUFFER_DELTA_UNIT: 
+@GST_BUFFER_FLAG_LAST: 
 
 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
 <para>
@@ -179,6 +168,16 @@ Clears a buffer flag.
 @flag: the #GstBufferFlag to clear.
 
 
+<!-- ##### MACRO gst_buffer_set_data ##### -->
+<para>
+A convenience function to set the data and size on a buffer
+</para>
+
+@buf: The buffer to modify
+@data: The data to set on the buffer
+@size: The size to set on the buffer
+
+
 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
 <para>
 Retrieves a pointer to the data element of this buffer.
@@ -236,165 +235,180 @@ Gets the offset in the source file of this buffer.
 @buf: 
 
 
-<!-- ##### MACRO GST_BUFFER_FREE_DATA_FUNC ##### -->
+<!-- ##### MACRO gst_buffer_ref ##### -->
 <para>
-
+Increases the refcount of the given buffer by one.
 </para>
 
-@buf: 
+@buf: a #GstBuffer to increase the refcount of.
 
 
-<!-- ##### MACRO GST_BUFFER_PRIVATE ##### -->
+<!-- ##### MACRO gst_buffer_ref_by_count ##### -->
 <para>
-
+Increases the refcount of the buffer by the given value. 
 </para>
 
-@buf: 
+@buf: a #GstBuffer to increase the refcount of.
+@c: the value to add to the refcount.
 
 
-<!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
+<!-- ##### MACRO gst_buffer_unref ##### -->
 <para>
-
+Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
+will be freed.
 </para>
 
+@buf: a #GstBuffer to unref.
 
 
-<!-- ##### MACRO GST_BUFFER_MAXSIZE_NONE ##### -->
+<!-- ##### FUNCTION gst_buffer_stamp ##### -->
 <para>
 
 </para>
 
+@dest: 
+@src: 
 
 
-<!-- ##### MACRO GST_BUFFER_DURATION_IS_VALID ##### -->
+<!-- ##### MACRO gst_buffer_copy ##### -->
 <para>
-
+Copies the given buffer using the copy function of the parent GstData structure.
 </para>
 
-@buffer: 
+@buf: a #GstBuffer to copy.
+@Returns: a new #GstBuffer copy of the buffer.
 
 
-<!-- ##### MACRO GST_BUFFER_TIMESTAMP_IS_VALID ##### -->
+<!-- ##### MACRO gst_buffer_is_writable ##### -->
 <para>
 
 </para>
 
-@buffer: 
+@buf: 
 
 
-<!-- ##### MACRO GST_BUFFER_OFFSET_IS_VALID ##### -->
+<!-- ##### MACRO gst_buffer_copy_on_write ##### -->
 <para>
-
+This function returns a buffer that is safe to write to.
+Copy the buffer if the refcount > 1 so that the newly 
+created buffer can be safely written to. 
+If the refcount is 1, this function just returns the original buffer.
 </para>
 
-@buffer: 
+@buf: a #GstBuffer to copy
+@Returns: the #GstBuffer that can safely be written to.
 
 
-<!-- ##### MACRO GST_BUFFER_OFFSET_END_IS_VALID ##### -->
+<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 <para>
 
 </para>
 
-@buffer: 
+@parent: 
+@offset: 
+@size: 
+@Returns: 
 
 
-<!-- ##### MACRO GST_BUFFER_MAXSIZE_IS_VALID ##### -->
+<!-- ##### FUNCTION gst_buffer_join ##### -->
 <para>
 
 </para>
 
-@buffer: 
+@buf1: 
+@buf2: 
+@Returns: 
 
 
-<!-- ##### ENUM GstBufferFlag ##### -->
+<!-- ##### FUNCTION gst_buffer_merge ##### -->
 <para>
-A set of buffer flags used to describe properties of a #GstBuffer.
+
 </para>
 
-@GST_BUFFER_READONLY: the buffer is read-only.
-@GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be 
-                       found with the GST_BUFFER_POOL_PRIVATE() macro.
-@GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
-@GST_BUFFER_DONTFREE: do not try to free the data when this buffer is 
-                      unreferenced.
-@GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be 
-                      decoded independently of other buffers.
-@GST_BUFFER_DONTKEEP: 
-@GST_BUFFER_IN_CAPS: the buffer has been added as a field in a #GstCaps.
-@GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
+@buf1: 
+@buf2: 
+@Returns: 
 
-<!-- ##### FUNCTION gst_buffer_new ##### -->
+
+<!-- ##### FUNCTION gst_buffer_span ##### -->
 <para>
 
 </para>
 
+@buf1: 
+@offset: 
+@buf2: 
+@len: 
 @Returns: 
 
 
-<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
+<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 <para>
 
 </para>
 
-@size: 
+@buf1: 
+@buf2: 
 @Returns: 
 
 
-<!-- ##### MACRO gst_buffer_set_data ##### -->
+<!-- ##### FUNCTION gst_buffer_default_free ##### -->
 <para>
-A convenience function to set the data and size on a buffer
+
 </para>
 
-@buf: The buffer to modify
-@data: The data to set on the buffer
-@size: The size to set on the buffer
+@buffer: 
 
 
-<!-- ##### MACRO gst_buffer_ref ##### -->
+<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
 <para>
-Increases the refcount of the given buffer by one.
+
 </para>
 
-@buf: a #GstBuffer to increase the refcount of.
+@buffer: 
+@Returns: 
 
 
-<!-- ##### MACRO gst_buffer_ref_by_count ##### -->
+<!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
 <para>
-Increases the refcount of the buffer by the given value. 
+The name used for tracing memory allocations
 </para>
 
-@buf: a #GstBuffer to increase the refcount of.
-@c: the value to add to the refcount.
 
 
-<!-- ##### MACRO gst_buffer_unref ##### -->
+<!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
 <para>
-Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
-will be freed.
+Gets a handle to the refcount structure of the buffer.
 </para>
 
-@buf: a #GstBuffer to unref.
+@buf: a #GstBuffer to get the refcount structure of.
 
 
-<!-- ##### FUNCTION gst_buffer_stamp ##### -->
+<!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
 <para>
-
+Gets the current refcount value of the buffer.
 </para>
 
-@dest: 
-@src: 
+@buf: a #GstBuffer to get the refcount value of.
 
 
-<!-- ##### MACRO gst_buffer_copy ##### -->
+<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
 <para>
-Copies the given buffer using the copy function of the parent GstData structure.
+Calls the buffer-specific copy function on the given buffer.
 </para>
 
 @buf: a #GstBuffer to copy.
-@Returns: a new #GstBuffer copy of the buffer.
 
 
-<!-- ##### MACRO gst_buffer_is_writable ##### -->
+<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
+<para>
+Calls the buffer-specific free function on the given buffer.
+</para>
+
+@buf: a #GstBuffer to free.
+
+
+<!-- ##### MACRO GST_BUFFER_FREE_DATA_FUNC ##### -->
 <para>
 
 </para>
@@ -402,72 +416,53 @@ Copies the given buffer using the copy function of the parent GstData structure.
 @buf: 
 
 
-<!-- ##### MACRO gst_buffer_copy_on_write ##### -->
+<!-- ##### USER_FUNCTION GstBufferFreeDataFunc ##### -->
 <para>
-This function returns a buffer that is safe to write to.
-Copy the buffer if the refcount > 1 so that the newly 
-created buffer can be safely written to. 
-If the refcount is 1, this function just returns the original buffer.
+
 </para>
 
-@buf: a #GstBuffer to copy
-@Returns: the #GstBuffer that can safely be written to.
+@buffer: 
 
 
-<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
+<!-- ##### MACRO GST_BUFFER_PRIVATE ##### -->
 <para>
 
 </para>
 
-@parent: 
-@offset: 
-@size: 
-@Returns: 
+@buf: 
 
 
-<!-- ##### FUNCTION gst_buffer_join ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
 <para>
 
 </para>
 
-@buf1: 
-@buf2: 
-@Returns: 
 
 
-<!-- ##### FUNCTION gst_buffer_merge ##### -->
+<!-- ##### MACRO GST_BUFFER_MAXSIZE_NONE ##### -->
 <para>
 
 </para>
 
-@buf1: 
-@buf2: 
-@Returns: 
 
 
-<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
+<!-- ##### MACRO GST_BUFFER_DURATION_IS_VALID ##### -->
 <para>
 
 </para>
 
-@buf1: 
-@buf2: 
-@Returns: 
+@buffer: 
 
 
-<!-- ##### FUNCTION gst_buffer_span ##### -->
+<!-- ##### MACRO GST_BUFFER_TIMESTAMP_IS_VALID ##### -->
 <para>
 
 </para>
 
-@buf1: 
-@offset: 
-@buf2: 
-@len: 
-@Returns: 
+@buffer: 
 
 
-<!-- ##### FUNCTION gst_buffer_default_free ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_IS_VALID ##### -->
 <para>
 
 </para>
@@ -475,12 +470,19 @@ If the refcount is 1, this function just returns the original buffer.
 @buffer: 
 
 
-<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
+<!-- ##### MACRO GST_BUFFER_OFFSET_END_IS_VALID ##### -->
+<para>
+
+</para>
+
+@buffer: 
+
+
+<!-- ##### MACRO GST_BUFFER_MAXSIZE_IS_VALID ##### -->
 <para>
 
 </para>
 
 @buffer: 
-@Returns: 
 
 

diff --git a/docs/gst/tmpl/gstschedulerfactory.sgml b/docs/gst/tmpl/gstschedulerfactory.sgml
index 592d227..ebc48da 100644 (file)
--- a/docs/gst/tmpl/gstschedulerfactory.sgml
+++ b/docs/gst/tmpl/gstschedulerfactory.sgml
@@ -44,6 +44,18 @@ Use gst_scheduler_factory_destroy() to remove the factory from the global list.
 
 
 
+<!-- ##### FUNCTION gst_scheduler_register ##### -->
+<para>
+
+</para>
+
+@plugin: 
+@name: 
+@longdesc: 
+@type: 
+@Returns: 
+
+
 <!-- ##### FUNCTION gst_scheduler_factory_new ##### -->
 <para>
 

diff --git a/gst/gstbuffer.h b/gst/gstbuffer.h
index f61a232..b23e5b7 100644 (file)
--- a/gst/gstbuffer.h
+++ b/gst/gstbuffer.h
@@ -73,14 +73,34 @@ extern GType _gst_buffer_type;
 #define GST_BUFFER_OFFSET_END_IS_VALID(buffer) (GST_BUFFER_OFFSET_END (buffer) != GST_BUFFER_OFFSET_NONE)
 #define GST_BUFFER_MAXSIZE_IS_VALID(buffer)    (GST_BUFFER_MAXSIZE (buffer) != GST_BUFFER_MAXSIZE_NONE)
 
+/**
+ * GstBufferFlag:
+ * @GST_BUFFER_READONLY: the buffer is read-only.
+ * @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
+ * found with the GST_BUFFER_POOL_PRIVATE() macro.
+ * @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
+ * @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
+ * unreferenced.
+ * @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
+ * decoded independently of other buffers.
+ * This flag has been deprecated, see #GST_BUFFER_DELTA_UNIT.
+ * @GST_BUFFER_DONTKEEP:
+ * @GST_BUFFER_IN_CAPS: the buffer has been added as a field in a #GstCaps.
+ * @GST_BUFFER_DELTA_UNIT: this unit cannot be decoded independently.
+ * Since 0.8.5
+ * @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
+ *
+ * A set of buffer flags used to describe properties of a #GstBuffer.
+ */
 typedef enum {
   GST_BUFFER_READONLY   = GST_DATA_READONLY,
   GST_BUFFER_SUBBUFFER  = GST_DATA_FLAG_LAST,
   GST_BUFFER_ORIGINAL,
   GST_BUFFER_DONTFREE,
-  GST_BUFFER_KEY_UNIT,         /* sync point in the stream */
+  GST_BUFFER_KEY_UNIT,         /* deprecated, use reverse DELTA_UNIT */
   GST_BUFFER_DONTKEEP,
   GST_BUFFER_IN_CAPS,
+  GST_BUFFER_DELTA_UNIT,       /* this unit depends on a previous unit */
   GST_BUFFER_FLAG_LAST = GST_DATA_FLAG_LAST + 8
 } GstBufferFlag;
 

diff --git a/gst/gstscheduler.c b/gst/gstscheduler.c
index 6ea86d5..1615ada 100644 (file)
--- a/gst/gstscheduler.c
+++ b/gst/gstscheduler.c
@@ -802,7 +802,9 @@ gst_scheduler_factory_init (GstSchedulerFactory * factory)
  *
  * Registers a scheduler with GStreamer.
  *
- * Returns: TRUE, if the registering succeeded, FALSE on error
+ * Returns: TRUE, if the registering succeeded, FALSE on error.
+ *
+ * Since: 0.8.5
  **/
 gboolean
 gst_scheduler_register (GstPlugin * plugin, const gchar * name,