- \ref usage_init
- \ref usage_errors
- Fore more information on decoder and encoder specific usage, see the
+ For more information on decoder and encoder specific usage, see the
following pages:
\if decoder
- - \subpage usage_decode
+ \li \subpage usage_decode
\endif
- \if decoder
- - \subpage usage_encode
+ \if encoder
+ \li \subpage usage_encode
\endif
\section usage_types Important Data Types
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
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
The available initialization methods are:
- \if encoder - #vpx_codec_enc_init (calls vpx_codec_enc_init_ver()) \endif
- \if multi-encoder - #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver()) \endif
- \if decoder - #vpx_codec_dec_init (calls vpx_codec_dec_init_ver()) \endif
-
+ \if encoder
+ \li #vpx_codec_enc_init (calls vpx_codec_enc_init_ver())
+ \li #vpx_codec_enc_init_multi (calls vpx_codec_enc_init_multi_ver())
+ \endif
+ \if decoder
+ \li #vpx_codec_dec_init (calls vpx_codec_dec_init_ver())
+ \endif
\section usage_errors Error Handling
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.
-*/
projects / platform / upstream / libvpx.git / blobdiff