x264_param_t 详解

x264的x264_param_t结构

typedef struct x264_param_t
{
    /* CPU flags */
    unsigned int cpu;

    /* 并行线程的数量，即同时被编码的图像的数量，增加线程数量会影响编码速度，
     * 同时也会影响编码延迟（所谓编码延迟就是 编码器中得到第一个输出时已经往输入的帧数）
     */
    int         i_threads;           /* encode multiple frames in parallel */
    /* 向前看线程的数量，为了提高压缩率得到更好的质量，x264会缓存一部分帧用于分析
     * 以得到最优的编码参数，但是会增加编码延迟
     */
    int         i_lookahead_threads; /* multiple threads for lookahead analysis */
/* 是否使用基于slice的线程，使用zerolatency将会禁用该选项，和i_threads是互斥的，即frame级别的并性
 * 和slice级别的并行不能同时进行
     */
    int         b_sliced_threads;  /* Whether to use slice-based threading. */
    /* 当进行并行处理时，是否使用使用非确定的优化，默认是true
     */
    int         b_deterministic; /* whether to allow non-deterministic optimizations when threaded */
    /* 是否使用cpu相关的优化算法，如果否，那么选择传统的规范的算法（性能可能不高）
     */
    int         b_cpu_independent; /* force canonical behavior rather than cpu-dependent optimal algorithms */
    /* 前向缓存的帧的数量，前向缓存的目的是为了得到更好的比特率或画面质量
     */
    int         i_sync_lookahead; /* threaded lookahead buffer */

    /* Video Properties */
    int         i_width;
    int         i_height;
    int         i_csp;         /* CSP of encoded bitstream */
    int         i_level_idc;
    int         i_frame_total; /* number of frames to encode if known, else 0 */

    /* NAL HRD
     * Uses Buffering and Picture Timing SEIs to signal HRD
     * The HRD in H.264 was not designed with VFR in mind.
     * It is therefore not recommendeded to use NAL HRD with VFR.
     * Furthermore, reconfiguring the VBV (via x264_encoder_reconfig)
     * will currently generate invalid HRD. */
    /* 检验编码器产生的符合该标准的NAL单元流或字节流的偏差值。蓝光视频、电视广播及其它特殊领域有此要求
     */
    int         i_nal_hrd;

    /* 视频可用信息
     */
    struct
    {
        /* they will be reduced to be 0 < x <= 65535 and prime */
        /*
         * 样本的宽高比
         */
        int         i_sar_height;
        int         i_sar_width;

        /* 过扫描的类型：不设置、观看、过扫描
         */
        int         i_overscan;    /* 0=undef, 1=no overscan, 2=overscan */
x264_param_t
        /* see h264 annex E for the values of the following */
        /* 视频在编码/数字化之前是什么类型，默认"undef".
         * 取值有：Component, PAL, NTSC, SECAM, MAC 等
         */
        int         i_vidformat;
        /*样本亮度和色度的计算方式，默认"off"，可选项：off/on
         */
        int         b_fullrange;
        /* 原始色度格式，默认"undef"
         */
        int         i_colorprim;
        /* 转换方式，默认"undef"
         */
        int         i_transfer;
        /* 设置从RGB计算得到亮度和色度所用的矩阵系数，默认"undef"
         */
        int         i_colmatrix;
        /* 设置色度采样位置，范围0~5，默认0
         */
        int         i_chroma_loc;    /* both top & bottom */
    } vui;

    /* Bitstream parameters */
    int         i_frame_reference;  /* Maximum number of reference frames */
    /* 强迫DPB（解码图像缓存区）的尺寸大于通过（B帧数量和参考帧数量）计算出来的大小
     */
    int         i_dpb_size;         /* Force a DPB size larger than that implied by B-frames and reference frames.
                                     * Useful in combination with interactive error resilience. */
    /*
     * IDR帧的间隔
     */
    int         i_keyint_max;       /* Force an IDR keyframe at this interval */
    /* IDR帧的最小间隔，如果遇到场景切换，但是间隔小于keyint_min。那么它将被看作I帧而不是IDR帧
     */
    int         i_keyint_min;       /* Scenecuts closer together than this are coded as I, not IDR. */
    /* 判断一个帧是否为常见切换的阈值
     */
    int         i_scenecut_threshold; /* how aggressively to insert extra I frames */
    /* 是否使用周期帧内刷新代替IDR帧
     */
    int         b_intra_refresh;    /* Whether or not to use periodic intra refresh instead of IDR frames. */
    /* 两个参考帧之间的B帧数量
     */
    int         i_bframe;   /* how many b-frame between 2 references pictures */
    /* 自适应的B帧判断，判断一个帧是否被编码器设置为B帧
     */
    int         i_bframe_adaptive;
    /* 控制B帧代替P帧的概率从-100到100，值越大，概率越高
     */
    int         i_bframe_bias;
    /*是否允许B帧也作为参考帧，默认是不允许的，这个功能可以进一步压缩数据，但是相应的延迟也会增加
     */
    int         i_bframe_pyramid;   /* Keep some B-frames as references: 0=off, 1=strict hierarchical, 2=normal */
    /* 是否使用开放式图像组，所谓开放式图像组就是当前图像组的帧可以参考前一个图像组的帧，默认是false
     */
    int         b_open_gop;x264_param_t
    /* 是否支持蓝光碟片
     */
    int         b_bluray_compat;
    /* 这个参数没搞懂，好像是avc帧内处理的一个东西
     */
    int         i_avcintra_class;
    /* 是否开启去放开滤波
     */
    int         b_deblocking_filter;
    /*alpha和beta是去方块滤波的参数，强弱滤波相关
     */
    int         i_deblocking_filter_alphac0;    /* [-6, 6] -6 light filter, 6 strong */
    int         i_deblocking_filter_beta;       /* [-6, 6]  idem */
    /* 是否使用上下文自适应二进制算术编码x264_param_t
     */
    int         b_cabac;
    /* cabac的初始参数
     */
    int         i_cabac_init_idc;
    /* 场编码还是帧编码
     */
    int         b_interlaced;
    /* 强迫进行帧内预测
     */
    int         b_constrained_intra;
    /* 自定义的量化矩阵，量化的模式：flat、jvt、custom
     */
    int         i_cqm_preset;
    /* 自定义量化矩阵的文件名
     */
    char        *psz_cqm_file;      /* filename (in UTF-8) of CQM file, JM format */
    /* 自定义量化矩阵，只有在custom模式下才有效
     */
    uint8_t     cqm_4iy[16];        /* used only if i_cqm_preset == X264_CQM_CUSTOM */
    uint8_t     cqm_4py[16];
    uint8_t     cqm_4ic[16];
    uint8_t     cqm_4pc[16];
    uint8_t     cqm_8iy[64];
    uint8_t     cqm_8py[64];
    uint8_t     cqm_8ic[64];
    uint8_t     cqm_8pc[64];
    /* Log */
    void        (*pf_log)( void *, int i_level, const char *psz, va_list );
    void        *p_log_private;
    int         i_log_level;
    /* 是否进行完整的重建
     */
    int         b_full_recon;   /* fully reconstruct frames, even when not necessary for encoding.  Implied by psz_dump_yuv */
    /* 重建帧，文件名
     */
    char        *psz_dump_yuv;  /* filename (in UTF-8) for reconstructed frames */

    /* Encoder analyser parameters */
    struct
    {
        /* 帧内partition（划分）的数量
         */
        unsigned int intra;     /* intra partitions */
        /* 帧间partition的数量
         */
        unsigned int inter;     /* inter partitions */
        /* 是否使用8x8的DCT变换
         */
        int          b_transform_8x8;
        /* 权重预测中，P帧的权值
         */
        int          i_weighted_pred; /* weighting for P-frames */
        /* B帧的权值是隐式的还是显示的
         */
        int          b_weighted_bipred; /* implicit weighting for B-frames */
        /* 时域、空间的MV预测方式：是使用时域、还是空域，或者让编码器自动选择
         */
        int          i_direct_mv_pred; /* spatial vs temporal mv prediction */
        /* 色度量化步长的偏移量
         */
        int          i_chroma_qp_offset;
        /* 运动估计的方法：钻石形状、三步模式什么的
         */
        int          i_me_method; /* motion estimation algorithm to use (X264_ME_*) */
        /* 运动搜索的范围，对编码速度由很大影响，不同的preset对应不同的搜索范围
         */
        int          i_me_range; /* integer pixel motion estimation search range (from predicted mv) */
        /* 运动向量的取值范围，由level决定，-1表示由编码器自己设置
         */
        int          i_mv_range; /* maximum length of a mv (in pixels). -1 = auto, based on level */
        /* 线程之间的最小运动向量缓存，这个不太理解
         */
        int          i_mv_range_thread; /* minimum space between threads. -1 = auto, based on number of threads. */
        /* 亚像素运动估计的质量（精度）
         */
        int          i_subpel_refine; /* subpixel motion estimation quality */
        /* 是否允许 亚像素色度运动估计和P帧的模式选择
         */
        int          b_chroma_me; /* chroma ME for subpel and mode decision in P-frames */
        /* 是否允许每个宏块的分区有自己的参考编号
         */
        int          b_mixed_references; /* allow each mb partition to have its own reference number */
        /* Trellis量化提高效率，对每个8x8的块寻找合适的量化值，需要CABAC，
         * 0 ：即关闭  1：只在最后编码时使用  2：在所有模式决策上启用
         */
        int          i_trellis;  /* trellis RD quantization */
        /* 快速P帧跳过检测
         */
        int          b_fast_pskip; /* early SKIP detection on P-frames */
        /* P帧变换系数阈值
         */
        int          b_dct_decimate; /* transform coefficient thresholding on P-frames */
        /* 自适应伪盲区
         */
        int          i_noise_reduction; /* adaptive pseudo-deadzone */
        /* Psy优化强度，可能会增强细节
         */
        float        f_psy_rd; /* Psy RD strength */
        /* Psy Trellis强度
         */
        float        f_psy_trellis; /* Psy trellis strength */
        /* Psy优化开关
         */
        int          b_psy; /* Toggle all psy optimizations */
        /* 是否使用输入的mb信息（在x264_picture_t中）
         */
        int          b_mb_info;            /* Use input mb_info data in x264_picture_t */
        /* 是否根据编码结果更新mb信息
         */
        int          b_mb_info_update; /* Update the values in mb_info according to the results of encoding. */

        /* the deadzone size that will be used in luma quantization */
        /* 亮度量化中使用的盲区大小
         */
        int          i_luma_deadzone[2]; /* {inter, intra} */
        /*是否打印，psnr
         */
        int          b_psnr;    /* compute and print PSNR stats */
        /* 是否打印ssim
         */
        int          b_ssim;    /* compute and print SSIM stats */
    } analyse;

    /* Rate control parameters */
    struct
    {
        /* 码率控制的方法，默认是CRF
         * X264_RC_CQP恒定质量,  X264_RC_CRF恒定码率,  X264_RC_ABR平均码率
         */
        int         i_rc_method;    /* X264_RC_* */

        /* 指定P帧的量化值
         */
        int         i_qp_constant;  /* 0 to (51 + 6*(x264_bit_depth-8)). 0=lossless */
        /* 允许的最大最小QP值
         */
        int         i_qp_min;       /* min allowed QP value */
        int         i_qp_max;       /* max allowed QP value */
        /* 量化步长，相邻两帧之间量化值的最大差值
         */
        int         i_qp_step;      /* max QP step between frames */
        /* 码率
         */
        int         i_bitrate;
        /* 实际质量，值越大图像越花,越小越清晰
         */
        float       f_rf_constant;  /* 1pass VBR, nominal QP */
        /* 最大码率因子，该选项仅在使用CRF并开启VBV时有效，图像质量的最大值，可能会导致VBV下溢
         */
        float       f_rf_constant_max;  /* In CRF mode, maximum CRF as caused by VBV */
        /* 允许的码率误差
         */
        float       f_rate_tolerance;
        /* 平均码率模式下，最大瞬时码率，默认0
         */
        int         i_vbv_max_bitrate;
        /* 码率控制缓冲区的大小，单位kbit，默认0
         */
        int         i_vbv_buffer_size;
        /* 设置码率控制缓冲区（VBV）缓冲达到多满(百分比)，才开始回放，范围0~1.0，默认0.9
         */
        float       f_vbv_buffer_init; /* <=1: fraction of buffer_size. >1: kbit */
        /* I帧和P帧之间的量化因子（QP）比值，默认1.4
         */
        float       f_ip_factor;
        /* P帧和B帧之间的量化因子（QP）比值，默认1.3
         */
        float       f_pb_factor;

        /* VBV filler: force CBR VBV and use filler bytes to ensure hard-CBR.
         * Implied by NAL-HRD CBR. */
        /* 这个参数还不太明白
         */
        int         b_filler;

        /* 自适应量化（AQ）模式。 0：关闭AQ ， 1：允许AQ在整个视频中和帧内重新分配码 2：自方差AQ(实验阶段)，尝试逐帧调整强度
         */
        int         i_aq_mode;      /* psy adaptive QP. (X264_AQ_*) */
        /* 自适应量化的强度，减少平趟和纹理区域的块效应和模糊度
         */
        float       f_aq_strength;
        /* 是否开启基于macroblock的qp控制方法
         * MBTree File是一个临时文件，记录了每个P帧中每个MB被参考的情况。
         *  目前mbtree只处理P帧的MB，同时也不支持b_pyramid
         */
        int         b_mb_tree;      /* Macroblock-tree ratecontrol. */
        /* 决定mbtree向前预测的帧数
         */
        int         i_lookahead;

        /* 2pass */
        /* 是否允许把2pass的统计信息写入psz_stat_out中
         */
        int         b_stat_write;   /* Enable stat writing in psz_stat_out */
        char        *psz_stat_out;  /* output filename (in UTF-8) of the 2pass stats file */
        /* 2pass是否允许从psz_stat_in中读取统计信息
         */
        int         b_stat_read;    /* Read stat from psz_stat_in and use it */
        char        *psz_stat_in;   /* input filename (in UTF-8) of the 2pass stats file */

        /* 2pass params (same as ffmpeg ones) */
        /* 量化曲线(quantizer curve)压缩因子 0.0 => 恒定比特率，1.0 => 恒定量化值。
         */
        float       f_qcompress;    /* 0.0 => cbr, 1.0 => constant qp */
        /* 时间上模糊量化，减少QP的波动
         */
        float       f_qblur;        /* temporally blur quants */
        /* 时间上模糊复杂性，减少QP的波动
         */
        float       f_complexity_blur; /* temporally blur complexity */
        /* 码率控制覆盖
         */
        x264_zone_t *zones;         /* ratecontrol overrides */
        int         i_zones;        /* number of zone_t's */
        /* 指定区的另一种方法
         */
        char        *psz_zones;     /* alternate method of specifying zones */
    } rc;

    /* Cropping Rectangle parameters: added to those implicitly defined by
       non-mod16 video resolutions. */
    /* 裁剪矩形窗口参数：隐式添加到分辨率非16倍数的视频中
     * 在码流层指定一个切除(crop)矩形。若不想x264在编码时做crop，
     * 但希望解码器在回放时进行切除，可使用此项。单位为像素
     */
    struct
    {
        unsigned int i_left;
        unsigned int i_top;
        unsigned int i_right;
        unsigned int i_bottom;
    } crop_rect;

    /* frame packing arrangement flag */
    /*
     * 编码3D视频时，此参数在码流中插入一个标志，告知解码器此3D视频是如何封装的。
     * 3D视频帧封装格式：帧封装、场交错、线交错、左右全景、左右半景、上下半景、L+深度、L+深度+图形+图形深度
     */
    int i_frame_packing;

    /* Muxing parameters */
    /* 是否生成nalu分隔符
     */
    int b_aud;                  /* generate access unit delimiters */
    /*
     * 是否复制sps和pps放在每个关键帧的前面
     */
    int b_repeat_headers;       /* put SPS/PPS before each keyframe */
    /* nalu是否符合标准
     * 值为true，则NALU之前是4字节前缀码0x00000001;值为false，则NALU之前的4个字节为NALU长度
     */
    int b_annexb;               /* if set, place start codes (4 bytes) before NAL units,
                                 * otherwise place size (4 bytes) before NAL units. */
    int i_sps_id;               /* SPS and PPS id number */
    /* VFR输入。1 ：时间基和时间戳用于码率控制  0 ：仅帧率用于码率控制
     */
    int b_vfr_input;            /* VFR input.  If 1, use timebase and timestamps for ratecontrol purposes.
                                 * If 0, use fps only. */
    /*以某个预设模式将输入流(隔行，恒定帧率)标记为软交错(soft telecine)。默认none. 可用预设有：
     * none, 22, 32, 64, double, triple, euro.  使用除none以外任一预设，都会连带开启--pic-struct
     */
    int b_pulldown;             /* use explicity set timebase for CFR */
    /*  帧率的分子
     */
    uint32_t i_fps_num;
    /* 帧率的分母
     */
    uint32_t i_fps_den;
    /* 时间基的分子
     */
    uint32_t i_timebase_num;    /* Timebase numerator */
    /* 时间基的分母
     */
    uint32_t i_timebase_den;    /* Timebase denominator */

    int b_tff;

    /* Pulldown:
     * The correct pic_struct must be passed with each input frame.
     * The input timebase should be the timebase corresponding to the output framerate. This should be constant.
     * e.g. for 3:2 pulldown timebase should be 1001/30000
     * The PTS passed with each frame must be the PTS of the frame after pulldown is applied.
     * Frame doubling and tripling require b_vfr_input set to zero (see H.264 Table D-1)
     *
     * Pulldown changes are not clearly defined in H.264. Therefore, it is the calling app's responsibility to manage this.
     */
    /* 强制在Picture Timing SEI传送pic_struct. 默认是未开启
     */
    int b_pic_struct;

    /* Fake Interlaced.
     *
     * Used only when b_interlaced=0. Setting this flag makes it possible to flag the stream as PAFF interlaced yet
     * encode all frames progessively. It is useful for encoding 25p and 30p Blu-Ray streams.
     */
    /*
     * 将视频流标记为交错(隔行)，哪怕并非为交错式编码。可用于编码蓝光兼容的25p和30p视频。默认是未开启
     */
    int b_fake_interlaced;

    /* Don't optimize header parameters based on video content, e.g. ensure that splitting an input video, compressing
     * each part, and stitching them back together will result in identical SPS/PPS. This is necessary for stitching
     * with container formats that don't allow multiple SPS/PPS. */
    /* 不要根据视频内容优化标头参数
     */
    int b_stitchable;

    /* openCL 相关的设置
     */
    int b_opencl;            /* use OpenCL when available */
    int i_opencl_device;     /* specify count of GPU devices to skip, for CLI users */
    void *opencl_device_id;  /* pass explicit cl_device_id as void*, for API users */
    char *psz_clbin_file;    /* filename (in UTF-8) of the compiled OpenCL kernel cache file */

    /* Slicing parameters */
    /* slice的参数，大小尺寸等
     */
    int i_slice_max_size;    /* Max size per slice in bytes; includes estimated NAL overhead. */
    int i_slice_max_mbs;     /* Max number of MBs per slice; overrides i_slice_count. */
    int i_slice_min_mbs;     /* Min number of MBs per slice */
    int i_slice_count;       /* Number of slices per frame: forces rectangular slices. */
    int i_slice_count_max;   /* Absolute cap on slices per frame; stops applying slice-max-size
                              * and slice-max-mbs if this is reached. */

    /* Optional callback for freeing this x264_param_t when it is done being used.
     * Only used when the x264_param_t sits in memory for an indefinite period of time,
     * i.e. when an x264_param_t is passed to x264_t in an x264_picture_t or in zones.
     * Not used when x264_encoder_reconfig is called directly. */
    /* x264_param_t参数释放的函数指针
     */
    void (*param_free)( void* );

    /* Optional low-level callback for low-latency encoding.  Called for each output NAL unit
     * immediately after the NAL unit is finished encoding.  This allows the calling application
     * to begin processing video data (e.g. by sending packets over a network) before the frame
     * is done encoding.
     *
     * This callback MUST do the following in order to work correctly:
     * 1) Have available an output buffer of at least size nal->i_payload*3/2 + 5 + 64.
     * 2) Call x264_nal_encode( h, dst, nal ), where dst is the output buffer.
     * After these steps, the content of nal is valid and can be used in the same way as if
     * the NAL unit were output by x264_encoder_encode.
     *
     * This does not need to be synchronous with the encoding process: the data pointed to
     * by nal (both before and after x264_nal_encode) will remain valid until the next
     * x264_encoder_encode call.  The callback must be re-entrant.
     *
     * This callback does not work with frame-based threads; threads must be disabled
     * or sliced-threads enabled.  This callback also does not work as one would expect
     * with HRD -- since the buffering period SEI cannot be calculated until the frame
     * is finished encoding, it will not be sent via this callback.
     *
     * Note also that the NALs are not necessarily returned in order when sliced threads is
     * enabled.  Accordingly, the variable i_first_mb and i_last_mb are available in
     * x264_nal_t to help the calling application reorder the slices if necessary.
     *
     * When this callback is enabled, x264_encoder_encode does not return valid NALs;
     * the calling application is expected to acquire all output NALs through the callback.
     *
     * It is generally sensible to combine this callback with a use of slice-max-mbs or
     * slice-max-size.
     *
     * The opaque pointer is the opaque pointer from the input frame associated with this
     * NAL unit. This helps distinguish between nalu_process calls from different sources,
     * e.g. if doing multiple encodes in one process.
     */
    /* nalu处理的函数指针
     */
    void (*nalu_process)( x264_t *h, x264_nal_t *nal, void *opaque );
} x264_param_t;