WebM VP8 Codec SDK
vpx/vpx_encoder.h
Go to the documentation of this file.
00001 /*
00002  *  Copyright (c) 2010 The WebM project authors. All Rights Reserved.
00003  *
00004  *  Use of this source code is governed by a BSD-style license
00005  *  that can be found in the LICENSE file in the root of the source
00006  *  tree. An additional intellectual property rights grant can be found
00007  *  in the file PATENTS.  All contributing project authors may
00008  *  be found in the AUTHORS file in the root of the source tree.
00009  */
00010 
00011 
00027 #ifdef __cplusplus
00028 extern "C" {
00029 #endif
00030 
00031 #ifndef VPX_ENCODER_H
00032 #define VPX_ENCODER_H
00033 #include "vpx_codec.h"
00034 
00038 #define VPX_TS_MAX_PERIODICITY 16
00039 
00041 #define VPX_TS_MAX_LAYERS       5
00042 
00044 #define MAX_PERIODICITY VPX_TS_MAX_PERIODICITY
00045 
00047 #define MAX_LAYERS      VPX_TS_MAX_LAYERS
00048 
00057 #define VPX_ENCODER_ABI_VERSION (3 + VPX_CODEC_ABI_VERSION) 
00069 #define VPX_CODEC_CAP_PSNR  0x10000 
00076 #define VPX_CODEC_CAP_OUTPUT_PARTITION  0x20000
00077 
00078 
00086 #define VPX_CODEC_USE_PSNR  0x10000 
00087 #define VPX_CODEC_USE_OUTPUT_PARTITION  0x20000 
00095   typedef struct vpx_fixed_buf {
00096     void          *buf; 
00097     size_t         sz;  
00098   } vpx_fixed_buf_t; 
00106   typedef int64_t vpx_codec_pts_t;
00107 
00108 
00116   typedef uint32_t vpx_codec_frame_flags_t;
00117 #define VPX_FRAME_IS_KEY       0x1 
00118 #define VPX_FRAME_IS_DROPPABLE 0x2 
00121 #define VPX_FRAME_IS_INVISIBLE 0x4 
00123 #define VPX_FRAME_IS_FRAGMENT  0x8 
00132   typedef uint32_t vpx_codec_er_flags_t;
00133 #define VPX_ERROR_RESILIENT_DEFAULT     0x1 
00135 #define VPX_ERROR_RESILIENT_PARTITIONS  0x2 
00150   enum vpx_codec_cx_pkt_kind {
00151     VPX_CODEC_CX_FRAME_PKT,    
00152     VPX_CODEC_STATS_PKT,       
00153     VPX_CODEC_PSNR_PKT,        
00154     VPX_CODEC_CUSTOM_PKT = 256 
00155   };
00156 
00157 
00163   typedef struct vpx_codec_cx_pkt {
00164     enum vpx_codec_cx_pkt_kind  kind; 
00165     union {
00166       struct {
00167         void                    *buf;      
00168         size_t                   sz;       
00169         vpx_codec_pts_t          pts;      
00171         unsigned long            duration; 
00173         vpx_codec_frame_flags_t  flags;    
00174         int                      partition_id; 
00181       } frame;  
00182       struct vpx_fixed_buf twopass_stats;  
00183       struct vpx_psnr_pkt {
00184         unsigned int samples[4];  
00185         uint64_t     sse[4];      
00186         double       psnr[4];     
00187       } psnr;                       
00188       struct vpx_fixed_buf raw;     
00190       /* This packet size is fixed to allow codecs to extend this
00191        * interface without having to manage storage for raw packets,
00192        * i.e., if it's smaller than 128 bytes, you can store in the
00193        * packet list directly.
00194        */
00195       char pad[128 - sizeof(enum vpx_codec_cx_pkt_kind)]; 
00196     } data; 
00197   } vpx_codec_cx_pkt_t; 
00204   typedef struct vpx_rational {
00205     int num; 
00206     int den; 
00207   } vpx_rational_t; 
00211   enum vpx_enc_pass {
00212     VPX_RC_ONE_PASS,   
00213     VPX_RC_FIRST_PASS, 
00214     VPX_RC_LAST_PASS   
00215   };
00216 
00217 
00219   enum vpx_rc_mode {
00220     VPX_VBR, 
00221     VPX_CBR,  
00222     VPX_CQ   
00223   };
00224 
00225 
00234   enum vpx_kf_mode {
00235     VPX_KF_FIXED, 
00236     VPX_KF_AUTO,  
00237     VPX_KF_DISABLED = 0 
00238   };
00239 
00240 
00248   typedef long vpx_enc_frame_flags_t;
00249 #define VPX_EFLAG_FORCE_KF (1<<0)  
00258   typedef struct vpx_codec_enc_cfg {
00259     /*
00260      * generic settings (g)
00261      */
00262 
00270     unsigned int           g_usage;
00271 
00272 
00279     unsigned int           g_threads;
00280 
00281 
00290     unsigned int           g_profile;  
00301     unsigned int           g_w;
00302 
00303 
00311     unsigned int           g_h;
00312 
00313 
00326     struct vpx_rational    g_timebase;
00327 
00328 
00335     vpx_codec_er_flags_t   g_error_resilient;
00336 
00337 
00343     enum vpx_enc_pass      g_pass;
00344 
00345 
00358     unsigned int           g_lag_in_frames;
00359 
00360 
00361     /*
00362      * rate control settings (rc)
00363      */
00364 
00381     unsigned int           rc_dropframe_thresh;
00382 
00383 
00391     unsigned int           rc_resize_allowed;
00392 
00393 
00400     unsigned int           rc_resize_up_thresh;
00401 
00402 
00409     unsigned int           rc_resize_down_thresh;
00410 
00411 
00420     enum vpx_rc_mode       rc_end_usage;
00421 
00422 
00428     struct vpx_fixed_buf   rc_twopass_stats_in;
00429 
00430 
00435     unsigned int           rc_target_bitrate;
00436 
00437 
00438     /*
00439      * quantizer settings
00440      */
00441 
00442 
00451     unsigned int           rc_min_quantizer;
00452 
00453 
00462     unsigned int           rc_max_quantizer;
00463 
00464 
00465     /*
00466      * bitrate tolerance
00467      */
00468 
00469 
00480     unsigned int           rc_undershoot_pct;
00481 
00482 
00493     unsigned int           rc_overshoot_pct;
00494 
00495 
00496     /*
00497      * decoder buffer model parameters
00498      */
00499 
00500 
00510     unsigned int           rc_buf_sz;
00511 
00512 
00520     unsigned int           rc_buf_initial_sz;
00521 
00522 
00530     unsigned int           rc_buf_optimal_sz;
00531 
00532 
00533     /*
00534      * 2 pass rate control parameters
00535      */
00536 
00537 
00546     unsigned int           rc_2pass_vbr_bias_pct;       
00554     unsigned int           rc_2pass_vbr_minsection_pct;
00555 
00556 
00562     unsigned int           rc_2pass_vbr_maxsection_pct;
00563 
00564 
00565     /*
00566      * keyframing settings (kf)
00567      */
00568 
00575     enum vpx_kf_mode       kf_mode;
00576 
00577 
00585     unsigned int           kf_min_dist;
00586 
00587 
00595     unsigned int           kf_max_dist;
00596 
00597     /*
00598      * Temporal scalability settings (ts)
00599      */
00600 
00605     unsigned int           ts_number_layers;
00606 
00611     unsigned int           ts_target_bitrate[VPX_TS_MAX_LAYERS];
00612 
00618     unsigned int           ts_rate_decimator[VPX_TS_MAX_LAYERS];
00619 
00627     unsigned int           ts_periodicity;
00628 
00636     unsigned int           ts_layer_id[VPX_TS_MAX_PERIODICITY];
00637   } vpx_codec_enc_cfg_t; 
00666   vpx_codec_err_t vpx_codec_enc_init_ver(vpx_codec_ctx_t      *ctx,
00667                                          vpx_codec_iface_t    *iface,
00668                                          vpx_codec_enc_cfg_t  *cfg,
00669                                          vpx_codec_flags_t     flags,
00670                                          int                   ver);
00671 
00672 
00677 #define vpx_codec_enc_init(ctx, iface, cfg, flags) \
00678   vpx_codec_enc_init_ver(ctx, iface, cfg, flags, VPX_ENCODER_ABI_VERSION)
00679 
00680 
00705   vpx_codec_err_t vpx_codec_enc_init_multi_ver(vpx_codec_ctx_t      *ctx,
00706                                                vpx_codec_iface_t    *iface,
00707                                                vpx_codec_enc_cfg_t  *cfg,
00708                                                int                   num_enc,
00709                                                vpx_codec_flags_t     flags,
00710                                                vpx_rational_t       *dsf,
00711                                                int                   ver);
00712 
00713 
00718 #define vpx_codec_enc_init_multi(ctx, iface, cfg, num_enc, flags, dsf) \
00719   vpx_codec_enc_init_multi_ver(ctx, iface, cfg, num_enc, flags, dsf, \
00720                                VPX_ENCODER_ABI_VERSION)
00721 
00722 
00742   vpx_codec_err_t  vpx_codec_enc_config_default(vpx_codec_iface_t    *iface,
00743                                                 vpx_codec_enc_cfg_t  *cfg,
00744                                                 unsigned int          usage);
00745 
00746 
00761   vpx_codec_err_t  vpx_codec_enc_config_set(vpx_codec_ctx_t            *ctx,
00762                                             const vpx_codec_enc_cfg_t  *cfg);
00763 
00764 
00776   vpx_fixed_buf_t *vpx_codec_get_global_headers(vpx_codec_ctx_t   *ctx);
00777 
00778 
00779 #define VPX_DL_REALTIME     (1)        
00781 #define VPX_DL_GOOD_QUALITY (1000000)  
00783 #define VPX_DL_BEST_QUALITY (0)        
00821   vpx_codec_err_t  vpx_codec_encode(vpx_codec_ctx_t            *ctx,
00822                                     const vpx_image_t          *img,
00823                                     vpx_codec_pts_t             pts,
00824                                     unsigned long               duration,
00825                                     vpx_enc_frame_flags_t       flags,
00826                                     unsigned long               deadline);
00827 
00871   vpx_codec_err_t vpx_codec_set_cx_data_buf(vpx_codec_ctx_t       *ctx,
00872                                             const vpx_fixed_buf_t *buf,
00873                                             unsigned int           pad_before,
00874                                             unsigned int           pad_after);
00875 
00876 
00900   const vpx_codec_cx_pkt_t *vpx_codec_get_cx_data(vpx_codec_ctx_t   *ctx,
00901                                                   vpx_codec_iter_t  *iter);
00902 
00903 
00916   const vpx_image_t *vpx_codec_get_preview_frame(vpx_codec_ctx_t   *ctx);
00917 
00918 
00921 #endif
00922 #ifdef __cplusplus
00923 }
00924 #endif