mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-06-27 02:10:41 +00:00
Code Issues 1 Projects Releases Wiki Activity

Improve GstBuffer documentation. It's now 100% Spiffier.

Browse source 
Original commit message from CVS:
Improve GstBuffer documentation. It's now 100% Spiffier.
This commit is contained in:
Michael Smith 2005-10-28 17:01:14 +00:00
parent 201e8082ad
commit f6021bd73c
3 changed files with 123 additions and 95 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

86
gst/gstbuffer.c
View file

@ -29,7 +29,7 @@
* 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
@ -61,6 +61,20 @@
* 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
@ -75,7 +89,7 @@
*
* 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()
@ -84,10 +98,11 @@
* 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"
@ -228,9 +243,8 @@ gst_buffer_init (GTypeInstance * instance, gpointer g_class)
*
* Creates a newly allocated buffer without any data.
*
* Returns: the new #GstBuffer.
*
* MT safe.
* Returns: the new #GstBuffer.
*/
GstBuffer *
gst_buffer_new (void)
@ -250,9 +264,8 @@ 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)
@ -272,14 +285,13 @@ 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. */
@ -300,10 +312,10 @@ gst_buffer_get_caps (GstBuffer * buffer)
/**
* 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.
*/
@ -319,7 +331,6 @@ gst_buffer_set_caps (GstBuffer * buffer, GstCaps * caps)
gst_caps_replace (&GST_BUFFER_CAPS (buffer), caps);
}
typedef struct _GstSubBuffer GstSubBuffer;
typedef struct _GstSubBufferClass GstSubBufferClass;
@ -398,19 +409,20 @@ gst_subbuffer_init (GTypeInstance * instance, gpointer g_class)
/**
* 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)
@ -462,16 +474,16 @@ 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.
*
* Returns: TRUE if the buffers are contiguous,
* FALSE if a copy would be required.
* 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.
*/
gboolean
gst_buffer_is_span_fast (GstBuffer * buf1, GstBuffer * buf2)
@ -489,7 +501,7 @@ 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.
@ -505,9 +517,9 @@ gst_buffer_is_span_fast (GstBuffer * buf1, GstBuffer * buf2)
* 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,
@ -516,8 +528,8 @@ 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);

116
gst/gstbuffer.h
View file

@ -50,30 +50,30 @@ typedef struct _GstBufferClass GstBufferClass;
/**
* 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.
@ -82,60 +82,63 @@ typedef struct _GstBufferClass GstBufferClass;
/**
* 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)
@ -148,28 +151,28 @@ typedef struct _GstBufferClass GstBufferClass;
/**
* 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.
*/
@ -185,19 +188,18 @@ typedef struct _GstBufferClass GstBufferClass;
* @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;
@ -245,11 +247,16 @@ GstBuffer* gst_buffer_new_and_alloc (guint size);
/**
* 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 { \
@ -260,50 +267,59 @@ 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.
*
* Replaces the data in @obuf with the one in @nbuf
* 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).
*
* 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))

16
gst/gstutils.c
View file

@ -2147,7 +2147,7 @@ gst_element_class_install_std_props (GstElementClass * klass,
/**
* 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
@ -2158,7 +2158,7 @@ gst_element_class_install_std_props (GstElementClass * klass,
* 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)
@ -2173,16 +2173,16 @@ 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)
@ -2202,8 +2202,8 @@ 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)