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 
00035 #define MAX_PERIODICITY 16
00036 #define MAX_LAYERS       5
00037 
00046 #define VPX_ENCODER_ABI_VERSION (3 + VPX_CODEC_ABI_VERSION) 
00058 #define VPX_CODEC_CAP_PSNR  0x10000 
00065 #define VPX_CODEC_CAP_OUTPUT_PARTITION  0x20000
00066 
00067 
00075 #define VPX_CODEC_USE_PSNR  0x10000 
00076 #define VPX_CODEC_USE_OUTPUT_PARTITION  0x20000 
00084     typedef struct vpx_fixed_buf
00085     {
00086         void          *buf; 
00087         size_t         sz;  
00088     } vpx_fixed_buf_t; 
00096     typedef int64_t vpx_codec_pts_t;
00097 
00098 
00106     typedef uint32_t vpx_codec_frame_flags_t;
00107 #define VPX_FRAME_IS_KEY       0x1 
00108 #define VPX_FRAME_IS_DROPPABLE 0x2 
00111 #define VPX_FRAME_IS_INVISIBLE 0x4 
00113 #define VPX_FRAME_IS_FRAGMENT  0x8 
00122     typedef uint32_t vpx_codec_er_flags_t;
00123 #define VPX_ERROR_RESILIENT_DEFAULT     0x1 
00125 #define VPX_ERROR_RESILIENT_PARTITIONS  0x2 
00140     enum vpx_codec_cx_pkt_kind
00141     {
00142         VPX_CODEC_CX_FRAME_PKT,    
00143         VPX_CODEC_STATS_PKT,       
00144         VPX_CODEC_PSNR_PKT,        
00145         VPX_CODEC_CUSTOM_PKT = 256 
00146     };
00147 
00148 
00154     typedef struct vpx_codec_cx_pkt
00155     {
00156         enum vpx_codec_cx_pkt_kind  kind; 
00157         union
00158         {
00159             struct
00160             {
00161                 void                    *buf;      
00162                 size_t                   sz;       
00163                 vpx_codec_pts_t          pts;      
00165                 unsigned long            duration; 
00167                 vpx_codec_frame_flags_t  flags;    
00168                 int                      partition_id; 
00175             } frame;  
00176             struct vpx_fixed_buf twopass_stats;  
00177             struct vpx_psnr_pkt
00178             {
00179                 unsigned int samples[4];  
00180                 uint64_t     sse[4];      
00181                 double       psnr[4];     
00182             } psnr;                       
00183             struct vpx_fixed_buf raw;     
00185             /* This packet size is fixed to allow codecs to extend this
00186              * interface without having to manage storage for raw packets,
00187              * i.e., if it's smaller than 128 bytes, you can store in the
00188              * packet list directly.
00189              */
00190             char pad[128 - sizeof(enum vpx_codec_cx_pkt_kind)]; 
00191         } data; 
00192     } vpx_codec_cx_pkt_t; 
00199     typedef struct vpx_rational
00200     {
00201         int num; 
00202         int den; 
00203     } vpx_rational_t; 
00207     enum vpx_enc_pass
00208     {
00209         VPX_RC_ONE_PASS,   
00210         VPX_RC_FIRST_PASS, 
00211         VPX_RC_LAST_PASS   
00212     };
00213 
00214 
00216     enum vpx_rc_mode
00217     {
00218         VPX_VBR, 
00219         VPX_CBR,  
00220         VPX_CQ   
00221     };
00222 
00223 
00232     enum vpx_kf_mode
00233     {
00234         VPX_KF_FIXED, 
00235         VPX_KF_AUTO,  
00236         VPX_KF_DISABLED = 0 
00237     };
00238 
00239 
00247     typedef long vpx_enc_frame_flags_t;
00248 #define VPX_EFLAG_FORCE_KF (1<<0)  
00257     typedef struct vpx_codec_enc_cfg
00258     {
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[MAX_LAYERS];
00612 
00618         unsigned int           ts_rate_decimator[MAX_LAYERS];
00619 
00627         unsigned int           ts_periodicity;
00628 
00636         unsigned int           ts_layer_id[MAX_PERIODICITY];
00637     } vpx_codec_enc_cfg_t; 
00662     vpx_codec_err_t vpx_codec_enc_init_ver(vpx_codec_ctx_t      *ctx,
00663                                            vpx_codec_iface_t    *iface,
00664                                            vpx_codec_enc_cfg_t  *cfg,
00665                                            vpx_codec_flags_t     flags,
00666                                            int                   ver);
00667 
00668 
00673 #define vpx_codec_enc_init(ctx, iface, cfg, flags) \
00674     vpx_codec_enc_init_ver(ctx, iface, cfg, flags, VPX_ENCODER_ABI_VERSION)
00675 
00676 
00701     vpx_codec_err_t vpx_codec_enc_init_multi_ver(vpx_codec_ctx_t      *ctx,
00702                                                  vpx_codec_iface_t    *iface,
00703                                                  vpx_codec_enc_cfg_t  *cfg,
00704                                                  int                   num_enc,
00705                                                  vpx_codec_flags_t     flags,
00706                                                  vpx_rational_t       *dsf,
00707                                                  int                   ver);
00708 
00709 
00714 #define vpx_codec_enc_init_multi(ctx, iface, cfg, num_enc, flags, dsf) \
00715     vpx_codec_enc_init_multi_ver(ctx, iface, cfg, num_enc, flags, dsf, \
00716                                  VPX_ENCODER_ABI_VERSION)
00717 
00718 
00738     vpx_codec_err_t  vpx_codec_enc_config_default(vpx_codec_iface_t    *iface,
00739             vpx_codec_enc_cfg_t  *cfg,
00740             unsigned int          usage);
00741 
00742 
00757     vpx_codec_err_t  vpx_codec_enc_config_set(vpx_codec_ctx_t            *ctx,
00758             const vpx_codec_enc_cfg_t  *cfg);
00759 
00760 
00772     vpx_fixed_buf_t *vpx_codec_get_global_headers(vpx_codec_ctx_t   *ctx);
00773 
00774 
00775 #define VPX_DL_REALTIME     (1)        
00777 #define VPX_DL_GOOD_QUALITY (1000000)  
00779 #define VPX_DL_BEST_QUALITY (0)        
00817     vpx_codec_err_t  vpx_codec_encode(vpx_codec_ctx_t            *ctx,
00818                                       const vpx_image_t          *img,
00819                                       vpx_codec_pts_t             pts,
00820                                       unsigned long               duration,
00821                                       vpx_enc_frame_flags_t       flags,
00822                                       unsigned long               deadline);
00823 
00867     vpx_codec_err_t vpx_codec_set_cx_data_buf(vpx_codec_ctx_t       *ctx,
00868             const vpx_fixed_buf_t *buf,
00869             unsigned int           pad_before,
00870             unsigned int           pad_after);
00871 
00872 
00896     const vpx_codec_cx_pkt_t *vpx_codec_get_cx_data(vpx_codec_ctx_t   *ctx,
00897             vpx_codec_iter_t  *iter);
00898 
00899 
00912     const vpx_image_t *vpx_codec_get_preview_frame(vpx_codec_ctx_t   *ctx);
00913 
00914 
00917 #endif
00918 #ifdef __cplusplus
00919 }
00920 #endif