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 @GST_BUFFER_FLUSH: this buffer is not related to previous buffers. This flag is mainly
 257 used when data in a stream has been skipped
 258 @GST_BUFFER_EOS: this buffer is the last one in the stream
 259 @GST_BUFFER_DISCONTINUOUS: The buffer has a discontinuity
 260
 261 <!-- ##### STRUCT GstBuffer ##### -->
 262 <para>
 263
 264 </para>
 265
 266 @data_type:
 267 @lock:
 268 @data:
 269 @size:
 270 @maxsize:
 271 @offset:
 272 @timestamp:
 273 @maxage:
 274 @parent:
 275 @pool:
 276 @pool_private:
 277 @free:
 278
 279 <!-- ##### FUNCTION gst_buffer_new ##### -->
 280 <para>
 281
 282 </para>
 283
 284 @Returns:
 285
 286
 287 <!-- ##### FUNCTION gst_buffer_new_from_pool ##### -->
 288 <para>
 289
 290 </para>
 291
 292 @pool:
 293 @offset:
 294 @size:
 295 @Returns:
 296 <!-- # Unused Parameters # -->
 297 @location:
 298
 299
 300 <!-- ##### FUNCTION gst_buffer_copy ##### -->
 301 <para>
 302
 303 </para>
 304
 305 @buffer:
 306 @Returns:
 307
 308
 309 <!-- ##### FUNCTION gst_buffer_create_sub ##### -->
 310 <para>
 311
 312 </para>
 313
 314 @parent:
 315 @offset:
 316 @size:
 317 @Returns:
 318
 319
 320 <!-- ##### FUNCTION gst_buffer_append ##### -->
 321 <para>
 322
 323 </para>
 324
 325 @buffer:
 326 @append:
 327 @Returns:
 328 <!-- # Unused Parameters # -->
 329 @buf:
 330 @buf2:
 331
 332
 333 <!-- ##### FUNCTION gst_buffer_ref ##### -->
 334 <para>
 335
 336 </para>
 337
 338 @buffer:
 339
 340
 341 <!-- ##### FUNCTION gst_buffer_unref ##### -->
 342 <para>
 343
 344 </para>
 345
 346 @buffer:
 347
 348
 349 <!-- ##### FUNCTION gst_buffer_destroy ##### -->
 350 <para>
 351
 352 </para>
 353
 354 @buffer:
 355
 356
 357 <!-- ##### FUNCTION gst_buffer_is_span_fast ##### -->
 358 <para>
 359
 360 </para>
 361
 362 @buf1:
 363 @buf2:
 364 @Returns:
 365
 366
 367 <!-- ##### FUNCTION gst_buffer_merge ##### -->
 368 <para>
 369
 370 </para>
 371
 372 @buf1:
 373 @buf2:
 374 @Returns:
 375
 376
 377 <!-- ##### FUNCTION gst_buffer_span ##### -->
 378 <para>
 379
 380 </para>
 381
 382 @buf1:
 383 @offset:
 384 @buf2:
 385 @len:
 386 @Returns:
 387
 388