michael@0: /* michael@0: * Copyright (c) 2010 The WebM project authors. All Rights Reserved. michael@0: * michael@0: * Use of this source code is governed by a BSD-style license michael@0: * that can be found in the LICENSE file in the root of the source michael@0: * tree. An additional intellectual property rights grant can be found michael@0: * in the file PATENTS. All contributing project authors may michael@0: * be found in the AUTHORS file in the root of the source tree. michael@0: */ michael@0: #ifndef VPX_ENCODER_H michael@0: #define VPX_ENCODER_H michael@0: michael@0: /*!\defgroup encoder Encoder Algorithm Interface michael@0: * \ingroup codec michael@0: * This abstraction allows applications using this encoder to easily support michael@0: * multiple video formats with minimal code duplication. This section describes michael@0: * the interface common to all encoders. michael@0: * @{ michael@0: */ michael@0: michael@0: /*!\file michael@0: * \brief Describes the encoder algorithm interface to applications. michael@0: * michael@0: * This file describes the interface between an application and a michael@0: * video encoder algorithm. michael@0: * michael@0: */ michael@0: #ifdef __cplusplus michael@0: extern "C" { michael@0: #endif michael@0: michael@0: #include "vpx_codec.h" michael@0: michael@0: /*! Temporal Scalability: Maximum length of the sequence defining frame michael@0: * layer membership michael@0: */ michael@0: #define VPX_TS_MAX_PERIODICITY 16 michael@0: michael@0: /*! Temporal Scalability: Maximum number of coding layers */ michael@0: #define VPX_TS_MAX_LAYERS 5 michael@0: michael@0: /*!\deprecated Use #VPX_TS_MAX_PERIODICITY instead. */ michael@0: #define MAX_PERIODICITY VPX_TS_MAX_PERIODICITY michael@0: michael@0: /*!\deprecated Use #VPX_TS_MAX_LAYERS instead. */ michael@0: #define MAX_LAYERS VPX_TS_MAX_LAYERS michael@0: michael@0: /*! Spatial Scalability: Maximum number of coding layers */ michael@0: #define VPX_SS_MAX_LAYERS 5 michael@0: michael@0: /*! Spatial Scalability: Default number of coding layers */ michael@0: #define VPX_SS_DEFAULT_LAYERS 3 michael@0: michael@0: /*!\brief Current ABI version number michael@0: * michael@0: * \internal michael@0: * If this file is altered in any way that changes the ABI, this value michael@0: * must be bumped. Examples include, but are not limited to, changing michael@0: * types, removing or reassigning enums, adding/removing/rearranging michael@0: * fields to structures michael@0: */ michael@0: #define VPX_ENCODER_ABI_VERSION (3 + VPX_CODEC_ABI_VERSION) /**<\hideinitializer*/ michael@0: michael@0: michael@0: /*! \brief Encoder capabilities bitfield michael@0: * michael@0: * Each encoder advertises the capabilities it supports as part of its michael@0: * ::vpx_codec_iface_t interface structure. Capabilities are extra michael@0: * interfaces or functionality, and are not required to be supported michael@0: * by an encoder. michael@0: * michael@0: * The available flags are specified by VPX_CODEC_CAP_* defines. michael@0: */ michael@0: #define VPX_CODEC_CAP_PSNR 0x10000 /**< Can issue PSNR packets */ michael@0: michael@0: /*! Can output one partition at a time. Each partition is returned in its michael@0: * own VPX_CODEC_CX_FRAME_PKT, with the FRAME_IS_FRAGMENT flag set for michael@0: * every partition but the last. In this mode all frames are always michael@0: * returned partition by partition. michael@0: */ michael@0: #define VPX_CODEC_CAP_OUTPUT_PARTITION 0x20000 michael@0: michael@0: michael@0: /*! \brief Initialization-time Feature Enabling michael@0: * michael@0: * Certain codec features must be known at initialization time, to allow michael@0: * for proper memory allocation. michael@0: * michael@0: * The available flags are specified by VPX_CODEC_USE_* defines. michael@0: */ michael@0: #define VPX_CODEC_USE_PSNR 0x10000 /**< Calculate PSNR on each frame */ michael@0: #define VPX_CODEC_USE_OUTPUT_PARTITION 0x20000 /**< Make the encoder output one michael@0: partition at a time. */ michael@0: michael@0: michael@0: /*!\brief Generic fixed size buffer structure michael@0: * michael@0: * This structure is able to hold a reference to any fixed size buffer. michael@0: */ michael@0: typedef struct vpx_fixed_buf { michael@0: void *buf; /**< Pointer to the data */ michael@0: size_t sz; /**< Length of the buffer, in chars */ michael@0: } vpx_fixed_buf_t; /**< alias for struct vpx_fixed_buf */ michael@0: michael@0: michael@0: /*!\brief Time Stamp Type michael@0: * michael@0: * An integer, which when multiplied by the stream's time base, provides michael@0: * the absolute time of a sample. michael@0: */ michael@0: typedef int64_t vpx_codec_pts_t; michael@0: michael@0: michael@0: /*!\brief Compressed Frame Flags michael@0: * michael@0: * This type represents a bitfield containing information about a compressed michael@0: * frame that may be useful to an application. The most significant 16 bits michael@0: * can be used by an algorithm to provide additional detail, for example to michael@0: * support frame types that are codec specific (MPEG-1 D-frames for example) michael@0: */ michael@0: typedef uint32_t vpx_codec_frame_flags_t; michael@0: #define VPX_FRAME_IS_KEY 0x1 /**< frame is the start of a GOP */ michael@0: #define VPX_FRAME_IS_DROPPABLE 0x2 /**< frame can be dropped without affecting michael@0: the stream (no future frame depends on michael@0: this one) */ michael@0: #define VPX_FRAME_IS_INVISIBLE 0x4 /**< frame should be decoded but will not michael@0: be shown */ michael@0: #define VPX_FRAME_IS_FRAGMENT 0x8 /**< this is a fragment of the encoded michael@0: frame */ michael@0: michael@0: /*!\brief Error Resilient flags michael@0: * michael@0: * These flags define which error resilient features to enable in the michael@0: * encoder. The flags are specified through the michael@0: * vpx_codec_enc_cfg::g_error_resilient variable. michael@0: */ michael@0: typedef uint32_t vpx_codec_er_flags_t; michael@0: #define VPX_ERROR_RESILIENT_DEFAULT 0x1 /**< Improve resiliency against michael@0: losses of whole frames */ michael@0: #define VPX_ERROR_RESILIENT_PARTITIONS 0x2 /**< The frame partitions are michael@0: independently decodable by the michael@0: bool decoder, meaning that michael@0: partitions can be decoded even michael@0: though earlier partitions have michael@0: been lost. Note that intra michael@0: predicition is still done over michael@0: the partition boundary. */ michael@0: michael@0: /*!\brief Encoder output packet variants michael@0: * michael@0: * This enumeration lists the different kinds of data packets that can be michael@0: * returned by calls to vpx_codec_get_cx_data(). Algorithms \ref MAY michael@0: * extend this list to provide additional functionality. michael@0: */ michael@0: enum vpx_codec_cx_pkt_kind { michael@0: VPX_CODEC_CX_FRAME_PKT, /**< Compressed video frame */ michael@0: VPX_CODEC_STATS_PKT, /**< Two-pass statistics for this frame */ michael@0: VPX_CODEC_PSNR_PKT, /**< PSNR statistics for this frame */ michael@0: VPX_CODEC_CUSTOM_PKT = 256 /**< Algorithm extensions */ michael@0: }; michael@0: michael@0: michael@0: /*!\brief Encoder output packet michael@0: * michael@0: * This structure contains the different kinds of output data the encoder michael@0: * may produce while compressing a frame. michael@0: */ michael@0: typedef struct vpx_codec_cx_pkt { michael@0: enum vpx_codec_cx_pkt_kind kind; /**< packet variant */ michael@0: union { michael@0: struct { michael@0: void *buf; /**< compressed data buffer */ michael@0: size_t sz; /**< length of compressed data */ michael@0: vpx_codec_pts_t pts; /**< time stamp to show frame michael@0: (in timebase units) */ michael@0: unsigned long duration; /**< duration to show frame michael@0: (in timebase units) */ michael@0: vpx_codec_frame_flags_t flags; /**< flags for this frame */ michael@0: int partition_id; /**< the partition id michael@0: defines the decoding order michael@0: of the partitions. Only michael@0: applicable when "output partition" michael@0: mode is enabled. First partition michael@0: has id 0.*/ michael@0: michael@0: } frame; /**< data for compressed frame packet */ michael@0: struct vpx_fixed_buf twopass_stats; /**< data for two-pass packet */ michael@0: struct vpx_psnr_pkt { michael@0: unsigned int samples[4]; /**< Number of samples, total/y/u/v */ michael@0: uint64_t sse[4]; /**< sum squared error, total/y/u/v */ michael@0: double psnr[4]; /**< PSNR, total/y/u/v */ michael@0: } psnr; /**< data for PSNR packet */ michael@0: struct vpx_fixed_buf raw; /**< data for arbitrary packets */ michael@0: michael@0: /* This packet size is fixed to allow codecs to extend this michael@0: * interface without having to manage storage for raw packets, michael@0: * i.e., if it's smaller than 128 bytes, you can store in the michael@0: * packet list directly. michael@0: */ michael@0: char pad[128 - sizeof(enum vpx_codec_cx_pkt_kind)]; /**< fixed sz */ michael@0: } data; /**< packet data */ michael@0: } vpx_codec_cx_pkt_t; /**< alias for struct vpx_codec_cx_pkt */ michael@0: michael@0: michael@0: /*!\brief Rational Number michael@0: * michael@0: * This structure holds a fractional value. michael@0: */ michael@0: typedef struct vpx_rational { michael@0: int num; /**< fraction numerator */ michael@0: int den; /**< fraction denominator */ michael@0: } vpx_rational_t; /**< alias for struct vpx_rational */ michael@0: michael@0: michael@0: /*!\brief Multi-pass Encoding Pass */ michael@0: enum vpx_enc_pass { michael@0: VPX_RC_ONE_PASS, /**< Single pass mode */ michael@0: VPX_RC_FIRST_PASS, /**< First pass of multi-pass mode */ michael@0: VPX_RC_LAST_PASS /**< Final pass of multi-pass mode */ michael@0: }; michael@0: michael@0: michael@0: /*!\brief Rate control mode */ michael@0: enum vpx_rc_mode { michael@0: VPX_VBR, /**< Variable Bit Rate (VBR) mode */ michael@0: VPX_CBR, /**< Constant Bit Rate (CBR) mode */ michael@0: VPX_CQ, /**< Constrained Quality (CQ) mode */ michael@0: VPX_Q, /**< Constant Quality (Q) mode */ michael@0: }; michael@0: michael@0: michael@0: /*!\brief Keyframe placement mode. michael@0: * michael@0: * This enumeration determines whether keyframes are placed automatically by michael@0: * the encoder or whether this behavior is disabled. Older releases of this michael@0: * SDK were implemented such that VPX_KF_FIXED meant keyframes were disabled. michael@0: * This name is confusing for this behavior, so the new symbols to be used michael@0: * are VPX_KF_AUTO and VPX_KF_DISABLED. michael@0: */ michael@0: enum vpx_kf_mode { michael@0: VPX_KF_FIXED, /**< deprecated, implies VPX_KF_DISABLED */ michael@0: VPX_KF_AUTO, /**< Encoder determines optimal placement automatically */ michael@0: VPX_KF_DISABLED = 0 /**< Encoder does not place keyframes. */ michael@0: }; michael@0: michael@0: michael@0: /*!\brief Encoded Frame Flags michael@0: * michael@0: * This type indicates a bitfield to be passed to vpx_codec_encode(), defining michael@0: * per-frame boolean values. By convention, bits common to all codecs will be michael@0: * named VPX_EFLAG_*, and bits specific to an algorithm will be named michael@0: * /algo/_eflag_*. The lower order 16 bits are reserved for common use. michael@0: */ michael@0: typedef long vpx_enc_frame_flags_t; michael@0: #define VPX_EFLAG_FORCE_KF (1<<0) /**< Force this frame to be a keyframe */ michael@0: michael@0: michael@0: /*!\brief Encoder configuration structure michael@0: * michael@0: * This structure contains the encoder settings that have common representations michael@0: * across all codecs. This doesn't imply that all codecs support all features, michael@0: * however. michael@0: */ michael@0: typedef struct vpx_codec_enc_cfg { michael@0: /* michael@0: * generic settings (g) michael@0: */ michael@0: michael@0: /*!\brief Algorithm specific "usage" value michael@0: * michael@0: * Algorithms may define multiple values for usage, which may convey the michael@0: * intent of how the application intends to use the stream. If this value michael@0: * is non-zero, consult the documentation for the codec to determine its michael@0: * meaning. michael@0: */ michael@0: unsigned int g_usage; michael@0: michael@0: michael@0: /*!\brief Maximum number of threads to use michael@0: * michael@0: * For multi-threaded implementations, use no more than this number of michael@0: * threads. The codec may use fewer threads than allowed. The value michael@0: * 0 is equivalent to the value 1. michael@0: */ michael@0: unsigned int g_threads; michael@0: michael@0: michael@0: /*!\brief Bitstream profile to use michael@0: * michael@0: * Some codecs support a notion of multiple bitstream profiles. Typically michael@0: * this maps to a set of features that are turned on or off. Often the michael@0: * profile to use is determined by the features of the intended decoder. michael@0: * Consult the documentation for the codec to determine the valid values michael@0: * for this parameter, or set to zero for a sane default. michael@0: */ michael@0: unsigned int g_profile; /**< profile of bitstream to use */ michael@0: michael@0: michael@0: michael@0: /*!\brief Width of the frame michael@0: * michael@0: * This value identifies the presentation resolution of the frame, michael@0: * in pixels. Note that the frames passed as input to the encoder must michael@0: * have this resolution. Frames will be presented by the decoder in this michael@0: * resolution, independent of any spatial resampling the encoder may do. michael@0: */ michael@0: unsigned int g_w; michael@0: michael@0: michael@0: /*!\brief Height of the frame michael@0: * michael@0: * This value identifies the presentation resolution of the frame, michael@0: * in pixels. Note that the frames passed as input to the encoder must michael@0: * have this resolution. Frames will be presented by the decoder in this michael@0: * resolution, independent of any spatial resampling the encoder may do. michael@0: */ michael@0: unsigned int g_h; michael@0: michael@0: michael@0: /*!\brief Stream timebase units michael@0: * michael@0: * Indicates the smallest interval of time, in seconds, used by the stream. michael@0: * For fixed frame rate material, or variable frame rate material where michael@0: * frames are timed at a multiple of a given clock (ex: video capture), michael@0: * the \ref RECOMMENDED method is to set the timebase to the reciprocal michael@0: * of the frame rate (ex: 1001/30000 for 29.970 Hz NTSC). This allows the michael@0: * pts to correspond to the frame number, which can be handy. For michael@0: * re-encoding video from containers with absolute time timestamps, the michael@0: * \ref RECOMMENDED method is to set the timebase to that of the parent michael@0: * container or multimedia framework (ex: 1/1000 for ms, as in FLV). michael@0: */ michael@0: struct vpx_rational g_timebase; michael@0: michael@0: michael@0: /*!\brief Enable error resilient modes. michael@0: * michael@0: * The error resilient bitfield indicates to the encoder which features michael@0: * it should enable to take measures for streaming over lossy or noisy michael@0: * links. michael@0: */ michael@0: vpx_codec_er_flags_t g_error_resilient; michael@0: michael@0: michael@0: /*!\brief Multi-pass Encoding Mode michael@0: * michael@0: * This value should be set to the current phase for multi-pass encoding. michael@0: * For single pass, set to #VPX_RC_ONE_PASS. michael@0: */ michael@0: enum vpx_enc_pass g_pass; michael@0: michael@0: michael@0: /*!\brief Allow lagged encoding michael@0: * michael@0: * If set, this value allows the encoder to consume a number of input michael@0: * frames before producing output frames. This allows the encoder to michael@0: * base decisions for the current frame on future frames. This does michael@0: * increase the latency of the encoding pipeline, so it is not appropriate michael@0: * in all situations (ex: realtime encoding). michael@0: * michael@0: * Note that this is a maximum value -- the encoder may produce frames michael@0: * sooner than the given limit. Set this value to 0 to disable this michael@0: * feature. michael@0: */ michael@0: unsigned int g_lag_in_frames; michael@0: michael@0: michael@0: /* michael@0: * rate control settings (rc) michael@0: */ michael@0: michael@0: /*!\brief Temporal resampling configuration, if supported by the codec. michael@0: * michael@0: * Temporal resampling allows the codec to "drop" frames as a strategy to michael@0: * meet its target data rate. This can cause temporal discontinuities in michael@0: * the encoded video, which may appear as stuttering during playback. This michael@0: * trade-off is often acceptable, but for many applications is not. It can michael@0: * be disabled in these cases. michael@0: * michael@0: * Note that not all codecs support this feature. All vpx VPx codecs do. michael@0: * For other codecs, consult the documentation for that algorithm. michael@0: * michael@0: * This threshold is described as a percentage of the target data buffer. michael@0: * When the data buffer falls below this percentage of fullness, a michael@0: * dropped frame is indicated. Set the threshold to zero (0) to disable michael@0: * this feature. michael@0: */ michael@0: unsigned int rc_dropframe_thresh; michael@0: michael@0: michael@0: /*!\brief Enable/disable spatial resampling, if supported by the codec. michael@0: * michael@0: * Spatial resampling allows the codec to compress a lower resolution michael@0: * version of the frame, which is then upscaled by the encoder to the michael@0: * correct presentation resolution. This increases visual quality at michael@0: * low data rates, at the expense of CPU time on the encoder/decoder. michael@0: */ michael@0: unsigned int rc_resize_allowed; michael@0: michael@0: michael@0: /*!\brief Spatial resampling up watermark. michael@0: * michael@0: * This threshold is described as a percentage of the target data buffer. michael@0: * When the data buffer rises above this percentage of fullness, the michael@0: * encoder will step up to a higher resolution version of the frame. michael@0: */ michael@0: unsigned int rc_resize_up_thresh; michael@0: michael@0: michael@0: /*!\brief Spatial resampling down watermark. michael@0: * michael@0: * This threshold is described as a percentage of the target data buffer. michael@0: * When the data buffer falls below this percentage of fullness, the michael@0: * encoder will step down to a lower resolution version of the frame. michael@0: */ michael@0: unsigned int rc_resize_down_thresh; michael@0: michael@0: michael@0: /*!\brief Rate control algorithm to use. michael@0: * michael@0: * Indicates whether the end usage of this stream is to be streamed over michael@0: * a bandwidth constrained link, indicating that Constant Bit Rate (CBR) michael@0: * mode should be used, or whether it will be played back on a high michael@0: * bandwidth link, as from a local disk, where higher variations in michael@0: * bitrate are acceptable. michael@0: */ michael@0: enum vpx_rc_mode rc_end_usage; michael@0: michael@0: michael@0: /*!\brief Two-pass stats buffer. michael@0: * michael@0: * A buffer containing all of the stats packets produced in the first michael@0: * pass, concatenated. michael@0: */ michael@0: struct vpx_fixed_buf rc_twopass_stats_in; michael@0: michael@0: michael@0: /*!\brief Target data rate michael@0: * michael@0: * Target bandwidth to use for this stream, in kilobits per second. michael@0: */ michael@0: unsigned int rc_target_bitrate; michael@0: michael@0: michael@0: /* michael@0: * quantizer settings michael@0: */ michael@0: michael@0: michael@0: /*!\brief Minimum (Best Quality) Quantizer michael@0: * michael@0: * The quantizer is the most direct control over the quality of the michael@0: * encoded image. The range of valid values for the quantizer is codec michael@0: * specific. Consult the documentation for the codec to determine the michael@0: * values to use. To determine the range programmatically, call michael@0: * vpx_codec_enc_config_default() with a usage value of 0. michael@0: */ michael@0: unsigned int rc_min_quantizer; michael@0: michael@0: michael@0: /*!\brief Maximum (Worst Quality) Quantizer michael@0: * michael@0: * The quantizer is the most direct control over the quality of the michael@0: * encoded image. The range of valid values for the quantizer is codec michael@0: * specific. Consult the documentation for the codec to determine the michael@0: * values to use. To determine the range programmatically, call michael@0: * vpx_codec_enc_config_default() with a usage value of 0. michael@0: */ michael@0: unsigned int rc_max_quantizer; michael@0: michael@0: michael@0: /* michael@0: * bitrate tolerance michael@0: */ michael@0: michael@0: michael@0: /*!\brief Rate control adaptation undershoot control michael@0: * michael@0: * This value, expressed as a percentage of the target bitrate, michael@0: * controls the maximum allowed adaptation speed of the codec. michael@0: * This factor controls the maximum amount of bits that can michael@0: * be subtracted from the target bitrate in order to compensate michael@0: * for prior overshoot. michael@0: * michael@0: * Valid values in the range 0-1000. michael@0: */ michael@0: unsigned int rc_undershoot_pct; michael@0: michael@0: michael@0: /*!\brief Rate control adaptation overshoot control michael@0: * michael@0: * This value, expressed as a percentage of the target bitrate, michael@0: * controls the maximum allowed adaptation speed of the codec. michael@0: * This factor controls the maximum amount of bits that can michael@0: * be added to the target bitrate in order to compensate for michael@0: * prior undershoot. michael@0: * michael@0: * Valid values in the range 0-1000. michael@0: */ michael@0: unsigned int rc_overshoot_pct; michael@0: michael@0: michael@0: /* michael@0: * decoder buffer model parameters michael@0: */ michael@0: michael@0: michael@0: /*!\brief Decoder Buffer Size michael@0: * michael@0: * This value indicates the amount of data that may be buffered by the michael@0: * decoding application. Note that this value is expressed in units of michael@0: * time (milliseconds). For example, a value of 5000 indicates that the michael@0: * client will buffer (at least) 5000ms worth of encoded data. Use the michael@0: * target bitrate (#rc_target_bitrate) to convert to bits/bytes, if michael@0: * necessary. michael@0: */ michael@0: unsigned int rc_buf_sz; michael@0: michael@0: michael@0: /*!\brief Decoder Buffer Initial Size michael@0: * michael@0: * This value indicates the amount of data that will be buffered by the michael@0: * decoding application prior to beginning playback. This value is michael@0: * expressed in units of time (milliseconds). Use the target bitrate michael@0: * (#rc_target_bitrate) to convert to bits/bytes, if necessary. michael@0: */ michael@0: unsigned int rc_buf_initial_sz; michael@0: michael@0: michael@0: /*!\brief Decoder Buffer Optimal Size michael@0: * michael@0: * This value indicates the amount of data that the encoder should try michael@0: * to maintain in the decoder's buffer. This value is expressed in units michael@0: * of time (milliseconds). Use the target bitrate (#rc_target_bitrate) michael@0: * to convert to bits/bytes, if necessary. michael@0: */ michael@0: unsigned int rc_buf_optimal_sz; michael@0: michael@0: michael@0: /* michael@0: * 2 pass rate control parameters michael@0: */ michael@0: michael@0: michael@0: /*!\brief Two-pass mode CBR/VBR bias michael@0: * michael@0: * Bias, expressed on a scale of 0 to 100, for determining target size michael@0: * for the current frame. The value 0 indicates the optimal CBR mode michael@0: * value should be used. The value 100 indicates the optimal VBR mode michael@0: * value should be used. Values in between indicate which way the michael@0: * encoder should "lean." michael@0: */ michael@0: unsigned int rc_2pass_vbr_bias_pct; /**< RC mode bias between CBR and VBR(0-100: 0->CBR, 100->VBR) */ michael@0: michael@0: michael@0: /*!\brief Two-pass mode per-GOP minimum bitrate michael@0: * michael@0: * This value, expressed as a percentage of the target bitrate, indicates michael@0: * the minimum bitrate to be used for a single GOP (aka "section") michael@0: */ michael@0: unsigned int rc_2pass_vbr_minsection_pct; michael@0: michael@0: michael@0: /*!\brief Two-pass mode per-GOP maximum bitrate michael@0: * michael@0: * This value, expressed as a percentage of the target bitrate, indicates michael@0: * the maximum bitrate to be used for a single GOP (aka "section") michael@0: */ michael@0: unsigned int rc_2pass_vbr_maxsection_pct; michael@0: michael@0: michael@0: /* michael@0: * keyframing settings (kf) michael@0: */ michael@0: michael@0: /*!\brief Keyframe placement mode michael@0: * michael@0: * This value indicates whether the encoder should place keyframes at a michael@0: * fixed interval, or determine the optimal placement automatically michael@0: * (as governed by the #kf_min_dist and #kf_max_dist parameters) michael@0: */ michael@0: enum vpx_kf_mode kf_mode; michael@0: michael@0: michael@0: /*!\brief Keyframe minimum interval michael@0: * michael@0: * This value, expressed as a number of frames, prevents the encoder from michael@0: * placing a keyframe nearer than kf_min_dist to the previous keyframe. At michael@0: * least kf_min_dist frames non-keyframes will be coded before the next michael@0: * keyframe. Set kf_min_dist equal to kf_max_dist for a fixed interval. michael@0: */ michael@0: unsigned int kf_min_dist; michael@0: michael@0: michael@0: /*!\brief Keyframe maximum interval michael@0: * michael@0: * This value, expressed as a number of frames, forces the encoder to code michael@0: * a keyframe if one has not been coded in the last kf_max_dist frames. michael@0: * A value of 0 implies all frames will be keyframes. Set kf_min_dist michael@0: * equal to kf_max_dist for a fixed interval. michael@0: */ michael@0: unsigned int kf_max_dist; michael@0: michael@0: /* michael@0: * Spatial scalability settings (ss) michael@0: */ michael@0: michael@0: /*!\brief Number of coding layers (spatial) michael@0: * michael@0: * This value specifies the number of coding layers to be used. michael@0: */ michael@0: unsigned int ss_number_layers; michael@0: michael@0: /*!\brief Number of coding layers michael@0: * michael@0: * This value specifies the number of coding layers to be used. michael@0: */ michael@0: unsigned int ts_number_layers; michael@0: michael@0: /*!\brief Target bitrate for each layer michael@0: * michael@0: * These values specify the target coding bitrate for each coding layer. michael@0: */ michael@0: unsigned int ts_target_bitrate[VPX_TS_MAX_LAYERS]; michael@0: michael@0: /*!\brief Frame rate decimation factor for each layer michael@0: * michael@0: * These values specify the frame rate decimation factors to apply michael@0: * to each layer. michael@0: */ michael@0: unsigned int ts_rate_decimator[VPX_TS_MAX_LAYERS]; michael@0: michael@0: /*!\brief Length of the sequence defining frame layer membership michael@0: * michael@0: * This value specifies the length of the sequence that defines the michael@0: * membership of frames to layers. For example, if ts_periodicity=8 then michael@0: * frames are assigned to coding layers with a repeated sequence of michael@0: * length 8. michael@0: */ michael@0: unsigned int ts_periodicity; michael@0: michael@0: /*!\brief Template defining the membership of frames to coding layers michael@0: * michael@0: * This array defines the membership of frames to coding layers. For a michael@0: * 2-layer encoding that assigns even numbered frames to one layer (0) michael@0: * and odd numbered frames to a second layer (1) with ts_periodicity=8, michael@0: * then ts_layer_id = (0,1,0,1,0,1,0,1). michael@0: */ michael@0: unsigned int ts_layer_id[VPX_TS_MAX_PERIODICITY]; michael@0: } vpx_codec_enc_cfg_t; /**< alias for struct vpx_codec_enc_cfg */ michael@0: michael@0: michael@0: /*!\brief Initialize an encoder instance michael@0: * michael@0: * Initializes a encoder context using the given interface. Applications michael@0: * should call the vpx_codec_enc_init convenience macro instead of this michael@0: * function directly, to ensure that the ABI version number parameter michael@0: * is properly initialized. michael@0: * michael@0: * If the library was configured with --disable-multithread, this call michael@0: * is not thread safe and should be guarded with a lock if being used michael@0: * in a multithreaded context. michael@0: * michael@0: * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags michael@0: * parameter), the storage pointed to by the cfg parameter must be michael@0: * kept readable and stable until all memory maps have been set. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context. michael@0: * \param[in] iface Pointer to the algorithm interface to use. michael@0: * \param[in] cfg Configuration to use, if known. May be NULL. michael@0: * \param[in] flags Bitfield of VPX_CODEC_USE_* flags michael@0: * \param[in] ver ABI version number. Must be set to michael@0: * VPX_ENCODER_ABI_VERSION michael@0: * \retval #VPX_CODEC_OK michael@0: * The decoder algorithm initialized. michael@0: * \retval #VPX_CODEC_MEM_ERROR michael@0: * Memory allocation failed. michael@0: */ michael@0: vpx_codec_err_t vpx_codec_enc_init_ver(vpx_codec_ctx_t *ctx, michael@0: vpx_codec_iface_t *iface, michael@0: vpx_codec_enc_cfg_t *cfg, michael@0: vpx_codec_flags_t flags, michael@0: int ver); michael@0: michael@0: michael@0: /*!\brief Convenience macro for vpx_codec_enc_init_ver() michael@0: * michael@0: * Ensures the ABI version parameter is properly set. michael@0: */ michael@0: #define vpx_codec_enc_init(ctx, iface, cfg, flags) \ michael@0: vpx_codec_enc_init_ver(ctx, iface, cfg, flags, VPX_ENCODER_ABI_VERSION) michael@0: michael@0: michael@0: /*!\brief Initialize multi-encoder instance michael@0: * michael@0: * Initializes multi-encoder context using the given interface. michael@0: * Applications should call the vpx_codec_enc_init_multi convenience macro michael@0: * instead of this function directly, to ensure that the ABI version number michael@0: * parameter is properly initialized. michael@0: * michael@0: * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags michael@0: * parameter), the storage pointed to by the cfg parameter must be michael@0: * kept readable and stable until all memory maps have been set. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context. michael@0: * \param[in] iface Pointer to the algorithm interface to use. michael@0: * \param[in] cfg Configuration to use, if known. May be NULL. michael@0: * \param[in] num_enc Total number of encoders. michael@0: * \param[in] flags Bitfield of VPX_CODEC_USE_* flags michael@0: * \param[in] dsf Pointer to down-sampling factors. michael@0: * \param[in] ver ABI version number. Must be set to michael@0: * VPX_ENCODER_ABI_VERSION michael@0: * \retval #VPX_CODEC_OK michael@0: * The decoder algorithm initialized. michael@0: * \retval #VPX_CODEC_MEM_ERROR michael@0: * Memory allocation failed. michael@0: */ michael@0: vpx_codec_err_t vpx_codec_enc_init_multi_ver(vpx_codec_ctx_t *ctx, michael@0: vpx_codec_iface_t *iface, michael@0: vpx_codec_enc_cfg_t *cfg, michael@0: int num_enc, michael@0: vpx_codec_flags_t flags, michael@0: vpx_rational_t *dsf, michael@0: int ver); michael@0: michael@0: michael@0: /*!\brief Convenience macro for vpx_codec_enc_init_multi_ver() michael@0: * michael@0: * Ensures the ABI version parameter is properly set. michael@0: */ michael@0: #define vpx_codec_enc_init_multi(ctx, iface, cfg, num_enc, flags, dsf) \ michael@0: vpx_codec_enc_init_multi_ver(ctx, iface, cfg, num_enc, flags, dsf, \ michael@0: VPX_ENCODER_ABI_VERSION) michael@0: michael@0: michael@0: /*!\brief Get a default configuration michael@0: * michael@0: * Initializes a encoder configuration structure with default values. Supports michael@0: * the notion of "usages" so that an algorithm may offer different default michael@0: * settings depending on the user's intended goal. This function \ref SHOULD michael@0: * be called by all applications to initialize the configuration structure michael@0: * before specializing the configuration with application specific values. michael@0: * michael@0: * \param[in] iface Pointer to the algorithm interface to use. michael@0: * \param[out] cfg Configuration buffer to populate michael@0: * \param[in] usage End usage. Set to 0 or use codec specific values. michael@0: * michael@0: * \retval #VPX_CODEC_OK michael@0: * The configuration was populated. michael@0: * \retval #VPX_CODEC_INCAPABLE michael@0: * Interface is not an encoder interface. michael@0: * \retval #VPX_CODEC_INVALID_PARAM michael@0: * A parameter was NULL, or the usage value was not recognized. michael@0: */ michael@0: vpx_codec_err_t vpx_codec_enc_config_default(vpx_codec_iface_t *iface, michael@0: vpx_codec_enc_cfg_t *cfg, michael@0: unsigned int usage); michael@0: michael@0: michael@0: /*!\brief Set or change configuration michael@0: * michael@0: * Reconfigures an encoder instance according to the given configuration. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context michael@0: * \param[in] cfg Configuration buffer to use michael@0: * michael@0: * \retval #VPX_CODEC_OK michael@0: * The configuration was populated. michael@0: * \retval #VPX_CODEC_INCAPABLE michael@0: * Interface is not an encoder interface. michael@0: * \retval #VPX_CODEC_INVALID_PARAM michael@0: * A parameter was NULL, or the usage value was not recognized. michael@0: */ michael@0: vpx_codec_err_t vpx_codec_enc_config_set(vpx_codec_ctx_t *ctx, michael@0: const vpx_codec_enc_cfg_t *cfg); michael@0: michael@0: michael@0: /*!\brief Get global stream headers michael@0: * michael@0: * Retrieves a stream level global header packet, if supported by the codec. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context michael@0: * michael@0: * \retval NULL michael@0: * Encoder does not support global header michael@0: * \retval Non-NULL michael@0: * Pointer to buffer containing global header packet michael@0: */ michael@0: vpx_fixed_buf_t *vpx_codec_get_global_headers(vpx_codec_ctx_t *ctx); michael@0: michael@0: michael@0: #define VPX_DL_REALTIME (1) /**< deadline parameter analogous to michael@0: * VPx REALTIME mode. */ michael@0: #define VPX_DL_GOOD_QUALITY (1000000) /**< deadline parameter analogous to michael@0: * VPx GOOD QUALITY mode. */ michael@0: #define VPX_DL_BEST_QUALITY (0) /**< deadline parameter analogous to michael@0: * VPx BEST QUALITY mode. */ michael@0: /*!\brief Encode a frame michael@0: * michael@0: * Encodes a video frame at the given "presentation time." The presentation michael@0: * time stamp (PTS) \ref MUST be strictly increasing. michael@0: * michael@0: * The encoder supports the notion of a soft real-time deadline. Given a michael@0: * non-zero value to the deadline parameter, the encoder will make a "best michael@0: * effort" guarantee to return before the given time slice expires. It is michael@0: * implicit that limiting the available time to encode will degrade the michael@0: * output quality. The encoder can be given an unlimited time to produce the michael@0: * best possible frame by specifying a deadline of '0'. This deadline michael@0: * supercedes the VPx notion of "best quality, good quality, realtime". michael@0: * Applications that wish to map these former settings to the new deadline michael@0: * based system can use the symbols #VPX_DL_REALTIME, #VPX_DL_GOOD_QUALITY, michael@0: * and #VPX_DL_BEST_QUALITY. michael@0: * michael@0: * When the last frame has been passed to the encoder, this function should michael@0: * continue to be called, with the img parameter set to NULL. This will michael@0: * signal the end-of-stream condition to the encoder and allow it to encode michael@0: * any held buffers. Encoding is complete when vpx_codec_encode() is called michael@0: * and vpx_codec_get_cx_data() returns no data. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context michael@0: * \param[in] img Image data to encode, NULL to flush. michael@0: * \param[in] pts Presentation time stamp, in timebase units. michael@0: * \param[in] duration Duration to show frame, in timebase units. michael@0: * \param[in] flags Flags to use for encoding this frame. michael@0: * \param[in] deadline Time to spend encoding, in microseconds. (0=infinite) michael@0: * michael@0: * \retval #VPX_CODEC_OK michael@0: * The configuration was populated. michael@0: * \retval #VPX_CODEC_INCAPABLE michael@0: * Interface is not an encoder interface. michael@0: * \retval #VPX_CODEC_INVALID_PARAM michael@0: * A parameter was NULL, the image format is unsupported, etc. michael@0: */ michael@0: vpx_codec_err_t vpx_codec_encode(vpx_codec_ctx_t *ctx, michael@0: const vpx_image_t *img, michael@0: vpx_codec_pts_t pts, michael@0: unsigned long duration, michael@0: vpx_enc_frame_flags_t flags, michael@0: unsigned long deadline); michael@0: michael@0: /*!\brief Set compressed data output buffer michael@0: * michael@0: * Sets the buffer that the codec should output the compressed data michael@0: * into. This call effectively sets the buffer pointer returned in the michael@0: * next VPX_CODEC_CX_FRAME_PKT packet. Subsequent packets will be michael@0: * appended into this buffer. The buffer is preserved across frames, michael@0: * so applications must periodically call this function after flushing michael@0: * the accumulated compressed data to disk or to the network to reset michael@0: * the pointer to the buffer's head. michael@0: * michael@0: * `pad_before` bytes will be skipped before writing the compressed michael@0: * data, and `pad_after` bytes will be appended to the packet. The size michael@0: * of the packet will be the sum of the size of the actual compressed michael@0: * data, pad_before, and pad_after. The padding bytes will be preserved michael@0: * (not overwritten). michael@0: * michael@0: * Note that calling this function does not guarantee that the returned michael@0: * compressed data will be placed into the specified buffer. In the michael@0: * event that the encoded data will not fit into the buffer provided, michael@0: * the returned packet \ref MAY point to an internal buffer, as it would michael@0: * if this call were never used. In this event, the output packet will michael@0: * NOT have any padding, and the application must free space and copy it michael@0: * to the proper place. This is of particular note in configurations michael@0: * that may output multiple packets for a single encoded frame (e.g., lagged michael@0: * encoding) or if the application does not reset the buffer periodically. michael@0: * michael@0: * Applications may restore the default behavior of the codec providing michael@0: * the compressed data buffer by calling this function with a NULL michael@0: * buffer. michael@0: * michael@0: * Applications \ref MUSTNOT call this function during iteration of michael@0: * vpx_codec_get_cx_data(). michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context michael@0: * \param[in] buf Buffer to store compressed data into michael@0: * \param[in] pad_before Bytes to skip before writing compressed data michael@0: * \param[in] pad_after Bytes to skip after writing compressed data michael@0: * michael@0: * \retval #VPX_CODEC_OK michael@0: * The buffer was set successfully. michael@0: * \retval #VPX_CODEC_INVALID_PARAM michael@0: * A parameter was NULL, the image format is unsupported, etc. michael@0: */ michael@0: vpx_codec_err_t vpx_codec_set_cx_data_buf(vpx_codec_ctx_t *ctx, michael@0: const vpx_fixed_buf_t *buf, michael@0: unsigned int pad_before, michael@0: unsigned int pad_after); michael@0: michael@0: michael@0: /*!\brief Encoded data iterator michael@0: * michael@0: * Iterates over a list of data packets to be passed from the encoder to the michael@0: * application. The different kinds of packets available are enumerated in michael@0: * #vpx_codec_cx_pkt_kind. michael@0: * michael@0: * #VPX_CODEC_CX_FRAME_PKT packets should be passed to the application's michael@0: * muxer. Multiple compressed frames may be in the list. michael@0: * #VPX_CODEC_STATS_PKT packets should be appended to a global buffer. michael@0: * michael@0: * The application \ref MUST silently ignore any packet kinds that it does michael@0: * not recognize or support. michael@0: * michael@0: * The data buffers returned from this function are only guaranteed to be michael@0: * valid until the application makes another call to any vpx_codec_* function. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context michael@0: * \param[in,out] iter Iterator storage, initialized to NULL michael@0: * michael@0: * \return Returns a pointer to an output data packet (compressed frame data, michael@0: * two-pass statistics, etc.) or NULL to signal end-of-list. michael@0: * michael@0: */ michael@0: const vpx_codec_cx_pkt_t *vpx_codec_get_cx_data(vpx_codec_ctx_t *ctx, michael@0: vpx_codec_iter_t *iter); michael@0: michael@0: michael@0: /*!\brief Get Preview Frame michael@0: * michael@0: * Returns an image that can be used as a preview. Shows the image as it would michael@0: * exist at the decompressor. The application \ref MUST NOT write into this michael@0: * image buffer. michael@0: * michael@0: * \param[in] ctx Pointer to this instance's context michael@0: * michael@0: * \return Returns a pointer to a preview image, or NULL if no image is michael@0: * available. michael@0: * michael@0: */ michael@0: const vpx_image_t *vpx_codec_get_preview_frame(vpx_codec_ctx_t *ctx); michael@0: michael@0: michael@0: /*!@} - end defgroup encoder*/ michael@0: #ifdef __cplusplus michael@0: } michael@0: #endif michael@0: #endif michael@0: