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