1 <!-- ##### SECTION Title ##### -->
4 <!-- ##### SECTION Short_Description ##### -->
5 Data-passing buffer type, supporting sub-buffers.
7 <!-- ##### SECTION Long_Description ##### -->
9 Buffers are the basic unit of data transfer in GStreamer. The GstBuffer type
10 provides all the state necessary to define a region of memory as part of a
11 stream. Sub-buffers are also supported, allowing a smaller region of a
12 buffer to become its own buffer, with mechanisms in place to ensure that
13 neither memory space goes away.
16 Buffers are usually created with gst_buffer_new(). After a buffer has been
17 created one will typically allocate memory for it and set the size of the
18 buffer data. The following example creates a buffer that can hold a given
19 video frame with a given width, height and bits per plane.
22 gint size, width, height, bpp;
26 size = width * height * bpp;
28 buffer = gst_buffer_new ();
29 GST_BUFFER_SIZE (buffer) = size;
30 GST_BUFFER_DATA (buffer) = g_alloc (size);
35 Alternatively, use gst_buffer_new_and_alloc()
36 to create a buffer with preallocated
40 GstBuffers can also be created from a #GstBufferPool with
41 gst_buffer_new_from_pool(). The bufferpool can be obtained from a
42 peer element with gst_pad_get_bufferpool().
45 gst_buffer_ref() is used to increase the refcount of a buffer. This must be
46 done when you want to keep a handle to the buffer after pushing it to the
50 To efficiently create a smaller buffer out of an existing one, you can
51 use gst_buffer_create_sub().
54 If the plug-in wants to modify the buffer in-place, it should first obtain
55 a buffer that is safe to modify by using gst_buffer_copy_on_write(). This
56 function is optimized so that a copy will only be made when it is necessary.
59 Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET()
60 and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
61 a certain #GstBufferFlag is set.
64 Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and
65 gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
68 An element should either unref the buffer or push it out on a src pad
69 using gst_pad_push() (see #GstPad).
71 Buffers usually are freed by unreffing them with gst_buffer_unref().
72 Do not use gst_buffer_free() : this function effectively frees the buffer
73 regardless of the refcount, which is dangerous.
77 Last reviewed on August 30th, 2002 (0.4.0.1)
80 <!-- ##### SECTION See_Also ##### -->
82 #GstBufferPool, #GstPad, #GstData
85 <!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
87 The name used for tracing memory allocations
92 <!-- ##### MACRO GST_BUFFER ##### -->
94 Casts an object to a GstBuffer.
97 @buf: an object to cast.
98 @Returns: the #GstBuffer to which the given object points.
101 <!-- ##### MACRO GST_IS_BUFFER ##### -->
103 Checks if the pointer is a GstBuffer.
106 @buf: a pointer to query.
109 <!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
111 Gets a handle to the refcount structure of the buffer.
114 @buf: a #GstBuffer to get the refcount structure of.
117 <!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
119 Gets the current refcount value of the buffer.
122 @buf: a #GstBuffer to get the refcount value of.
125 <!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
127 Calls the buffer-specific copy function on the given buffer.
130 @buf: a #GstBuffer to copy.
133 <!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
135 Calls the buffer-specific free function on the given buffer.
138 @buf: a #GstBuffer to free.
141 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
143 Gets the flags from this buffer.
146 @buf: a #GstBuffer to retrieve the flags from.
149 <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
151 Gives the status of a given flag of a buffer.
154 @buf: a #GstBuffer to query flags of.
155 @flag: the #GstBufferFlag to check.
158 <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
163 @buf: a #GstBuffer to modify flags of.
164 @flag: the #GstBufferFlag to set.
167 <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
169 Clears a buffer flag.
172 @buf: a #GstBuffer to modify flags of.
173 @flag: the #GstBufferFlag to clear.
176 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
178 Retrieves a pointer to the data element of this buffer.
181 @buf: a #GstBuffer to get data pointer of.
182 @Returns: the pointer to the actual data contents of the buffer.
185 <!-- ##### MACRO GST_BUFFER_SIZE ##### -->
187 Gets the size of the data in this buffer.
190 @buf: a #GstBuffer to get data size of.
193 <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
195 Gets the maximum size of this buffer.
198 @buf: a #GstBuffer to get maximum size of.
201 <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
203 Gets the timestamp for this buffer.
206 @buf: a #GstBuffer to get timestamp of.
209 <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
211 Gets the offset in the source file of this buffer.
214 @buf: a #GstBuffer to get offset of.
217 <!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
219 Gets the bufferpool for this buffer.
222 @buf: a #GstBuffer to get the bufferpool of.
223 @Returns: the #GstBufferPool of this buffer.
226 <!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
228 Gets the bufferpool private data.
231 @buf: a #GstBuffer to get bufferpool's private data of.
234 <!-- ##### ENUM GstBufferFlag ##### -->
236 A set of buffer flags used to describe properties of a #GstBuffer.
239 @GST_BUFFER_READONLY: the buffer is read-only.
240 @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
241 found with the GST_BUFFER_POOL_PRIVATE() macro.
242 @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
243 @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
245 @GST_BUFFER_DISCONTINUOUS: the buffer is the first one after a discontinuity
247 @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
248 decoded independently of other buffers.
249 @GST_BUFFER_PREROLL: the buffer should be decoded but not rendered, it is
250 mainly used to resynchronise the stream.
251 @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
253 <!-- ##### STRUCT GstBuffer ##### -->
255 The basic structure of a buffer.
270 <!-- ##### FUNCTION gst_buffer_new ##### -->
278 <!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
287 <!-- ##### MACRO gst_buffer_set_data ##### -->
289 A convenience function to set the data and size on a buffer
292 @buf: The buffer to modify
293 @data: The data to set on the buffer
294 @size: The size to set on the buffer
297 <!-- ##### FUNCTION gst_buffer_default_free ##### -->
305 <!-- ##### FUNCTION gst_buffer_default_copy ##### -->
314 <!-- ##### MACRO gst_buffer_ref ##### -->
316 Increases the refcount of the given buffer by one.
319 @buf: a #GstBuffer to increase the refcount of.
322 <!-- ##### MACRO gst_buffer_ref_by_count ##### -->
324 Increases the refcount of the buffer by the given value.
327 @buf: a #GstBuffer to increase the refcount of.
328 @c: the value to add to the refcount.
331 <!-- ##### MACRO gst_buffer_unref ##### -->
333 Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
337 @buf: a #GstBuffer to unref.
340 <!-- ##### MACRO gst_buffer_copy ##### -->
342 Copies the given buffer using the copy function of the parent GstData structure.
345 @buf: a #GstBuffer to copy.
346 @Returns: a new #GstBuffer copy of the buffer.
349 <!-- ##### MACRO gst_buffer_copy_on_write ##### -->
351 This function returns a buffer that is safe to write to.
352 Copy the buffer if the refcount > 1 so that the newly
353 created buffer can be safely written to.
354 If the refcount is 1, this function just returns the original buffer.
357 @buf: a #GstBuffer to copy
358 @Returns: the #GstBuffer that can safely be written to.
361 <!-- ##### MACRO gst_buffer_free ##### -->
363 Frees the given buffer, regardless of the refcount.
364 It is dangerous to use this function, you should use gst_buffer_unref() instead.
367 @buf: a #GstBuffer to free.
370 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
381 <!-- ##### FUNCTION gst_buffer_merge ##### -->
391 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
401 <!-- ##### FUNCTION gst_buffer_span ##### -->