gstbuffer.sgml 9.03 KB
Newer Older
1 2 3 4
<!-- ##### SECTION Title ##### -->
GstBuffer

<!-- ##### SECTION Short_Description ##### -->
Wim Taymans's avatar
Wim Taymans committed
5
Data-passing buffer type, supporting sub-buffers.
6 7 8

<!-- ##### SECTION Long_Description ##### -->
<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
Wim Taymans's avatar
Wim Taymans committed
13
neither memory space goes away. 
14 15 16 17
</para>
<para>
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 
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
18 19
buffer data.  The following example creates a buffer that can hold a given
video frame with a given width, height and bits per plane.
20 21
<programlisting>
  GstBuffer *buffer;
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
22 23 24
  gint size, width, height, bpp;

  ...
25 26 27 28 29 30 31 32 33 34

  size = width * height * bpp;

  buffer = gst_buffer_new ();
  GST_BUFFER_SIZE (buffer) = size;
  GST_BUFFER_DATA (buffer) = g_alloc (size);
  ...
</programlisting>
</para>
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
35 36
Alternatively, use gst_buffer_new_and_alloc() 
to create a buffer with preallocated
Wim Taymans's avatar
Wim Taymans committed
37 38 39 40
data of a given size.
</para>
<para>
GstBuffers can also be created from a #GstBufferPool with 
41 42 43 44 45 46 47 48 49 50 51 52 53
gst_buffer_new_from_pool(). The bufferpool can be obtained from a
peer element with gst_pad_get_bufferpool().
</para>
<para>
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
next element.
</para>
<para>
To efficiently create a smaller buffer out of an existing one, you can
use gst_buffer_create_sub().
</para>
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
54 55 56 57 58
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>
59 60
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
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
61
a certain #GstBufferFlag is set.
62 63
</para>
<para>
Wim Taymans's avatar
Wim Taymans committed
64 65 66 67
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.
</para>
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
68 69 70
An element should either unref the buffer or push it out on a src pad
using gst_pad_push() (see #GstPad).

71
Buffers usually are freed by unreffing them with gst_buffer_unref().
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
72 73 74 75 76 77
Do not use gst_buffer_free() : this function effectively frees the buffer
regardless of the refcount, which is dangerous.
</para>

<para>
Last reviewed on August 30th, 2002 (0.4.0.1)
78 79 80 81 82 83 84
</para>

<!-- ##### SECTION See_Also ##### -->
<para>
#GstBufferPool, #GstPad, #GstData
</para>

Wim Taymans's avatar
Wim Taymans committed
85 86 87 88 89 90 91
<!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
<para>
The name used for tracing memory allocations
</para>



Wim Taymans's avatar
Wim Taymans committed
92 93 94 95 96
<!-- ##### MACRO GST_BUFFER ##### -->
<para>
Casts an object to a GstBuffer.
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
97 98
@buf: an object to cast.
@Returns: the #GstBuffer to which the given object points.
Wim Taymans's avatar
Wim Taymans committed
99 100


101 102
<!-- ##### MACRO GST_IS_BUFFER ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
103
Checks if the pointer is a GstBuffer.
104 105
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
106
@buf: a pointer to query.
107 108


Wim Taymans's avatar
Wim Taymans committed
109
<!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
110
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
111
Gets a handle to the refcount structure of the buffer.
112 113
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
114
@buf: a #GstBuffer to get the refcount structure of.
Wim Taymans's avatar
Wim Taymans committed
115 116 117 118


<!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
119
Gets the current refcount value of the buffer.
Wim Taymans's avatar
Wim Taymans committed
120 121
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
122
@buf: a #GstBuffer to get the refcount value of.
Wim Taymans's avatar
Wim Taymans committed
123 124 125 126 127 128 129


<!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
<para>
Calls the buffer-specific copy function on the given buffer.
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
130
@buf: a #GstBuffer to copy.
Wim Taymans's avatar
Wim Taymans committed
131 132 133 134 135 136 137


<!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
<para>
Calls the buffer-specific free function on the given buffer.
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
138
@buf: a #GstBuffer to free.
139 140 141 142


<!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
<para>
143
Gets the flags from this buffer.
144 145
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
146
@buf: a #GstBuffer to retrieve the flags from.
147 148 149 150


<!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
151
Gives the status of a given flag of a buffer.
152 153
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
154 155
@buf: a #GstBuffer to query flags of.
@flag: the #GstBufferFlag to check.
156 157 158 159


<!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
<para>
160
Sets a buffer flag.
161 162
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
163 164
@buf: a #GstBuffer to modify flags of.
@flag: the #GstBufferFlag to set.
165 166 167 168


<!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
<para>
169
Clears a buffer flag.
170 171
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
172 173
@buf: a #GstBuffer to modify flags of.
@flag: the #GstBufferFlag to clear.
174 175 176 177


<!-- ##### MACRO GST_BUFFER_DATA ##### -->
<para>
178
Retrieves a pointer to the data element of this buffer.
179 180
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
181 182
@buf: a #GstBuffer to get data pointer of.
@Returns: the pointer to the actual data contents of the buffer.
183 184 185 186


<!-- ##### MACRO GST_BUFFER_SIZE ##### -->
<para>
187
Gets the size of the data in this buffer.
188 189
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
190
@buf: a #GstBuffer to get data size of.
191 192 193 194


<!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
<para>
195
Gets the maximum size of this buffer.
196 197
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
198
@buf: a #GstBuffer to get maximum size of.
199 200 201 202


<!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
<para>
203
Gets the timestamp for this buffer.
204 205
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
206
@buf: a #GstBuffer to get timestamp of.
207 208


Wim Taymans's avatar
Wim Taymans committed
209 210 211 212 213
<!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
<para>
Gets the offset in the source file of this buffer.
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
214
@buf: a #GstBuffer to get offset of.
Wim Taymans's avatar
Wim Taymans committed
215 216


217 218
<!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
<para>
219
Gets the bufferpool for this buffer.
220 221
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
222 223
@buf: a #GstBuffer to get the bufferpool of.
@Returns: the #GstBufferPool of this buffer.
224 225 226 227


<!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
<para>
228
Gets the bufferpool private data.
229 230
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
231
@buf: a #GstBuffer to get bufferpool's private data of.
232 233


Wim Taymans's avatar
Wim Taymans committed
234
<!-- ##### ENUM GstBufferFlag ##### -->
235
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
236
A set of buffer flags used to describe properties of a #GstBuffer.
237 238
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
239 240 241 242 243 244 245 246 247 248 249 250 251
@GST_BUFFER_READONLY: the buffer is read-only.
@GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be 
                       found with the GST_BUFFER_POOL_PRIVATE() macro.
@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_DISCONTINUOUS: the buffer is the first one after a discontinuity 
                          in the stream.
@GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be 
                      decoded independently of other buffers.
@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.
252 253 254

<!-- ##### STRUCT GstBuffer ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
255
The basic structure of a buffer.
256 257 258 259 260 261 262
</para>

@data_type: 
@data: 
@size: 
@maxsize: 
@timestamp: 
263
@duration: 
Andy Wingo Wingo's avatar
Andy Wingo Wingo committed
264
@offset: 
Benjamin Otte's avatar
Benjamin Otte committed
265
@offset_end: 
266 267 268 269 270 271 272 273 274 275 276
@pool: 
@pool_private: 

<!-- ##### FUNCTION gst_buffer_new ##### -->
<para>

</para>

@Returns: 


Wim Taymans's avatar
Wim Taymans committed
277 278 279 280 281 282 283 284 285
<!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
<para>

</para>

@size: 
@Returns: 


Wim Taymans's avatar
Wim Taymans committed
286 287 288 289 290 291 292 293 294 295
<!-- ##### MACRO gst_buffer_set_data ##### -->
<para>
A convenience function to set the data and size on a buffer
</para>

@buf: The buffer to modify
@data: The data to set on the buffer
@size: The size to set on the buffer


296 297 298 299 300 301 302 303 304 305 306
<!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
<para>

</para>

@pool: 
@offset: 
@size: 
@Returns: 


Wim Taymans's avatar
Wim Taymans committed
307
<!-- ##### FUNCTION gst_buffer_default_free ##### -->
308 309 310 311 312 313 314
<para>

</para>

@buffer: 


Wim Taymans's avatar
Wim Taymans committed
315
<!-- ##### FUNCTION gst_buffer_default_copy ##### -->
316 317 318 319
<para>

</para>

Wim Taymans's avatar
Wim Taymans committed
320
@buffer: 
321 322 323
@Returns: 


Andy Wingo Wingo's avatar
Andy Wingo Wingo committed
324
<!-- ##### MACRO gst_buffer_ref ##### -->
325
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
326
Increases the refcount of the given buffer by one.
327 328
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
329
@buf: a #GstBuffer to increase the refcount of.
330 331


Andy Wingo Wingo's avatar
Andy Wingo Wingo committed
332
<!-- ##### MACRO gst_buffer_ref_by_count ##### -->
333
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
334
Increases the refcount of the buffer by the given value. 
335 336
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
337 338
@buf: a #GstBuffer to increase the refcount of.
@c: the value to add to the refcount.
339 340


Andy Wingo Wingo's avatar
Andy Wingo Wingo committed
341
<!-- ##### MACRO gst_buffer_unref ##### -->
342
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
343
Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
Wim Taymans's avatar
Wim Taymans committed
344 345 346
will be freed.
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
347
@buf: a #GstBuffer to unref.
Wim Taymans's avatar
Wim Taymans committed
348 349 350 351


<!-- ##### MACRO gst_buffer_copy ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
352
Copies the given buffer using the copy function of the parent GstData structure.
Wim Taymans's avatar
Wim Taymans committed
353 354
</para>

Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
355 356
@buf: a #GstBuffer to copy.
@Returns: a new #GstBuffer copy of the buffer.
Wim Taymans's avatar
Wim Taymans committed
357 358 359 360


<!-- ##### MACRO gst_buffer_copy_on_write ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
361 362 363 364
This function returns a buffer that is safe to write to.
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.
Wim Taymans's avatar
Wim Taymans committed
365 366
</para>

Wim Taymans's avatar
Wim Taymans committed
367
@buf: a #GstBuffer to copy
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
368
@Returns: the #GstBuffer that can safely be written to.
Wim Taymans's avatar
Wim Taymans committed
369

370

Wim Taymans's avatar
Wim Taymans committed
371 372
<!-- ##### MACRO gst_buffer_free ##### -->
<para>
Thomas Vander Stichele's avatar
Thomas Vander Stichele committed
373 374
Frees the given buffer, regardless of the refcount. 
It is dangerous to use this function, you should use gst_buffer_unref() instead.
375 376
</para>

Wim Taymans's avatar
Wim Taymans committed
377
@buf: a #GstBuffer to free.
378 379


Wim Taymans's avatar
Wim Taymans committed
380 381 382 383 384 385 386 387 388 389 390 391
<!-- ##### FUNCTION gst_buffer_create_sub ##### -->
<para>

</para>

@parent: 
@offset: 
@size: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_merge ##### -->
392 393 394 395 396 397 398 399 400
<para>

</para>

@buf1: 
@buf2: 
@Returns: 


Wim Taymans's avatar
Wim Taymans committed
401
<!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422
<para>

</para>

@buf1: 
@buf2: 
@Returns: 


<!-- ##### FUNCTION gst_buffer_span ##### -->
<para>

</para>

@buf1: 
@offset: 
@buf2: 
@len: 
@Returns: