docs/gst/tmpl/gstbuffer.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstBuffer
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Data-passing buffer type, supporting sub-buffers.
   6
   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;
  23
  24   ...
  25
  26   size = width * height * bpp;
  27
  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 gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  41 done when you want to keep a handle to the buffer after pushing it to the
  42 next element.
  43 </para>
  44 <para>
  45 To efficiently create a smaller buffer out of an existing one, you can
  46 use gst_buffer_create_sub().
  47 </para>
  48 <para>
  49 If the plug-in wants to modify the buffer in-place, it should first obtain
  50 a buffer that is safe to modify by using gst_buffer_copy_on_write().  This
  51 function is optimized so that a copy will only be made when it is necessary.
  52 </para>
  53 <para>
  54 Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET()
  55 and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
  56 a certain #GstBufferFlag is set.
  57 </para>
  58 <para>
  59 Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and
  60 gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
  61 </para>
  62 <para>
  63 An element should either unref the buffer or push it out on a src pad
  64 using gst_pad_push() (see #GstPad).
  65
  66 Buffers usually are freed by unreffing them with gst_buffer_unref().
  67 Do not use gst_buffer_free() : this function effectively frees the buffer
  68 regardless of the refcount, which is dangerous.
  69 </para>
  70
  71 <para>
  72 Last reviewed on August 30th, 2002 (0.4.0.1)
  73 </para>
  74
  75 <!-- ##### SECTION See_Also ##### -->
  76 <para>
  77 #GstBufferPool, #GstPad, #GstData
  78 </para>
  79
  80 <!-- ##### STRUCT GstBuffer ##### -->
  81 <para>
  82 The basic structure of a buffer.
  83 </para>
  84
  85 @data_type:
  86 @data:
  87 @size:
  88 @maxsize:
  89 @timestamp:
  90 @duration:
  91 @offset:
  92 @offset_end:
  93 @free_data:
  94 @buffer_private:
  95 @_gst_reserved:
  96
  97 <!-- ##### USER_FUNCTION GstBufferFreeDataFunc ##### -->
  98 <para>
  99
 100 </para>
 101
 102 @buffer:
 103
 104
 105 <!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
 106 <para>
 107 The name used for tracing memory allocations
 108 </para>
 109
 110
 111
 112 <!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
 113 <para>
 114 Gets a handle to the refcount structure of the buffer.
 115 </para>
 116
 117 @buf: a #GstBuffer to get the refcount structure of.
 118
 119
 120 <!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
 121 <para>
 122 Gets the current refcount value of the buffer.
 123 </para>
 124
 125 @buf: a #GstBuffer to get the refcount value of.
 126
 127
 128 <!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
 129 <para>
 130 Calls the buffer-specific copy function on the given buffer.
 131 </para>
 132
 133 @buf: a #GstBuffer to copy.
 134
 135
 136 <!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
 137 <para>
 138 Calls the buffer-specific free function on the given buffer.
 139 </para>
 140
 141 @buf: a #GstBuffer to free.
 142
 143
 144 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
 145 <para>
 146 Gets the flags from this buffer.
 147 </para>
 148
 149 @buf: a #GstBuffer to retrieve the flags from.
 150
 151
 152 <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
 153 <para>
 154 Gives the status of a given flag of a buffer.
 155 </para>
 156
 157 @buf: a #GstBuffer to query flags of.
 158 @flag: the #GstBufferFlag to check.
 159
 160
 161 <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
 162 <para>
 163 Sets a buffer flag.
 164 </para>
 165
 166 @buf: a #GstBuffer to modify flags of.
 167 @flag: the #GstBufferFlag to set.
 168
 169
 170 <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
 171 <para>
 172 Clears a buffer flag.
 173 </para>
 174
 175 @buf: a #GstBuffer to modify flags of.
 176 @flag: the #GstBufferFlag to clear.
 177
 178
 179 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
 180 <para>
 181 Retrieves a pointer to the data element of this buffer.
 182 </para>
 183
 184 @buf: a #GstBuffer to get data pointer of.
 185 @Returns: the pointer to the actual data contents of the buffer.
 186
 187
 188 <!-- ##### MACRO GST_BUFFER_SIZE ##### -->
 189 <para>
 190 Gets the size of the data in this buffer.
 191 </para>
 192
 193 @buf: a #GstBuffer to get data size of.
 194
 195
 196 <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
 197 <para>
 198 Gets the maximum size of this buffer.
 199 </para>
 200
 201 @buf: a #GstBuffer to get maximum size of.
 202
 203
 204 <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
 205 <para>
 206 Gets the timestamp for this buffer.
 207 </para>
 208
 209 @buf: a #GstBuffer to get timestamp of.
 210
 211
 212 <!-- ##### MACRO GST_BUFFER_DURATION ##### -->
 213 <para>
 214
 215 </para>
 216
 217 @buf:
 218
 219
 220 <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
 221 <para>
 222 Gets the offset in the source file of this buffer.
 223 </para>
 224
 225 @buf: a #GstBuffer to get offset of.
 226
 227
 228 <!-- ##### MACRO GST_BUFFER_OFFSET_END ##### -->
 229 <para>
 230
 231 </para>
 232
 233 @buf:
 234
 235
 236 <!-- ##### MACRO GST_BUFFER_FREE_DATA_FUNC ##### -->
 237 <para>
 238
 239 </para>
 240
 241 @buf:
 242
 243
 244 <!-- ##### MACRO GST_BUFFER_PRIVATE ##### -->
 245 <para>
 246
 247 </para>
 248
 249 @buf:
 250
 251
 252 <!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
 253 <para>
 254
 255 </para>
 256
 257
 258
 259 <!-- ##### MACRO GST_BUFFER_MAXSIZE_NONE ##### -->
 260 <para>
 261
 262 </para>
 263
 264
 265
 266 <!-- ##### MACRO GST_BUFFER_DURATION_IS_VALID ##### -->
 267 <para>
 268
 269 </para>
 270
 271 @buffer:
 272
 273
 274 <!-- ##### MACRO GST_BUFFER_TIMESTAMP_IS_VALID ##### -->
 275 <para>
 276
 277 </para>
 278
 279 @buffer:
 280
 281
 282 <!-- ##### MACRO GST_BUFFER_OFFSET_IS_VALID ##### -->
 283 <para>
 284
 285 </para>
 286
 287 @buffer:
 288
 289
 290 <!-- ##### MACRO GST_BUFFER_OFFSET_END_IS_VALID ##### -->
 291 <para>
 292
 293 </para>
 294
 295 @buffer:
 296
 297
 298 <!-- ##### MACRO GST_BUFFER_MAXSIZE_IS_VALID ##### -->
 299 <para>
 300
 301 </para>
 302
 303 @buffer:
 304
 305
 306 <!-- ##### ENUM GstBufferFlag ##### -->
 307 <para>
 308 A set of buffer flags used to describe properties of a #GstBuffer.
 309 </para>
 310
 311 @GST_BUFFER_READONLY: the buffer is read-only.
 312 @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
 313                        found with the GST_BUFFER_POOL_PRIVATE() macro.
 314 @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
 315 @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
 316                       unreferenced.
 317 @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
 318                       decoded independently of other buffers.
 319 @GST_BUFFER_DONTKEEP:
 320 @GST_BUFFER_IN_CAPS:
 321 @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
 322
 323 <!-- ##### FUNCTION gst_buffer_new ##### -->
 324 <para>
 325
 326 </para>
 327
 328 @Returns:
 329
 330
 331 <!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
 332 <para>
 333
 334 </para>
 335
 336 @size:
 337 @Returns:
 338
 339
 340 <!-- ##### MACRO gst_buffer_set_data ##### -->
 341 <para>
 342 A convenience function to set the data and size on a buffer
 343 </para>
 344
 345 @buf: The buffer to modify
 346 @data: The data to set on the buffer
 347 @size: The size to set on the buffer
 348
 349
 350 <!-- ##### MACRO gst_buffer_ref ##### -->
 351 <para>
 352 Increases the refcount of the given buffer by one.
 353 </para>
 354
 355 @buf: a #GstBuffer to increase the refcount of.
 356
 357
 358 <!-- ##### MACRO gst_buffer_ref_by_count ##### -->
 359 <para>
 360 Increases the refcount of the buffer by the given value.
 361 </para>
 362
 363 @buf: a #GstBuffer to increase the refcount of.
 364 @c: the value to add to the refcount.
 365
 366
 367 <!-- ##### MACRO gst_buffer_unref ##### -->
 368 <para>
 369 Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
 370 will be freed.
 371 </para>
 372
 373 @buf: a #GstBuffer to unref.
 374
 375
 376 <!-- ##### FUNCTION gst_buffer_stamp ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @dest:
 382 @src:
 383
 384
 385 <!-- ##### MACRO gst_buffer_copy ##### -->
 386 <para>
 387 Copies the given buffer using the copy function of the parent GstData structure.
 388 </para>
 389
 390 @buf: a #GstBuffer to copy.
 391 @Returns: a new #GstBuffer copy of the buffer.
 392
 393
 394 <!-- ##### MACRO gst_buffer_is_writable ##### -->
 395 <para>
 396
 397 </para>
 398
 399 @buf:
 400
 401
 402 <!-- ##### MACRO gst_buffer_copy_on_write ##### -->
 403 <para>
 404 This function returns a buffer that is safe to write to.
 405 Copy the buffer if the refcount > 1 so that the newly
 406 created buffer can be safely written to.
 407 If the refcount is 1, this function just returns the original buffer.
 408 </para>
 409
 410 @buf: a #GstBuffer to copy
 411 @Returns: the #GstBuffer that can safely be written to.
 412
 413
 414 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 415 <para>
 416
 417 </para>
 418
 419 @parent:
 420 @offset:
 421 @size:
 422 @Returns:
 423
 424
 425 <!-- ##### FUNCTION gst_buffer_join ##### -->
 426 <para>
 427
 428 </para>
 429
 430 @buf1:
 431 @buf2:
 432 @Returns:
 433
 434
 435 <!-- ##### FUNCTION gst_buffer_merge ##### -->
 436 <para>
 437
 438 </para>
 439
 440 @buf1:
 441 @buf2:
 442 @Returns:
 443
 444
 445 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 446 <para>
 447
 448 </para>
 449
 450 @buf1:
 451 @buf2:
 452 @Returns:
 453
 454
 455 <!-- ##### FUNCTION gst_buffer_span ##### -->
 456 <para>
 457
 458 </para>
 459
 460 @buf1:
 461 @offset:
 462 @buf2:
 463 @len:
 464 @Returns:
 465
 466
 467 <!-- ##### FUNCTION gst_buffer_default_free ##### -->
 468 <para>
 469
 470 </para>
 471
 472 @buffer:
 473
 474
 475 <!-- ##### FUNCTION gst_buffer_default_copy ##### -->
 476 <para>
 477
 478 </para>
 479
 480 @buffer:
 481 @Returns:
 482
 483