Applications that wish to have fine grained control over how and where decoders allocate memory MAY make use of the eXternal Memory Allocation (XMA) interface. Not all codecs support the XMA Features.
To use a decoder in XMA mode, the decoder 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 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.
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.
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 MUST honor the alignment requested. Failure to do so could result in program crashes or may incur a speed penalty.
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 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 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 MAY choose to place other segments in fast memory as well, but the most critical segments will be identified by this flag.
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
base 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
members can be set.