mirrors/gstreamer
mirrors/gstreamer
1
1
Fork 0
mirror of https://gitlab.freedesktop.org/gstreamer/gstreamer.git synced 2024-12-24 09:10:36 +00:00
Code Issues 1 Projects Releases Wiki Activity

doc updates

Browse source 
Original commit message from CVS:
doc updates
This commit is contained in:
Thomas Vander Stichele 2002-08-30 14:54:58 +00:00
parent f2a11148a8
commit 56c8649f39
2 changed files with 159 additions and 127 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

147
docs/gst/tmpl/gstbuffer.sgml
View file

@ -15,10 +15,13 @@ neither memory space goes away.
<para> <para>
Buffers are usually created with gst_buffer_new(). After a buffer has been 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 created one will typically allocate memory for it and set the size of the
buffer data. buffer data. The following example creates a buffer that can hold a given
video frame with a given width, height and bits per plane.
<programlisting> <programlisting>
GstBuffer *buffer; GstBuffer *buffer;
gint size, widht, height, bpp; gint size, width, height, bpp;
...
size = width * height * bpp; size = width * height * bpp;
@ -29,7 +32,8 @@ buffer data.
</programlisting> </programlisting>
</para> </para>
<para> <para>
Alternatively, use gst_buffer_new_and_alloc() to create a buffer with preallocated Alternatively, use gst_buffer_new_and_alloc()
to create a buffer with preallocated
data of a given size. data of a given size.
</para> </para>
<para> <para>
@ -47,18 +51,30 @@ To efficiently create a smaller buffer out of an existing one, you can
use gst_buffer_create_sub(). use gst_buffer_create_sub().
</para> </para>
<para> <para>
If the plug-in wants to modify the buffer in-place, it should first obtain
a buffer that is safe to modify by using gst_buffer_copy_on_write(). This
function is optimized so that a copy will only be made when it is necessary.
</para>
<para>
Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET() 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 and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
a certain flag is set. a certain #GstBufferFlag is set.
</para> </para>
<para> <para>
Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and
gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE. gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
</para> </para>
<para> <para>
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(). Buffers usually are freed by unreffing them with gst_buffer_unref().
gst_buffer_free() can also be used to effectively free the buffer Do not use gst_buffer_free() : this function effectively frees the buffer
regardless of the refcount (dangerous). regardless of the refcount, which is dangerous.
</para>
<para>
Last reviewed on August 30th, 2002 (0.4.0.1)
</para> </para>
<!-- ##### SECTION See_Also ##### --> <!-- ##### SECTION See_Also ##### -->
@ -71,31 +87,32 @@ regardless of the refcount (dangerous).
Casts an object to a GstBuffer. Casts an object to a GstBuffer.
</para> </para>
@buf: object to cast @buf: an object to cast.
@Returns: the #GstBuffer to which the given object points.
<!-- ##### MACRO GST_IS_BUFFER ##### --> <!-- ##### MACRO GST_IS_BUFFER ##### -->
<para> <para>
Checks if the pointer is a GstBuffer Checks if the pointer is a GstBuffer.
</para> </para>
@buf: The buffer to query @buf: a pointer to query.
<!-- ##### MACRO GST_BUFFER_REFCOUNT ##### --> <!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
<para> <para>
Get a handle to the refcount structure of the buffer Gets a handle to the refcount structure of the buffer.
</para> </para>
@buf: The buffer to query @buf: a #GstBuffer to get the refcount structure of.
<!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### --> <!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
<para> <para>
Get the current refcount value of the buffer Gets the current refcount value of the buffer.
</para> </para>
@buf: The buffer to query @buf: a #GstBuffer to get the refcount value of.
<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### --> <!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
@ -103,7 +120,7 @@ Get the current refcount value of the buffer
Calls the buffer-specific copy function on the given buffer. Calls the buffer-specific copy function on the given buffer.
</para> </para>
@buf: a #GstBuffer to copy @buf: a #GstBuffer to copy.
<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### --> <!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
@ -111,7 +128,7 @@ Calls the buffer-specific copy function on the given buffer.
Calls the buffer-specific free function on the given buffer. Calls the buffer-specific free function on the given buffer.
</para> </para>
@buf: a #GstBuffer to free @buf: a #GstBuffer to free.
<!-- ##### MACRO GST_BUFFER_FLAGS ##### --> <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
@ -119,16 +136,16 @@ Calls the buffer-specific free function on the given buffer.
Gets the flags from this buffer. Gets the flags from this buffer.
</para> </para>
@buf: a #GstBuffer to retrieve the flags from @buf: a #GstBuffer to retrieve the flags from.
<!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### --> <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
<para> <para>
Gives the status of a given #GstBufferFlag. Gives the status of a given flag of a buffer.
</para> </para>
@buf: a #GstBuffer to query @buf: a #GstBuffer to query flags of.
@flag: the #GstBufferFlag to check @flag: the #GstBufferFlag to check.
<!-- ##### MACRO GST_BUFFER_FLAG_SET ##### --> <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
@ -136,8 +153,8 @@ Gives the status of a given #GstBufferFlag.
Sets a buffer flag. Sets a buffer flag.
</para> </para>
@buf: a #GstBuffer to modify @buf: a #GstBuffer to modify flags of.
@flag: the #GstBufferFlag to set @flag: the #GstBufferFlag to set.
<!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### --> <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
@ -145,8 +162,8 @@ Sets a buffer flag.
Clears a buffer flag. Clears a buffer flag.
</para> </para>
@buf: a #GstBuffer to modify @buf: a #GstBuffer to modify flags of.
@flag: the #GstBufferFlag to clear @flag: the #GstBufferFlag to clear.
<!-- ##### MACRO GST_BUFFER_DATA ##### --> <!-- ##### MACRO GST_BUFFER_DATA ##### -->
@ -154,7 +171,8 @@ Clears a buffer flag.
Retrieves a pointer to the data element of this buffer. Retrieves a pointer to the data element of this buffer.
</para> </para>
@buf: a #GstBuffer to get data pointer of @buf: a #GstBuffer to get data pointer of.
@Returns: the pointer to the actual data contents of the buffer.
<!-- ##### MACRO GST_BUFFER_SIZE ##### --> <!-- ##### MACRO GST_BUFFER_SIZE ##### -->
@ -162,7 +180,7 @@ Retrieves a pointer to the data element of this buffer.
Gets the size of the data in this buffer. Gets the size of the data in this buffer.
</para> </para>
@buf: a #GstBuffer to get data size of @buf: a #GstBuffer to get data size of.
<!-- ##### MACRO GST_BUFFER_MAXSIZE ##### --> <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
@ -170,7 +188,7 @@ Gets the size of the data in this buffer.
Gets the maximum size of this buffer. Gets the maximum size of this buffer.
</para> </para>
@buf: a #GstBuffer to get maximum size of @buf: a #GstBuffer to get maximum size of.
<!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### --> <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
@ -178,7 +196,7 @@ Gets the maximum size of this buffer.
Gets the timestamp for this buffer. Gets the timestamp for this buffer.
</para> </para>
@buf: a #GstBuffer to get timestamp of @buf: a #GstBuffer to get timestamp of.
<!-- ##### MACRO GST_BUFFER_OFFSET ##### --> <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
@ -186,7 +204,7 @@ Gets the timestamp for this buffer.
Gets the offset in the source file of this buffer. Gets the offset in the source file of this buffer.
</para> </para>
@buf: a #GstBuffer to get offset of @buf: a #GstBuffer to get offset of.
<!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### --> <!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
@ -194,7 +212,8 @@ Gets the offset in the source file of this buffer.
Gets the bufferpool for this buffer. Gets the bufferpool for this buffer.
</para> </para>
@buf: a #GstBuffer to get bufferpool of @buf: a #GstBuffer to get the bufferpool of.
@Returns: the #GstBufferPool of this buffer.
<!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### --> <!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
@ -202,34 +221,31 @@ Gets the bufferpool for this buffer.
Gets the bufferpool private data. Gets the bufferpool private data.
</para> </para>
@buf: a #GstBuffer to get bufferpool's private data of @buf: a #GstBuffer to get bufferpool's private data of.
<<<<<<< gstbuffer.sgml
<!-- ##### ENUM GstBufferFlag ##### --> <!-- ##### ENUM GstBufferFlag ##### -->
<para> <para>
This enumeration type describes the flags that can be used for a buffer. A set of buffer flags used to describe properties of a #GstBuffer.
</para> </para>
@GST_BUFFER_READONLY: buffer is read-only @GST_BUFFER_READONLY: the buffer is read-only.
@GST_BUFFER_SUBBUFFER: This buffer is a subbuffer, the parent buffer can be found with the @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
GST_BUFFER_POOL_PRIVATE() macro. found with the GST_BUFFER_POOL_PRIVATE() macro.
@GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer @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_DONTFREE: do not try to free the data when this buffer is
@GST_BUFFER_DISCONTINOUS: This buffer is the first one after a discontinuity in the stream unreferenced.
@GST_BUFFER_KEY_UNIT: This buffer holds a key unit, a unit that can be decoded independently @GST_BUFFER_DISCONTINUOUS: the buffer is the first one after a discontinuity
of other buffers in the stream.
@GST_BUFFER_PREROLL: This buffer should be decoded but not rendered, it is mainly used @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
to resynchronise the stream decoded independently of other buffers.
@GST_BUFFER_FLAG_LAST: Additional flags can be added starting from this flag. @GST_BUFFER_PREROLL: the buffer should be decoded but not rendered, it is
mainly used to resynchronise the stream.
======= @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
<!-- ##### STRUCT GstBuffer ##### --> <!-- ##### STRUCT GstBuffer ##### -->
<para> <para>
The basic structure of a buffer The basic structure of a buffer.
</para> </para>
@data_type: @data_type:
@ -288,55 +304,58 @@ The basic structure of a buffer
<!-- ##### MACRO gst_buffer_ref ##### --> <!-- ##### MACRO gst_buffer_ref ##### -->
<para> <para>
Increase the refcount of the given buffer Increases the refcount of the given buffer by one.
</para> </para>
@buf: The buffer to refcount @buf: a #GstBuffer to increase the refcount of.
<!-- ##### MACRO gst_buffer_ref_by_count ##### --> <!-- ##### MACRO gst_buffer_ref_by_count ##### -->
<para> <para>
Increase the refcount of the buffer with the given value. Increases the refcount of the buffer by the given value.
</para> </para>
@buf: The buffer to refcount @buf: a #GstBuffer to increase the refcount of.
@c: The value to add to the refcount. @c: the value to add to the refcount.
<!-- ##### MACRO gst_buffer_unref ##### --> <!-- ##### MACRO gst_buffer_unref ##### -->
<para> <para>
Decrease the refcount of the buffer. If the refcount reaches 0, the buffer Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
will be freed. will be freed.
</para> </para>
@buf: The buffer to unref @buf: a #GstBuffer to unref.
<!-- ##### MACRO gst_buffer_copy ##### --> <!-- ##### MACRO gst_buffer_copy ##### -->
<para> <para>
Copy the given buffer using the copy function of the parent GstData structure. Copies the given buffer using the copy function of the parent GstData structure.
</para> </para>
@buffer: The buffer to copy @buf: a #GstBuffer to copy.
@Returns: A new copy of the buffer @Returns: a new #GstBuffer copy of the buffer.
<!-- ##### MACRO gst_buffer_copy_on_write ##### --> <!-- ##### MACRO gst_buffer_copy_on_write ##### -->
<para> <para>
Copy the buffer if the refcount > 1 so that the newly created buffer can be safely This function returns a buffer that is safe to write to.
written to. If the refcount is 1, this function just returns the original buffer. 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> </para>
@buffer: The buffer to copy. @buffer: a #GstBuffer to copy.
@Returns: the #GstBuffer that can safely be written to.
<!-- ##### MACRO gst_buffer_free ##### --> <!-- ##### MACRO gst_buffer_free ##### -->
<para> <para>
Free the given buffer. It is dangerous to use this function, use gst_buffer_unref() Frees the given buffer, regardless of the refcount.
instead. It is dangerous to use this function, you should use gst_buffer_unref() instead.
</para> </para>
@buffer: The buffer to free. @buffer: a #GstBuffer to free.
<!-- ##### FUNCTION gst_buffer_create_sub ##### --> <!-- ##### FUNCTION gst_buffer_create_sub ##### -->

127
gst/gstbuffer.c
View file

@ -52,7 +52,8 @@ _gst_buffer_initialize (void)
_gst_buffer_live = 0; _gst_buffer_live = 0;
_gst_buffer_pool_live = 0; _gst_buffer_pool_live = 0;
chunk = gst_mem_chunk_new ("GstBufferChunk", sizeof (GstBuffer), sizeof (GstBuffer) * 200, 0); chunk = gst_mem_chunk_new ("GstBufferChunk", sizeof (GstBuffer),
sizeof (GstBuffer) * 200, 0);
GST_INFO (GST_CAT_BUFFER, "Buffers are initialized now"); GST_INFO (GST_CAT_BUFFER, "Buffers are initialized now");
} }
@ -65,10 +66,10 @@ _gst_buffer_initialize (void)
void void
gst_buffer_print_stats (void) gst_buffer_print_stats (void)
{ {
g_log (g_log_domain_gstreamer, G_LOG_LEVEL_INFO, g_log (g_log_domain_gstreamer, G_LOG_LEVEL_INFO, "%d live buffer(s)",
"%d live buffer(s)", _gst_buffer_live); _gst_buffer_live);
g_log (g_log_domain_gstreamer, G_LOG_LEVEL_INFO, g_log (g_log_domain_gstreamer, G_LOG_LEVEL_INFO, "%d live bufferpool(s)",
"%d live bufferpool(s)", _gst_buffer_pool_live); _gst_buffer_pool_live);
} }
static void static void
@ -97,9 +98,9 @@ _gst_buffer_sub_free (GstBuffer *buffer)
/** /**
* gst_buffer_default_free: * gst_buffer_default_free:
* @buffer: a #GstBuffer to free * @buffer: a #GstBuffer to free.
* *
* Free the memory associated with the buffer including the buffer data, * Frees the memory associated with the buffer including the buffer data,
* unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL. * unless the GST_BUFFER_DONTFREE flags was set or the buffer data is NULL.
* This function is used by buffer pools. * This function is used by buffer pools.
*/ */
@ -128,12 +129,12 @@ _gst_buffer_copy_from_pool (GstBuffer *buffer)
/** /**
* gst_buffer_default_copy: * gst_buffer_default_copy:
* @buffer: a #GstBuffer to make a copy of * @buffer: a #GstBuffer to make a copy of.
* *
* Make a full newly allocated copy of the given buffer, data and all. * Make a full newly allocated copy of the given buffer, data and all.
* This function is used by buffer pools. * This function is used by buffer pools.
* *
* Returns: new #GstBuffer * Returns: the new #GstBuffer.
*/ */
GstBuffer* GstBuffer*
gst_buffer_default_copy (GstBuffer *buffer) gst_buffer_default_copy (GstBuffer *buffer)
@ -144,7 +145,8 @@ gst_buffer_default_copy (GstBuffer *buffer)
copy = gst_buffer_new (); copy = gst_buffer_new ();
/* we simply copy everything from our parent */ /* we simply copy everything from our parent */
GST_BUFFER_DATA (copy) = g_memdup (GST_BUFFER_DATA (buffer), GST_BUFFER_SIZE (buffer)); GST_BUFFER_DATA (copy) = g_memdup (GST_BUFFER_DATA (buffer),
GST_BUFFER_SIZE (buffer));
GST_BUFFER_SIZE (copy) = GST_BUFFER_SIZE (buffer); GST_BUFFER_SIZE (copy) = GST_BUFFER_SIZE (buffer);
GST_BUFFER_MAXSIZE (copy) = GST_BUFFER_MAXSIZE (buffer); GST_BUFFER_MAXSIZE (copy) = GST_BUFFER_MAXSIZE (buffer);
GST_BUFFER_TIMESTAMP (copy) = GST_BUFFER_TIMESTAMP (buffer); GST_BUFFER_TIMESTAMP (copy) = GST_BUFFER_TIMESTAMP (buffer);
@ -158,7 +160,7 @@ gst_buffer_default_copy (GstBuffer *buffer)
* *
* Creates a newly allocated buffer without any data. * Creates a newly allocated buffer without any data.
* *
* Returns: new #GstBuffer * Returns: the new #GstBuffer.
*/ */
GstBuffer* GstBuffer*
gst_buffer_new (void) gst_buffer_new (void)
@ -182,11 +184,11 @@ gst_buffer_new (void)
/** /**
* gst_buffer_new_and_alloc: * gst_buffer_new_and_alloc:
* @size: the size of the buffer and the memory to allocate * @size: the size of the new buffer's data.
* *
* Creates a newly allocated buffer with data of the given size. * Creates a newly allocated buffer with data of the given size.
* *
* Returns: new #GstBuffer * Returns: the new #GstBuffer.
*/ */
GstBuffer* GstBuffer*
gst_buffer_new_and_alloc (guint size) gst_buffer_new_and_alloc (guint size)
@ -203,13 +205,14 @@ gst_buffer_new_and_alloc (guint size)
/** /**
* gst_buffer_new_from_pool: * gst_buffer_new_from_pool:
* @pool: the buffer pool to use * @pool: a #GstBufferPool to use.
* @offset: the offset of the new buffer * @offset: the offset of the new buffer.
* @size: the size of the new buffer * @size: the size of the new buffer.
* *
* Creates a newly allocated buffer using the specified bufferpool, offset and size. * Creates a newly allocated buffer using the specified buffer pool,
* offset and size.
* *
* Returns: new #GstBuffer * Returns: the new #GstBuffer, or NULL if there was an error.
*/ */
GstBuffer* GstBuffer*
gst_buffer_new_from_pool (GstBufferPool *pool, guint64 offset, guint size) gst_buffer_new_from_pool (GstBufferPool *pool, guint64 offset, guint size)
@ -236,14 +239,14 @@ gst_buffer_new_from_pool (GstBufferPool *pool, guint64 offset, guint size)
/** /**
* gst_buffer_create_sub: * gst_buffer_create_sub:
* @parent: parent #GstBuffer * @parent: a parent #GstBuffer to create a subbuffer from.
* @offset: offset into parent #GstBuffer * @offset: the offset into parent #GstBuffer.
* @size: size of new sub-buffer * @size: the size of the new #GstBuffer sub-buffer (with size > 0).
* *
* Creates a sub-buffer from the parent at a given offset. * Creates a sub-buffer from the parent at a given offset.
* This sub-buffer uses the actual memory space of the parent buffer. * This sub-buffer uses the actual memory space of the parent buffer.
* *
* Returns: a new #GstBuffer * Returns: the new #GstBuffer, or NULL if there was an error.
*/ */
GstBuffer* GstBuffer*
gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size) gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size)
@ -274,7 +277,8 @@ gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size)
buffer = gst_mem_chunk_alloc0 (chunk); buffer = gst_mem_chunk_alloc0 (chunk);
_gst_buffer_live++; _gst_buffer_live++;
/* make sure nobody overwrites data in the new buffer by setting the READONLY flag */ /* make sure nobody overwrites data in the new buffer
* by setting the READONLY flag */
_GST_DATA_INIT (GST_DATA (buffer), _GST_DATA_INIT (GST_DATA (buffer),
_gst_buffer_type, _gst_buffer_type,
GST_DATA_FLAG_SHIFT (GST_BUFFER_SUBBUFFER) | GST_DATA_FLAG_SHIFT (GST_BUFFER_SUBBUFFER) |
@ -297,8 +301,8 @@ gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size)
/** /**
* gst_buffer_merge: * gst_buffer_merge:
* @buf1: first source #GstBuffer to merge * @buf1: a first source #GstBuffer to merge.
* @buf2: second source #GstBuffer to merge * @buf2: the second source #GstBuffer to merge.
* *
* Create a new buffer that is the concatenation of the two source * Create a new buffer that is the concatenation of the two source
* buffers. The original source buffers will not be modified or * buffers. The original source buffers will not be modified or
@ -307,7 +311,7 @@ gst_buffer_create_sub (GstBuffer *parent, guint offset, guint size)
* Internally is nothing more than a specialized gst_buffer_span(), * Internally is nothing more than a specialized gst_buffer_span(),
* so the same optimizations can occur. * so the same optimizations can occur.
* *
* Returns: a new #GstBuffer that's the concatenation of the source buffers * Returns: the new #GstBuffer that's the concatenation of the source buffers.
*/ */
GstBuffer* GstBuffer*
gst_buffer_merge (GstBuffer *buf1, GstBuffer *buf2) gst_buffer_merge (GstBuffer *buf1, GstBuffer *buf2)
@ -321,13 +325,14 @@ gst_buffer_merge (GstBuffer *buf1, GstBuffer *buf2)
/** /**
* gst_buffer_is_span_fast: * gst_buffer_is_span_fast:
* @buf1: first source buffer * @buf1: a first source #GstBuffer.
* @buf2: second source buffer * @buf2: the second source #GstBuffer.
* *
* Determines whether a gst_buffer_span() is free (as in free beer), * Determines whether a gst_buffer_span() is free (as in free beer),
* or requires a memcpy. * or requires a memcpy.
* *
* Returns: TRUE if the buffers are contiguous, FALSE if a copy would be required. * Returns: TRUE if the buffers are contiguous,
* FALSE if a copy would be required.
*/ */
gboolean gboolean
gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2) gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2)
@ -344,10 +349,11 @@ gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2)
/** /**
* gst_buffer_span: * gst_buffer_span:
* @buf1: first source #GstBuffer to merge * @buf1: a first source #GstBuffer to merge.
* @offset: offset in first buffer to start new buffer * @offset: the offset in the first buffer from where the new
* @buf2: second source #GstBuffer to merge * buffer should start.
* @len: length of new buffer * @buf2: the second source #GstBuffer to merge.
* @len: the total length of the new buffer.
* *
* Creates a new buffer that consists of part of buf1 and buf2. * Creates a new buffer that consists of part of buf1 and buf2.
* Logically, buf1 and buf2 are concatenated into a single larger * Logically, buf1 and buf2 are concatenated into a single larger
@ -359,7 +365,7 @@ gst_buffer_is_span_fast (GstBuffer *buf1, GstBuffer *buf2)
* parent, and thus no copying is necessary. you can use * parent, and thus no copying is necessary. you can use
* gst_buffer_is_span_fast() to determine if a memcpy will be needed. * gst_buffer_is_span_fast() to determine if a memcpy will be needed.
* *
* Returns: a new #GstBuffer that spans the two source buffers * Returns: the new #GstBuffer that spans the two source buffers.
*/ */
GstBuffer* GstBuffer*
gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len) gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len)
@ -374,10 +380,13 @@ gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len)
if (gst_buffer_is_span_fast (buf1, buf2)) { if (gst_buffer_is_span_fast (buf1, buf2)) {
GstBuffer *parent = GST_BUFFER (buf1->pool_private); GstBuffer *parent = GST_BUFFER (buf1->pool_private);
/* we simply create a subbuffer of the common parent */ /* we simply create a subbuffer of the common parent */
newbuf = gst_buffer_create_sub (parent, buf1->data - parent->data + offset, len); newbuf = gst_buffer_create_sub (parent,
buf1->data - parent->data + offset, len);
} }
else { else {
GST_DEBUG (GST_CAT_BUFFER,"slow path taken while spanning buffers %p and %p", buffer, append); GST_DEBUG (GST_CAT_BUFFER,
"slow path taken while spanning buffers %p and %p",
buffer, append);
/* otherwise we simply have to brute-force copy the buffers */ /* otherwise we simply have to brute-force copy the buffers */
newbuf = gst_buffer_new_and_alloc (len); newbuf = gst_buffer_new_and_alloc (len);
@ -387,7 +396,8 @@ gst_buffer_span (GstBuffer *buf1, guint32 offset, GstBuffer *buf2, guint32 len)
/* copy the first buffer's data across */ /* copy the first buffer's data across */
memcpy (newbuf->data, buf1->data + offset, buf1->size - offset); memcpy (newbuf->data, buf1->data + offset, buf1->size - offset);
/* copy the second buffer's data across */ /* copy the second buffer's data across */
memcpy (newbuf->data + (buf1->size - offset), buf2->data, len - (buf1->size - offset)); memcpy (newbuf->data + (buf1->size - offset), buf2->data,
len - (buf1->size - offset));
} }
/* if the offset is 0, the new buffer has the same timestamp as buf1 */ /* if the offset is 0, the new buffer has the same timestamp as buf1 */
if (offset == 0) if (offset == 0)
@ -406,16 +416,19 @@ gst_buffer_pool_default_free (GstBufferPool *pool)
/** /**
* gst_buffer_pool_new: * gst_buffer_pool_new:
* @free: The function to free the bufferpool * @free: the #GstDataFreeFunction to free the buffer pool.
* @copy: The function to copy the bufferpool * @copy: the #GstDataCopyFunction to copy the buffer pool.
* @buffer_new: the function to create a new buffer from this pool * @buffer_new: the #GstBufferPoolBufferNewFunction to create a new buffer
* @buffer_copy: the function to copy a buffer from this pool * from this pool
* @buffer_free: the function to free a buffer in this pool * @buffer_copy: the #GstBufferPoolBufferCopyFunction to copy a buffer
* @user_data: user data passed to buffer_* functions * from this pool
* @buffer_free: the #GstBufferPoolBufferFreeFunction to free a buffer
* in this pool
* @user_data: the user data gpointer passed to buffer_* functions.
* *
* Create a new bufferpool with the given functions. * Creates a new buffer pool with the given functions.
* *
* Returns: a new GstBufferPool or NULL on error. * Returns: a new #GstBufferPool, or NULL on error.
*/ */
GstBufferPool* GstBufferPool*
gst_buffer_pool_new (GstDataFreeFunction free, gst_buffer_pool_new (GstDataFreeFunction free,
@ -453,9 +466,9 @@ gst_buffer_pool_new (GstDataFreeFunction free,
/** /**
* gst_buffer_pool_is_active: * gst_buffer_pool_is_active:
* @pool: the pool to query * @pool: the #GstBufferPool to query.
* *
* Query if the geven bufferpool is active. * Queries if the given buffer pool is active.
* *
* Returns: TRUE if the pool is active. * Returns: TRUE if the pool is active.
*/ */
@ -467,11 +480,11 @@ gst_buffer_pool_is_active (GstBufferPool *pool)
/** /**
* gst_buffer_pool_set_active: * gst_buffer_pool_set_active:
* @pool: the pool to activate * @pool: a #GstBufferPool to set the activity status on.
* @active: new status of the pool * @active: the new status of the pool.
* *
* Set the given pool to the active or inactive state depending on the * Sets the given pool to the active or inactive state depending on the
* activate parameter * active parameter.
*/ */
void void
gst_buffer_pool_set_active (GstBufferPool *pool, gboolean active) gst_buffer_pool_set_active (GstBufferPool *pool, gboolean active)
@ -481,10 +494,10 @@ gst_buffer_pool_set_active (GstBufferPool *pool, gboolean active)
/** /**
* gst_buffer_pool_set_user_data: * gst_buffer_pool_set_user_data:
* @pool: the pool set the user data for * @pool: the #GstBufferPool to set the user data for.
* @user_data: the user_data to set * @user_data: the user_data to set on the buffer pool.
* *
* Set the given user data to the bufferpool * Sets the given user data on the buffer pool.
*/ */
void void
gst_buffer_pool_set_user_data (GstBufferPool *pool, gpointer user_data) gst_buffer_pool_set_user_data (GstBufferPool *pool, gpointer user_data)
@ -494,11 +507,11 @@ gst_buffer_pool_set_user_data (GstBufferPool *pool, gpointer user_data)
/** /**
* gst_buffer_pool_get_user_data: * gst_buffer_pool_get_user_data:
* @pool: the pool get the user data for * @pool: the #GstBufferPool to get the user data for.
* *
* Get the user data of the bufferpool * Gets the user data of the buffer pool.
* *
* Returns: the user data associated with this bufferpool * Returns: the user data associated with this buffer pool.
*/ */
gpointer gpointer
gst_buffer_pool_get_user_data (GstBufferPool *pool) gst_buffer_pool_get_user_data (GstBufferPool *pool)