docs/design/part-buffer.txt

   1 GstBuffer
   2 ---------
   3
   4 This document describes the design for buffers.
   5
   6 A GstBuffer is the object that is passed from an upstream element to a
   7 downstream element and contains memory and metadata information.
   8
   9 Requirements
  10 ~~~~~~~~~~~~
  11
  12  - It must be fast
  13     * allocation, free, low fragmentation
  14  - Must be able to attach multiple memory blocks to the buffer
  15  - Must be able to attach artibtrary metadata to buffers
  16  - efficient handling of subbuffer, copy, span, trim
  17
  18 Writability
  19 -----------
  20
  21 The Buffers is writable when the refcount is 1. This means that:
  22
  23  - metadata can be added/removed and the metadata can be changed
  24  - GstMemory blocks can be added/removed
  25
  26 The individual memory blocks have their own refcounting and READONLY flags
  27 that might influence their writability.
  28
  29 Buffers can be made writable with gst_buffer_make_writable(). This will copy the
  30 buffer with the metadata and will ref the memory in the buffer. This means that
  31 the memory is not automatically copied when copying buffers.
  32
  33
  34 Managing GstMemory
  35 ------------------
  36
  37 A GstBuffer contains an array of pointers to GstMemory objects.
  38
  39 When the buffer is writable, gst_buffer_insert_memory() can be used to add a
  40 new GstMemory object to the buffer. When the array of memory is full, memory
  41 will be merged to make room for the new memory object.
  42
  43 gst_buffer_n_memory() is used to get the amount of memory blocks on the
  44 GstBuffer.
  45
  46 With gst_buffer_peek_memory(), memory can be retrieved from the memory array.
  47 The desired access pattern for the memory block should be specified so that
  48 appropriate checks can be made and, in case of GST_MAP_WRITE, a writable copy
  49 can be constructed when needed.
  50
  51 gst_buffer_remove_memory_range() and gst_buffer_remove_memory() can be used to
  52 remove memory from the GstBuffer.
  53
  54
  55 Subbuffers
  56 ----------
  57
  58 Subbuffers are made by copying only a region of the memory blocks and copying
  59 all of the metadata.
  60
  61
  62 Span
  63 ----
  64
  65 Spanning will merge together the data of 2 buffers into a new buffer
  66
  67
  68 Data access
  69 -----------
  70
  71  Accessing the data of the buffer can happen by retrieving the individual
  72  GstMemory objects in the GstBuffer or my using the gst_buffer_map() and
  73  gst_buffer_unmap() function.
  74
  75  The _map and _unmap function will always return the memory of all blocks as one
  76  large contiguous region of memory. Using the _map and _unmap function might be
  77  more convenient than accessing the individual memory blocks at the expense of
  78  being more expensive because it might perform memcpy operations.
  79
  80  For buffers with only one GstMemory object (the most common case), _map and
  81  _unmap have no performance penalty at all.
  82
  83
  84 * Read access with 1 memory block
  85
  86   The memory block is accessed and mapped for read access.
  87   The memory block is unmapped after usage
  88
  89 * write access with 1 memory block
  90
  91   The buffer should be writable or this operation will fail..
  92   The memory block is accessed. If the memory block is readonly, a copy is made
  93   and the original memory block is replaced with this copy. then the memory
  94   block is mapped in write mode.
  95   The memory block is unmapped after usage.
  96
  97 * Read access with multiple memory blocks
  98
  99   The memory blocks are combined into one large memory block. If the buffer is
 100   writable, The memory blocks are replace with this new memory block. If the
 101   buffer is not writable, the memory is returned as is.
 102   The memory block is then mapped in read mode.
 103
 104   When the memory is unmapped after usage and the buffer has multiple memory
 105   blocks, this means that the map operation was not able to store the combined
 106   buffer and it thus returned memory that should be freed. Otherwise, the memory
 107   is unmapped.
 108
 109 * Write access with multiple memory blocks
 110
 111   The buffer should be writable or the operation fails. The memory blocks are
 112   combined into one large memory block and the existing blocks are replaced with
 113   this new block. The memory is then mapped in write mode.
 114   The memory is unmapped after usage.
 115
 116
 117 Use cases
 118 ---------
 119
 120 Generating RTP packets from h264 video
 121 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 122
 123 We receive as input a GstBuffer with an encoded h264 image and we need to
 124 create RTP packets containing this h264 data as the payload. We typically need
 125 to fragment the h264 data into multiple packets, each with their own RTP and
 126 payload specific header.
 127
 128                        +-------+-------+---------------------------+--------+
 129   input H264 buffer:   | NALU1 | NALU2 |  .....                    | NALUx  |
 130                        +-------+-------+---------------------------+--------+
 131                              |
 132                              V
 133   array of             +-+ +-------+  +-+ +-------+            +-+ +-------+
 134   output buffers:      | | | NALU1 |  | | | NALU2 |   ....     | | | NALUx |
 135                        +-+ +-------+  +-+ +-------+            +-+ +-------+
 136                        :           :  :           :
 137                        \-----------/  \-----------/
 138                          buffer 1        buffer 2
 139
 140 The output buffer array consists of x buffers consisting of an RTP payload header
 141 and a subbuffer of the original input H264 buffer. Since the rtp headers and
 142 the h264 data don't need to be contiguous in memory, they are added to the buffer
 143 as separate GstMemory blocks and we can avoid to memcpy the h264 data into
 144 contiguous memory.
 145
 146 A typical udpsink will then use something like sendmsg to send the memory regions
 147 on the network inside one UDP packet. This will further avoid having to memcpy
 148 data into contiguous memory.
 149
 150 Using bufferlists, the complete array of output buffers can be pushed in one
 151 operation to the peer element.
 152
 153
 154