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:
 238 <!-- # Unused Parameters # -->
 239 @dstbuf: the destination buffer
 240
 241
 242 <!-- ##### USER_FUNCTION GstBufferFreeFunc ##### -->
 243 <para>
 244 The function called when the buffer data has to be freed
 245 </para>
 246
 247 @buf: the buffer to clear the buffer data of.
 248
 249
 250 <!-- ##### ENUM GstBufferFlags ##### -->
 251 <para>
 252
 253 </para>
 254
 255 @GST_BUFFER_READONLY: the buffer is read only
 256 @GST_BUFFER_ORIGINAL: this buffer not a copy
 257 @GST_BUFFER_DONTFREE: do not try to free the data when this buffer is unref-ed
 258 @GST_BUFFER_FLUSH: this buffer is not related to previous buffers. This flag is mainly
 259 used when data in a stream has been skipped
 260 @GST_BUFFER_EOS: this buffer is the last one in the stream
 261 @GST_BUFFER_DISCONTINUOUS: The buffer has a discontinuity
 262
 263 <!-- ##### STRUCT GstBuffer ##### -->
 264 <para>
 265
 266 </para>
 267
 268 @data_type:
 269 @lock:
 270 @data:
 271 @size:
 272 @maxsize:
 273 @offset:
 274 @timestamp:
 275 @maxage:
 276 @parent:
 277 @pool:
 278 @pool_private:
 279 @free:
 280
 281 <!-- ##### FUNCTION gst_buffer_new ##### -->
 282 <para>
 283
 284 </para>
 285
 286 @Returns:
 287
 288
 289 <!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
 290 <para>
 291
 292 </para>
 293
 294 @pool:
 295 @offset:
 296 @size:
 297 @Returns:
 298 <!-- # Unused Parameters # -->
 299 @location:
 300
 301
 302 <!-- ##### FUNCTION gst_buffer_copy ##### -->
 303 <para>
 304
 305 </para>
 306
 307 @buffer:
 308 @Returns:
 309
 310
 311 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 312 <para>
 313
 314 </para>
 315
 316 @parent:
 317 @offset:
 318 @size:
 319 @Returns:
 320
 321
 322 <!-- ##### FUNCTION gst_buffer_append ##### -->
 323 <para>
 324
 325 </para>
 326
 327 @buffer:
 328 @append:
 329 @Returns:
 330 <!-- # Unused Parameters # -->
 331 @buf:
 332 @buf2:
 333
 334
 335 <!-- ##### FUNCTION gst_buffer_ref ##### -->
 336 <para>
 337
 338 </para>
 339
 340 @buffer:
 341
 342
 343 <!-- ##### FUNCTION gst_buffer_ref_by_count ##### -->
 344 <para>
 345
 346 </para>
 347
 348 @buffer:
 349 @count:
 350
 351
 352 <!-- ##### FUNCTION gst_buffer_unref ##### -->
 353 <para>
 354
 355 </para>
 356
 357 @buffer:
 358
 359
 360 <!-- ##### FUNCTION gst_buffer_destroy ##### -->
 361 <para>
 362
 363 </para>
 364
 365 @buffer:
 366
 367
 368 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 369 <para>
 370
 371 </para>
 372
 373 @buf1:
 374 @buf2:
 375 @Returns:
 376
 377
 378 <!-- ##### FUNCTION gst_buffer_merge ##### -->
 379 <para>
 380
 381 </para>
 382
 383 @buf1:
 384 @buf2:
 385 @Returns:
 386
 387
 388 <!-- ##### FUNCTION gst_buffer_span ##### -->
 389 <para>
 390
 391 </para>
 392
 393 @buf1:
 394 @offset:
 395 @buf2:
 396 @len:
 397 @Returns:
 398
 399