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_MALLOCDATA (buffer) = g_alloc (size);
  33   GST_BUFFER_DATA (buffer) = GST_BUFFER_MALLOCDATA (buffer);
  34   ...
  35   </programlisting>
  36 </example>
  37 </para>
  38 <para>
  39 Alternatively, use gst_buffer_new_and_alloc()
  40 to create a buffer with preallocated data of a given size.
  41 </para>
  42 <para>
  43 If an element knows what pad you will push the buffer out on, it should use
  44 gst_pad_alloc_buffer() instead to create a buffer.  This allows downstream
  45 elements to provide special buffers to write in, like hardware buffers.
  46 </para>
  47 <para>
  48 gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  49 done when you want to keep a handle to the buffer after pushing it to the
  50 next element.
  51 </para>
  52 <para>
  53 To efficiently create a smaller buffer out of an existing one, you can
  54 use gst_buffer_create_sub().
  55 </para>
  56 <para>
  57 If the plug-in wants to modify the buffer in-place, it should first obtain
  58 a buffer that is safe to modify by using gst_buffer_make_writable().  This
  59 function is optimized so that a copy will only be made when it is necessary.
  60 </para>
  61 <para>
  62 Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET()
  63 and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
  64 a certain #GstBufferFlag is set.
  65 </para>
  66 <para>
  67 Buffers can be efficiently merged into a larger buffer with gst_buffer_merge() and
  68 gst_buffer_span() if the gst_buffer_is_span_fast() function returns TRUE.
  69 </para>
  70 <para>
  71 An element should either unref the buffer or push it out on a src pad
  72 using gst_pad_push() (see #GstPad).
  73
  74 Buffers usually are freed by unreffing them with gst_buffer_unref().
  75 Do not use gst_buffer_free() : this function effectively frees the buffer
  76 regardless of the refcount, which is dangerous.
  77 </para>
  78
  79 <para>
  80 Last reviewed on August 12th, 2004 (0.8.5)
  81 </para>
  82
  83 <!-- ##### SECTION See_Also ##### -->
  84 <para>
  85 #GstPad, #GstMiniObject
  86 </para>
  87
  88 <!-- ##### STRUCT GstBuffer ##### -->
  89 <para>
  90 The basic structure of a buffer.
  91 </para>
  92
  93 @mini_object:
  94 @data:
  95 @size:
  96 @timestamp:
  97 @duration:
  98 @caps:
  99 @offset:
 100 @offset_end:
 101
 102 <!-- ##### FUNCTION gst_buffer_new ##### -->
 103 <para>
 104
 105 </para>
 106
 107 @Returns:
 108
 109
 110 <!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
 111 <para>
 112
 113 </para>
 114
 115 @size:
 116 @Returns:
 117
 118
 119 <!-- ##### ENUM GstBufferFlag ##### -->
 120 <para>
 121
 122 </para>
 123
 124 @GST_BUFFER_FLAG_READONLY:
 125 @GST_BUFFER_FLAG_ORIGINAL:
 126 @GST_BUFFER_FLAG_PREROLL:
 127 @GST_BUFFER_FLAG_DISCONT:
 128 @GST_BUFFER_FLAG_IN_CAPS:
 129 @GST_BUFFER_FLAG_GAP:
 130 @GST_BUFFER_FLAG_DELTA_UNIT:
 131 @GST_BUFFER_FLAG_LAST:
 132
 133 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
 134 <para>
 135 Gets the flags from this buffer.
 136 </para>
 137
 138 @buf: a #GstBuffer to retrieve the flags from.
 139
 140
 141 <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
 142 <para>
 143 Gives the status of a given flag of a buffer.
 144 </para>
 145
 146 @buf: a #GstBuffer to query flags of.
 147 @flag: the #GstBufferFlag to check.
 148
 149
 150 <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
 151 <para>
 152 Sets a buffer flag.
 153 </para>
 154
 155 @buf: a #GstBuffer to modify flags of.
 156 @flag: the #GstBufferFlag to set.
 157
 158
 159 <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
 160 <para>
 161 Clears a buffer flag.
 162 </para>
 163
 164 @buf: a #GstBuffer to modify flags of.
 165 @flag: the #GstBufferFlag to clear.
 166
 167
 168 <!-- ##### MACRO gst_buffer_set_data ##### -->
 169 <para>
 170 A convenience function to set the data and size on a buffer
 171 </para>
 172
 173 @buf: The buffer to modify
 174 @data: The data to set on the buffer
 175 @size: The size to set on the buffer
 176
 177
 178 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
 179 <para>
 180 Retrieves a pointer to the data element of this buffer.
 181 </para>
 182
 183 @buf: a #GstBuffer to get data pointer of.
 184 @Returns: the pointer to the actual data contents of the buffer.
 185
 186
 187 <!-- ##### MACRO GST_BUFFER_SIZE ##### -->
 188 <para>
 189 Gets the size of the data in this buffer.
 190 </para>
 191
 192 @buf: a #GstBuffer to get data size of.
 193
 194
 195 <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
 196 <para>
 197 Gets the timestamp for this buffer.
 198 </para>
 199
 200 @buf: a #GstBuffer to get timestamp of.
 201
 202
 203 <!-- ##### MACRO GST_BUFFER_DURATION ##### -->
 204 <para>
 205 Gets the duration in nanoseconds of the data in the buffer.
 206 Value will be GST_CLOCK_TIME_NONE if the duration is unknown.
 207 </para>
 208
 209 @buf: a #GstBuffer to get the duration from.
 210
 211
 212 <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
 213 <para>
 214 Gets the offset in the source file of the beinning of this buffer.
 215 </para>
 216
 217 @buf: a #GstBuffer to get offset of.
 218
 219
 220 <!-- ##### MACRO GST_BUFFER_OFFSET_END ##### -->
 221 <para>
 222 Gets the offset in the source file of the end of this buffer.
 223 </para>
 224
 225 @buf: a #GstBuffer to get offset of.
 226
 227
 228 <!-- ##### MACRO gst_buffer_ref ##### -->
 229 <para>
 230 Increases the refcount of the given buffer by one.
 231 </para>
 232
 233 @buf: a #GstBuffer to increase the refcount of.
 234
 235
 236 <!-- ##### MACRO gst_buffer_unref ##### -->
 237 <para>
 238 Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
 239 will be freed.
 240 </para>
 241
 242 @buf: a #GstBuffer to unref.
 243
 244
 245 <!-- ##### MACRO gst_buffer_copy ##### -->
 246 <para>
 247 Copies the given buffer using the copy function of the parent GstData structure.
 248 </para>
 249
 250 @buf: a #GstBuffer to copy.
 251 @Returns: a new #GstBuffer copy of the buffer.
 252
 253
 254 <!-- ##### MACRO gst_buffer_is_writable ##### -->
 255 <para>
 256 Tests if you can safely write data into a buffer's data array.
 257 </para>
 258
 259 @buf: a #GstBuffer to check
 260
 261
 262 <!-- ##### MACRO gst_buffer_make_writable ##### -->
 263 <para>
 264
 265 </para>
 266
 267 @buf:
 268
 269
 270 <!-- ##### MACRO gst_buffer_replace ##### -->
 271 <para>
 272
 273 </para>
 274
 275 @obuf:
 276 @nbuf:
 277
 278
 279 <!-- ##### FUNCTION gst_buffer_get_caps ##### -->
 280 <para>
 281
 282 </para>
 283
 284 @buffer:
 285 @Returns:
 286
 287
 288 <!-- ##### FUNCTION gst_buffer_set_caps ##### -->
 289 <para>
 290
 291 </para>
 292
 293 @buffer:
 294 @caps:
 295
 296
 297 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @parent:
 303 @offset:
 304 @size:
 305 @Returns:
 306
 307
 308 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 309 <para>
 310
 311 </para>
 312
 313 @buf1:
 314 @buf2:
 315 @Returns:
 316
 317
 318 <!-- ##### FUNCTION gst_buffer_span ##### -->
 319 <para>
 320
 321 </para>
 322
 323 @buf1:
 324 @offset:
 325 @buf2:
 326 @len:
 327 @Returns:
 328
 329
 330 <!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
 331 <para>
 332 The name used for tracing memory allocations
 333 </para>
 334
 335
 336
 337 <!-- ##### MACRO GST_BUFFER_OFFSET_NONE ##### -->
 338 <para>
 339
 340 </para>
 341
 342
 343
 344 <!-- ##### MACRO GST_BUFFER_DURATION_IS_VALID ##### -->
 345 <para>
 346 Tests if the duration is known.
 347 </para>
 348
 349 @buffer: the #GstBuffer to check for the duration
 350
 351
 352 <!-- ##### MACRO GST_BUFFER_TIMESTAMP_IS_VALID ##### -->
 353 <para>
 354 Tests if the timestamp is known.
 355 </para>
 356
 357 @buffer: the #GstBuffer to check for the timestamp
 358
 359
 360 <!-- ##### MACRO GST_BUFFER_OFFSET_IS_VALID ##### -->
 361 <para>
 362
 363 </para>
 364
 365 @buffer:
 366
 367
 368 <!-- ##### MACRO GST_BUFFER_OFFSET_END_IS_VALID ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @buffer:
 374
 375
 376 <!-- ##### FUNCTION gst_buffer_stamp ##### -->
 377 <para>
 378
 379 </para>
 380
 381 @dest:
 382 @src:
 383
 384
 385 <!-- ##### FUNCTION gst_buffer_join ##### -->
 386 <para>
 387
 388 </para>
 389
 390 @buf1:
 391 @buf2:
 392 @Returns:
 393
 394
 395 <!-- ##### FUNCTION gst_buffer_merge ##### -->
 396 <para>
 397
 398 </para>
 399
 400 @buf1:
 401 @buf2:
 402 @Returns:
 403
 404