* provides all the state necessary to define a region of memory as part of a
* stream. Sub-buffers are also supported, allowing a smaller region of a
* buffer to become its own buffer, with mechanisms in place to ensure that
- * neither memory space goes away.
+ * 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
* 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.
+ *
+ * A buffer will usually have a timestamp, and a duration, but neither of these
+ * are guaranteed (they may be set to GST_CLOCK_TIME_NONE). Whenever a
+ * meaningful value can be given for these, they should be set. The timestamp
+ * and duration are measured in nanoseconds (they are #GstClockTime values).
+ *
+ * A buffer can also have one or both of a start and an end offset. These are
+ * media-type specific. For video buffers, the start offset will generally be
+ * the frame number. For audio buffers, it will be the number of samples
+ * produced so far. For compressed data, it could be the byte offset in a
+ * source or destination file. Likewise, the end offset will be the offset of
+ * the end of the buffer. These can only be meaningfully interpreted if you
+ * know the media type of the buffer (the #GstCaps set on it). Either or both
+ * can be set to GST_BUFFER_OFFSET_NONE.
*
* 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
*
* 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 #GstBufferFlag is set.
+ * GST_BUFFER_FLAG_IS_SET() to test if a certain #GstBufferFlag is set.
*
* Buffers can be efficiently merged into a larger buffer with
* gst_buffer_merge() and gst_buffer_span() if the gst_buffer_is_span_fast()
* An element should either unref the buffer or push it out on a src pad
* using gst_pad_push() (see #GstPad).
*
- * Buffers usually are freed by unreffing them with gst_buffer_unref(). When
- * the refcount drops to 0, the buffer memory will be freed again.
+ * Buffers are usually freed by unreffing them with gst_buffer_unref(). When
+ * the refcount drops to 0, any data pointed to by GST_BUFFER_MALLOCDATA() will
+ * also be freed.
*
- * Last reviewed on September 24th, 2005 (0.9.0)
+ * Last reviewed on October 28th, 2005 (0.9.4)
*/
#include "gst_private.h"
*
* Creates a newly allocated buffer without any data.
*
- * Returns: the new #GstBuffer.
- *
* MT safe.
+ * Returns: the new #GstBuffer.
*/
GstBuffer *
gst_buffer_new (void)
*
* Creates a newly allocated buffer with data of the given size.
*
- * Returns: the new #GstBuffer.
- *
* MT safe.
+ * Returns: the new #GstBuffer.
*/
GstBuffer *
gst_buffer_new_and_alloc (guint size)
/**
* gst_buffer_get_caps:
- * @buffer: a #GstBuffer to get the caps of.
+ * @buffer: a #GstBuffer.
*
* Gets the media type of the buffer. This can be NULL if there
- * is not media type attached to this buffer or when the media
- * type is the same as the previous received buffer.
+ * is no media type attached to this buffer.
*
- * Returns: a reference to the #GstCaps, or NULL if there were no caps on this
- * buffer.
+ * Returns: a reference to the #GstCaps.
+ * Returns NULL if there were no caps on this buffer.
*/
/* FIXME can we make this threadsafe without a lock on the buffer?
* We can use compare and swap and atomic reads. */
/**
* gst_buffer_set_caps:
- * @buffer: a #GstBuffer to set the caps of.
- * @caps: a #GstCaps to set.
+ * @buffer: a #GstBuffer.
+ * @caps: a #GstCaps.
*
- * Sets the media type on the buffer. The caps' refcount will
+ * Sets the media type on the buffer. The refcount of the caps will
* be increased and any previous caps on the buffer will be
* unreffed.
*/
gst_caps_replace (&GST_BUFFER_CAPS (buffer), caps);
}
-
typedef struct _GstSubBuffer GstSubBuffer;
typedef struct _GstSubBufferClass GstSubBufferClass;
/**
* gst_buffer_create_sub:
- * @parent: a parent #GstBuffer to create a subbuffer from.
- * @offset: the offset into parent #GstBuffer.
- * @size: the size of the new #GstBuffer sub-buffer (with size > 0).
+ * @parent: a #GstBuffer.
+ * @offset: the offset into parent #GstBuffer at which the new sub-buffer
+ * begins.
+ * @size: the size of the new #GstBuffer sub-buffer, in bytes (with size > 0).
*
* Creates a sub-buffer from the parent at a given offset.
* This sub-buffer uses the actual memory space of the parent buffer.
- * This function will copy the offset and timestamp field when the
- * offset is 0, else they are set to _NONE.
- * The duration field of the new buffer are set to GST_CLOCK_TIME_NONE.
- *
- * Returns: the new #GstBuffer, or NULL if there was an error.
+ * This function will copy the offset and timestamp fields when the
+ * offset is 0, else they are set to GST_CLOCK_TIME_NONE/GST_BUFFER_OFFSET_NONE.
+ * The duration field of the new buffer is set to GST_CLOCK_TIME_NONE.
*
* MT safe.
+ * Returns: the new #GstBuffer.
+ * Returns NULL if the arguments were invalid.
*/
GstBuffer *
gst_buffer_create_sub (GstBuffer * buffer, guint offset, guint size)
/**
* gst_buffer_is_span_fast:
- * @buf1: a first source #GstBuffer.
- * @buf2: the second source #GstBuffer.
+ * @buf1: the first #GstBuffer.
+ * @buf2: the second #GstBuffer.
*
* Determines whether a gst_buffer_span() can be done without copying
- * the contents, that is, whether the data areas are contiguous.
+ * the contents, that is, whether the data areas are contiguous sub-buffers of
+ * the same buffer.
*
+ * MT safe.
* Returns: TRUE if the buffers are contiguous,
* FALSE if a copy would be required.
- *
- * MT safe.
*/
gboolean
gst_buffer_is_span_fast (GstBuffer * buf1, GstBuffer * buf2)
/**
* gst_buffer_span:
- * @buf1: a first source #GstBuffer to merge.
+ * @buf1: the first source #GstBuffer to merge.
* @offset: the offset in the first buffer from where the new
* buffer should start.
* @buf2: the second source #GstBuffer to merge.
* parent, and thus no copying is necessary. you can use
* gst_buffer_is_span_fast() to determine if a memcpy will be needed.
*
- * Returns: the new #GstBuffer that spans the two source buffers.
- *
* MT safe.
+ * Returns: the new #GstBuffer that spans the two source buffers.
+ * Returns NULL if the arguments are invalid.
*/
GstBuffer *
gst_buffer_span (GstBuffer * buf1, guint32 offset, GstBuffer * buf2,
GstBuffer *newbuf;
g_return_val_if_fail (buf1 != NULL && buf2 != NULL, NULL);
- g_return_val_if_fail (buf1->mini_object.refcount > 0, FALSE);
- g_return_val_if_fail (buf2->mini_object.refcount > 0, FALSE);
+ g_return_val_if_fail (buf1->mini_object.refcount > 0, NULL);
+ g_return_val_if_fail (buf2->mini_object.refcount > 0, NULL);
g_return_val_if_fail (len > 0, NULL);
g_return_val_if_fail (len <= buf1->size + buf2->size - offset, NULL);
/**
* GST_BUFFER_FLAGS:
- * @buf: a #GstBuffer to retrieve the flags from.
+ * @buf: a #GstBuffer.
*
- * Gets the #GstBufferFlag flags from this buffer.
+ * A flags word containing #GstBufferFlag flags set on this buffer.
*/
#define GST_BUFFER_FLAGS(buf) GST_MINI_OBJECT_FLAGS(buf)
/**
* GST_BUFFER_FLAG_IS_SET:
- * @buf: a #GstBuffer to query flags of.
+ * @buf: a #GstBuffer.
* @flag: the #GstBufferFlag to check.
*
- * Gives the status of a given flag of a buffer.
+ * Gives the status of a specific flag on a buffer.
*/
#define GST_BUFFER_FLAG_IS_SET(buf,flag) GST_MINI_OBJECT_FLAG_IS_SET (buf, flag)
/**
* GST_BUFFER_FLAG_SET:
- * @buf: a #GstBuffer to modify flags of.
+ * @buf: a #GstBuffer.
* @flag: the #GstBufferFlag to set.
*
- * Sets a buffer flag.
+ * Sets a buffer flag on a buffer.
*/
#define GST_BUFFER_FLAG_SET(buf,flag) GST_MINI_OBJECT_FLAG_SET (buf, flag)
/**
* GST_BUFFER_FLAG_UNSET:
- * @buf: a #GstBuffer to modify flags of.
+ * @buf: a #GstBuffer.
* @flag: the #GstBufferFlag to clear.
*
* Clears a buffer flag.
/**
* GST_BUFFER_DATA:
- * @buf: a #GstBuffer to get data pointer of.
+ * @buf: a #GstBuffer.
*
- * Retrieves a pointer to the data element of this buffer.
+ * A pointer to the data element of this buffer.
*/
#define GST_BUFFER_DATA(buf) (GST_BUFFER_CAST(buf)->data)
/**
* GST_BUFFER_SIZE:
- * @buf: a #GstBuffer to get data size of.
+ * @buf: a #GstBuffer.
*
- * Gets the size of the data in this buffer.
+ * The size in bytes of the data in this buffer.
*/
#define GST_BUFFER_SIZE(buf) (GST_BUFFER_CAST(buf)->size)
/**
* GST_BUFFER_TIMESTAMP:
- * @buf: a #GstBuffer to get the timestamp of.:
+ * @buf: a #GstBuffer.:
+ *
+ * The timestamp in nanoseconds (as a #GstClockTime) of the data in the buffer.
+ * Value will be %GST_CLOCK_TIME_NONE if the duration is unknown.
*
- * Gets the timestamp for this buffer.
*/
#define GST_BUFFER_TIMESTAMP(buf) (GST_BUFFER_CAST(buf)->timestamp)
/**
* GST_BUFFER_DURATION:
- * @buf: a #GstBuffer to get the duration from.
+ * @buf: a #GstBuffer.
*
- * Gets the duration in nanoseconds of the data in the buffer.
+ * The duration in nanoseconds (as a #GstClockTime) of the data in the buffer.
* Value will be %GST_CLOCK_TIME_NONE if the duration is unknown.
*/
#define GST_BUFFER_DURATION(buf) (GST_BUFFER_CAST(buf)->duration)
/**
* GST_BUFFER_CAPS:
- * @buf: a #GstBuffer to get the caps of.
+ * @buf: a #GstBuffer.
*
- * Gets the caps for this buffer.
+ * The caps for this buffer.
*/
#define GST_BUFFER_CAPS(buf) (GST_BUFFER_CAST(buf)->caps)
/**
* GST_BUFFER_OFFSET:
- * @buf: a #GstBuffer to get the offset of.
+ * @buf: a #GstBuffer.
*
- * Gets the offset in the source file of the beginning of this buffer.
+ * The offset in the source file of the beginning of this buffer.
*/
#define GST_BUFFER_OFFSET(buf) (GST_BUFFER_CAST(buf)->offset)
/**
* GST_BUFFER_OFFSET_END:
- * @buf: a #GstBuffer to get the offset of.
+ * @buf: a #GstBuffer.
*
- * Gets the offset in the source file of the end of this buffer.
+ * The offset in the source file of the end of this buffer.
*/
#define GST_BUFFER_OFFSET_END(buf) (GST_BUFFER_CAST(buf)->offset_end)
/**
* GST_BUFFER_MALLOCDATA:
- * @buf: a #GstBuffer to get access to the malloc_data field
+ * @buf: a #GstBuffer.
*
- * If the buffers data should be automatically freed by buffer management at the
- * end of the buffers lifecycle, also set the data to the mallocdata field.
+ * A pointer to any data allocated for this buffer using malloc(). If this is
+ * non-NULL, this memory will be freed at the end of the buffer's lifecycle
+ * (i.e. when its refcount becomes zero).
*/
#define GST_BUFFER_MALLOCDATA(buf) (GST_BUFFER_CAST(buf)->malloc_data)
/**
* GST_BUFFER_DURATION_IS_VALID:
- * @buffer: the #GstBuffer to check for the duration
+ * @buffer: a #GstBuffer
*
* Tests if the duration is known.
*/
#define GST_BUFFER_DURATION_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_DURATION (buffer)))
/**
* GST_BUFFER_TIMESTAMP_IS_VALID:
- * @buffer: the #GstBuffer to check for the timestamp
+ * @buffer: a #GstBuffer
*
* Tests if the timestamp is known.
*/
#define GST_BUFFER_TIMESTAMP_IS_VALID(buffer) (GST_CLOCK_TIME_IS_VALID (GST_BUFFER_TIMESTAMP (buffer)))
/**
* GST_BUFFER_OFFSET_IS_VALID:
- * @buffer: the #GstBuffer to check for the start offset
+ * @buffer: a #GstBuffer
*
* Tests if the start offset is known.
*/
#define GST_BUFFER_OFFSET_IS_VALID(buffer) (GST_BUFFER_OFFSET (buffer) != GST_BUFFER_OFFSET_NONE)
/**
* GST_BUFFER_OFFSET_END_IS_VALID:
- * @buffer: the #GstBuffer to check for the end offset
+ * @buffer: a #GstBuffer
*
* Tests if the end offset is known.
*/
* @GST_BUFFER_FLAG_IN_CAPS: the buffer has been added as a field in a #GstCaps.
* @GST_BUFFER_FLAG_GAP: the buffer has been created to fill a gap in the stream.
* @GST_BUFFER_FLAG_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_FLAG_READONLY = GST_MINI_OBJECT_FLAG_READONLY,
- GST_BUFFER_FLAG_ORIGINAL = (GST_MINI_OBJECT_FLAG_LAST << 0), /* original data, not copied, not currently used */
- GST_BUFFER_FLAG_PREROLL = (GST_MINI_OBJECT_FLAG_LAST << 1), /* sample should not be displayed */
- GST_BUFFER_FLAG_DISCONT = (GST_MINI_OBJECT_FLAG_LAST << 2), /* buffer is first after discontinuity in the stream */
- GST_BUFFER_FLAG_IN_CAPS = (GST_MINI_OBJECT_FLAG_LAST << 3), /* buffer is also part of caps */
- GST_BUFFER_FLAG_GAP = (GST_MINI_OBJECT_FLAG_LAST << 4), /* buffer has been created to fill a gap in the stream */
- GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 5), /* can't be used as sync point in stream */
+ GST_BUFFER_FLAG_ORIGINAL = (GST_MINI_OBJECT_FLAG_LAST << 0),
+ GST_BUFFER_FLAG_PREROLL = (GST_MINI_OBJECT_FLAG_LAST << 1),
+ GST_BUFFER_FLAG_DISCONT = (GST_MINI_OBJECT_FLAG_LAST << 2),
+ GST_BUFFER_FLAG_IN_CAPS = (GST_MINI_OBJECT_FLAG_LAST << 3),
+ GST_BUFFER_FLAG_GAP = (GST_MINI_OBJECT_FLAG_LAST << 4),
+ GST_BUFFER_FLAG_DELTA_UNIT = (GST_MINI_OBJECT_FLAG_LAST << 5),
/* padding */
GST_BUFFER_FLAG_LAST = (GST_MINI_OBJECT_FLAG_LAST << 8)
} GstBufferFlag;
/**
* gst_buffer_set_data:
- * @buf: The buffer to modify
- * @data: The data to set on the buffer
- * @size: The size to set on the buffer
+ * @buf: a #GstBuffer
+ * @data: The data (a #guint8 *) to set on the buffer.
+ * @size: The size (in bytes, as a #guint) of the data being set.
*
* A convenience function to set the data and size on a buffer.
+ * This will replace any existing data pointer set on this buffer, but will
+ * not change GST_BUFFER_MALLOCDATA(), if any. Callers should ensure that
+ * GST_BUFFER_MALLOCDATA() is non-NULL, or should free that and set it to NULL.
+ *
+ * No checks are done on the data or size arguments passed.
*/
#define gst_buffer_set_data(buf, data, size) \
G_STMT_START { \
/* refcounting */
/**
* gst_buffer_ref:
- * @buf: a #GstBuffer to increase the refcount of.
+ * @buf: a #GstBuffer.
*
* Increases the refcount of the given buffer by one.
*/
#define gst_buffer_ref(buf) GST_BUFFER_CAST (gst_mini_object_ref (GST_MINI_OBJECT (buf)))
/**
* gst_buffer_unref:
- * @buf: a #GstBuffer to decrease the refcount of.
+ * @buf: a #GstBuffer.
*
* Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
- * will be freed.
+ * will be freed. If GST_BUFFER_MALLOCDATA() is non-NULL, this pointer will
+ * also be freed at this time.
*/
#define gst_buffer_unref(buf) gst_mini_object_unref (GST_MINI_OBJECT (buf))
/* copy buffer */
/**
* gst_buffer_copy:
- * @buf: a #GstBuffer to copy.
+ * @buf: a #GstBuffer.
*
- * Copies the given buffer using the copy function of the parent #GstData
- * structure.
+ * Returns a copy of the given buffer. This will also make a newly allocated
+ * copy of the data the source buffer points at.
*/
#define gst_buffer_copy(buf) GST_BUFFER_CAST (gst_mini_object_copy (GST_MINI_OBJECT (buf)))
/**
* gst_buffer_is_writable:
- * @buf: a #GstBuffer to check
+ * @buf: a #GstBuffer
*
* Tests if you can safely write data into a buffer's data array.
*/
#define gst_buffer_is_writable(buf) gst_mini_object_is_writable (GST_MINI_OBJECT (buf))
/**
* gst_buffer_make_writable:
- * @buf: a #GstBuffer to make writable
+ * @buf: a #GstBuffer
*
- * Makes a writable buffer from the given buffer.
+ * Makes a writable buffer from the given buffer. If the source buffer is
+ * already writable, this will simply return the same buffer. A copy will
+ * otherwise be made using gst_buffer_copy().
*/
#define gst_buffer_make_writable(buf) GST_BUFFER_CAST (gst_mini_object_make_writable (GST_MINI_OBJECT (buf)))
/**
* gst_buffer_replace:
- * @obuf: a #GstBuffer to receive the data
- * @nbuf: a #GstBuffer to take the data from
+ * @obuf: pointer to a pointer to a #GstBuffer to be replaced.
+ * @nbuf: pointer to a #GstBuffer that will replace the buffer pointed to by
+ * @obuf.
+ *
+ * Modifies a pointer to a #Gstbuffer to point to a different #GstBuffer. The
+ * modification is done atomically (so this is useful for ensuring thread safety
+ * in some cases), and the reference counts are updated appropriately (the old
+ * buffer is unreffed, the new is reffed).
*
- * Replaces the data in @obuf with the one in @nbuf
+ * Either @nbuf or the #GstBuffer pointed to by @obuf may be NULL.
*/
#define gst_buffer_replace(obuf,nbuf) gst_mini_object_replace ((GstMiniObject **)(obuf), GST_MINI_OBJECT (nbuf))
/**
* gst_buffer_merge:
- * @buf1: a first source #GstBuffer to merge.
+ * @buf1: the first source #GstBuffer to merge.
* @buf2: the second source #GstBuffer to merge.
*
* Create a new buffer that is the concatenation of the two source
* If the buffers point to contiguous areas of memory, the buffer
* is created without copying the data.
*
- * Returns: the new #GstBuffer that's the concatenation of the source buffers.
+ * Returns: the new #GstBuffer which is the concatenation of the source buffers.
*/
GstBuffer *
gst_buffer_merge (GstBuffer * buf1, GstBuffer * buf2)
/**
* gst_buffer_join:
- * @buf1: a first source #GstBuffer to join.
- * @buf2: the second source #GstBuffer to join.
+ * @buf1: the first source #GstBuffer.
+ * @buf2: the second source #GstBuffer.
*
* Create a new buffer that is the concatenation of the two source
- * buffers, and takes ownership of the original source buffers.
+ * buffers, and unrefs the original source buffers.
*
* If the buffers point to contiguous areas of memory, the buffer
* is created without copying the data.
*
- * Returns: the new #GstBuffer that's the concatenation of the source buffers.
+ * Returns: the new #GstBuffer which is the concatenation of the source buffers.
*/
GstBuffer *
gst_buffer_join (GstBuffer * buf1, GstBuffer * buf2)
* @dest: buffer to stamp
* @src: buffer to stamp from
*
- * Copies additional information (timestamps and offsets) from one buffer to
- * the other.
+ * Copies additional information (the timestamp, duration, and offset start
+ * and end) from one buffer to the other.
*/
void
gst_buffer_stamp (GstBuffer * dest, const GstBuffer * src)
projects / platform / upstream / gstreamer.git / commitdiff