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
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.
-*/
res = VPX_CODEC_INVALID_PARAM;
else if (iface->abi_version != VPX_CODEC_INTERNAL_ABI_VERSION)
res = VPX_CODEC_ABI_MISMATCH;
- else if ((flags & VPX_CODEC_USE_XMA) && !(iface->caps & VPX_CODEC_CAP_XMA))
- res = VPX_CODEC_INCAPABLE;
else if ((flags & VPX_CODEC_USE_POSTPROC) && !(iface->caps & VPX_CODEC_CAP_POSTPROC))
res = VPX_CODEC_INCAPABLE;
else if ((flags & VPX_CODEC_USE_ERROR_CONCEALMENT) &&
ctx->priv = NULL;
ctx->init_flags = flags;
ctx->config.dec = cfg;
- res = VPX_CODEC_OK;
-
- if (!(flags & VPX_CODEC_USE_XMA)) {
- res = ctx->iface->init(ctx, NULL);
- if (res) {
- ctx->err_detail = ctx->priv ? ctx->priv->err_detail : NULL;
- vpx_codec_destroy(ctx);
- }
-
- if (ctx->priv)
- ctx->priv->iface = ctx->iface;
+ res = ctx->iface->init(ctx, NULL);
+ if (res) {
+ ctx->err_detail = ctx->priv ? ctx->priv->err_detail : NULL;
+ vpx_codec_destroy(ctx);
}
+
+ if (ctx->priv)
+ ctx->priv->iface = ctx->iface;
}
return SAVE_STATUS(ctx, res);
* is not thread safe and should be guarded with a lock if being used
* in a multithreaded context.
*
- * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags
- * parameter), the storage pointed to by the cfg parameter must be
- * kept readable and stable until all memory maps have been set.
- *
* \param[in] ctx Pointer to this instance's context.
* \param[in] iface Pointer to the algorithm interface to use.
* \param[in] cfg Configuration to use, if known. May be NULL.
* instead of this function directly, to ensure that the ABI version number
* parameter is properly initialized.
*
- * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags
- * parameter), the storage pointed to by the cfg parameter must be
- * kept readable and stable until all memory maps have been set.
- *
* \param[in] ctx Pointer to this instance's context.
* \param[in] iface Pointer to the algorithm interface to use.
* \param[in] cfg Configuration to use, if known. May be NULL.
projects / platform / upstream / libvpx.git / commitdiff