Allocation
----------

This document outlines the requirements for determining how memory and buffers
will be allocated between to pads.


Overview
~~~~~~~~

After a particular media format has been negotiated between two pads, they must
agree on how to allocate buffers.

The srcpad will always take the initiative to negotiate the allocation
properties. It starts with creating a GST_QUERY_ALLOCATION with the negotiated
caps. 

The srcpad can set the need-pool flag to TRUE in the query to optionally make the
peer pad allocate a bufferpool.

It will then inspect the returned results and configure the returned pool or
create a new pool when needed.

Buffers are then allocated by the srcpad from the negotiated pool.


Allocation query
~~~~~~~~~~~~~~~~

  (in) "caps", GST_TYPE_CAPS
        - the caps that was negotiated

  (in) "need-pool", G_TYPE_BOOLEAN
        - if a GstBufferPool is requested

  (out) "prefix", G_TYPE_UINT
        - the prefix of the buffer memory

  (out) "align", G_TYPE_UINT
        - the aligment of the memory in the buffers, the alignment will be applied
          to the prefix.

  (out) "size", G_TYPE_UINT
        - the total size of the buffer memory

  (out) "pool", GST_TYPE_BUFFER_POOL
        - a buffer pool when need-pool was TRUE and the peer can provide a pool

  (out) "metadata", G_TYPE_VALUE_ARRAY of G_TYPE_STRING
        - an array of metadata API strings that can be accepted.