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 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).
  70
  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>
  75
  76 <para>
  77 Last reviewed on August 30th, 2002 (0.4.0.1)
  78 </para>
  79
  80 <!-- ##### SECTION See_Also ##### -->
  81 <para>
  82 #GstBufferPool, #GstPad, #GstData
  83 </para>
  84
  85 <!-- ##### MACRO GST_BUFFER_TRACE_NAME ##### -->
  86 <para>
  87 The name used for tracing memory allocations
  88 </para>
  89
  90
  91
  92 <!-- ##### MACRO GST_BUFFER ##### -->
  93 <para>
  94 Casts an object to a GstBuffer.
  95 </para>
  96
  97 @buf: an object to cast.
  98 @Returns: the #GstBuffer to which the given object points.
  99
 100
 101 <!-- ##### MACRO GST_IS_BUFFER ##### -->
 102 <para>
 103 Checks if the pointer is a GstBuffer.
 104 </para>
 105
 106 @buf: a pointer to query.
 107
 108
 109 <!-- ##### MACRO GST_BUFFER_REFCOUNT ##### -->
 110 <para>
 111 Gets a handle to the refcount structure of the buffer.
 112 </para>
 113
 114 @buf: a #GstBuffer to get the refcount structure of.
 115
 116
 117 <!-- ##### MACRO GST_BUFFER_REFCOUNT_VALUE ##### -->
 118 <para>
 119 Gets the current refcount value of the buffer.
 120 </para>
 121
 122 @buf: a #GstBuffer to get the refcount value of.
 123
 124
 125 <!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
 126 <para>
 127 Calls the buffer-specific copy function on the given buffer.
 128 </para>
 129
 130 @buf: a #GstBuffer to copy.
 131
 132
 133 <!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
 134 <para>
 135 Calls the buffer-specific free function on the given buffer.
 136 </para>
 137
 138 @buf: a #GstBuffer to free.
 139
 140
 141 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
 142 <para>
 143 Gets the flags from this buffer.
 144 </para>
 145
 146 @buf: a #GstBuffer to retrieve the flags from.
 147
 148
 149 <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
 150 <para>
 151 Gives the status of a given flag of a buffer.
 152 </para>
 153
 154 @buf: a #GstBuffer to query flags of.
 155 @flag: the #GstBufferFlag to check.
 156
 157
 158 <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
 159 <para>
 160 Sets a buffer flag.
 161 </para>
 162
 163 @buf: a #GstBuffer to modify flags of.
 164 @flag: the #GstBufferFlag to set.
 165
 166
 167 <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
 168 <para>
 169 Clears a buffer flag.
 170 </para>
 171
 172 @buf: a #GstBuffer to modify flags of.
 173 @flag: the #GstBufferFlag to clear.
 174
 175
 176 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
 177 <para>
 178 Retrieves a pointer to the data element of this buffer.
 179 </para>
 180
 181 @buf: a #GstBuffer to get data pointer of.
 182 @Returns: the pointer to the actual data contents of the buffer.
 183
 184
 185 <!-- ##### MACRO GST_BUFFER_SIZE ##### -->
 186 <para>
 187 Gets the size of the data in this buffer.
 188 </para>
 189
 190 @buf: a #GstBuffer to get data size of.
 191
 192
 193 <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
 194 <para>
 195 Gets the maximum size of this buffer.
 196 </para>
 197
 198 @buf: a #GstBuffer to get maximum size of.
 199
 200
 201 <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
 202 <para>
 203 Gets the timestamp for this buffer.
 204 </para>
 205
 206 @buf: a #GstBuffer to get timestamp of.
 207
 208
 209 <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
 210 <para>
 211 Gets the offset in the source file of this buffer.
 212 </para>
 213
 214 @buf: a #GstBuffer to get offset of.
 215
 216
 217 <!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
 218 <para>
 219 Gets the bufferpool for this buffer.
 220 </para>
 221
 222 @buf: a #GstBuffer to get the bufferpool of.
 223 @Returns: the #GstBufferPool of this buffer.
 224
 225
 226 <!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
 227 <para>
 228 Gets the bufferpool private data.
 229 </para>
 230
 231 @buf: a #GstBuffer to get bufferpool's private data of.
 232
 233
 234 <!-- ##### ENUM GstBufferFlag ##### -->
 235 <para>
 236 A set of buffer flags used to describe properties of a #GstBuffer.
 237 </para>
 238
 239 @GST_BUFFER_READONLY: the buffer is read-only.
 240 @GST_BUFFER_SUBBUFFER: the buffer is a subbuffer, the parent buffer can be
 241                        found with the GST_BUFFER_POOL_PRIVATE() macro.
 242 @GST_BUFFER_ORIGINAL: buffer is not a copy of another buffer.
 243 @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is
 244                       unreferenced.
 245 @GST_BUFFER_DISCONTINUOUS: the buffer is the first one after a discontinuity
 246                           in the stream.
 247 @GST_BUFFER_KEY_UNIT: the buffer holds a key unit, a unit that can be
 248                       decoded independently of other buffers.
 249 @GST_BUFFER_PREROLL: the buffer should be decoded but not rendered, it is
 250                      mainly used to resynchronise the stream.
 251 @GST_BUFFER_FLAG_LAST: additional flags can be added starting from this flag.
 252
 253 <!-- ##### STRUCT GstBuffer ##### -->
 254 <para>
 255 The basic structure of a buffer.
 256 </para>
 257
 258 @data_type:
 259 @data:
 260 @size:
 261 @maxsize:
 262 @timestamp:
 263 @duration:
 264 @offset:
 265 @offset_end:
 266 @pool:
 267 @pool_private:
 268 @_gst_reserved:
 269
 270 <!-- ##### FUNCTION gst_buffer_new ##### -->
 271 <para>
 272
 273 </para>
 274
 275 @Returns:
 276
 277
 278 <!-- ##### FUNCTION gst_buffer_new_and_alloc ##### -->
 279 <para>
 280
 281 </para>
 282
 283 @size:
 284 @Returns:
 285
 286
 287 <!-- ##### MACRO gst_buffer_set_data ##### -->
 288 <para>
 289 A convenience function to set the data and size on a buffer
 290 </para>
 291
 292 @buf: The buffer to modify
 293 @data: The data to set on the buffer
 294 @size: The size to set on the buffer
 295
 296
 297 <!-- ##### FUNCTION gst_buffer_default_free ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @buffer:
 303
 304
 305 <!-- ##### FUNCTION gst_buffer_default_copy ##### -->
 306 <para>
 307
 308 </para>
 309
 310 @buffer:
 311 @Returns:
 312
 313
 314 <!-- ##### MACRO gst_buffer_ref ##### -->
 315 <para>
 316 Increases the refcount of the given buffer by one.
 317 </para>
 318
 319 @buf: a #GstBuffer to increase the refcount of.
 320
 321
 322 <!-- ##### MACRO gst_buffer_ref_by_count ##### -->
 323 <para>
 324 Increases the refcount of the buffer by the given value.
 325 </para>
 326
 327 @buf: a #GstBuffer to increase the refcount of.
 328 @c: the value to add to the refcount.
 329
 330
 331 <!-- ##### MACRO gst_buffer_unref ##### -->
 332 <para>
 333 Decreases the refcount of the buffer. If the refcount reaches 0, the buffer
 334 will be freed.
 335 </para>
 336
 337 @buf: a #GstBuffer to unref.
 338
 339
 340 <!-- ##### MACRO gst_buffer_copy ##### -->
 341 <para>
 342 Copies the given buffer using the copy function of the parent GstData structure.
 343 </para>
 344
 345 @buf: a #GstBuffer to copy.
 346 @Returns: a new #GstBuffer copy of the buffer.
 347
 348
 349 <!-- ##### MACRO gst_buffer_copy_on_write ##### -->
 350 <para>
 351 This function returns a buffer that is safe to write to.
 352 Copy the buffer if the refcount > 1 so that the newly
 353 created buffer can be safely written to.
 354 If the refcount is 1, this function just returns the original buffer.
 355 </para>
 356
 357 @buf: a #GstBuffer to copy
 358 @Returns: the #GstBuffer that can safely be written to.
 359
 360
 361 <!-- ##### MACRO gst_buffer_free ##### -->
 362 <para>
 363 Frees the given buffer, regardless of the refcount.
 364 It is dangerous to use this function, you should use gst_buffer_unref() instead.
 365 </para>
 366
 367 @buf: a #GstBuffer to free.
 368
 369
 370 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 371 <para>
 372
 373 </para>
 374
 375 @parent:
 376 @offset:
 377 @size:
 378 @Returns:
 379
 380
 381 <!-- ##### FUNCTION gst_buffer_merge ##### -->
 382 <para>
 383
 384 </para>
 385
 386 @buf1:
 387 @buf2:
 388 @Returns:
 389
 390
 391 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 392 <para>
 393
 394 </para>
 395
 396 @buf1:
 397 @buf2:
 398 @Returns:
 399
 400
 401 <!-- ##### FUNCTION gst_buffer_span ##### -->
 402 <para>
 403
 404 </para>
 405
 406 @buf1:
 407 @offset:
 408 @buf2:
 409 @len:
 410 @Returns:
 411
 412