wearable/docs/design/part-bufferlist.txt

   1 Buffer Lists
   2 ------------
   3
   4 GstBuffer provides a datastructure to manage:
   5
   6  - a continuous region of memory
   7  - functions to copy/free the memory
   8  - metadata associated with that memory such as timestamps and caps.
   9
  10 It is the primary means of transfering data between pads and elements.
  11
  12 GstBufferList expands on GstBuffer to allow multiple GstBuffers (conceptually
  13 organized in a list) to be treated as a multiple groups of GstBuffers. This allows
  14 for the following extra functionality:
  15
  16  - A logical GstBuffer (called a group) can consist of disjoint memory each with
  17    their own copy/free and metadata. Logically the group should be treated as
  18    one single GstBuffer.
  19  - Multiple groups can be put into one bufferlist. This allows for a single
  20    method call to pass multiple (logical) buffers downstream.
  21
  22
  23 Use cases
  24 ~~~~~~~~~
  25
  26 A typical use case for multimedia pipelines is to append or remove 'headers'
  27 from packets of data.
  28
  29 Generating RTP packets from h264 video
  30 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  31
  32 We receive as input a GstBuffer with an encoded h264 image and we need to
  33 create RTP packets containing this h264 data as the payload. We typically need
  34 to fragment the h264 data into multiple packets, each with their own RTP and
  35 payload specific header.
  36
  37                        +-------+-------+---------------------------+--------+
  38   input H264 buffer:   | NALU1 | NALU2 |  .....                    | NALUx  |
  39                        +-------+-------+---------------------------+--------+
  40                              |
  41                              V
  42                        +-+ +-------+  +-+ +-------+            +-+ +-------+
  43   output bufferlist:   | | | NALU1 |  | | | NALU2 |   ....     | | | NALUx |
  44                        +-+ +-------+  +-+ +-------+            +-+ +-------+
  45                        :           :  :           :
  46                        \-----------/  \-----------/
  47                          group 1        group 2
  48
  49 The output bufferlist consists of x groups consisting of an RTP payload header
  50 and a subbuffer of the original input H264 buffer. Since the rtp headers and
  51 the h264 data don't need to be contiguous in memory, we can avoid to memcpy the
  52 h264 data into the rtp packets.
  53
  54 Since we can generate a bufferlist with multiple groups, we can push all the
  55 RTP packets for the input data to the next element in one operation.
  56
  57 A typical udpsink will then use something like sendmsg to send the groups on
  58 the network inside one UDP packet. This will further avoid having to memcpy
  59 data into contiguous memory.
  60
  61
  62 API
  63 ~~~
  64
  65 The GstBufferList is an opaque data structure and is operated on using an
  66 iterator. It derives from GstMiniObject so that it has basic refcounting and
  67 copy/free functions.
  68
  69 The bufferlist is writable when its refcount is 1 and it's not marked as
  70 readonly. A writable bufferlist means that elements can be added and removed
  71 form the list but it does not mean that the actual buffers in the list are
  72 writable.
  73
  74 To modify the data in the buffers of the bufferlist, both the list and the
  75 buffer must be writable.
  76
  77 Methods exist for navigating the groups in the list and the buffers inside a
  78 group.
  79
  80
  81 Metadata
  82 ~~~~~~~~
  83
  84 Each of the buffers inside the bufferlist can have metadata associated with it.
  85
  86 The metadata of the bufferlist is always the metadata of the first buffer of the
  87 first group in the bufferlist. This means that:
  88
  89   - Before pushing the list to a pad, negotiation happens with (only) the caps of
  90     the first buffer in the list. Caps of other buffers is ignore.
  91
  92   - synchronisation happens on the timestamp of the first buffer in the list.
  93
  94 This allows for efficient (re)timestamping and re-typing (caps) of a group of
  95 buffers without having to modify each of the buffer's metadata.
  96