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     {
00097         void          *buf; 
00098         size_t         sz;  
00099     } vpx_fixed_buf_t; 
00107     typedef int64_t vpx_codec_pts_t;
00108 
00109 
00117     typedef uint32_t vpx_codec_frame_flags_t;
00118 #define VPX_FRAME_IS_KEY       0x1 
00119 #define VPX_FRAME_IS_DROPPABLE 0x2 
00122 #define VPX_FRAME_IS_INVISIBLE 0x4 
00124 #define VPX_FRAME_IS_FRAGMENT  0x8 
00133     typedef uint32_t vpx_codec_er_flags_t;
00134 #define VPX_ERROR_RESILIENT_DEFAULT     0x1 
00136 #define VPX_ERROR_RESILIENT_PARTITIONS  0x2 
00151     enum vpx_codec_cx_pkt_kind
00152     {
00153         VPX_CODEC_CX_FRAME_PKT,    
00154         VPX_CODEC_STATS_PKT,       
00155         VPX_CODEC_PSNR_PKT,        
00156         VPX_CODEC_CUSTOM_PKT = 256 
00157     };
00158 
00159 
00165     typedef struct vpx_codec_cx_pkt
00166     {
00167         enum vpx_codec_cx_pkt_kind  kind; 
00168         union
00169         {
00170             struct
00171             {
00172                 void                    *buf;      
00173                 size_t                   sz;       
00174                 vpx_codec_pts_t          pts;      
00176                 unsigned long            duration; 
00178                 vpx_codec_frame_flags_t  flags;    
00179                 int                      partition_id; 
00186             } frame;  
00187             struct vpx_fixed_buf twopass_stats;  
00188             struct vpx_psnr_pkt
00189             {
00190                 unsigned int samples[4];  
00191                 uint64_t     sse[4];      
00192                 double       psnr[4];     
00193             } psnr;                       
00194             struct vpx_fixed_buf raw;     
00196             /* This packet size is fixed to allow codecs to extend this
00197              * interface without having to manage storage for raw packets,
00198              * i.e., if it's smaller than 128 bytes, you can store in the
00199              * packet list directly.
00200              */
00201             char pad[128 - sizeof(enum vpx_codec_cx_pkt_kind)]; 
00202         } data; 
00203     } vpx_codec_cx_pkt_t; 
00210     typedef struct vpx_rational
00211     {
00212         int num; 
00213         int den; 
00214     } vpx_rational_t; 
00218     enum vpx_enc_pass
00219     {
00220         VPX_RC_ONE_PASS,   
00221         VPX_RC_FIRST_PASS, 
00222         VPX_RC_LAST_PASS   
00223     };
00224 
00225 
00227     enum vpx_rc_mode
00228     {
00229         VPX_VBR, 
00230         VPX_CBR,  
00231         VPX_CQ   
00232     };
00233 
00234 
00243     enum vpx_kf_mode
00244     {
00245         VPX_KF_FIXED, 
00246         VPX_KF_AUTO,  
00247         VPX_KF_DISABLED = 0 
00248     };
00249 
00250 
00258     typedef long vpx_enc_frame_flags_t;
00259 #define VPX_EFLAG_FORCE_KF (1<<0)  
00268     typedef struct vpx_codec_enc_cfg
00269     {
00270         /*
00271          * generic settings (g)
00272          */
00273 
00281         unsigned int           g_usage;
00282 
00283 
00290         unsigned int           g_threads;
00291 
00292 
00301         unsigned int           g_profile;  
00312         unsigned int           g_w;
00313 
00314 
00322         unsigned int           g_h;
00323 
00324 
00337         struct vpx_rational    g_timebase;
00338 
00339 
00346         vpx_codec_er_flags_t   g_error_resilient;
00347 
00348 
00354         enum vpx_enc_pass      g_pass;
00355 
00356 
00369         unsigned int           g_lag_in_frames;
00370 
00371 
00372         /*
00373          * rate control settings (rc)
00374          */
00375 
00392         unsigned int           rc_dropframe_thresh;
00393 
00394 
00402         unsigned int           rc_resize_allowed;
00403 
00404 
00411         unsigned int           rc_resize_up_thresh;
00412 
00413 
00420         unsigned int           rc_resize_down_thresh;
00421 
00422 
00431         enum vpx_rc_mode       rc_end_usage;
00432 
00433 
00439         struct vpx_fixed_buf   rc_twopass_stats_in;
00440 
00441 
00446         unsigned int           rc_target_bitrate;
00447 
00448 
00449         /*
00450          * quantizer settings
00451          */
00452 
00453 
00462         unsigned int           rc_min_quantizer;
00463 
00464 
00473         unsigned int           rc_max_quantizer;
00474 
00475 
00476         /*
00477          * bitrate tolerance
00478          */
00479 
00480 
00491         unsigned int           rc_undershoot_pct;
00492 
00493 
00504         unsigned int           rc_overshoot_pct;
00505 
00506 
00507         /*
00508          * decoder buffer model parameters
00509          */
00510 
00511 
00521         unsigned int           rc_buf_sz;
00522 
00523 
00531         unsigned int           rc_buf_initial_sz;
00532 
00533 
00541         unsigned int           rc_buf_optimal_sz;
00542 
00543 
00544         /*
00545          * 2 pass rate control parameters
00546          */
00547 
00548 
00557         unsigned int           rc_2pass_vbr_bias_pct;       
00565         unsigned int           rc_2pass_vbr_minsection_pct;
00566 
00567 
00573         unsigned int           rc_2pass_vbr_maxsection_pct;
00574 
00575 
00576         /*
00577          * keyframing settings (kf)
00578          */
00579 
00586         enum vpx_kf_mode       kf_mode;
00587 
00588 
00596         unsigned int           kf_min_dist;
00597 
00598 
00606         unsigned int           kf_max_dist;
00607 
00608         /*
00609          * Temporal scalability settings (ts)
00610          */
00611 
00616         unsigned int           ts_number_layers;
00617 
00622         unsigned int           ts_target_bitrate[VPX_TS_MAX_LAYERS];
00623 
00629         unsigned int           ts_rate_decimator[VPX_TS_MAX_LAYERS];
00630 
00638         unsigned int           ts_periodicity;
00639 
00647         unsigned int           ts_layer_id[VPX_TS_MAX_PERIODICITY];
00648     } vpx_codec_enc_cfg_t; 
00673     vpx_codec_err_t vpx_codec_enc_init_ver(vpx_codec_ctx_t      *ctx,
00674                                            vpx_codec_iface_t    *iface,
00675                                            vpx_codec_enc_cfg_t  *cfg,
00676                                            vpx_codec_flags_t     flags,
00677                                            int                   ver);
00678 
00679 
00684 #define vpx_codec_enc_init(ctx, iface, cfg, flags) \
00685     vpx_codec_enc_init_ver(ctx, iface, cfg, flags, VPX_ENCODER_ABI_VERSION)
00686 
00687 
00712     vpx_codec_err_t vpx_codec_enc_init_multi_ver(vpx_codec_ctx_t      *ctx,
00713                                                  vpx_codec_iface_t    *iface,
00714                                                  vpx_codec_enc_cfg_t  *cfg,
00715                                                  int                   num_enc,
00716                                                  vpx_codec_flags_t     flags,
00717                                                  vpx_rational_t       *dsf,
00718                                                  int                   ver);
00719 
00720 
00725 #define vpx_codec_enc_init_multi(ctx, iface, cfg, num_enc, flags, dsf) \
00726     vpx_codec_enc_init_multi_ver(ctx, iface, cfg, num_enc, flags, dsf, \
00727                                  VPX_ENCODER_ABI_VERSION)
00728 
00729 
00749     vpx_codec_err_t  vpx_codec_enc_config_default(vpx_codec_iface_t    *iface,
00750             vpx_codec_enc_cfg_t  *cfg,
00751             unsigned int          usage);
00752 
00753 
00768     vpx_codec_err_t  vpx_codec_enc_config_set(vpx_codec_ctx_t            *ctx,
00769             const vpx_codec_enc_cfg_t  *cfg);
00770 
00771 
00783     vpx_fixed_buf_t *vpx_codec_get_global_headers(vpx_codec_ctx_t   *ctx);
00784 
00785 
00786 #define VPX_DL_REALTIME     (1)        
00788 #define VPX_DL_GOOD_QUALITY (1000000)  
00790 #define VPX_DL_BEST_QUALITY (0)        
00828     vpx_codec_err_t  vpx_codec_encode(vpx_codec_ctx_t            *ctx,
00829                                       const vpx_image_t          *img,
00830                                       vpx_codec_pts_t             pts,
00831                                       unsigned long               duration,
00832                                       vpx_enc_frame_flags_t       flags,
00833                                       unsigned long               deadline);
00834 
00878     vpx_codec_err_t vpx_codec_set_cx_data_buf(vpx_codec_ctx_t       *ctx,
00879             const vpx_fixed_buf_t *buf,
00880             unsigned int           pad_before,
00881             unsigned int           pad_after);
00882 
00883 
00907     const vpx_codec_cx_pkt_t *vpx_codec_get_cx_data(vpx_codec_ctx_t   *ctx,
00908             vpx_codec_iter_t  *iter);
00909 
00910 
00923     const vpx_image_t *vpx_codec_get_preview_frame(vpx_codec_ctx_t   *ctx);
00924 
00925 
00928 #endif
00929 #ifdef __cplusplus
00930 }
00931 #endif