usage.dox - platform/external/libvpx - Git at Google

 /*!\page usage Usage

     The vpx Multi-Format codec SDK provides a unified interface amongst its
     supported codecs. This abstraction allows applications using this SDK to
     easily support multiple video formats with minimal code duplication or
     "special casing." This section describes the interface common to all codecs.
     For codec-specific details, see the \ref codecs page.

     The following sections are common to all codecs:
     - \ref usage_types
     - \ref usage_features
     - \ref usage_init
     - \ref usage_errors

     Fore more information on decoder and encoder specific usage, see the
     following pages:
     \if decoder - \subpage usage_decode \endif
     \if decoder - \subpage usage_encode \endif

     \section usage_types Important Data Types
     There are two important data structures to consider in this interface.

     \subsection usage_ctxs Contexts
     A context is a storage area allocated by the calling application that the
     codec may write into to store details about a single instance of that codec.
     Most of the context is implementation specific, and thus opaque to the
     application. The context structure as seen by the application is of fixed
     size, and thus can be allocated eith with automatic storage or dynamically
     on the heap.

     Most operations require an initialized codec context. Codec context
     instances are codec specific. That is, the codec to be used for the encoded
     video must be known at initialization time. See #vpx_codec_ctx_t for further
     information.

     \subsection usage_ifaces Interfaces
     A codec interface is an opaque structure that controls how function calls
     into the generic interface are dispatched to their codec-specific
     implementations. Applications \ref MUSTNOT attempt to examine or override
     this storage, as it contains internal implementation details likely to
     change from release to release.

     Each supported codec will expose an interface structure to the application
     as an <code>extern</code> reference to a structure of the incomplete type
     #vpx_codec_iface_t.

     \section usage_features Features
     Several "features" are defined that are optionally implemented by codec
     algorithms. Indeed, the same algorithm may support different features on
     different platforms. The purpose of defining these features is that when
     they are implemented, they conform to a common interface. The features, or
     capabilities, of an algorithm can be queried from it's interface by using
     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
     - \ref usage_postproc
     \endif

     \section usage_init Initialization
     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.

     To prevent cases of confusion where the ABI of the library changes,
     the ABI is versioned. The ABI version number must be passed at
     initialization time to ensure the application is using a header file that
     matches the library. The current ABI version number is stored in the
     prepropcessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and
     #VPX_DECODER_ABI_VERSION. For convenience, each initialization function has
     a wrapper macro that inserts the correct version number. These macros are
     named like the initialization methods, but without the _ver suffix.


     The available initialization methods are:
     \if encoder - #vpx_codec_enc_init (calls vpx_codec_enc_init_ver()) \endif
     \if decoder - #vpx_codec_dec_init (calls vpx_codec_dec_init_ver()) \endif


     \section usage_errors Error Handling
     Almost all codec functions return an error status of type #vpx_codec_err_t.
     The semantics of how each error condition should be processed is clearly
     defined in the definitions of each enumerated value. Error values can be
     converted into ASCII strings with the vpx_codec_error() and
     vpx_codec_err_to_string() methods. The difference between these two methods is
     that vpx_codec_error() returns the error state from an initialized context,
     whereas vpx_codec_err_to_string() can be used in cases where an error occurs
     outside any context. The enumerated value returned from the last call can be
     retrieved from the <code>err</code> member of the decoder context as well.
     Finally, more detailed error information may be able to be obtained by using
     the vpx_codec_error_detail() method. Not all errors produce detailed error
     information.

     In addition to error information, the codec library's build configuration
     is available at runtime on some platforms. This information can be returned
     by calling vpx_codec_build_config(), and is formatted as a base64 coded string
     (comprised of characters in the set [a-z_a-Z0-9+/]). This information is not
     useful to an application at runtime, but may be of use to vpx for support.


     \section usage_deadline Deadline
     Both the encoding and decoding functions have a <code>deadline</code>
     parameter. This parameter indicates the amount of time, in microseconds
     (us), that the application wants the codec to spend processing before
     returning. This is a soft deadline -- that is, the semantics of the
     requested operation take precedence over meeting the deadline. If, for
     example, an application sets a <code>deadline</code> of 1000us, and the
     frame takes 2000us to decode, the call to vpx_codec_decode() will return
     after 2000us. In this case the deadline is not met, but the semantics of the
     function are preserved. If, for the same frame, an application instead sets
     a <code>deadline</code> of 5000us, the decoder will see that it has 3000us
     remaining in its time slice when decoding completes. It could then choose to
     run a set of \ref usage_postproc filters, and perhaps would return after
     4000us (instead of the allocated 5000us). In this case the deadline is met,
     and the semantics of the call are preserved, as before.

     The special value <code>0</code> is reserved to represent an infinite
     deadline. In this case, the codec will perform as much processing as
     possible to yeild the highest quality frame.

     By convention, the value <code>1</code> is used to mean "return as fast as
     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 e_xternal 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 contructed 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 aligment 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.
 */
	/*!\page usage Usage

	The vpx Multi-Format codec SDK provides a unified interface amongst its
	supported codecs. This abstraction allows applications using this SDK to
	easily support multiple video formats with minimal code duplication or
	"special casing." This section describes the interface common to all codecs.
	For codec-specific details, see the \ref codecs page.

	The following sections are common to all codecs:
	- \ref usage_types
	- \ref usage_features
	- \ref usage_init
	- \ref usage_errors

	Fore more information on decoder and encoder specific usage, see the
	following pages:
	\if decoder - \subpage usage_decode \endif
	\if decoder - \subpage usage_encode \endif

	\section usage_types Important Data Types
	There are two important data structures to consider in this interface.

	\subsection usage_ctxs Contexts
	A context is a storage area allocated by the calling application that the
	codec may write into to store details about a single instance of that codec.
	Most of the context is implementation specific, and thus opaque to the
	application. The context structure as seen by the application is of fixed
	size, and thus can be allocated eith with automatic storage or dynamically
	on the heap.

	Most operations require an initialized codec context. Codec context
	instances are codec specific. That is, the codec to be used for the encoded
	video must be known at initialization time. See #vpx_codec_ctx_t for further
	information.

	\subsection usage_ifaces Interfaces
	A codec interface is an opaque structure that controls how function calls
	into the generic interface are dispatched to their codec-specific
	implementations. Applications \ref MUSTNOT attempt to examine or override
	this storage, as it contains internal implementation details likely to
	change from release to release.

	Each supported codec will expose an interface structure to the application
	as an <code>extern</code> reference to a structure of the incomplete type
	#vpx_codec_iface_t.

	\section usage_features Features
	Several "features" are defined that are optionally implemented by codec
	algorithms. Indeed, the same algorithm may support different features on
	different platforms. The purpose of defining these features is that when
	they are implemented, they conform to a common interface. The features, or
	capabilities, of an algorithm can be queried from it's interface by using
	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
	- \ref usage_postproc
	\endif

	\section usage_init Initialization
	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.

	To prevent cases of confusion where the ABI of the library changes,
	the ABI is versioned. The ABI version number must be passed at
	initialization time to ensure the application is using a header file that
	matches the library. The current ABI version number is stored in the
	prepropcessor macros #VPX_CODEC_ABI_VERSION, #VPX_ENCODER_ABI_VERSION, and
	#VPX_DECODER_ABI_VERSION. For convenience, each initialization function has
	a wrapper macro that inserts the correct version number. These macros are
	named like the initialization methods, but without the _ver suffix.


	The available initialization methods are:
	\if encoder - #vpx_codec_enc_init (calls vpx_codec_enc_init_ver()) \endif
	\if decoder - #vpx_codec_dec_init (calls vpx_codec_dec_init_ver()) \endif



	\section usage_errors Error Handling
	Almost all codec functions return an error status of type #vpx_codec_err_t.
	The semantics of how each error condition should be processed is clearly
	defined in the definitions of each enumerated value. Error values can be
	converted into ASCII strings with the vpx_codec_error() and
	vpx_codec_err_to_string() methods. The difference between these two methods is
	that vpx_codec_error() returns the error state from an initialized context,
	whereas vpx_codec_err_to_string() can be used in cases where an error occurs
	outside any context. The enumerated value returned from the last call can be
	retrieved from the <code>err</code> member of the decoder context as well.
	Finally, more detailed error information may be able to be obtained by using
	the vpx_codec_error_detail() method. Not all errors produce detailed error
	information.

	In addition to error information, the codec library's build configuration
	is available at runtime on some platforms. This information can be returned
	by calling vpx_codec_build_config(), and is formatted as a base64 coded string
	(comprised of characters in the set [a-z_a-Z0-9+/]). This information is not
	useful to an application at runtime, but may be of use to vpx for support.


	\section usage_deadline Deadline
	Both the encoding and decoding functions have a <code>deadline</code>
	parameter. This parameter indicates the amount of time, in microseconds
	(us), that the application wants the codec to spend processing before
	returning. This is a soft deadline -- that is, the semantics of the
	requested operation take precedence over meeting the deadline. If, for
	example, an application sets a <code>deadline</code> of 1000us, and the
	frame takes 2000us to decode, the call to vpx_codec_decode() will return
	after 2000us. In this case the deadline is not met, but the semantics of the
	function are preserved. If, for the same frame, an application instead sets
	a <code>deadline</code> of 5000us, the decoder will see that it has 3000us
	remaining in its time slice when decoding completes. It could then choose to
	run a set of \ref usage_postproc filters, and perhaps would return after
	4000us (instead of the allocated 5000us). In this case the deadline is met,
	and the semantics of the call are preserved, as before.

	The special value <code>0</code> is reserved to represent an infinite
	deadline. In this case, the codec will perform as much processing as
	possible to yeild the highest quality frame.

	By convention, the value <code>1</code> is used to mean "return as fast as
	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 e_xternal 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 contructed 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 aligment 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.
	*/