1 /*****************************************************************************
2 * Copyright (C) 2013 x265 project
4 * Authors: Steve Borho <steve@borho.org>
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02111, USA.
20 * This program is also available under a commercial proprietary license.
21 * For more information, contact us at license @ x265.com.
22 *****************************************************************************/
28 #include "x265_config.h"
35 * opaque handler for encoder */
36 typedef struct x265_encoder x265_encoder
;
38 /* Application developers planning to link against a shared library version of
39 * libx265 from a Microsoft Visual Studio or similar development environment
40 * will need to define X265_API_IMPORTS before including this header.
41 * This clause does not apply to MinGW, similar development environments, or non
42 * Windows platforms. */
43 #ifdef X265_API_IMPORTS
44 #define X265_API __declspec(dllimport)
51 NAL_UNIT_CODED_SLICE_TRAIL_N
= 0,
52 NAL_UNIT_CODED_SLICE_TRAIL_R
,
53 NAL_UNIT_CODED_SLICE_TSA_N
,
54 NAL_UNIT_CODED_SLICE_TLA_R
,
55 NAL_UNIT_CODED_SLICE_STSA_N
,
56 NAL_UNIT_CODED_SLICE_STSA_R
,
57 NAL_UNIT_CODED_SLICE_RADL_N
,
58 NAL_UNIT_CODED_SLICE_RADL_R
,
59 NAL_UNIT_CODED_SLICE_RASL_N
,
60 NAL_UNIT_CODED_SLICE_RASL_R
,
61 NAL_UNIT_CODED_SLICE_BLA_W_LP
= 16,
62 NAL_UNIT_CODED_SLICE_BLA_W_RADL
,
63 NAL_UNIT_CODED_SLICE_BLA_N_LP
,
64 NAL_UNIT_CODED_SLICE_IDR_W_RADL
,
65 NAL_UNIT_CODED_SLICE_IDR_N_LP
,
66 NAL_UNIT_CODED_SLICE_CRA
,
70 NAL_UNIT_ACCESS_UNIT_DELIMITER
,
76 NAL_UNIT_INVALID
= 64,
79 /* The data within the payload is already NAL-encapsulated; the type is merely
80 * in the struct for easy access by the calling application. All data returned
81 * in an x265_nal, including the data in payload, is no longer valid after the
82 * next call to x265_encoder_encode. Thus it must be used or copied before
83 * calling x265_encoder_encode again. */
84 typedef struct x265_nal
86 uint32_t type
; /* NalUnitType */
87 uint32_t sizeBytes
; /* size in bytes */
91 /* Stores all analysis data for a single frame */
92 typedef struct x265_analysis_data
94 uint32_t frameRecordSize
;
97 uint32_t numCUsInFrame
;
98 uint32_t numPartitions
;
101 } x265_analysis_data
;
103 /* Used to pass pictures into the encoder, and to get picture data back out of
104 * the encoder. The input and output semantics are different */
105 typedef struct x265_picture
107 /* Must be specified on input pictures, the number of planes is determined
108 * by the colorSpace value */
111 /* Stride is the number of bytes between row starts */
114 /* Must be specified on input pictures. x265_picture_init() will set it to
115 * the encoder's internal bit depth, but this field must describe the depth
116 * of the input pictures. Must be between 8 and 16. Values larger than 8
117 * imply 16bits per input sample. If input bit depth is larger than the
118 * internal bit depth, the encoder will down-shift pixels. Input samples
119 * larger than 8bits will be masked to internal bit depth. On output the
120 * bitDepth will be the internal encoder bit depth */
123 /* Must be specified on input pictures: X265_TYPE_AUTO or other.
124 * x265_picture_init() sets this to auto, returned on output */
127 /* Ignored on input, set to picture count, returned on output */
130 /* Must be specified on input pictures: X265_CSP_I420 or other. It must
131 * match the internal color space of the encoder. x265_picture_init() will
132 * initialize this value to the internal color space */
135 /* presentation time stamp: user-specified, returned on output */
138 /* display time stamp: ignored on input, copied from reordered pts. Returned
142 /* The value provided on input is returned with the same picture (POC) on
146 /* force quantizer for != X265_QP_AUTO */
149 /* If param.analysisMode is X265_ANALYSIS_OFF this field is ignored on input
150 * and output. Else the user must call x265_alloc_analysis_data() to
151 * allocate analysis buffers for every picture passed to the encoder.
153 * On input when param.analysisMode is X265_ANALYSIS_LOAD and analysisData
154 * member pointers are valid, the encoder will use the data stored here to
155 * reduce encoder work.
157 * On output when param.analysisMode is X265_ANALYSIS_SAVE and analysisData
158 * member pointers are valid, the encoder will write output analysis into
159 * this data structure */
160 x265_analysis_data analysisData
;
162 /* new data members to this structure must be added to the end so that
163 * users of x265_picture_alloc/free() can be assured of future safety */
178 #define X265_CPU_CMOV 0x0000001
179 #define X265_CPU_MMX 0x0000002
180 #define X265_CPU_MMX2 0x0000004 /* MMX2 aka MMXEXT aka ISSE */
181 #define X265_CPU_MMXEXT X265_CPU_MMX2
182 #define X265_CPU_SSE 0x0000008
183 #define X265_CPU_SSE2 0x0000010
184 #define X265_CPU_SSE3 0x0000020
185 #define X265_CPU_SSSE3 0x0000040
186 #define X265_CPU_SSE4 0x0000080 /* SSE4.1 */
187 #define X265_CPU_SSE42 0x0000100 /* SSE4.2 */
188 #define X265_CPU_LZCNT 0x0000200 /* Phenom support for "leading zero count" instruction. */
189 #define X265_CPU_AVX 0x0000400 /* AVX support: requires OS support even if YMM registers aren't used. */
190 #define X265_CPU_XOP 0x0000800 /* AMD XOP */
191 #define X265_CPU_FMA4 0x0001000 /* AMD FMA4 */
192 #define X265_CPU_AVX2 0x0002000 /* AVX2 */
193 #define X265_CPU_FMA3 0x0004000 /* Intel FMA3 */
194 #define X265_CPU_BMI1 0x0008000 /* BMI1 */
195 #define X265_CPU_BMI2 0x0010000 /* BMI2 */
197 #define X265_CPU_CACHELINE_32 0x0020000 /* avoid memory loads that span the border between two cachelines */
198 #define X265_CPU_CACHELINE_64 0x0040000 /* 32/64 is the size of a cacheline in bytes */
199 #define X265_CPU_SSE2_IS_SLOW 0x0080000 /* avoid most SSE2 functions on Athlon64 */
200 #define X265_CPU_SSE2_IS_FAST 0x0100000 /* a few functions are only faster on Core2 and Phenom */
201 #define X265_CPU_SLOW_SHUFFLE 0x0200000 /* The Conroe has a slow shuffle unit (relative to overall SSE performance) */
202 #define X265_CPU_STACK_MOD4 0x0400000 /* if stack is only mod4 and not mod16 */
203 #define X265_CPU_SLOW_CTZ 0x0800000 /* BSR/BSF x86 instructions are really slow on some CPUs */
204 #define X265_CPU_SLOW_ATOM 0x1000000 /* The Atom is terrible: slow SSE unaligned loads, slow
205 * SIMD multiplies, slow SIMD variable shifts, slow pshufb,
206 * cacheline split penalties -- gather everything here that
207 * isn't shared by other CPUs to avoid making half a dozen
209 #define X265_CPU_SLOW_PSHUFB 0x2000000 /* such as on the Intel Atom */
210 #define X265_CPU_SLOW_PALIGNR 0x4000000 /* such as on the AMD Bobcat */
213 #define X265_CPU_ARMV6 0x0000001
214 #define X265_CPU_NEON 0x0000002 /* ARM NEON */
215 #define X265_CPU_FAST_NEON_MRC 0x0000004 /* Transfer from NEON to ARM register is fast (Cortex-A9) */
217 #define X265_MAX_SUBPEL_LEVEL 7
220 #define X265_LOG_NONE (-1)
221 #define X265_LOG_ERROR 0
222 #define X265_LOG_WARNING 1
223 #define X265_LOG_INFO 2
224 #define X265_LOG_DEBUG 3
225 #define X265_LOG_FULL 4
227 #define X265_B_ADAPT_NONE 0
228 #define X265_B_ADAPT_FAST 1
229 #define X265_B_ADAPT_TRELLIS 2
231 #define X265_BFRAME_MAX 16
233 #define X265_TYPE_AUTO 0x0000 /* Let x265 choose the right type */
234 #define X265_TYPE_IDR 0x0001
235 #define X265_TYPE_I 0x0002
236 #define X265_TYPE_P 0x0003
237 #define X265_TYPE_BREF 0x0004 /* Non-disposable B-frame */
238 #define X265_TYPE_B 0x0005
239 #define X265_QP_AUTO 0
241 #define X265_AQ_NONE 0
242 #define X265_AQ_VARIANCE 1
243 #define X265_AQ_AUTO_VARIANCE 2
244 #define IS_X265_TYPE_I(x) ((x) == X265_TYPE_I || (x) == X265_TYPE_IDR)
245 #define IS_X265_TYPE_B(x) ((x) == X265_TYPE_B || (x) == X265_TYPE_BREF)
247 /* NOTE! For this release only X265_CSP_I420 and X265_CSP_I444 are supported */
249 /* Supported internal color space types (according to semantics of chroma_format_idc) */
250 #define X265_CSP_I400 0 /* yuv 4:0:0 planar */
251 #define X265_CSP_I420 1 /* yuv 4:2:0 planar */
252 #define X265_CSP_I422 2 /* yuv 4:2:2 planar */
253 #define X265_CSP_I444 3 /* yuv 4:4:4 planar */
254 #define X265_CSP_COUNT 4 /* Number of supported internal color spaces */
256 /* These color spaces will eventually be supported as input pictures. The pictures will
257 * be converted to the appropriate planar color spaces at ingest */
258 #define X265_CSP_NV12 4 /* yuv 4:2:0, with one y plane and one packed u+v */
259 #define X265_CSP_NV16 5 /* yuv 4:2:2, with one y plane and one packed u+v */
261 /* Interleaved color-spaces may eventually be supported as input pictures */
262 #define X265_CSP_BGR 6 /* packed bgr 24bits */
263 #define X265_CSP_BGRA 7 /* packed bgr 32bits */
264 #define X265_CSP_RGB 8 /* packed rgb 24bits */
265 #define X265_CSP_MAX 9 /* end of list */
267 #define X265_EXTENDED_SAR 255 /* aspect ratio explicitly specified as width:height */
269 /* Analysis options */
270 #define X265_ANALYSIS_OFF 0
271 #define X265_ANALYSIS_SAVE 1
272 #define X265_ANALYSIS_LOAD 2
280 static const x265_cli_csp x265_cli_csps
[] =
282 { 1, { 0, 0, 0 }, { 0, 0, 0 } }, /* i400 */
283 { 3, { 0, 1, 1 }, { 0, 1, 1 } }, /* i420 */
284 { 3, { 0, 1, 1 }, { 0, 0, 0 } }, /* i422 */
285 { 3, { 0, 0, 0 }, { 0, 0, 0 } }, /* i444 */
286 { 2, { 0, 0 }, { 0, 1 } }, /* nv12 */
287 { 2, { 0, 0 }, { 0, 0 } }, /* nv16 */
290 /* rate tolerance method */
298 /* Output statistics from encoder */
299 typedef struct x265_stats
306 double elapsedEncodeTime
; /* wall time since encoder was opened */
307 double elapsedVideoTime
; /* encoded picture count / frame rate */
308 double bitrate
; /* accBits / elapsed video time */
309 uint32_t encodedPictureCount
; /* number of output pictures thus far */
310 uint32_t totalWPFrames
; /* number of uni-directional weighted frames used */
311 uint64_t accBits
; /* total bits output thus far */
313 /* new statistic member variables must be added below this line */
316 /* String values accepted by x265_param_parse() (and CLI) for various parameters */
317 static const char * const x265_motion_est_names
[] = { "dia", "hex", "umh", "star", "full", 0 };
318 static const char * const x265_source_csp_names
[] = { "i400", "i420", "i422", "i444", "nv12", "nv16", 0 };
319 static const char * const x265_video_format_names
[] = { "component", "pal", "ntsc", "secam", "mac", "undef", 0 };
320 static const char * const x265_fullrange_names
[] = { "limited", "full", 0 };
321 static const char * const x265_colorprim_names
[] = { "", "bt709", "undef", "", "bt470m", "bt470bg", "smpte170m", "smpte240m", "film", "bt2020", 0 };
322 static const char * const x265_transfer_names
[] = { "", "bt709", "undef", "", "bt470m", "bt470bg", "smpte170m", "smpte240m", "linear", "log100",
323 "log316", "iec61966-2-4", "bt1361e", "iec61966-2-1", "bt2020-10", "bt2020-12", 0 };
324 static const char * const x265_colmatrix_names
[] = { "GBR", "bt709", "undef", "", "fcc", "bt470bg", "smpte170m", "smpte240m",
325 "YCgCo", "bt2020nc", "bt2020c", 0 };
326 static const char * const x265_sar_names
[] = { "undef", "1:1", "12:11", "10:11", "16:11", "40:33", "24:11", "20:11",
327 "32:11", "80:33", "18:11", "15:11", "64:33", "160:99", "4:3", "3:2", "2:1", 0 };
328 static const char * const x265_interlace_names
[] = { "prog", "tff", "bff", 0 };
329 static const char * const x265_analysis_names
[] = { "off", "save", "load", 0 };
331 /* x265 input parameters
333 * For version safety you may use x265_param_alloc/free() to manage the
334 * allocation of x265_param instances, and x265_param_parse() to assign values
335 * by name. By never dereferencing param fields in your own code you can treat
336 * x265_param as an opaque data structure */
337 typedef struct x265_param
339 /*== Encoder Environment ==*/
341 /* x265_param_default() will auto-detect this cpu capability bitmap. it is
342 * recommended to not change this value unless you know the cpu detection is
343 * somehow flawed on your target hardware. The asm function tables are
344 * process global, the first encoder configures them for all encoders */
347 /* Enable wavefront parallel processing, greatly increases parallelism for
348 * less than 1% compression efficiency loss */
349 int bEnableWavefront
;
351 /* Number of threads to allocate for the process global thread pool, if no
352 * thread pool has yet been created. 0 implies auto-detection. By default
353 * x265 will try to allocate one worker thread per CPU core */
356 /* Number of concurrently encoded frames, 0 implies auto-detection. By
357 * default x265 will use a number of frame threads emperically determined to
358 * be optimal for your CPU core count, between 2 and 6. Using more than one
359 * frame thread causes motion search in the down direction to be clamped but
360 * otherwise encode behavior is unaffected. With CQP rate control the output
361 * bitstream is deterministic for all values of frameNumThreads greater than
362 * 1. All other forms of rate-control can be negatively impacted by
363 * increases to the number of frame threads because the extra concurrency
364 * adds uncertainty to the bitrate estimations. There is no limit to the
365 * number of frame threads you use for each encoder, but frame parallelism
366 * is generally limited by the the number of CU rows */
369 /* Use multiple threads to measure CU mode costs. Recommended for many core
370 * CPUs. On RD levels less than 5, it may not offload enough work to warrant
371 * the overhead. It is useful with the slow preset since it has the
372 * rectangular predictions enabled. At RD level 5 and 6 (preset slower and
373 * below), this feature should be an unambiguous win if you have CPU
374 * cores available for work. Default disabled */
375 int bDistributeModeAnalysis
;
377 /* Use multiple threads to perform motion estimation to (ME to one reference
378 * per thread). Recommended for many core CPUs. The more references the more
379 * motion searches there will be to distribute. This option is often not a
380 * win, particularly in video sequences with low motion. Default disabled */
381 int bDistributeMotionEstimation
;
383 /* The level of logging detail emitted by the encoder. X265_LOG_NONE to
384 * X265_LOG_FULL, default is X265_LOG_INFO */
387 /* Enable analysis and logging distribution of Cus encoded across various
388 * modes during mode decision. Default disabled */
391 /* Enable the measurement and reporting of PSNR. Default is enabled */
394 /* Enable the measurement and reporting of SSIM. Default is disabled */
397 /* filename of CSV log. If logLevel is X265_LOG_DEBUG, the encoder will emit
398 * per-slice statistics to this log file in encode order. Otherwise the
399 * encoder will emit per-stream statistics into the log file when
400 * x265_encoder_log is called (presumably at the end of the encode) */
403 /* Enable the generation of SEI messages for each encoded frame containing
404 * the hashes of the three reconstructed picture planes. Most decoders will
405 * validate those hashes against the reconstructed images it generates and
406 * report any mismatches. This is essentially a debugging feature. Hash
407 * types are MD5(1), CRC(2), Checksum(3). Default is 0, none */
408 int decodedPictureHashSEI
;
410 /*== Internal Picture Specification ==*/
412 /* Internal encoder bit depth. If x265 was compiled to use 8bit pixels
413 * (HIGH_BIT_DEPTH=0), this field must be 8, else this field must be 10.
414 * Future builds may support 12bit pixels. */
415 int internalBitDepth
;
417 /* Color space of internal pictures. Only X265_CSP_I420 and X265_CSP_I444
418 * are supported. Eventually, i422 will also be supported as an internal
419 * color space and other packed formats will be supported in
420 * x265_picture.colorSpace */
423 /* Numerator and denominator of frame rate */
427 /* Width (in pixels) of the source pictures. If this width is not an even
428 * multiple of 4, the encoder will pad the pictures internally to meet this
429 * minimum requirement. All valid HEVC widths are supported */
432 /* Height (in pixels) of the source pictures. If this height is not an even
433 * multiple of 4, the encoder will pad the pictures internally to meet this
434 * minimum requirement. All valid HEVC heights are supported */
437 /* Minimum decoder requirement level. Defaults to 0, which implies auto-
438 * detection by the encoder. If specified, the encoder will attempt to bring
439 * the encode specifications within that specified level. If the encoder is
440 * unable to reach the level it issues a warning and emits the actual
441 * decoder requirement. If the requested requirement level is higher than
442 * the actual level, the actual requirement level is signaled. The value is
443 * an specified as an integer with the level times 10, for example level
444 * "5.1" is specified as 51, and level "5.0" is specified as 50. */
447 /* if levelIdc is specified (non-zero) this flag will differentiate between
448 * Main (0) and High (1) tier. Default is Main tier (0) */
451 /* Interlace type of source pictures. 0 - progressive pictures (default).
452 * 1 - top field first, 2 - bottom field first. HEVC encodes interlaced
453 * content as fields, they must be provided to the encoder in the correct
454 * temporal order. EXPERIMENTAL */
457 /* Flag indicating whether VPS, SPS and PPS headers should be output with
458 * each keyframe. Default false */
461 /* Flag indicating whether the encoder should emit an Access Unit Delimiter
462 * NAL at the start of every access unit. Default false */
463 int bEnableAccessUnitDelimiters
;
465 /* Enables the buffering period SEI and picture timing SEI to signal the HRD
466 * parameteres. Default is disabled */
469 /* Enables the emission of a user data SEI with the stream headers which
470 * describes the encoder version, build info, and parameters. This is
471 * very helpful for debugging, but may interfere with regression tests.
475 /*== Coding Unit (CU) definitions ==*/
477 /* Maxiumum CU width and height in pixels. The size must be 64, 32, or 16.
478 * The higher the size, the more efficiently x265 can encode areas of low
479 * complexity, greatly improving compression efficiency at large
480 * resolutions. The smaller the size, the more effective wavefront and
481 * frame parallelism will become because of the increase in rows. default 64 */
484 /* The additional depth the residual quadtree is allowed to recurse beyond
485 * the coding quadtree, for inter coded blocks. This must be between 1 and
486 * 4. The higher the value the more efficiently the residual can be
487 * compressed by the DCT transforms, at the expense of much more compute */
488 uint32_t tuQTMaxInterDepth
;
490 /* The additional depth the residual quadtree is allowed to recurse beyond
491 * the coding quadtree, for intra coded blocks. This must be between 1 and
492 * 4. The higher the value the more efficiently the residual can be
493 * compressed by the DCT transforms, at the expense of much more compute */
494 uint32_t tuQTMaxIntraDepth
;
496 /*== GOP Structure and Lokoahead ==*/
498 /* Enable open GOP - meaning I slices are not necessariy IDR and thus frames
499 * encoded after an I slice may reference frames encoded prior to the I
500 * frame which have remained in the decoded picture buffer. Open GOP
501 * generally has better compression efficiency and negligable encoder
502 * performance impact, but the use case may preclude it. Default true */
505 /* Scenecuts closer together than this are coded as I, not IDR. */
508 /* Maximum keyframe distance or intra period in number of frames. If 0 or 1,
509 * all frames are I frames. A negative value is casted to MAX_INT internally
510 * which effectively makes frame 0 the only I frame. Default is 250 */
513 /* The maximum number of L0 references a P or B slice may use. This
514 * influences the size of the decoded picture buffer. The higher this
515 * number, the more reference frames there will be available for motion
516 * search, improving compression efficiency of most video at a cost of
517 * performance. Value must be between 1 and 16, default is 3 */
518 int maxNumReferences
;
520 /* Sets the operating mode of the lookahead. With b-adapt 0, the GOP
521 * structure is fixed based on the values of keyframeMax and bframes.
522 * With b-adapt 1 a light lookahead is used to chose B frame placement.
523 * With b-adapt 2 (trellis) a viterbi B path selection is performed */
526 /* Maximum consecutive B frames that can be emitted by the lookehead. When
527 * b-adapt is 0 and keyframMax is greater than bframes, the lookahead emits
528 * a fixed pattern of `bframes` B frames between each P. With b-adapt 1 the
529 * lookahead ignores the value of bframes for the most part. With b-adapt 2
530 * the value of bframes determines the search (POC) distance performeed in
531 * both directions, quadradically increasing the compute load of the
532 * lookahead. The higher the value, the more B frames the lookahead may
533 * possibly use consecutively, usually improving compression. Default is 3,
537 /* Total Number of frames to be encoded, caclulated from the user input
538 * (--frames) and (--seek). In case, the input is read from a pipe, this can
539 * remain as 0. It is later used in 2 pass RateControl, hence storing the
543 /* When enabled, the encoder will use the B frame in the middle of each
544 * mini-GOP larger than 2 B frames as a motion reference for the surrounding
545 * B frames. This improves compression efficiency for a small performance
546 * penalty. Referenced B frames are treated somewhere between a B and a P
547 * frame by rate control. Default is enabled. */
550 /* The number of frames that must be queued in the lookahead before it may
551 * make slice decisions. Increasing this value directly increases the encode
552 * latency. The longer the queue the more optimally the lookahead may make
553 * slice decisions, particularly with b-adapt 2. When mb-tree is enabled,
554 * the length of the queue linearly increases the effectiveness of the
555 * mb-tree analysis. Default is 40 frames, maximum is 250 */
558 /* A value which is added to the cost estimate of B frames in the lookahead.
559 * It may be a positive value (making B frames appear more expensive, which
560 * causes the lookahead to chose more P frames) or negative, which makes the
561 * lookahead chose more B frames. Default is 0, there are no limits */
564 /* An arbitrary threshold which determines how agressively the lookahead
565 * should detect scene cuts. The default (40) is recommended. */
566 int scenecutThreshold
;
568 /*== Intra Coding Tools ==*/
570 /* Enable constrained intra prediction. This causes intra prediction to
571 * input samples that were inter predicted. For some use cases this is
572 * believed to me more robust to stream errors, but it has a compression
573 * penalty on P and (particularly) B slices. Defaults to diabled */
574 int bEnableConstrainedIntra
;
576 /* Enable strong intra smoothing for 32x32 blocks where the reference
577 * samples are flat. It may or may not improve compression efficiency,
578 * depending on your source material. Defaults to disabled */
579 int bEnableStrongIntraSmoothing
;
581 /* Use a faster search method to find the best intra mode. Default is 0 */
582 int bEnableFastIntra
;
584 /*== Inter Coding Tools ==*/
586 /* ME search method (DIA, HEX, UMH, STAR, FULL). The search patterns
587 * (methods) are sorted in increasing complexity, with diamond being the
588 * simplest and fastest and full being the slowest. DIA, HEX, and UMH were
589 * adapted from x264 directly. STAR is an adaption of the HEVC reference
590 * encoder's three step search, while full is a naive exhaustive search. The
591 * default is the star search, it has a good balance of performance and
592 * compression efficiecy */
595 /* A value between 0 and X265_MAX_SUBPEL_LEVEL which adjusts the amount of
596 * effort performed during subpel refine. Default is 5 */
599 /* The maximum distance from the motion prediction that the full pel motion
600 * search is allowed to progress before terminating. This value can have an
601 * effect on frame parallelism, as referenced frames must be at least this
602 * many rows of reconstructed pixels ahead of the referencee at all times.
603 * (When considering reference lag, the motion prediction must be ignored
604 * because it cannot be known ahead of time). Default is 60, which is the
605 * default max CU size (64) minus the luma HPEL half-filter length (4). If a
606 * smaller CU size is used, the search range should be similarly reduced */
609 /* The maximum number of merge candidates that are considered during inter
610 * analysis. This number (between 1 and 5) is signaled in the stream
611 * headers and determines the number of bits required to signal a merge so
612 * it can have significant trade-offs. The smaller this number the higher
613 * the performance but the less compression efficiency. Default is 3 */
614 uint32_t maxNumMergeCand
;
616 /* Disable availability of temporal motion vector for AMVP */
617 int bEnableTemporalMvp
;
619 /* Enable weighted prediction in P slices. This enables weighting analysis
620 * in the lookahead, which influences slice decisions, and enables weighting
621 * analysis in the main encoder which allows P reference samples to have a
622 * weight function applied to them prior to using them for motion
623 * compensation. In video which has lighting changes, it can give a large
624 * improvement in compression efficiency. Default is enabled */
625 int bEnableWeightedPred
;
627 /* Enable weighted prediction in B slices. Default is disabled */
628 int bEnableWeightedBiPred
;
630 /*== Analysis tools ==*/
632 /* Enable asymmetrical motion predictions. At CU depths 64, 32, and 16, it
633 * is possible to use 25%/75% split partitions in the up, down, right, left
634 * directions. For some material this can improve compression efficiency at
635 * the cost of extra analysis. bEnableRectInter must be enabled for this
636 * feature to be used. Default enabled */
639 /* Enable rectangular motion prediction partitions (vertical and
640 * horizontal), available at all CU depths from 64x64 to 8x8. Default is
642 int bEnableRectInter
;
644 /* Enable the use of `coded block flags` (flags set to true when a residual
645 * has been coded for a given block) to avoid intra analysis in likely skip
646 * blocks. Only applicable in RD levels 5 and 6. Default is disabled */
647 int bEnableCbfFastMode
;
649 /* Enable early skip decisions to avoid intra and inter analysis in likely
650 * skip blocks. Default is disabled */
651 int bEnableEarlySkip
;
653 /* Apply an optional penalty to the estimated cost of 32x32 intra blocks in
654 * non-intra slices. 0 is disabled, 1 enables a small penalty, and 2 enables
655 * a full penalty. This favors inter-coding and its low bitrate over
656 * potential increases in distortion, but usually improves performance.
660 /* A value betwen X265_NO_RDO_NO_RDOQ and X265_RDO_LEVEL which determines
661 * the level of rate distortion optimizations to perform during mode
662 * decisions and quantization. The more RDO the better the compression
663 * efficiency at a major cost of performance. Default is no RDO (0) */
666 /* Psycho-visual rate-distortion strength. Only has an effect in presets
667 * which use RDO. It makes mode decision favor options which preserve the
668 * energy of the source, at the cost of lost compression. The value must
669 * be between 0 and 2.0, 1.0 is typical. Default 0.0 */
672 /* Quantization scaling lists. HEVC supports 6 quantization scaling lists to
673 * be defined; one each for Y, Cb, Cr for intra prediction and one each for
676 * - NULL and "off" will disable quant scaling (default)
677 * - "default" will enable the HEVC default scaling lists, which
678 * do not need to be signaled since they are specified
679 * - all other strings indicate a filename containing custom scaling lists
680 * in the HM format. The encode will fail if the file is not parsed
681 * correctly. Custom lists must be signaled in the SPS. */
682 const char *scalingLists
;
684 /* Strength of psycho-visual optimizations in quantization. Only has an
685 * effect in presets which use RDOQ (rd-levels 4 and 5). The value must be
686 * between 0 and 50, 1.0 is typical. Default 0.0 */
689 /* If X265_ANALYSIS_SAVE, write per-frame analysis information into analysis
690 * buffers. if X265_ANALYSIS_LOAD, read analysis information into analysis
691 * buffer and use this analysis information to reduce the amount of work
692 * the encoder must perform. Default X265_ANALYSIS_OFF */
694 /* Filename for analysisMode save/load. Default name is "x265_analysis.dat" */
695 char* analysisFileName
;
697 /*== Coding tools ==*/
698 /* Enable the implicit signaling of the sign bit of the last coefficient of
699 * each transform unit. This saves one bit per TU at the expense of figuring
700 * out which coefficient can be toggled with the least distortion.
701 * Default is enabled */
702 int bEnableSignHiding
;
704 /* Allow intra coded blocks to be encoded directly as residual without the
705 * DCT transform, when this improves efficiency. Checking whether the block
706 * will benefit from this option incurs a performance penalty. Default is
708 int bEnableTransformSkip
;
710 /* Enable a faster determination of whether skippig the DCT transform will
711 * be beneficial. Slight performance gain for some compression loss. Default
713 int bEnableTSkipFast
;
715 /* Enable the deblocking loop filter, which improves visual quality by
716 * reducing blocking effects at block edges, particularly at lower bitrates
717 * or higher QP. When enabled it adds another CU row of reference lag,
718 * reducing frame parallelism effectiveness. Default is enabled */
719 int bEnableLoopFilter
;
721 /* deblocking filter tC offset [-6, 6] -6 light filter, 6 strong.
722 * This is the coded div2 value, actual offset is doubled at use */
723 int deblockingFilterTCOffset
;
725 /* deblocking filter Beta offset [-6, 6] -6 light filter, 6 strong
726 * This is the coded div2 value, actual offset is doubled at use */
727 int deblockingFilterBetaOffset
;
729 /* Enable the Sample Adaptive Offset loop filter, which reduces distortion
730 * effects by adjusting reconstructed sample values based on histogram
731 * analysis to better approximate the original samples. When enabled it adds
732 * a CU row of reference lag, reducing frame parallelism effectiveness.
733 * Default is enabled */
736 /* Note: when deblocking and SAO are both enabled, the loop filter CU lag is
737 * only one row, as they operate in series on the same row. */
739 /* Select the method in which SAO deals with deblocking boundary pixels. If
740 * disabled the right and bottom boundary areas are skipped. If enabled,
741 * non-deblocked pixels are used entirely. Default is disabled */
742 int bSaoNonDeblocked
;
744 /* Generally a small signed integer which offsets the QP used to quantize
745 * the Cb chroma residual (delta from luma QP specified by rate-control).
746 * Default is 0, which is recommended */
749 /* Generally a small signed integer which offsets the QP used to quantize
750 * the Cr chroma residual (delta from luma QP specified by rate-control).
751 * Default is 0, which is recommended */
754 /* Specify whether to attempt to encode intra modes in B frames. By default
755 * enabled, but only applicable for the presets which use rdLevel 5 or 6
756 * (veryslow and placebo). All other presets will not try intra in B frames
757 * regardless of this setting. */
760 /* An integer value in range of 0 to 2000, which denotes strength of noise
761 * reduction in intra CUs. 0 means disabled */
762 int noiseReductionIntra
;
764 /* An integer value in range of 0 to 2000, which denotes strength of noise
765 * reduction in inter CUs. 0 means disabled */
766 int noiseReductionInter
;
768 /* The lossless flag enables true lossless coding, by bypassing scaling,
769 * transform, quantization and in-loop filter processes. This is used for
770 * ultra-high bitrates with zero loss of quality. */
773 /* The CU Lossless flag, when enabled, compares the rate-distortion costs
774 * for normal and lossless encoding, and chooses the best mode for each CU.
775 * If lossless mode is chosen, the cu-transquant-bypass flag is set for that
779 /*== Rate Control ==*/
783 /* Explicit mode of rate-control, necessary for API users. It must
784 * be one of the X265_RC_METHODS enum values. */
787 /* Base QP to use for Constant QP rate control. Adaptive QP may alter
788 * the QP used for each block. If a QP is specified on the command line
789 * CQP rate control is implied. Default: 32 */
792 /* target bitrate for Average BitRate (ABR) rate control. If a non- zero
793 * bitrate is specified on the command line, ABR is implied. Default 0 */
796 /* The degree of rate fluctuation that x265 tolerates. Rate tolerance is used
797 * along with overflow (difference between actual and target bitrate), to adjust
798 * qp. Default is 1.0 */
799 double rateTolerance
;
801 /* qComp sets the quantizer curve compression factor. It weights the frame
802 * quantizer based on the complexity of residual (measured by lookahead).
803 * Default value is 0.6. Increasing it to 1 will effectively generate CQP */
806 /* QP offset between I/P and P/B frames. Default ipfactor: 1.4
807 * Default pbFactor: 1.3 */
811 /* Max QP difference between frames. Default: 4 */
814 /* Ratefactor constant: targets a certain constant "quality".
815 * Acceptable values between 0 and 51. Default value: 28 */
818 /* Enable adaptive quantization. This mode distributes available bits between all
819 * CTUs of a frame, assigning more bits to low complexity areas. Turning
820 * this ON will usually affect PSNR negatively, however SSIM and visual quality
821 * generally improves. Default: X265_AQ_VARIANCE */
824 /* Sets the strength of AQ bias towards low detail CTUs. Valid only if
825 * AQ is enabled. Default value: 1.0. Acceptable values between 0.0 and 3.0 */
828 /* Sets the maximum rate the VBV buffer should be assumed to refill at
832 /* Sets the size of the VBV buffer in kilobits. Default is zero */
835 /* Sets how full the VBV buffer must be before playback starts. If it is less than
836 * 1, then the initial fill is vbv-init * vbvBufferSize. Otherwise, it is
837 * interpreted as the initial fill in kbits. Default is 0.9 */
838 double vbvBufferInit
;
840 /* Enable CUTree ratecontrol. This keeps track of the CUs that propagate temporally
841 * across frames and assigns more bits to these CUs. Improves encode efficiency.
842 * Default: enabled */
845 /* In CRF mode, maximum CRF as caused by VBV. 0 implies no limit */
846 double rfConstantMax
;
848 /* In CRF mode, minimum CRF as caused by VBV */
849 double rfConstantMin
;
851 /* Multi-pass encoding */
852 /* Enable writing the stats in a multipass encode to the stat output file */
855 /* Enable loading data from the stat input file in a multi pass encode */
858 /* Filename of the 2pass output/input stats file, if unspecified the
859 * encoder will default to using x265_2pass.log */
862 /* temporally blur quants */
865 /* temporally blur complexity */
866 double complexityBlur
;
868 /* Enable slow and a more detailed first pass encode in multi pass rate control */
869 int bEnableSlowFirstPass
;
871 /* specify a text file which contains MAX_MAX_QP + 1 floating point
872 * values to be copied into x265_lambda_tab and a second set of
873 * MAX_MAX_QP + 1 floating point values for x265_lambda2_tab. All values
874 * are separated by comma, space or newline. Text after a hash (#) is
875 * ignored. The lambda tables are process-global, so these new lambda
876 * values will affect all encoders in the same process */
877 const char* lambdaFileName
;
880 /*== Video Usability Information ==*/
883 /* Aspect ratio idc to be added to the VUI. The default is 0 indicating
884 * the apsect ratio is unspecified. If set to X265_EXTENDED_SAR then
885 * sarWidth and sarHeight must also be set */
888 /* Sample Aspect Ratio width in arbitrary units to be added to the VUI
889 * only if aspectRatioIdc is set to X265_EXTENDED_SAR. This is the width
890 * of an individual pixel. If this is set then sarHeight must also be set */
893 /* Sample Aspect Ratio height in arbitrary units to be added to the VUI.
894 * only if aspectRatioIdc is set to X265_EXTENDED_SAR. This is the width
895 * of an individual pixel. If this is set then sarWidth must also be set */
898 /* Enable overscan info present flag in the VUI. If this is set then
899 * bEnabledOverscanAppropriateFlag will be added to the VUI. The default
901 int bEnableOverscanInfoPresentFlag
;
903 /* Enable overscan appropriate flag. The status of this flag is added
904 * to the VUI only if bEnableOverscanInfoPresentFlag is set. If this
905 * flag is set then cropped decoded pictures may be output for display.
906 * The default is false */
907 int bEnableOverscanAppropriateFlag
;
909 /* Video signal type present flag of the VUI. If this is set then
910 * videoFormat, bEnableVideoFullRangeFlag and
911 * bEnableColorDescriptionPresentFlag will be added to the VUI. The
912 * default is false */
913 int bEnableVideoSignalTypePresentFlag
;
915 /* Video format of the source video. 0 = component, 1 = PAL, 2 = NTSC,
916 * 3 = SECAM, 4 = MAC, 5 = unspecified video format is the default */
919 /* Video full range flag indicates the black level and range of the luma
920 * and chroma signals as derived from E′Y, E′PB, and E′PR or E′R, E′G,
921 * and E′B real-valued component signals. The default is false */
922 int bEnableVideoFullRangeFlag
;
924 /* Color description present flag in the VUI. If this is set then
925 * color_primaries, transfer_characteristics and matrix_coeffs are to be
926 * added to the VUI. The default is false */
927 int bEnableColorDescriptionPresentFlag
;
929 /* Color primaries holds the chromacity coordinates of the source
930 * primaries. The default is 2 */
933 /* Transfer characteristics indicates the opto-electronic transfer
934 * characteristic of the source picture. The default is 2 */
935 int transferCharacteristics
;
937 /* Matrix coefficients used to derive the luma and chroma signals from
938 * the red, blue and green primaries. The default is 2 */
941 /* Chroma location info present flag adds chroma_sample_loc_type_top_field and
942 * chroma_sample_loc_type_bottom_field to the VUI. The default is false */
943 int bEnableChromaLocInfoPresentFlag
;
945 /* Chroma sample location type top field holds the chroma location in
946 * the top field. The default is 0 */
947 int chromaSampleLocTypeTopField
;
949 /* Chroma sample location type bottom field holds the chroma location in
950 * the bottom field. The default is 0 */
951 int chromaSampleLocTypeBottomField
;
953 /* Default display window flag adds def_disp_win_left_offset,
954 * def_disp_win_right_offset, def_disp_win_top_offset and
955 * def_disp_win_bottom_offset to the VUI. The default is false */
956 int bEnableDefaultDisplayWindowFlag
;
958 /* Default display window left offset holds the left offset with the
959 * conformance cropping window to further crop the displayed window */
960 int defDispWinLeftOffset
;
962 /* Default display window right offset holds the right offset with the
963 * conformance cropping window to further crop the displayed window */
964 int defDispWinRightOffset
;
966 /* Default display window top offset holds the top offset with the
967 * conformance cropping window to further crop the displayed window */
968 int defDispWinTopOffset
;
970 /* Default display window bottom offset holds the bottom offset with the
971 * conformance cropping window to further crop the displayed window */
972 int defDispWinBottomOffset
;
977 * If not called, first encoder allocated will auto-detect the CPU and
978 * initialize performance primitives, which are process global.
979 * DEPRECATED: use x265_param.cpuid to specify CPU */
980 void x265_setup_primitives(x265_param
*param
, int cpu
);
983 * Allocates an x265_param instance. The returned param structure is not
984 * special in any way, but using this method together with x265_param_free()
985 * and x265_param_parse() to set values by name allows the application to treat
986 * x265_param as an opaque data struct for version safety */
987 x265_param
*x265_param_alloc(void);
990 * Use x265_param_free() to release storage for an x265_param instance
991 * allocated by x265_param_alloc() */
992 void x265_param_free(x265_param
*);
995 * Initialize an x265_param structure to default values
997 void x265_param_default(x265_param
*param
);
1000 * set one parameter by name.
1001 * returns 0 on success, or returns one of the following errors.
1002 * note: BAD_VALUE occurs only if it can't even parse the value,
1003 * numerical range is not checked until x265_encoder_open().
1004 * value=NULL means "true" for boolean options, but is a BAD_VALUE for non-booleans. */
1005 #define X265_PARAM_BAD_NAME (-1)
1006 #define X265_PARAM_BAD_VALUE (-2)
1007 int x265_param_parse(x265_param
*p
, const char *name
, const char *value
);
1009 /* x265_param_apply_profile:
1010 * Applies the restrictions of the given profile. (one of below) */
1011 static const char * const x265_profile_names
[] = { "main", "main10", "mainstillpicture", 0 };
1013 /* (can be NULL, in which case the function will do nothing)
1014 * returns 0 on success, negative on failure (e.g. invalid profile name). */
1015 int x265_param_apply_profile(x265_param
*, const char *profile
);
1017 /* x265_param_default_preset:
1018 * The same as x265_param_default, but also use the passed preset and tune
1019 * to modify the default settings.
1020 * (either can be NULL, which implies no preset or no tune, respectively)
1022 * Currently available presets are, ordered from fastest to slowest: */
1023 static const char * const x265_preset_names
[] = { "ultrafast", "superfast", "veryfast", "faster", "fast", "medium", "slow", "slower", "veryslow", "placebo", 0 };
1025 /* The presets can also be indexed numerically, as in:
1026 * x265_param_default_preset( ¶m, "3", ... )
1027 * with ultrafast mapping to "0" and placebo mapping to "9". This mapping may
1028 * of course change if new presets are added in between, but will always be
1029 * ordered from fastest to slowest.
1031 * Warning: the speed of these presets scales dramatically. Ultrafast is a full
1032 * 100 times faster than placebo!
1034 * Currently available tunings are: */
1035 static const char * const x265_tune_names
[] = { "psnr", "ssim", "grain", "zerolatency", "fastdecode", "cbr", 0 };
1037 /* returns 0 on success, negative on failure (e.g. invalid preset/tune name). */
1038 int x265_param_default_preset(x265_param
*, const char *preset
, const char *tune
);
1040 /* x265_picture_alloc:
1041 * Allocates an x265_picture instance. The returned picture structure is not
1042 * special in any way, but using this method together with x265_picture_free()
1043 * and x265_picture_init() allows some version safety. New picture fields will
1044 * always be added to the end of x265_picture */
1045 x265_picture
*x265_picture_alloc(void);
1047 /* x265_picture_free:
1048 * Use x265_picture_free() to release storage for an x265_picture instance
1049 * allocated by x265_picture_alloc() */
1050 void x265_picture_free(x265_picture
*);
1052 * Initialize an x265_picture structure to default values. It sets the pixel
1053 * depth and color space to the encoder's internal values and sets the slice
1054 * type to auto - so the lookahead will determine slice type.
1056 void x265_picture_init(x265_param
*param
, x265_picture
*pic
);
1058 /* x265_max_bit_depth:
1059 * Specifies the maximum number of bits per pixel that x265 can input. This
1060 * is also the max bit depth that x265 encodes in. When x265_max_bit_depth
1061 * is 8, the internal and input bit depths must be 8. When
1062 * x265_max_bit_depth is 12, the internal and input bit depths can be
1063 * either 8, 10, or 12. Note that the internal bit depth must be the same
1064 * for all encoders allocated in the same process. */
1065 X265_API
extern const int x265_max_bit_depth
;
1067 /* x265_version_str:
1068 * A static string containing the version of this compiled x265 library */
1069 X265_API
extern const char *x265_version_str
;
1072 * A static string describing the compiler and target architecture */
1073 X265_API
extern const char *x265_build_info_str
;
1075 /* Force a link error in the case of linking against an incompatible API version.
1076 * Glue #defines exist to force correct macro expansion; the final output of the macro
1077 * is x265_encoder_open_##X265_BUILD (for purposes of dlopen). */
1078 #define x265_encoder_glue1(x, y) x ## y
1079 #define x265_encoder_glue2(x, y) x265_encoder_glue1(x, y)
1080 #define x265_encoder_open x265_encoder_glue2(x265_encoder_open_, X265_BUILD)
1082 /* x265_encoder_open:
1083 * create a new encoder handler, all parameters from x265_param are copied */
1084 x265_encoder
* x265_encoder_open(x265_param
*);
1086 /* x265_encoder_parameters:
1087 * copies the current internal set of parameters to the pointer provided
1088 * by the caller. useful when the calling application needs to know
1089 * how x265_encoder_open has changed the parameters.
1090 * note that the data accessible through pointers in the returned param struct
1091 * (e.g. filenames) should not be modified by the calling application. */
1092 void x265_encoder_parameters(x265_encoder
*, x265_param
*);
1094 /* x265_encoder_headers:
1095 * return the SPS and PPS that will be used for the whole stream.
1096 * *pi_nal is the number of NAL units outputted in pp_nal.
1097 * returns negative on error, total byte size of payload data on success
1098 * the payloads of all output NALs are guaranteed to be sequential in memory. */
1099 int x265_encoder_headers(x265_encoder
*, x265_nal
**pp_nal
, uint32_t *pi_nal
);
1101 /* x265_encoder_encode:
1102 * encode one picture.
1103 * *pi_nal is the number of NAL units outputted in pp_nal.
1104 * returns negative on error, 1 if a picture and access unit were output,
1105 * or zero if the encoder pipeline is still filling or is empty after flushing.
1106 * the payloads of all output NALs are guaranteed to be sequential in memory.
1107 * To flush the encoder and retrieve delayed output pictures, pass pic_in as NULL.
1108 * Once flushing has begun, all subsequent calls must pass pic_in as NULL. */
1109 int x265_encoder_encode(x265_encoder
*encoder
, x265_nal
**pp_nal
, uint32_t *pi_nal
, x265_picture
*pic_in
, x265_picture
*pic_out
);
1111 /* x265_encoder_get_stats:
1112 * returns encoder statistics */
1113 void x265_encoder_get_stats(x265_encoder
*encoder
, x265_stats
*, uint32_t statsSizeBytes
);
1115 /* x265_encoder_log:
1116 * write a line to the configured CSV file. If a CSV filename was not
1117 * configured, or file open failed, or the log level indicated frame level
1118 * logging, this function will perform no write. */
1119 void x265_encoder_log(x265_encoder
*encoder
, int argc
, char **argv
);
1121 /* x265_encoder_close:
1122 * close an encoder handler */
1123 void x265_encoder_close(x265_encoder
*);
1126 * Release library static allocations
1128 void x265_cleanup(void);