aom_codec.h

Go to the documentation of this file.

/*
 * 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.
 */
 
// Internal implementation details
//
// There are two levels of interfaces used to access the AOM codec: the
// aom_codec_iface and the aom_codec_ctx.
//
// 1. aom_codec_iface_t
//    (Related files: aom/aom_codec.h, aom/src/aom_codec.c,
//    aom/internal/aom_codec_internal.h, av1/av1_cx_iface.c,
//    av1/av1_dx_iface.c)
//
// Used to initialize the codec context, which contains the configuration for
// for modifying the encoder/decoder during run-time. See the other
// documentation in this header file for more details. For the most part,
// users will call helper functions, such as aom_codec_iface_name,
// aom_codec_get_caps, etc., to interact with it.
//
// The main purpose of the aom_codec_iface_t is to provide a way to generate
// a default codec config, find out what capabilities the implementation has,
// and create an aom_codec_ctx_t (which is actually used to interact with the
// codec).
//
// Note that the implementations for the AV1 algorithm are located in
// av1/av1_cx_iface.c and av1/av1_dx_iface.c
//
//
// 2. aom_codec_ctx_t
//  (Related files: aom/aom_codec.h, av1/av1_cx_iface.c, av1/av1_dx_iface.c,
//   aom/aomcx.h, aom/aomdx.h, aom/src/aom_encoder.c, aom/src/aom_decoder.c)
//
// The actual interface between user code and the codec. It stores the name
// of the codec, a pointer back to the aom_codec_iface_t that initialized it,
// initialization flags, a config for either encoder or the decoder, and a
// pointer to internal data.
//
// The codec is configured / queried through calls to aom_codec_control,
// which takes a control ID (listed in aomcx.h and aomdx.h) and a parameter.
// In the case of "getter" control IDs, the parameter is modified to have
// the requested value; in the case of "setter" control IDs, the codec's
// configuration is changed based on the parameter. Note that a aom_codec_err_t
// is returned, which indicates if the operation was successful or not.
//
// Note that for the encoder, the aom_codec_alg_priv_t points to the
// the aom_codec_alg_priv structure in av1/av1_cx_iface.c, and for the decoder,
// the struct in av1/av1_dx_iface.c. Variables such as AV1_COMP cpi are stored
// here and also used in the core algorithm.
//
// At the end, aom_codec_destroy should be called for each initialized
// aom_codec_ctx_t.
 
#ifndef AOM_AOM_AOM_CODEC_H_
#define AOM_AOM_AOM_CODEC_H_
 
#ifdef __cplusplus
extern "C" {
#endif
 
#include "aom/aom_image.h"
#include "aom/aom_integer.h"
 
#ifndef AOM_DEPRECATED
#if defined(__GNUC__)
#define AOM_DEPRECATED __attribute__((deprecated))
#elif defined(_MSC_VER)
#define AOM_DEPRECATED
#else
#define AOM_DEPRECATED
#endif
#endif /* AOM_DEPRECATED */
 
#ifndef AOM_DECLSPEC_DEPRECATED
#if defined(__GNUC__)
#define AOM_DECLSPEC_DEPRECATED 
#elif defined(_MSC_VER)
#define AOM_DECLSPEC_DEPRECATED __declspec(deprecated)
#else
#define AOM_DECLSPEC_DEPRECATED 
#endif
#endif /* AOM_DECLSPEC_DEPRECATED */
 
#ifdef AOM_UNUSED
#elif defined(__GNUC__) || defined(__clang__)
#define AOM_UNUSED __attribute__((unused))
#else
#define AOM_UNUSED
#endif
 
#ifndef ATTRIBUTE_PACKED
#if defined(__GNUC__)
#define ATTRIBUTE_PACKED __attribute__((packed))
#elif defined(_MSC_VER)
#define ATTRIBUTE_PACKED
#else
#define ATTRIBUTE_PACKED
#endif
#endif /* ATTRIBUTE_PACKED */
 
#define AOM_CODEC_ABI_VERSION (7 + AOM_IMAGE_ABI_VERSION) 
typedef enum {
  AOM_CODEC_OK,
 
  AOM_CODEC_ERROR,
 
  AOM_CODEC_MEM_ERROR,
 
  AOM_CODEC_ABI_MISMATCH,
 
  AOM_CODEC_INCAPABLE,
 
  AOM_CODEC_UNSUP_BITSTREAM,
 
  AOM_CODEC_UNSUP_FEATURE,
 
  AOM_CODEC_CORRUPT_FRAME,
 
  AOM_CODEC_INVALID_PARAM,
 
  AOM_CODEC_LIST_END
 
} aom_codec_err_t;
 
typedef long aom_codec_caps_t;
#define AOM_CODEC_CAP_DECODER 0x1 
#define AOM_CODEC_CAP_ENCODER 0x2 
typedef long aom_codec_flags_t;
 
// Experimental feature policy
//
// New features may be marked as experimental. Experimental features are not
// part of the stable API and may be modified or removed in a future release.
// Experimental features are made available only if you pass the
// AOM_CODEC_USE_EXPERIMENTAL flag to the codec init function.
//
// If you use experimental features, you must rebuild your code whenever you
// update to a new libaom release, and you must be prepared to modify your code
// when an experimental feature you use is modified or removed. If you are not
// sure, DO NOT use experimental features.
#define AOM_CODEC_USE_EXPERIMENTAL 0x1 
typedef int64_t aom_codec_pts_t;
 
typedef const struct aom_codec_iface aom_codec_iface_t;
 
typedef struct aom_codec_priv aom_codec_priv_t;
 
typedef uint32_t aom_codec_frame_flags_t;
#define AOM_FRAME_IS_KEY 0x1u 
#define AOM_FRAME_IS_DROPPABLE 0x2u
#define AOM_FRAME_IS_INTRAONLY 0x10u
#define AOM_FRAME_IS_SWITCH 0x20u
#define AOM_FRAME_IS_ERROR_RESILIENT 0x40u
#define AOM_FRAME_IS_DELAYED_RANDOM_ACCESS_POINT 0x80u
 
typedef const void *aom_codec_iter_t;
 
typedef struct aom_codec_ctx {
  const char *name;             
  aom_codec_iface_t *iface;     
  aom_codec_err_t err;          
  const char *err_detail;       
  aom_codec_flags_t init_flags; 
  union {
    const struct aom_codec_dec_cfg *dec;
    const struct aom_codec_enc_cfg *enc;
    const void *raw;
  } config;               
  aom_codec_priv_t *priv; 
} aom_codec_ctx_t;
 
typedef enum aom_bit_depth {
  AOM_BITS_8 = 8,   
  AOM_BITS_10 = 10, 
  AOM_BITS_12 = 12, 
} aom_bit_depth_t;
 
typedef enum aom_superblock_size {
  AOM_SUPERBLOCK_SIZE_64X64,   
  AOM_SUPERBLOCK_SIZE_128X128, 
  AOM_SUPERBLOCK_SIZE_DYNAMIC  
} aom_superblock_size_t;
 
/*
 * Library Version Number Interface
 *
 * For example, see the following sample return values:
 *     aom_codec_version()           (1<<16 | 2<<8 | 3)
 *     aom_codec_version_str()       "v1.2.3-rc1-16-gec6a1ba"
 *     aom_codec_version_extra_str() "rc1-16-gec6a1ba"
 */
 
int aom_codec_version(void);
 
#define aom_codec_version_major() ((aom_codec_version() >> 16) & 0xff)
 
#define aom_codec_version_minor() ((aom_codec_version() >> 8) & 0xff)
 
#define aom_codec_version_patch() ((aom_codec_version() >> 0) & 0xff)
 
const char *aom_codec_version_str(void);
 
const char *aom_codec_version_extra_str(void);
 
const char *aom_codec_build_config(void);
 
const char *aom_codec_iface_name(aom_codec_iface_t *iface);
 
const char *aom_codec_err_to_string(aom_codec_err_t err);
 
const char *aom_codec_error(const aom_codec_ctx_t *ctx);
 
const char *aom_codec_error_detail(const aom_codec_ctx_t *ctx);
 
/* REQUIRED FUNCTIONS
 *
 * The following functions are required to be implemented for all codecs.
 * They represent the base case functionality expected of all codecs.
 */
 
aom_codec_err_t aom_codec_destroy(aom_codec_ctx_t *ctx);
 
aom_codec_caps_t aom_codec_get_caps(aom_codec_iface_t *iface);
 
aom_codec_err_t aom_codec_control(aom_codec_ctx_t *ctx, int ctrl_id, ...);
 
aom_codec_err_t aom_codec_set_option(aom_codec_ctx_t *ctx, const char *name,
                                     const char *value);
 
#define AOM_CODEC_CONTROL_TYPECHECKED(ctx, id, data) \
  aom_codec_control_typechecked_##id(ctx, id, data) 
#define AOM_CTRL_USE_TYPE(id, typ)                           \
  static aom_codec_err_t aom_codec_control_typechecked_##id( \
      aom_codec_ctx_t *, int, typ) AOM_UNUSED;               \
  static aom_codec_err_t aom_codec_control_typechecked_##id( \
      aom_codec_ctx_t *ctx, int ctrl, typ data) {            \
    return aom_codec_control(ctx, ctrl, data);               \
  }                                    \
  typedef typ aom_codec_control_type_##id;
typedef enum ATTRIBUTE_PACKED {
  OBU_SEQUENCE_HEADER = 1,
  OBU_TEMPORAL_DELIMITER = 2,
  OBU_FRAME_HEADER = 3,
  OBU_TILE_GROUP = 4,
  OBU_METADATA = 5,
  OBU_FRAME = 6,
  OBU_REDUNDANT_FRAME_HEADER = 7,
  OBU_TILE_LIST = 8,
  OBU_PADDING = 15,
} OBU_TYPE;
 
typedef enum {
  OBU_METADATA_TYPE_AOM_RESERVED_0 = 0,
  OBU_METADATA_TYPE_HDR_CLL = 1,
  OBU_METADATA_TYPE_HDR_MDCV = 2,
  OBU_METADATA_TYPE_SCALABILITY = 3,
  OBU_METADATA_TYPE_ITUT_T35 = 4,
  OBU_METADATA_TYPE_TIMECODE = 5,
} OBU_METADATA_TYPE;
 
const char *aom_obu_type_to_string(OBU_TYPE type);
 
#ifdef __cplusplus
}
#endif
#endif  // AOM_AOM_AOM_CODEC_H_