466 lines
18 KiB
C
466 lines
18 KiB
C
/*
|
|
* Copyright (c) 2016, Alliance for Open Media. All rights reserved
|
|
*
|
|
* This source code is subject to the terms of the BSD 2 Clause License and
|
|
* the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
|
|
* was not distributed with this source code in the LICENSE file, you can
|
|
* obtain it at www.aomedia.org/license/software. If the Alliance for Open
|
|
* Media Patent License 1.0 was not distributed with this source code in the
|
|
* PATENTS file, you can obtain it at www.aomedia.org/license/patent.
|
|
*/
|
|
|
|
/*!\file
|
|
* \brief Describes the decoder algorithm interface for algorithm
|
|
* implementations.
|
|
*
|
|
* This file defines the private structures and data types that are only
|
|
* relevant to implementing an algorithm, as opposed to using it.
|
|
*
|
|
* To create a decoder algorithm class, an interface structure is put
|
|
* into the global namespace:
|
|
* <pre>
|
|
* my_codec.c:
|
|
* aom_codec_iface_t my_codec = {
|
|
* "My Codec v1.0",
|
|
* AOM_CODEC_ALG_ABI_VERSION,
|
|
* ...
|
|
* };
|
|
* </pre>
|
|
*
|
|
* An application instantiates a specific decoder instance by using
|
|
* aom_codec_init() and a pointer to the algorithm's interface structure:
|
|
* <pre>
|
|
* my_app.c:
|
|
* extern aom_codec_iface_t my_codec;
|
|
* {
|
|
* aom_codec_ctx_t algo;
|
|
* res = aom_codec_init(&algo, &my_codec);
|
|
* }
|
|
* </pre>
|
|
*
|
|
* Once initialized, the instance is manged using other functions from
|
|
* the aom_codec_* family.
|
|
*/
|
|
#ifndef AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
|
|
#define AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
|
|
#include "./aom_config.h"
|
|
#include "../aom_decoder.h"
|
|
#include "../aom_encoder.h"
|
|
#include <stdarg.h>
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
/*!\brief Current ABI version number
|
|
*
|
|
* \internal
|
|
* If this file is altered in any way that changes the ABI, this value
|
|
* must be bumped. Examples include, but are not limited to, changing
|
|
* types, removing or reassigning enums, adding/removing/rearranging
|
|
* fields to structures
|
|
*/
|
|
#define AOM_CODEC_INTERNAL_ABI_VERSION (5) /**<\hideinitializer*/
|
|
|
|
typedef struct aom_codec_alg_priv aom_codec_alg_priv_t;
|
|
typedef struct aom_codec_priv_enc_mr_cfg aom_codec_priv_enc_mr_cfg_t;
|
|
|
|
/*!\brief init function pointer prototype
|
|
*
|
|
* Performs algorithm-specific initialization of the decoder context. This
|
|
* function is called by the generic aom_codec_init() wrapper function, so
|
|
* plugins implementing this interface may trust the input parameters to be
|
|
* properly initialized.
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \retval #AOM_CODEC_OK
|
|
* The input stream was recognized and decoder initialized.
|
|
* \retval #AOM_CODEC_MEM_ERROR
|
|
* Memory operation failed.
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_init_fn_t)(
|
|
aom_codec_ctx_t *ctx, aom_codec_priv_enc_mr_cfg_t *data);
|
|
|
|
/*!\brief destroy function pointer prototype
|
|
*
|
|
* Performs algorithm-specific destruction of the decoder context. This
|
|
* function is called by the generic aom_codec_destroy() wrapper function,
|
|
* so plugins implementing this interface may trust the input parameters
|
|
* to be properly initialized.
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \retval #AOM_CODEC_OK
|
|
* The input stream was recognized and decoder initialized.
|
|
* \retval #AOM_CODEC_MEM_ERROR
|
|
* Memory operation failed.
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_destroy_fn_t)(aom_codec_alg_priv_t *ctx);
|
|
|
|
/*!\brief parse stream info function pointer prototype
|
|
*
|
|
* Performs high level parsing of the bitstream. This function is called by the
|
|
* generic aom_codec_peek_stream_info() wrapper function, so plugins
|
|
* implementing this interface may trust the input parameters to be properly
|
|
* initialized.
|
|
*
|
|
* \param[in] data Pointer to a block of data to parse
|
|
* \param[in] data_sz Size of the data buffer
|
|
* \param[in,out] si Pointer to stream info to update. The size member
|
|
* \ref MUST be properly initialized, but \ref MAY be
|
|
* clobbered by the algorithm. This parameter \ref MAY
|
|
* be NULL.
|
|
*
|
|
* \retval #AOM_CODEC_OK
|
|
* Bitstream is parsable and stream information updated
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_peek_si_fn_t)(const uint8_t *data,
|
|
unsigned int data_sz,
|
|
aom_codec_stream_info_t *si);
|
|
|
|
/*!\brief Return information about the current stream.
|
|
*
|
|
* Returns information about the stream that has been parsed during decoding.
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \param[in,out] si Pointer to stream info to update. The size member
|
|
* \ref MUST be properly initialized, but \ref MAY be
|
|
* clobbered by the algorithm. This parameter \ref MAY
|
|
* be NULL.
|
|
*
|
|
* \retval #AOM_CODEC_OK
|
|
* Bitstream is parsable and stream information updated
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_get_si_fn_t)(aom_codec_alg_priv_t *ctx,
|
|
aom_codec_stream_info_t *si);
|
|
|
|
/*!\brief control function pointer prototype
|
|
*
|
|
* This function is used to exchange algorithm specific data with the decoder
|
|
* instance. This can be used to implement features specific to a particular
|
|
* algorithm.
|
|
*
|
|
* This function is called by the generic aom_codec_control() wrapper
|
|
* function, so plugins implementing this interface may trust the input
|
|
* parameters to be properly initialized. However, this interface does not
|
|
* provide type safety for the exchanged data or assign meanings to the
|
|
* control codes. Those details should be specified in the algorithm's
|
|
* header file. In particular, the ctrl_id parameter is guaranteed to exist
|
|
* in the algorithm's control mapping table, and the data parameter may be NULL.
|
|
*
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \param[in] ctrl_id Algorithm specific control identifier
|
|
* \param[in,out] data Data to exchange with algorithm instance.
|
|
*
|
|
* \retval #AOM_CODEC_OK
|
|
* The internal state data was deserialized.
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_control_fn_t)(aom_codec_alg_priv_t *ctx,
|
|
va_list ap);
|
|
|
|
/*!\brief control function pointer mapping
|
|
*
|
|
* This structure stores the mapping between control identifiers and
|
|
* implementing functions. Each algorithm provides a list of these
|
|
* mappings. This list is searched by the aom_codec_control() wrapper
|
|
* function to determine which function to invoke. The special
|
|
* value {0, NULL} is used to indicate end-of-list, and must be
|
|
* present. The special value {0, <non-null>} can be used as a catch-all
|
|
* mapping. This implies that ctrl_id values chosen by the algorithm
|
|
* \ref MUST be non-zero.
|
|
*/
|
|
typedef const struct aom_codec_ctrl_fn_map {
|
|
int ctrl_id;
|
|
aom_codec_control_fn_t fn;
|
|
} aom_codec_ctrl_fn_map_t;
|
|
|
|
/*!\brief decode data function pointer prototype
|
|
*
|
|
* Processes a buffer of coded data. If the processing results in a new
|
|
* decoded frame becoming available, #AOM_CODEC_CB_PUT_SLICE and
|
|
* #AOM_CODEC_CB_PUT_FRAME events are generated as appropriate. This
|
|
* function is called by the generic aom_codec_decode() wrapper function,
|
|
* so plugins implementing this interface may trust the input parameters
|
|
* to be properly initialized.
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \param[in] data Pointer to this block of new coded data. If
|
|
* NULL, a #AOM_CODEC_CB_PUT_FRAME event is posted
|
|
* for the previously decoded frame.
|
|
* \param[in] data_sz Size of the coded data, in bytes.
|
|
*
|
|
* \return Returns #AOM_CODEC_OK if the coded data was processed completely
|
|
* and future pictures can be decoded without error. Otherwise,
|
|
* see the descriptions of the other error codes in ::aom_codec_err_t
|
|
* for recoverability capabilities.
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_decode_fn_t)(aom_codec_alg_priv_t *ctx,
|
|
const uint8_t *data,
|
|
unsigned int data_sz,
|
|
void *user_priv,
|
|
long deadline);
|
|
|
|
/*!\brief Decoded frames iterator
|
|
*
|
|
* Iterates over a list of the frames available for display. The iterator
|
|
* storage should be initialized to NULL to start the iteration. Iteration is
|
|
* complete when this function returns NULL.
|
|
*
|
|
* The list of available frames becomes valid upon completion of the
|
|
* aom_codec_decode call, and remains valid until the next call to
|
|
* aom_codec_decode.
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \param[in out] iter Iterator storage, initialized to NULL
|
|
*
|
|
* \return Returns a pointer to an image, if one is ready for display. Frames
|
|
* produced will always be in PTS (presentation time stamp) order.
|
|
*/
|
|
typedef aom_image_t *(*aom_codec_get_frame_fn_t)(aom_codec_alg_priv_t *ctx,
|
|
aom_codec_iter_t *iter);
|
|
|
|
/*!\brief Pass in external frame buffers for the decoder to use.
|
|
*
|
|
* Registers functions to be called when libaom needs a frame buffer
|
|
* to decode the current frame and a function to be called when libaom does
|
|
* not internally reference the frame buffer. This set function must
|
|
* be called before the first call to decode or libaom will assume the
|
|
* default behavior of allocating frame buffers internally.
|
|
*
|
|
* \param[in] ctx Pointer to this instance's context
|
|
* \param[in] cb_get Pointer to the get callback function
|
|
* \param[in] cb_release Pointer to the release callback function
|
|
* \param[in] cb_priv Callback's private data
|
|
*
|
|
* \retval #AOM_CODEC_OK
|
|
* External frame buffers will be used by libaom.
|
|
* \retval #AOM_CODEC_INVALID_PARAM
|
|
* One or more of the callbacks were NULL.
|
|
* \retval #AOM_CODEC_ERROR
|
|
* Decoder context not initialized, or algorithm not capable of
|
|
* using external frame buffers.
|
|
*
|
|
* \note
|
|
* When decoding AV1, the application may be required to pass in at least
|
|
* #AOM_MAXIMUM_WORK_BUFFERS external frame
|
|
* buffers.
|
|
*/
|
|
typedef aom_codec_err_t (*aom_codec_set_fb_fn_t)(
|
|
aom_codec_alg_priv_t *ctx, aom_get_frame_buffer_cb_fn_t cb_get,
|
|
aom_release_frame_buffer_cb_fn_t cb_release, void *cb_priv);
|
|
|
|
typedef aom_codec_err_t (*aom_codec_encode_fn_t)(aom_codec_alg_priv_t *ctx,
|
|
const aom_image_t *img,
|
|
aom_codec_pts_t pts,
|
|
unsigned long duration,
|
|
aom_enc_frame_flags_t flags,
|
|
unsigned long deadline);
|
|
typedef const aom_codec_cx_pkt_t *(*aom_codec_get_cx_data_fn_t)(
|
|
aom_codec_alg_priv_t *ctx, aom_codec_iter_t *iter);
|
|
|
|
typedef aom_codec_err_t (*aom_codec_enc_config_set_fn_t)(
|
|
aom_codec_alg_priv_t *ctx, const aom_codec_enc_cfg_t *cfg);
|
|
typedef aom_fixed_buf_t *(*aom_codec_get_global_headers_fn_t)(
|
|
aom_codec_alg_priv_t *ctx);
|
|
|
|
typedef aom_image_t *(*aom_codec_get_preview_frame_fn_t)(
|
|
aom_codec_alg_priv_t *ctx);
|
|
|
|
typedef aom_codec_err_t (*aom_codec_enc_mr_get_mem_loc_fn_t)(
|
|
const aom_codec_enc_cfg_t *cfg, void **mem_loc);
|
|
|
|
/*!\brief usage configuration mapping
|
|
*
|
|
* This structure stores the mapping between usage identifiers and
|
|
* configuration structures. Each algorithm provides a list of these
|
|
* mappings. This list is searched by the aom_codec_enc_config_default()
|
|
* wrapper function to determine which config to return. The special value
|
|
* {-1, {0}} is used to indicate end-of-list, and must be present. At least
|
|
* one mapping must be present, in addition to the end-of-list.
|
|
*
|
|
*/
|
|
typedef const struct aom_codec_enc_cfg_map {
|
|
int usage;
|
|
aom_codec_enc_cfg_t cfg;
|
|
} aom_codec_enc_cfg_map_t;
|
|
|
|
/*!\brief Decoder algorithm interface interface
|
|
*
|
|
* All decoders \ref MUST expose a variable of this type.
|
|
*/
|
|
struct aom_codec_iface {
|
|
const char *name; /**< Identification String */
|
|
int abi_version; /**< Implemented ABI version */
|
|
aom_codec_caps_t caps; /**< Decoder capabilities */
|
|
aom_codec_init_fn_t init; /**< \copydoc ::aom_codec_init_fn_t */
|
|
aom_codec_destroy_fn_t destroy; /**< \copydoc ::aom_codec_destroy_fn_t */
|
|
aom_codec_ctrl_fn_map_t *ctrl_maps; /**< \copydoc ::aom_codec_ctrl_fn_map_t */
|
|
struct aom_codec_dec_iface {
|
|
aom_codec_peek_si_fn_t peek_si; /**< \copydoc ::aom_codec_peek_si_fn_t */
|
|
aom_codec_get_si_fn_t get_si; /**< \copydoc ::aom_codec_get_si_fn_t */
|
|
aom_codec_decode_fn_t decode; /**< \copydoc ::aom_codec_decode_fn_t */
|
|
aom_codec_get_frame_fn_t
|
|
get_frame; /**< \copydoc ::aom_codec_get_frame_fn_t */
|
|
aom_codec_set_fb_fn_t set_fb_fn; /**< \copydoc ::aom_codec_set_fb_fn_t */
|
|
} dec;
|
|
struct aom_codec_enc_iface {
|
|
int cfg_map_count;
|
|
aom_codec_enc_cfg_map_t
|
|
*cfg_maps; /**< \copydoc ::aom_codec_enc_cfg_map_t */
|
|
aom_codec_encode_fn_t encode; /**< \copydoc ::aom_codec_encode_fn_t */
|
|
aom_codec_get_cx_data_fn_t
|
|
get_cx_data; /**< \copydoc ::aom_codec_get_cx_data_fn_t */
|
|
aom_codec_enc_config_set_fn_t
|
|
cfg_set; /**< \copydoc ::aom_codec_enc_config_set_fn_t */
|
|
aom_codec_get_global_headers_fn_t
|
|
get_glob_hdrs; /**< \copydoc ::aom_codec_get_global_headers_fn_t */
|
|
aom_codec_get_preview_frame_fn_t
|
|
get_preview; /**< \copydoc ::aom_codec_get_preview_frame_fn_t */
|
|
aom_codec_enc_mr_get_mem_loc_fn_t
|
|
mr_get_mem_loc; /**< \copydoc ::aom_codec_enc_mr_get_mem_loc_fn_t */
|
|
} enc;
|
|
};
|
|
|
|
/*!\brief Callback function pointer / user data pair storage */
|
|
typedef struct aom_codec_priv_cb_pair {
|
|
union {
|
|
aom_codec_put_frame_cb_fn_t put_frame;
|
|
aom_codec_put_slice_cb_fn_t put_slice;
|
|
} u;
|
|
void *user_priv;
|
|
} aom_codec_priv_cb_pair_t;
|
|
|
|
/*!\brief Instance private storage
|
|
*
|
|
* This structure is allocated by the algorithm's init function. It can be
|
|
* extended in one of two ways. First, a second, algorithm specific structure
|
|
* can be allocated and the priv member pointed to it. Alternatively, this
|
|
* structure can be made the first member of the algorithm specific structure,
|
|
* and the pointer cast to the proper type.
|
|
*/
|
|
struct aom_codec_priv {
|
|
const char *err_detail;
|
|
aom_codec_flags_t init_flags;
|
|
struct {
|
|
aom_codec_priv_cb_pair_t put_frame_cb;
|
|
aom_codec_priv_cb_pair_t put_slice_cb;
|
|
} dec;
|
|
struct {
|
|
aom_fixed_buf_t cx_data_dst_buf;
|
|
unsigned int cx_data_pad_before;
|
|
unsigned int cx_data_pad_after;
|
|
aom_codec_cx_pkt_t cx_data_pkt;
|
|
unsigned int total_encoders;
|
|
} enc;
|
|
};
|
|
|
|
/*
|
|
* Multi-resolution encoding internal configuration
|
|
*/
|
|
struct aom_codec_priv_enc_mr_cfg {
|
|
unsigned int mr_total_resolutions;
|
|
unsigned int mr_encoder_id;
|
|
struct aom_rational mr_down_sampling_factor;
|
|
void *mr_low_res_mode_info;
|
|
};
|
|
|
|
#undef AOM_CTRL_USE_TYPE
|
|
#define AOM_CTRL_USE_TYPE(id, typ) \
|
|
static AOM_INLINE typ id##__value(va_list args) { return va_arg(args, typ); }
|
|
|
|
#undef AOM_CTRL_USE_TYPE_DEPRECATED
|
|
#define AOM_CTRL_USE_TYPE_DEPRECATED(id, typ) \
|
|
static AOM_INLINE typ id##__value(va_list args) { return va_arg(args, typ); }
|
|
|
|
#define CAST(id, arg) id##__value(arg)
|
|
|
|
/* CODEC_INTERFACE convenience macro
|
|
*
|
|
* By convention, each codec interface is a struct with extern linkage, where
|
|
* the symbol is suffixed with _algo. A getter function is also defined to
|
|
* return a pointer to the struct, since in some cases it's easier to work
|
|
* with text symbols than data symbols (see issue #169). This function has
|
|
* the same name as the struct, less the _algo suffix. The CODEC_INTERFACE
|
|
* macro is provided to define this getter function automatically.
|
|
*/
|
|
#define CODEC_INTERFACE(id) \
|
|
aom_codec_iface_t *id(void) { return &id##_algo; } \
|
|
aom_codec_iface_t id##_algo
|
|
|
|
/* Internal Utility Functions
|
|
*
|
|
* The following functions are intended to be used inside algorithms as
|
|
* utilities for manipulating aom_codec_* data structures.
|
|
*/
|
|
struct aom_codec_pkt_list {
|
|
unsigned int cnt;
|
|
unsigned int max;
|
|
struct aom_codec_cx_pkt pkts[1];
|
|
};
|
|
|
|
#define aom_codec_pkt_list_decl(n) \
|
|
union { \
|
|
struct aom_codec_pkt_list head; \
|
|
struct { \
|
|
struct aom_codec_pkt_list head; \
|
|
struct aom_codec_cx_pkt pkts[n]; \
|
|
} alloc; \
|
|
}
|
|
|
|
#define aom_codec_pkt_list_init(m) \
|
|
(m)->alloc.head.cnt = 0, \
|
|
(m)->alloc.head.max = sizeof((m)->alloc.pkts) / sizeof((m)->alloc.pkts[0])
|
|
|
|
int aom_codec_pkt_list_add(struct aom_codec_pkt_list *,
|
|
const struct aom_codec_cx_pkt *);
|
|
|
|
const aom_codec_cx_pkt_t *aom_codec_pkt_list_get(
|
|
struct aom_codec_pkt_list *list, aom_codec_iter_t *iter);
|
|
|
|
#include <stdio.h>
|
|
#include <setjmp.h>
|
|
|
|
struct aom_internal_error_info {
|
|
aom_codec_err_t error_code;
|
|
int has_detail;
|
|
char detail[80];
|
|
int setjmp;
|
|
jmp_buf jmp;
|
|
};
|
|
|
|
#define CLANG_ANALYZER_NORETURN
|
|
#if defined(__has_feature)
|
|
#if __has_feature(attribute_analyzer_noreturn)
|
|
#undef CLANG_ANALYZER_NORETURN
|
|
#define CLANG_ANALYZER_NORETURN __attribute__((analyzer_noreturn))
|
|
#endif
|
|
#endif
|
|
|
|
void aom_internal_error(struct aom_internal_error_info *info,
|
|
aom_codec_err_t error, const char *fmt,
|
|
...) CLANG_ANALYZER_NORETURN;
|
|
|
|
#if CONFIG_DEBUG
|
|
#define AOM_CHECK_MEM_ERROR(error_info, lval, expr) \
|
|
do { \
|
|
lval = (expr); \
|
|
if (!lval) \
|
|
aom_internal_error(error_info, AOM_CODEC_MEM_ERROR, \
|
|
"Failed to allocate " #lval " at %s:%d", __FILE__, \
|
|
__LINE__); \
|
|
} while (0)
|
|
#else
|
|
#define AOM_CHECK_MEM_ERROR(error_info, lval, expr) \
|
|
do { \
|
|
lval = (expr); \
|
|
if (!lval) \
|
|
aom_internal_error(error_info, AOM_CODEC_MEM_ERROR, \
|
|
"Failed to allocate " #lval); \
|
|
} while (0)
|
|
#endif
|
|
#ifdef __cplusplus
|
|
} // extern "C"
|
|
#endif
|
|
|
|
#endif // AOM_INTERNAL_AOM_CODEC_INTERNAL_H_
|