<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<title>WebM VP8 Codec SDK: External Memory Allocation</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body>
<!-- Generated by Doxygen 1.7.4 -->
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">WebM VP8 Codec SDK</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li class="current"><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
</ul>
</div>
<div id="nav-path" class="navpath">
<ul>
<li class="navelem"><a class="el" href="usage.html">Usage</a> </li>
</ul>
</div>
</div>
<div class="header">
<div class="headertitle">
<div class="title">External Memory Allocation </div> </div>
</div>
<div class="contents">
<div class="textblock"><p>Applications that wish to have fine grained control over how and where decoders allocate memory <a class="el" href="rfc2119.html#MAY">MAY</a> make use of the eXternal Memory Allocation (XMA) interface. Not all codecs support the XMA <a class="el" href="usage.html#usage_features">Features</a>.</p>
<p>To use a decoder in XMA mode, the decoder <a class="el" href="rfc2119.html#MUST">MUST</a> 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 <a class="el" href="group__decoder.html#gadfee4664d644175d5aac1465ef11c4b0" title="Parse stream info from a buffer.">vpx_codec_peek_stream_info()</a> 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.</p>
<p>Once the decoder instance has been initialized and the stream information determined, the application calls the <a class="el" href="group__cap__xma.html#ga802003c8ed203def368a361fe0e92f13" title="Iterate over the list of segments to allocate.">vpx_codec_get_mem_map()</a> 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 <a class="el" href="group__codec.html#ggada1084710837ad363b92f2379dd2b8d2a452450a5adfcc14ef8a0ac12611dae21" title="An iterator reached the end of list.">VPX_CODEC_LIST_END</a> to signal the end of the list.</p>
<p>After each segment is identified, it must be passed to the codec through the <a class="el" href="group__cap__xma.html#gac2df376a4d76282a5c117313182dcf53" title="Identify allocated segments to codec instance.">vpx_codec_set_mem_map()</a> function. Segments <a class="el" href="rfc2119.html#MUST">MUST</a> be passed in the same order as they are returned from <a class="el" href="group__cap__xma.html#ga802003c8ed203def368a361fe0e92f13" title="Iterate over the list of segments to allocate.">vpx_codec_get_mem_map()</a>, but there is no requirement that <a class="el" href="group__cap__xma.html#ga802003c8ed203def368a361fe0e92f13" title="Iterate over the list of segments to allocate.">vpx_codec_get_mem_map()</a> must finish iterating before <a class="el" href="group__cap__xma.html#gac2df376a4d76282a5c117313182dcf53" title="Identify allocated segments to codec instance.">vpx_codec_set_mem_map()</a> 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 <a class="el" href="group__cap__xma.html#ga802003c8ed203def368a361fe0e92f13" title="Iterate over the list of segments to allocate.">vpx_codec_get_mem_map()</a>.</p>
<p>After all segments have been set using <a class="el" href="group__cap__xma.html#gac2df376a4d76282a5c117313182dcf53" title="Identify allocated segments to codec instance.">vpx_codec_set_mem_map()</a>, the codec may be used as it would be in normal internal allocation mode.</p>
<h2><a class="anchor" id="usage_xma_seg_id"></a>
Segment Identifiers</h2>
<p>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.</p>
<h2><a class="anchor" id="usage_xma_seg_szalign"></a>
Segment Size and Alignment</h2>
<p>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 <a class="el" href="rfc2119.html#MUST">MUST</a> honor the alignment requested. Failure to do so could result in program crashes or may incur a speed penalty.</p>
<h2><a class="anchor" id="usage_xma_seg_flags"></a>
Segment Flags</h2>
<p>The flags member of the segment structure indicates any requirements or desires of the codec for the particular segment. The <a class="el" href="vpx__codec_8h.html#a0a5b645a72e936464b1a9144bcbabed2">VPX_CODEC_MEM_ZERO</a> flag indicates that the segment <a class="el" href="rfc2119.html#MUST">MUST</a> be zeroed by the application prior to passing it to the application. The <a class="el" href="vpx__codec_8h.html#a7165be67097e7553d0983962a8828cf5">VPX_CODEC_MEM_WRONLY</a> flag indicates that the segment will only be written into by the decoder, not read. If this flag is not set, the application <a class="el" href="rfc2119.html#MUST">MUST</a> insure that the memory segment is readable. On some platforms, framebuffer memory is writable but not readable, for example. The <a class="el" href="vpx__codec_8h.html#a2d57a8f37a8f8c9cc3497759ffc52b2a">VPX_CODEC_MEM_FAST</a> flag indicates that the segment will be frequently accessed, and that it should be placed into fast memory, if any is available. The application <a class="el" href="rfc2119.html#MAY">MAY</a> choose to place other segments in fast memory as well, but the most critical segments will be identified by this flag.</p>
<h2><a class="anchor" id="usage_xma_seg_basedtor"></a>
Segment Base Address and Destructor</h2>
<p>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 <a class="el" href="structvpx__codec__mmap.html" title="Memory Map Entry.">vpx_codec_mmap</a> 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. </p>
</div></div>
<hr class="footer"/><address class="footer"><small>Generated on Mon Jan 30 2012 for WebM VP8 Codec SDK by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.4 </small></address>
</body>
</html>
