/**
* SECTION:gstbuffer
* @short_description: Data-passing buffer type, supporting sub-buffers.
- * @see_also: #GstPad, #GstMiniObject
+ * @see_also: #GstPad, #GstMiniObject, #GstBufferPool
*
* Buffers are the basic unit of data transfer in GStreamer. The #GstBuffer
* type provides all the state necessary to define the regions of memory as
* ensure that neither memory space goes away prematurely.
*
* 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. The following example creates a buffer that can hold a given
- * video frame with a given width, height and bits per plane.
+ * created one will typically allocate memory for it and add it to the buffer.
+ * The following example creates a buffer that can hold a given video frame
+ * with a given width, height and bits per plane.
* <example>
* <title>Creating a buffer for a video frame</title>
* <programlisting>
* GstBuffer *buffer;
+ * GstMemory *memory;
* gint size, width, height, bpp;
* ...
* size = width * height * bpp;
* buffer = gst_buffer_new ();
- * GST_BUFFER_SIZE (buffer) = size;
- * GST_BUFFER_MALLOCDATA (buffer) = g_malloc (size);
- * GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
+ * memory = gst_allocator_alloc (NULL, size, 0);
+ * gst_buffer_take_memory (buffer, -1, memory);
* ...
* </programlisting>
* </example>
*
- * Alternatively, use gst_buffer_new_and_alloc()
+ * Alternatively, use gst_buffer_new_allocate()
* to create a buffer with preallocated data of a given size.
*
- * The data pointed to by the buffer can be retrieved with the GST_BUFFER_DATA()
- * macro. The size of the data can be found with GST_BUFFER_SIZE(). For buffers
- * of size 0, the data pointer is undefined (usually NULL) and should never be used.
- *
- * 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.
- *
- * A buffer has a pointer to a #GstCaps describing the media type of the data
- * in the buffer. Attach caps to the buffer with gst_buffer_set_caps(); this
- * is typically done before pushing out a buffer using gst_pad_push() so that
- * the downstream element knows the type of the buffer.
+ * Buffers can contain a list of #GstMemory objects. You can retrieve how many
+ * memory objects with gst_buffer_n_memory() and you can get a pointer
+ * to memory with gst_buffer_peek_memory()
*
* A buffer will usually have timestamps, and a duration, but neither of these
* are guaranteed (they may be set to #GST_CLOCK_TIME_NONE). Whenever a
* the refcount drops to 0, any data pointed to by the buffer is unreffed as
* well.
*
- * Last reviewed on March 30, 2011 (0.11.0)
+ * Last reviewed on November 8, 2011 (0.11.2)
*/
#include "gst_private.h"