docs/gst/tmpl/gstbuffer.sgml

   1 <!-- ##### SECTION Title ##### -->
   2 GstBuffer
   3
   4 <!-- ##### SECTION Short_Description ##### -->
   5 Data-passing buffer type, supporting sub-buffers and metadata
   6
   7 <!-- ##### SECTION Long_Description ##### -->
   8 <para>
   9 Buffers are the basic unit of data transfer in GST.  The GstBuffer type
  10 provides all the state necessary to define a region of memory as part of a
  11 stream.  Sub-buffer 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.  Metadata is supported as a list of
  14 pointers to arbitrary metadata.
  15 </para>
  16 <para>
  17 Buffers are usually created with gst_buffer_new(). After a buffer has been
  18 created one will typically allocate memory for it and set the size of the
  19 buffer data.
  20 <programlisting>
  21   GstBuffer *buffer;
  22   gint size, widht, height, bpp;
  23
  24   size = width * height * bpp;
  25
  26   buffer = gst_buffer_new ();
  27   GST_BUFFER_SIZE (buffer) = size;
  28   GST_BUFFER_DATA (buffer) = g_alloc (size);
  29   ...
  30
  31 </programlisting>
  32 </para>
  33 <para>
  34 GstBuffers can also be created from a GstBufferPool with
  35 gst_buffer_new_from_pool(). The bufferpool can be obtained from a
  36 peer element with gst_pad_get_bufferpool().
  37 </para>
  38 <para>
  39 gst_buffer_ref() is used to increase the refcount of a buffer. This must be
  40 done when you want to keep a handle to the buffer after pushing it to the
  41 next element.
  42 </para>
  43 <para>
  44 To efficiently create a smaller buffer out of an existing one, you can
  45 use gst_buffer_create_sub().
  46 </para>
  47 <para>
  48 Several flags of the buffer can be set and unset with the GST_BUFFER_FLAG_SET()
  49 and GST_BUFFER_FLAG_UNSET() macros. Use GST_BUFFER_FLAG_IS_SET() to test it
  50 a certain flag is set.
  51 </para>
  52 <para>
  53 Buffers usually are freed by unreffing them with gst_buffer_unref().
  54 gst_buffer_destroy() can also be used to effectively destroy the buffer
  55 regardless of the refcount (dangerous).
  56 </para>
  57
  58 <!-- ##### SECTION See_Also ##### -->
  59 <para>
  60 #GstBufferPool, #GstPad, #GstData
  61 </para>
  62
  63 <!-- ##### MACRO GST_IS_BUFFER ##### -->
  64 <para>
  65 Check if the object is a buffer.
  66 </para>
  67
  68 @buf: The object to check
  69
  70
  71 <!-- ##### MACRO GST_BUFFER ##### -->
  72 <para>
  73 Cast an object to a GstBuffer
  74 </para>
  75
  76 @buf: The object to cast.
  77
  78
  79 <!-- ##### MACRO GST_BUFFER_FLAGS ##### -->
  80 <para>
  81 Get the flags from this buffer.
  82 </para>
  83
  84 @buf: GstBuffer to retrieve the flags from
  85
  86
  87 <!-- ##### MACRO GST_BUFFER_FLAG_IS_SET ##### -->
  88 <para>
  89 Gives the status of a given flag.
  90 </para>
  91
  92 @buf: GstBuffer to query
  93 @flag: the flag to check
  94
  95
  96 <!-- ##### MACRO GST_BUFFER_FLAG_SET ##### -->
  97 <para>
  98 Set a flag in a buffer.
  99 </para>
 100
 101 @buf: GstBuffer to query
 102 @flag: the flag to set
 103
 104
 105 <!-- ##### MACRO GST_BUFFER_FLAG_UNSET ##### -->
 106 <para>
 107 Clear a flag in a buffer.
 108 </para>
 109
 110 @buf: GstBuffer to modify
 111 @flag: the flag to clear
 112
 113
 114 <!-- ##### MACRO GST_BUFFER_DATA ##### -->
 115 <para>
 116 Retrieves a pointer to the data element of this buffer
 117 </para>
 118
 119 @buf: GstBuffer
 120
 121
 122 <!-- ##### MACRO GST_BUFFER_SIZE ##### -->
 123 <para>
 124 Get the size of the data in this buffer.
 125 </para>
 126
 127 @buf: GstBuffer
 128
 129
 130 <!-- ##### MACRO GST_BUFFER_OFFSET ##### -->
 131 <para>
 132 Get the offset in the source file of this buffer.
 133 </para>
 134
 135 @buf: GstBuffer
 136
 137
 138 <!-- ##### MACRO GST_BUFFER_MAXSIZE ##### -->
 139 <para>
 140 Gets the maximun size of this buffer.
 141 </para>
 142
 143 @buf: GstBuffer
 144
 145
 146 <!-- ##### MACRO GST_BUFFER_TIMESTAMP ##### -->
 147 <para>
 148 Get the timestamp for this buffer.
 149 </para>
 150
 151 @buf: GstBuffer
 152
 153
 154 <!-- ##### MACRO GST_BUFFER_BUFFERPOOL ##### -->
 155 <para>
 156 Get the bufferpool for this buffer.
 157 </para>
 158
 159 @buf: GstBuffer
 160
 161
 162 <!-- ##### MACRO GST_BUFFER_POOL_PRIVATE ##### -->
 163 <para>
 164 Get the bufferpool private data.
 165 </para>
 166
 167 @buf: GstBuffer
 168
 169
 170 <!-- ##### MACRO GST_BUFFER_LOCK ##### -->
 171 <para>
 172 This macro will obtain a lock on the object, making serialization
 173 possible.
 174
 175 </para>
 176
 177 @buf: GstBuffer to lock
 178
 179
 180 <!-- ##### MACRO GST_BUFFER_TRYLOCK ##### -->
 181 <para>
 182 This macro will try to obtain a lock on the object, but will return with
 183 FALSE if it can't get it immediately.
 184
 185 </para>
 186
 187 @buf: GstBuffer to try to lock
 188
 189
 190 <!-- ##### MACRO GST_BUFFER_UNLOCK ##### -->
 191 <para>
 192 This macro releases a lock on the object.
 193
 194 </para>
 195
 196 @buf: GstBuffer to unlock.
 197
 198
 199 <!-- ##### MACRO GST_BUFFER_PARENT ##### -->
 200 <para>
 201 Get the parent of this buffer. The parent is set on subbuffers.
 202 </para>
 203
 204 @buf: GstBuffer to get the parent of.
 205
 206
 207 <!-- ##### MACRO GST_BUFFER_MAXAGE ##### -->
 208 <para>
 209 Get the maximun age of a buffer.
 210 </para>
 211
 212 @buf: GstBuffer to get the maxage of.
 213
 214
 215 <!-- ##### MACRO GST_BUFFER_COPY_FUNC ##### -->
 216 <para>
 217 Call the buffer specific copy function on the given buffer.
 218 </para>
 219
 220 @buf: the buffer to copy.
 221
 222
 223 <!-- ##### MACRO GST_BUFFER_FREE_FUNC ##### -->
 224 <para>
 225 Call the buffer specific free function on the given buffer.
 226 </para>
 227
 228 @buf: the buffer to free.
 229
 230
 231 <!-- ##### USER_FUNCTION GstBufferCopyFunc ##### -->
 232 <para>
 233 This function is used to copy the buffer contents.
 234 </para>
 235
 236 @srcbuf: the src buffer
 237 @Returns: The copied buffer
 238
 239
 240 <!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
 241 <para>
 242 The function called when the buffer data has to be freed
 243 </para>
 244
 245 @buf: the buffer to clear the buffer data of.
 246
 247
 248 <!-- ##### ENUM GstBufferFlags ##### -->
 249 <para>
 250
 251 </para>
 252
 253 @GST_BUFFER_READONLY: the buffer is read only
 254 @GST_BUFFER_ORIGINAL: this buffer not a copy
 255 @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is unref-ed
 256
 257 <!-- ##### STRUCT GstBuffer ##### -->
 258 <para>
 259
 260 </para>
 261
 262 @data_type:
 263 @lock:
 264 @data:
 265 @size:
 266 @maxsize:
 267 @offset:
 268 @timestamp:
 269 @maxage:
 270 @parent:
 271 @pool:
 272 @pool_private:
 273 @free:
 274 @copy:
 275
 276 <!-- ##### FUNCTION gst_buffer_new ##### -->
 277 <para>
 278
 279 </para>
 280
 281 @Returns:
 282
 283
 284 <!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
 285 <para>
 286
 287 </para>
 288
 289 @pool:
 290 @offset:
 291 @size:
 292 @Returns:
 293 <!-- # Unused Parameters # -->
 294 @location:
 295
 296
 297 <!-- ##### FUNCTION gst_buffer_copy ##### -->
 298 <para>
 299
 300 </para>
 301
 302 @buffer:
 303 @Returns:
 304
 305
 306 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 307 <para>
 308
 309 </para>
 310
 311 @parent:
 312 @offset:
 313 @size:
 314 @Returns:
 315
 316
 317 <!-- ##### FUNCTION gst_buffer_append ##### -->
 318 <para>
 319
 320 </para>
 321
 322 @buffer:
 323 @append:
 324 @Returns:
 325 <!-- # Unused Parameters # -->
 326 @buf:
 327 @buf2:
 328
 329
 330 <!-- ##### FUNCTION gst_buffer_ref ##### -->
 331 <para>
 332
 333 </para>
 334
 335 @buffer:
 336
 337
 338 <!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
 339 <para>
 340
 341 </para>
 342
 343 @buffer:
 344 @count:
 345
 346
 347 <!-- ##### FUNCTION gst_buffer_unref ##### -->
 348 <para>
 349
 350 </para>
 351
 352 @buffer:
 353
 354
 355 <!-- ##### FUNCTION gst_buffer_destroy ##### -->
 356 <para>
 357
 358 </para>
 359
 360 @buffer:
 361
 362
 363 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 364 <para>
 365
 366 </para>
 367
 368 @buf1:
 369 @buf2:
 370 @Returns:
 371
 372
 373 <!-- ##### FUNCTION gst_buffer_merge ##### -->
 374 <para>
 375
 376 </para>
 377
 378 @buf1:
 379 @buf2:
 380 @Returns:
 381
 382
 383 <!-- ##### FUNCTION gst_buffer_span ##### -->
 384 <para>
 385
 386 </para>
 387
 388 @buf1:
 389 @offset:
 390 @buf2:
 391 @len:
 392 @Returns:
 393
 394
 395 <!-- ##### FUNCTION gst_buffer_print_stats ##### -->
 396 <para>
 397
 398 </para>
 399
 400
 401