libvpx: Pull from upstream

source/libvpx/usage.dox

Index: source/libvpx/usage.dox
===================================================================
--- source/libvpx/usage.dox	(revision 290053)
+++ source/libvpx/usage.dox	(working copy)
@@ -57,9 +57,6 @@
     the vpx_codec_get_caps() method. Attempts to invoke features not supported
     by an algorithm will generally result in #VPX_CODEC_INCAPABLE.
 
-    Currently defined features available in both encoders and decoders include:
-    - \subpage usage_xma
-
     \if decoder
     Currently defined decoder features include:
     - \ref usage_cb
@@ -70,9 +67,7 @@
     To initialize a codec instance, the address of the codec context
     and interface structures are passed to an initialization function. Depending
     on the \ref usage_features that the codec supports, the codec could be
-    initialized in different modes. Most notably, the application may choose to
-    use \ref usage_xma mode to gain fine grained control over how and where
-    memory is allocated for the codec.
+    initialized in different modes.
 
     To prevent cases of confusion where the ABI of the library changes,
     the ABI is versioned. The ABI version number must be passed at
@@ -136,73 +131,3 @@
     possible."
 
 */
-
-
-/*! \page usage_xma External Memory Allocation
-    Applications that wish to have fine grained control over how and where
-    decoders allocate memory \ref MAY make use of the eXternal Memory Allocation
-    (XMA) interface. Not all codecs support the XMA \ref usage_features.
-
-    To use a decoder in XMA mode, the decoder \ref MUST be initialized with the
-    vpx_codec_xma_init_ver() function. The amount of memory a decoder needs to
-    allocate is heavily dependent on the size of the encoded video frames. The
-    size of the video must be known before requesting the decoder's memory map.
-    This stream information can be obtained with the vpx_codec_peek_stream_info()
-    function, which does not require a constructed decoder context. If the exact
-    stream is not known, a stream info structure can be created that reflects
-    the maximum size that the decoder instance is required to support.
-
-    Once the decoder instance has been initialized and the stream information
-    determined, the application calls the vpx_codec_get_mem_map() iterator
-    repeatedly to get a list of the memory segments requested by the decoder.
-    The iterator value should be initialized to NULL to request the first
-    element, and the function will return #VPX_CODEC_LIST_END to signal the end of
-    the list.
-
-    After each segment is identified, it must be passed to the codec through the
-    vpx_codec_set_mem_map() function. Segments \ref MUST be passed in the same
-    order as they are returned from vpx_codec_get_mem_map(), but there is no
-    requirement that vpx_codec_get_mem_map() must finish iterating before
-    vpx_codec_set_mem_map() is called. For instance, some applications may choose
-    to get a list of all requests, construct an optimal heap, and then set all
-    maps at once with one call. Other applications may set one map at a time,
-    allocating it immediately after it is returned from vpx_codec_get_mem_map().
-
-    After all segments have been set using vpx_codec_set_mem_map(), the codec may
-    be used as it would be in normal internal allocation mode.
-
-    \section usage_xma_seg_id Segment Identifiers
-    Each requested segment is identified by an identifier unique to
-    that decoder type. Some of these identifiers are private, while others are
-    enumerated for application use. Identifiers not enumerated publicly are
-    subject to change. Identifiers are non-consecutive.
-
-    \section usage_xma_seg_szalign Segment Size and Alignment
-    The sz (size) and align (alignment) parameters describe the required size
-    and alignment of the requested segment. Alignment will always be a power of
-    two. Applications \ref MUST honor the alignment requested. Failure to do so
-    could result in program crashes or may incur a speed penalty.
-
-    \section usage_xma_seg_flags Segment Flags
-    The flags member of the segment structure indicates any requirements or
-    desires of the codec for the particular segment. The #VPX_CODEC_MEM_ZERO flag
-    indicates that the segment \ref MUST be zeroed by the application prior to
-    passing it to the application. The #VPX_CODEC_MEM_WRONLY flag indicates that
-    the segment will only be written into by the decoder, not read. If this flag
-    is not set, the application \ref MUST insure that the memory segment is
-    readable. On some platforms, framebuffer memory is writable but not
-    readable, for example. The #VPX_CODEC_MEM_FAST flag indicates that the segment
-    will be frequently accessed, and that it should be placed into fast memory,
-    if any is available. The application \ref MAY choose to place other segments
-    in fast memory as well, but the most critical segments will be identified by
-    this flag.
-
-    \section usage_xma_seg_basedtor Segment Base Address and Destructor
-    For each requested memory segment, the application must determine the
-    address of a memory segment that meets the requirements of the codec. This
-    address is set in the <code>base</code> member of the #vpx_codec_mmap
-    structure. If the application requires processing when the segment is no
-    longer used by the codec (for instance to deallocate it or close an
-    associated file descriptor) the <code>dtor</code> and <code>priv</code>
-    members can be set.
-*/