c1cdb8960520686fc4d1fbc846ec84a8e989ef8d
1 <!-- ##### SECTION Title ##### -->
2 GstBuffer
4 <!-- ##### SECTION Short_Description ##### -->
5 Data-passing buffer type, supporting sub-buffers.
7 <!-- ##### SECTION Long_Description ##### -->
8 <para>
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.
14 </para>
15 <para>
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.
20 <programlisting>
21 GstBuffer *buffer;
22 gint size, width, height, bpp;
24 ...
26 size = width * height * bpp;
28 buffer = gst_buffer_new ();
29 GST_BUFFER_SIZE (buffer) = size;
30 GST_BUFFER_DATA (buffer) = g_alloc (size);
31 ...
32 </programlisting>
33 </para>
34 <para>
35 Alternatively, use gst_buffer_new_and_alloc()
36 to create a buffer with preallocated
37 data of a given size.
38 </para>
39 <para>
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().
43 </para>
44 <para>
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
47 next element.
48 </para>
49 <para>
50 To efficiently create a smaller buffer out of an existing one, you can
51 use gst_buffer_create_sub().
52 </para>
53 <para>
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.
57 </para>
58 <para>
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.
62 </para>
63 <para>
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.
66 </para>
67 <para>
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.
74 </para>
76 <para>
77 Last reviewed on August 30th, 2002 (0.4.0.1)
78 </para>
80 <!-- ##### SECTION See_Also ##### -->
81 <para>
82 #GstBufferPool, #GstPad, #GstData
83 </para>
85 <!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
86 <para>
87 The name used for tracing memory allocations
88 </para>
92 <!-- ##### MACRO GST_BUFFER ##### -->
93 <para>
94 Casts an object to a GstBuffer.
95 </para>
97 @buf: an object to cast.
98 @Returns: the #GstBuffer to which the given object points.
101 <!-- ##### MACRO GST_IS_BUFFER ##### -->
102 <para>
103 Checks if the pointer is a GstBuffer.
104 </para>
106 @buf: a pointer to query.
109 <!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
110 <para>
111 Gets a handle to the refcount structure of the buffer.
112 </para>
114 @buf: a #GstBuffer to get the refcount structure of.
117 <!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
118 <para>
119 Gets the current refcount value of the buffer.
120 </para>
122 @buf: a #GstBuffer to get the refcount value of.
125 <!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
126 <para>
127 Calls the buffer-specific copy function on the given buffer.
128 </para>
130 @buf: a #GstBuffer to copy.
133 <!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
134 <para>
135 Calls the buffer-specific free function on the given buffer.
136 </para>
138 @buf: a #GstBuffer to free.
141 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
142 <para>
143 Gets the flags from this buffer.
144 </para>
146 @buf: a #GstBuffer to retrieve the flags from.
149 <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
150 <para>
151 Gives the status of a given flag of a buffer.
152 </para>
154 @buf: a #GstBuffer to query flags of.
155 @flag: the #GstBufferFlag to check.
158 <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
159 <para>
160 Sets a buffer flag.
161 </para>
163 @buf: a #GstBuffer to modify flags of.
164 @flag: the #GstBufferFlag to set.
167 <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
168 <para>
169 Clears a buffer flag.
170 </para>
172 @buf: a #GstBuffer to modify flags of.
173 @flag: the #GstBufferFlag to clear.
176 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
177 <para>
178 Retrieves a pointer to the data element of this buffer.
179 </para>
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 ##### -->
186 <para>
187 Gets the size of the data in this buffer.
188 </para>
190 @buf: a #GstBuffer to get data size of.
193 <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
194 <para>
195 Gets the maximum size of this buffer.
196 </para>
198 @buf: a #GstBuffer to get maximum size of.
201 <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
202 <para>
203 Gets the timestamp for this buffer.
204 </para>
206 @buf: a #GstBuffer to get timestamp of.
209 <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
210 <para>
211 Gets the offset in the source file of this buffer.
212 </para>
214 @buf: a #GstBuffer to get offset of.
217 <!-- ##### ENUM GstBufferFlag ##### -->
218 <para>
219 A set of buffer flags used to describe properties of a #GstBuffer.
220 </para>
222 @GST_BUFFER_READONLY: the buffer is read-only.
223 @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
224 found with the GST_BUFFER_POOL_PRIVATE() macro.
225 @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
226 @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
227 unreferenced.
228 @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
229 decoded independently of other buffers.
230 @GST_BUFFER_DONTKEEP:
231 @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
233 <!-- ##### STRUCT GstBuffer ##### -->
234 <para>
235 The basic structure of a buffer.
236 </para>
238 @data_type:
239 @data:
240 @size:
241 @maxsize:
242 @timestamp:
243 @duration:
244 @offset:
245 @offset_end:
246 @free_data:
247 @buffer_private:
248 @_gst_reserved:
250 <!-- ##### FUNCTION gst_buffer_new ##### -->
251 <para>
253 </para>
255 @Returns:
258 <!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
259 <para>
261 </para>
263 @size:
264 @Returns:
267 <!-- ##### MACRO gst_buffer_set_data ##### -->
268 <para>
269 A convenience function to set the data and size on a buffer
270 </para>
272 @buf: The buffer to modify
273 @data: The data to set on the buffer
274 @size: The size to set on the buffer
277 <!-- ##### FUNCTION gst_buffer_default_free ##### -->
278 <para>
280 </para>
282 @buffer:
285 <!-- ##### FUNCTION gst_buffer_default_copy ##### -->
286 <para>
288 </para>
290 @buffer:
291 @Returns:
294 <!-- ##### MACRO gst_buffer_ref ##### -->
295 <para>
296 Increases the refcount of the given buffer by one.
297 </para>
299 @buf: a #GstBuffer to increase the refcount of.
302 <!-- ##### MACRO gst_buffer_ref_by_count ##### -->
303 <para>
304 Increases the refcount of the buffer by the given value.
305 </para>
307 @buf: a #GstBuffer to increase the refcount of.
308 @c: the value to add to the refcount.
311 <!-- ##### MACRO gst_buffer_unref ##### -->
312 <para>
313 Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
314 will be freed.
315 </para>
317 @buf: a #GstBuffer to unref.
320 <!-- ##### MACRO gst_buffer_copy ##### -->
321 <para>
322 Copies the given buffer using the copy function of the parent GstData structure.
323 </para>
325 @buf: a #GstBuffer to copy.
326 @Returns: a new #GstBuffer copy of the buffer.
329 <!-- ##### MACRO gst_buffer_copy_on_write ##### -->
330 <para>
331 This function returns a buffer that is safe to write to.
332 Copy the buffer if the refcount > 1 so that the newly
333 created buffer can be safely written to.
334 If the refcount is 1, this function just returns the original buffer.
335 </para>
337 @buf: a #GstBuffer to copy
338 @Returns: the #GstBuffer that can safely be written to.
341 <!-- ##### MACRO gst_buffer_free ##### -->
342 <para>
343 Frees the given buffer, regardless of the refcount.
344 It is dangerous to use this function, you should use gst_buffer_unref() instead.
345 </para>
347 @buf: a #GstBuffer to free.
350 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
351 <para>
353 </para>
355 @parent:
356 @offset:
357 @size:
358 @Returns:
361 <!-- ##### FUNCTION gst_buffer_merge ##### -->
362 <para>
364 </para>
366 @buf1:
367 @buf2:
368 @Returns:
371 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
372 <para>
374 </para>
376 @buf1:
377 @buf2:
378 @Returns:
381 <!-- ##### FUNCTION gst_buffer_span ##### -->
382 <para>
384 </para>
386 @buf1:
387 @offset:
388 @buf2:
389 @len:
390 @Returns: