1 #ifndef KVAZAAR_H_ 2 #define KVAZAAR_H_ 3 /***************************************************************************** 4 * This file is part of Kvazaar HEVC encoder. 5 * 6 * Copyright (c) 2021, Tampere University, ITU/ISO/IEC, project contributors 7 * All rights reserved. 8 * 9 * Redistribution and use in source and binary forms, with or without modification, 10 * are permitted provided that the following conditions are met: 11 * 12 * * Redistributions of source code must retain the above copyright notice, this 13 * list of conditions and the following disclaimer. 14 * 15 * * Redistributions in binary form must reproduce the above copyright notice, this 16 * list of conditions and the following disclaimer in the documentation and/or 17 * other materials provided with the distribution. 18 * 19 * * Neither the name of the Tampere University or ITU/ISO/IEC nor the names of its 20 * contributors may be used to endorse or promote products derived from 21 * this software without specific prior written permission. 22 * 23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND 24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 26 * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR 27 * ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 28 * INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 29 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION HOWEVER CAUSED AND ON 30 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 31 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 32 * INCLUDING NEGLIGENCE OR OTHERWISE ARISING IN ANY WAY OUT OF THE USE OF THIS 33 ****************************************************************************/ 34 35 /** 36 * \ingroup Control 37 * \file 38 * This file defines the public API of Kvazaar when used as a library. 39 */ 40 41 #include <stdint.h> 42 #include <stdio.h> 43 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 #if defined(KVZ_DLL_EXPORTS) 50 #if !defined(PIC) 51 // Building static kvazaar library. 52 #define KVZ_PUBLIC 53 #elif defined(_WIN32) || defined(__CYGWIN__) 54 // Building kvazaar DLL on Windows. 55 #define KVZ_PUBLIC __declspec(dllexport) 56 #elif defined(__GNUC__) 57 // Building kvazaar shared library with GCC. 58 #define KVZ_PUBLIC __attribute__ ((visibility ("default"))) 59 #else 60 #define KVZ_PUBLIC 61 #endif 62 #else 63 #if defined(KVZ_STATIC_LIB) 64 // Using static kvazaar library. 65 #define KVZ_PUBLIC 66 #elif defined(_WIN32) || defined(__CYGWIN__) 67 // Using kvazaar DLL on Windows. 68 #define KVZ_PUBLIC __declspec(dllimport) 69 #else 70 // Using kvazaar shared library and not on Windows. 71 #define KVZ_PUBLIC 72 #endif 73 #endif 74 75 /** 76 * Maximum length of a GoP structure. 77 */ 78 #define KVZ_MAX_GOP_LENGTH 32 79 80 /** 81 * Maximum amount of GoP layers. 82 */ 83 #define KVZ_MAX_GOP_LAYERS 6 84 85 /** 86 * Size of data chunks. 87 */ 88 #define KVZ_DATA_CHUNK_SIZE 4096 89 90 #ifndef KVZ_BIT_DEPTH 91 #define KVZ_BIT_DEPTH 8 92 #endif 93 94 #if KVZ_BIT_DEPTH == 8 95 typedef uint8_t kvz_pixel; 96 #else 97 typedef uint16_t kvz_pixel; 98 #endif 99 100 /** 101 * \brief Opaque data structure representing one instance of the encoder. 102 */ 103 typedef struct kvz_encoder kvz_encoder; 104 105 /** 106 * \brief Integer motion estimation algorithms. 107 */ 108 enum kvz_ime_algorithm { 109 KVZ_IME_HEXBS = 0, 110 KVZ_IME_TZ = 1, 111 KVZ_IME_FULL = 2, 112 KVZ_IME_FULL8 = 3, //! \since 3.6.0 113 KVZ_IME_FULL16 = 4, //! \since 3.6.0 114 KVZ_IME_FULL32 = 5, //! \since 3.6.0 115 KVZ_IME_FULL64 = 6, //! \since 3.6.0 116 KVZ_IME_DIA = 7, // Experimental. TODO: change into a proper doc comment 117 }; 118 119 /** 120 * \brief Interlacing methods. 121 * \since 3.2.0 122 */ 123 enum kvz_interlacing 124 { 125 KVZ_INTERLACING_NONE = 0, 126 KVZ_INTERLACING_TFF = 1, // top field first 127 KVZ_INTERLACING_BFF = 2, // bottom field first 128 }; 129 130 /** 131 * \brief Constrain movement vectors. 132 * \since 3.3.0 133 */ 134 enum kvz_mv_constraint 135 { 136 KVZ_MV_CONSTRAIN_NONE = 0, 137 KVZ_MV_CONSTRAIN_FRAME = 1, // Don't refer outside the frame. 138 KVZ_MV_CONSTRAIN_TILE = 2, // Don't refer to other tiles. 139 KVZ_MV_CONSTRAIN_FRAME_AND_TILE = 3, // Don't refer outside the tile. 140 KVZ_MV_CONSTRAIN_FRAME_AND_TILE_MARGIN = 4, // Keep enough margin for fractional pixel margins not to refer outside the tile. 141 }; 142 143 /** 144 * \brief Constrain movement vectors. 145 * \since 3.5.0 146 */ 147 enum kvz_hash 148 { 149 KVZ_HASH_NONE = 0, 150 KVZ_HASH_CHECKSUM = 1, 151 KVZ_HASH_MD5 = 2, 152 }; 153 154 /** 155 * \brief cu split termination mode 156 * \since since 3.8.0 157 */ 158 enum kvz_cu_split_termination 159 { 160 KVZ_CU_SPLIT_TERMINATION_ZERO = 0, 161 KVZ_CU_SPLIT_TERMINATION_OFF = 1 162 }; 163 164 /** 165 * \brief Enable and disable crypto features. 166 * \since 3.7.0 167 */ 168 enum kvz_crypto_features { 169 KVZ_CRYPTO_OFF = 0, 170 KVZ_CRYPTO_MVs = (1 << 0), 171 KVZ_CRYPTO_MV_SIGNS = (1 << 1), 172 KVZ_CRYPTO_TRANSF_COEFFS = (1 << 2), 173 KVZ_CRYPTO_TRANSF_COEFF_SIGNS = (1 << 3), 174 KVZ_CRYPTO_INTRA_MODE = (1 << 4), 175 KVZ_CRYPTO_ON = (1 << 5) - 1, 176 }; 177 178 /** 179 * \brief me early termination mode 180 * \since since 3.8.0 181 */ 182 enum kvz_me_early_termination 183 { 184 KVZ_ME_EARLY_TERMINATION_OFF = 0, 185 KVZ_ME_EARLY_TERMINATION_ON = 1, 186 KVZ_ME_EARLY_TERMINATION_SENSITIVE = 2 187 }; 188 189 190 /** 191 * \brief Format the pixels are read in. 192 * This is separate from chroma subsampling, because we might want to read 193 * interleaved formats in the future. 194 * \since 3.12.0 195 */ 196 enum kvz_input_format { 197 KVZ_FORMAT_P400 = 0, 198 KVZ_FORMAT_P420 = 1, 199 KVZ_FORMAT_P422 = 2, 200 KVZ_FORMAT_P444 = 3, 201 }; 202 203 /** 204 * \brief Chroma subsampling format used for encoding. 205 * \since 3.12.0 206 */ 207 enum kvz_chroma_format { 208 KVZ_CSP_400 = 0, 209 KVZ_CSP_420 = 1, 210 KVZ_CSP_422 = 2, 211 KVZ_CSP_444 = 3, 212 }; 213 214 /** 215 * \brief Chroma subsampling format used for encoding. 216 * \since 3.15.0 217 */ 218 enum kvz_slices { 219 KVZ_SLICES_NONE, 220 KVZ_SLICES_TILES = (1 << 0), /*!< \brief Put each tile in a slice. */ 221 KVZ_SLICES_WPP = (1 << 1), /*!< \brief Put each row in a slice. */ 222 }; 223 224 enum kvz_sao { 225 KVZ_SAO_OFF = 0, 226 KVZ_SAO_EDGE = 1, 227 KVZ_SAO_BAND = 2, 228 KVZ_SAO_FULL = 3 229 }; 230 231 enum kvz_scalinglist { 232 KVZ_SCALING_LIST_OFF = 0, 233 KVZ_SCALING_LIST_CUSTOM = 1, 234 KVZ_SCALING_LIST_DEFAULT = 2, 235 }; 236 237 enum kvz_rc_algorithm 238 { 239 KVZ_NO_RC = 0, 240 KVZ_LAMBDA = 1, 241 KVZ_OBA = 2, 242 }; 243 244 enum kvz_file_format 245 { 246 KVZ_FORMAT_AUTO = 0, 247 KVZ_FORMAT_Y4M = 1, 248 KVZ_FORMAT_YUV = 2 249 }; 250 251 252 // Map from input format to chroma format. 253 #define KVZ_FORMAT2CSP(format) ((enum kvz_chroma_format)"\0\1\2\3"[format]) 254 255 /** 256 * \brief GoP picture configuration. 257 */ 258 typedef struct kvz_gop_config { 259 double qp_factor; 260 int8_t qp_offset; /*!< \brief QP offset */ 261 int8_t poc_offset; /*!< \brief POC offset */ 262 int8_t layer; /*!< \brief Current layer */ 263 int8_t is_ref; /*!< \brief Flag if this picture is used as a reference */ 264 int8_t ref_pos_count;/*!< \brief Reference picture count */ 265 int8_t ref_pos[16]; /*!< \brief reference picture offset list */ 266 int8_t ref_neg_count;/*!< \brief Reference picture count */ 267 int8_t ref_neg[16]; /*!< \brief reference picture offset list */ 268 double qp_model_offset; 269 double qp_model_scale; 270 } kvz_gop_config; 271 272 /** 273 * \brief Struct which contains all configuration data 274 * 275 * Functions config_alloc, config_init and config_destroy must be used to 276 * maintain ABI compatibility. Do not copy this struct, as the size might 277 * change. 278 */ 279 typedef struct kvz_config 280 { 281 int32_t qp; /*!< \brief Quantization parameter */ 282 int32_t intra_period; /*!< \brief the period of intra frames in stream */ 283 284 /** \brief How often the VPS, SPS and PPS are re-sent 285 * 286 * -1: never 287 * 0: first frame only 288 * 1: every intra frame 289 * 2: every other intra frame 290 * 3: every third intra frame 291 * and so on 292 */ 293 int32_t vps_period; 294 295 int32_t width; /*!< \brief frame width, must be a multiple of 8 */ 296 int32_t height; /*!< \brief frame height, must be a multiple of 8 */ 297 double framerate; /*!< \brief Deprecated, will be removed. */ 298 int32_t framerate_num; /*!< \brief Framerate numerator */ 299 int32_t framerate_denom; /*!< \brief Framerate denominator */ 300 int32_t deblock_enable; /*!< \brief Flag to enable deblocking filter */ 301 enum kvz_sao sao_type; /*!< \brief Flag to enable sample adaptive offset filter */ 302 int32_t rdoq_enable; /*!< \brief Flag to enable RD optimized quantization. */ 303 int32_t signhide_enable; /*!< \brief Flag to enable sign hiding. */ 304 int32_t smp_enable; /*!< \brief Flag to enable SMP blocks. */ 305 int32_t amp_enable; /*!< \brief Flag to enable AMP blocks. */ 306 int32_t rdo; /*!< \brief RD-calculation level (0..2) */ 307 int32_t full_intra_search; /*!< \brief If true, don't skip modes in intra search. */ 308 int32_t trskip_enable; /*!< \brief Flag to enable transform skip (for 4x4 blocks). */ 309 int32_t tr_depth_intra; /*!< \brief Maximum transform depth for intra. */ 310 enum kvz_ime_algorithm ime_algorithm; /*!< \brief Integer motion estimation algorithm. */ 311 int32_t fme_level; /*!< \brief Fractional pixel motion estimation level (0: disabled, 1: enabled). */ 312 int8_t source_scan_type; /*!< \brief Source scan type (0: progressive, 1: top field first, 2: bottom field first).*/ 313 int32_t bipred; /*!< \brief Bi-prediction (0: disabled, 1: enabled). */ 314 int32_t deblock_beta; /*!< \brief (deblocking) beta offset (div 2), range -6...6 */ 315 int32_t deblock_tc; /*!< \brief (deblocking) tc offset (div 2), range -6...6 */ 316 struct 317 { 318 int32_t sar_width; /*!< \brief the horizontal size of the sample aspect ratio (in arbitrary units) */ 319 int32_t sar_height; /*!< \brief the vertical size of the sample aspect ratio (in the same arbitrary units as sar_width). */ 320 int8_t overscan; /*!< \brief Crop overscan setting */ 321 int8_t videoformat; /*!< \brief Video format */ 322 int8_t fullrange; /*!< \brief Flag to indicate full-range */ 323 int8_t colorprim; /*!< \brief Color primaries */ 324 int8_t transfer; /*!< \brief Transfer characteristics */ 325 int8_t colormatrix; /*!< \brief Color matrix coefficients */ 326 int32_t chroma_loc; /*!< \brief Chroma sample location */ 327 } vui; 328 int32_t aud_enable; /*!< \brief Flag to use access unit delimiters */ 329 int32_t ref_frames; /*!< \brief number of reference frames to use */ 330 char * cqmfile; /*!< \brief Pointer to custom quantization matrices filename */ 331 332 int32_t tiles_width_count; /*!< \brief number of tiles separation in x direction */ 333 int32_t tiles_height_count; /*!< \brief number of tiles separation in y direction */ 334 int32_t* tiles_width_split; /*!< \brief tiles split x coordinates (dimension: tiles_width_count) */ 335 int32_t* tiles_height_split; /*!< \brief tiles split y coordinates (dimension: tiles_height_count) */ 336 337 int wpp; 338 int owf; 339 340 int32_t slice_count; 341 int32_t* slice_addresses_in_ts; 342 343 int32_t threads; 344 int32_t cpuid; 345 346 struct { 347 int32_t min[KVZ_MAX_GOP_LAYERS]; 348 int32_t max[KVZ_MAX_GOP_LAYERS]; 349 } pu_depth_inter, pu_depth_intra; 350 351 int32_t add_encoder_info; 352 int8_t gop_len; /*!< \brief length of GOP for the video sequence */ 353 int8_t gop_lowdelay; /*!< \brief specifies that the GOP does not use future pictures */ 354 kvz_gop_config gop[KVZ_MAX_GOP_LENGTH]; /*!< \brief Array of GOP settings */ 355 356 int32_t target_bitrate; 357 358 int8_t mv_rdo; /*!< \brief MV RDO calculation in search (0: estimation, 1: RDO). */ 359 int8_t calc_psnr; /*!< \since 3.1.0 \brief Print PSNR in CLI. */ 360 361 enum kvz_mv_constraint mv_constraint; /*!< \since 3.3.0 \brief Constrain movement vectors. */ 362 enum kvz_hash hash; /*!< \since 3.5.0 \brief What hash algorithm to use. */ 363 364 enum kvz_cu_split_termination cu_split_termination; /*!< \since 3.8.0 \brief Mode of cu split termination. */ 365 366 enum kvz_crypto_features crypto_features; /*!< \since 3.7.0 */ 367 uint8_t *optional_key; 368 369 enum kvz_me_early_termination me_early_termination; /*!< \since 3.8.0 \brief Mode of me early termination. */ 370 int32_t intra_rdo_et; /*!< \since 4.1.0 \brief Use early termination in intra rdo. */ 371 372 int32_t lossless; /*!< \brief Use lossless coding. */ 373 374 int32_t tmvp_enable; /*!> \brief Use Temporal Motion Vector Predictors. */ 375 376 int32_t rdoq_skip; /*!< \brief Mode of rdoq skip */ 377 378 enum kvz_input_format input_format; /*!< \brief Use Temporal Motion Vector Predictors. */ 379 int32_t input_bitdepth; /*!< \brief Use Temporal Motion Vector Predictors. */ 380 381 struct { 382 unsigned d; // depth 383 unsigned t; // temporal 384 } gop_lp_definition; 385 386 int32_t implicit_rdpcm; /*!< \brief Enable implicit residual DPCM. */ 387 388 struct { 389 int32_t width; 390 int32_t height; 391 int8_t *dqps; 392 } roi; /*!< \since 3.14.0 \brief Map of delta QPs for region of interest coding. */ 393 394 unsigned slices; /*!< \since 3.15.0 \brief How to map slices to frame. */ 395 396 /** 397 * \brief Use adaptive QP for 360 video with equirectangular projection. 398 */ 399 int32_t erp_aqp; 400 401 /** \brief The HEVC level */ 402 uint8_t level; 403 /** \brief Whether we ignore and just warn from all of the errors about the output not conforming to the level's requirements. */ 404 uint8_t force_level; 405 /** \brief Whether we use the high tier bitrates. Requires the level to be 4 or higher. */ 406 uint8_t high_tier; 407 /** \brief The maximum allowed bitrate for this level and tier. */ 408 uint32_t max_bitrate; 409 410 /** \brief Maximum steps that hexagonal and diagonal motion estimation can use. -1 to disable */ 411 uint32_t me_max_steps; 412 413 /** \brief Offset to add to QP for intra frames */ 414 int8_t intra_qp_offset; 415 /** \brief Select intra QP Offset based on GOP length */ 416 uint8_t intra_qp_offset_auto; 417 418 /** \brief Minimum QP that uses CABAC for residual cost instead of a fast estimate. */ 419 int8_t fast_residual_cost_limit; 420 421 /** \brief Set QP at CU level keeping pic_init_qp_minus26 in PPS zero */ 422 int8_t set_qp_in_cu; 423 424 /** \brief Flag to enable/disable open GOP configuration */ 425 int8_t open_gop; 426 427 int32_t vaq; /** \brief Enable variance adaptive quantization*/ 428 429 /** \brief Type of scaling lists to use */ 430 int8_t scaling_list; 431 432 /** \brief Maximum number of merge cadidates */ 433 uint8_t max_merge; 434 435 /** \brief Enable Early Skip Mode Decision */ 436 uint8_t early_skip; 437 438 /** \brief Enable Machine learning CU depth prediction for Intra encoding. */ 439 uint8_t ml_pu_depth_intra; 440 441 /** \brief Used for partial frame encoding*/ 442 struct { 443 uint8_t startCTU_x; 444 uint8_t startCTU_y; 445 uint16_t fullWidth; 446 uint16_t fullHeight; 447 } partial_coding; 448 449 /** \brief Always consider CU without any quantized residual */ 450 uint8_t zero_coeff_rdo; 451 452 /** \brief Currently unused parameter for OBA rc */ 453 int8_t frame_allocation; 454 455 /** \brief used rc scheme, 0 for QP */ 456 int8_t rc_algorithm; 457 458 /** \brief whether to use hadamard based bit allocation for intra frames or not */ 459 uint8_t intra_bit_allocation; 460 461 uint8_t clip_neighbour; 462 463 enum kvz_file_format file_format; 464 465 char *stats_file_prefix; 466 char *fast_coeff_table_fn; /*!< \brief Pointer to fast coeff table filename */ 467 468 /** \brief whether we're sampling TBs and their costs for fast cost 469 * estimation training */ 470 uint8_t rdo_cost_sampling_mode_on; 471 472 /** \brief whether we're running in normal mode, sampling TBs and their cost 473 * for fast estimation training, or comparing estimator accuracy to 474 * CABAC */ 475 uint8_t fastrd_sampling_on; 476 uint8_t fastrd_accuracy_check_on; 477 478 char *fastrd_learning_outdir_fn; 479 480 } kvz_config; 481 482 /** 483 * \brief Struct which contains all picture data 484 * 485 * Function picture_alloc in kvz_api must be used for allocation. 486 */ 487 typedef struct kvz_picture { 488 kvz_pixel *fulldata_buf; //!< \brief Allocated buffer with padding (only used in the base_image) 489 kvz_pixel *fulldata; //!< \brief Allocated buffer portion that's actually used 490 491 kvz_pixel *y; //!< \brief Pointer to luma pixel array. 492 kvz_pixel *u; //!< \brief Pointer to chroma U pixel array. 493 kvz_pixel *v; //!< \brief Pointer to chroma V pixel array. 494 kvz_pixel *data[3]; //!< \brief Alternate access method to same data. 495 496 int32_t width; //!< \brief Luma pixel array width. 497 int32_t height; //!< \brief Luma pixel array height. 498 499 int32_t stride; //!< \brief Luma pixel array width for the full picture (should be used as stride) 500 501 struct kvz_picture *base_image; //!< \brief Pointer to the picture which owns the pixels 502 int32_t refcount; //!< \brief Number of references to the picture 503 504 int64_t pts; //!< \brief Presentation timestamp. Should be set for input frames. 505 int64_t dts; //!< \brief Decompression timestamp. 506 507 enum kvz_interlacing interlacing; //!< \since 3.2.0 \brief Field order for interlaced pictures. 508 enum kvz_chroma_format chroma_format; 509 510 int32_t ref_pocs[16]; 511 } kvz_picture; 512 513 /** 514 * \brief NAL unit type codes. 515 * 516 * These are the nal_unit_type codes from Table 7-1 ITU-T H.265 v1.0. 517 */ 518 enum kvz_nal_unit_type { 519 520 // Trailing pictures 521 522 KVZ_NAL_TRAIL_N = 0, 523 KVZ_NAL_TRAIL_R = 1, 524 525 KVZ_NAL_TSA_N = 2, 526 KVZ_NAL_TSA_R = 3, 527 528 KVZ_NAL_STSA_N = 4, 529 KVZ_NAL_STSA_R = 5, 530 531 // Leading pictures 532 533 KVZ_NAL_RADL_N = 6, 534 KVZ_NAL_RADL_R = 7, 535 536 KVZ_NAL_RASL_N = 8, 537 KVZ_NAL_RASL_R = 9, 538 539 // Reserved non-IRAP RSV_VCL_N/R 10-15 540 541 // Intra random access point pictures 542 543 KVZ_NAL_BLA_W_LP = 16, 544 KVZ_NAL_BLA_W_RADL = 17, 545 KVZ_NAL_BLA_N_LP = 18, 546 547 KVZ_NAL_IDR_W_RADL = 19, 548 KVZ_NAL_IDR_N_LP = 20, 549 550 KVZ_NAL_CRA_NUT = 21, 551 552 // Reserved IRAP 553 554 KVZ_NAL_RSV_IRAP_VCL22 = 22, 555 KVZ_NAL_RSV_IRAP_VCL23 = 23, 556 557 // Reserved non-IRAP RSV_VCL 24-32 558 559 // non-VCL 560 561 KVZ_NAL_VPS_NUT = 32, 562 KVZ_NAL_SPS_NUT = 33, 563 KVZ_NAL_PPS_NUT = 34, 564 565 KVZ_NAL_AUD_NUT = 35, 566 KVZ_NAL_EOS_NUT = 36, 567 KVZ_NAL_EOB_NUT = 37, 568 KVZ_NAL_FD_NUT = 38, 569 570 KVZ_NAL_PREFIX_SEI_NUT = 39, 571 KVZ_NAL_SUFFIX_SEI_NUT = 40, 572 573 // Reserved RSV_NVCL 41-47 574 // Unspecified UNSPEC 48-63 575 }; 576 577 enum kvz_slice_type { 578 KVZ_SLICE_B = 0, 579 KVZ_SLICE_P = 1, 580 KVZ_SLICE_I = 2, 581 }; 582 583 /** 584 * \brief Other information about an encoded frame 585 */ 586 typedef struct kvz_frame_info { 587 588 /** 589 * \brief Picture order count 590 */ 591 int32_t poc; 592 593 /** 594 * \brief Quantization parameter 595 */ 596 int8_t qp; 597 598 /** 599 * \brief Type of the NAL VCL unit 600 */ 601 enum kvz_nal_unit_type nal_unit_type; 602 603 /** 604 * \brief Type of the slice 605 */ 606 enum kvz_slice_type slice_type; 607 608 /** 609 * \brief Reference picture lists 610 * 611 * The first list contains the reference picture POCs that are less than the 612 * POC of this frame and the second one contains those that are greater. 613 */ 614 int ref_list[2][16]; 615 616 /** 617 * \brief Lengths of the reference picture lists 618 */ 619 int ref_list_len[2]; 620 621 } kvz_frame_info; 622 623 /** 624 * \brief A linked list of chunks of data. 625 * 626 * Used for returning the encoded data. 627 */ 628 typedef struct kvz_data_chunk { 629 /// \brief Buffer for the data. 630 uint8_t data[KVZ_DATA_CHUNK_SIZE]; 631 632 /// \brief Number of bytes filled in this chunk. 633 uint32_t len; 634 635 /// \brief Next chunk in the list. 636 struct kvz_data_chunk *next; 637 } kvz_data_chunk; 638 639 typedef struct kvz_api { 640 641 /** 642 * \brief Allocate a kvz_config structure. 643 * 644 * The returned structure should be deallocated by calling config_destroy. 645 * 646 * \return allocated config, or NULL if allocation failed. 647 */ 648 kvz_config * (*config_alloc)(void); 649 650 /** 651 * \brief Deallocate a kvz_config structure. 652 * 653 * If cfg is NULL, do nothing. Otherwise, the given structure must have been 654 * returned from config_alloc. 655 * 656 * \param cfg configuration 657 * \return 1 on success, 0 on failure 658 */ 659 int (*config_destroy)(kvz_config *cfg); 660 661 /** 662 * \brief Initialize a config structure 663 * 664 * Set all fields in the given config to default values. 665 * 666 * \param cfg configuration 667 * \return 1 on success, 0 on failure 668 */ 669 int (*config_init)(kvz_config *cfg); 670 671 /** 672 * \brief Set an option. 673 * 674 * \param cfg configuration 675 * \param name name of the option to set 676 * \param value value to set 677 * \return 1 on success, 0 on failure 678 */ 679 int (*config_parse)(kvz_config *cfg, const char *name, const char *value); 680 681 /** 682 * \brief Allocate a kvz_picture. 683 * 684 * The returned kvz_picture should be deallocated by calling picture_free. 685 * 686 * \param width width of luma pixel array to allocate 687 * \param height height of luma pixel array to allocate 688 * \return allocated picture, or NULL if allocation failed. 689 */ 690 kvz_picture * (*picture_alloc)(int32_t width, int32_t height); 691 692 /** 693 * \brief Deallocate a kvz_picture. 694 * 695 * If pic is NULL, do nothing. Otherwise, the picture must have been returned 696 * from picture_alloc. 697 */ 698 void (*picture_free)(kvz_picture *pic); 699 700 /** 701 * \brief Deallocate a list of data chunks. 702 * 703 * Deallocates the given chunk and all chunks that follow it in the linked 704 * list. 705 */ 706 void (*chunk_free)(kvz_data_chunk *chunk); 707 708 /** 709 * \brief Create an encoder. 710 * 711 * The returned encoder should be closed by calling encoder_close. 712 * 713 * Only one encoder may be open at a time. 714 * 715 * \param cfg encoder configuration 716 * \return created encoder, or NULL if creation failed. 717 */ 718 kvz_encoder * (*encoder_open)(const kvz_config *cfg); 719 720 /** 721 * \brief Deallocate an encoder. 722 * 723 * If encoder is NULL, do nothing. Otherwise, the encoder must have been 724 * returned from encoder_open. 725 */ 726 void (*encoder_close)(kvz_encoder *encoder); 727 728 /** 729 * \brief Get parameter sets. 730 * 731 * Encode the VPS, SPS and PPS. 732 * 733 * If data_out is set to non-NULL values, the caller is responsible for 734 * calling chunk_free on it. 735 * 736 * A null pointer may be passed in place of the parameter data_out or len_out 737 * to skip returning the corresponding value. 738 * 739 * \param encoder encoder 740 * \param data_out Returns the encoded parameter sets. 741 * \param len_out Returns number of bytes in the encoded data. 742 * \return 1 on success, 0 on error. 743 */ 744 int (*encoder_headers)(kvz_encoder *encoder, 745 kvz_data_chunk **data_out, 746 uint32_t *len_out); 747 748 /** 749 * \brief Encode one frame. 750 * 751 * Add pic_in to the encoding pipeline. If an encoded frame is ready, return 752 * the bitstream, length of the bitstream, the reconstructed frame, the 753 * original frame and frame info in data_out, len_out, pic_out, src_out and 754 * info_out, respectively. Otherwise, set the output parameters to NULL. 755 * 756 * After passing all of the input frames, the caller should keep calling this 757 * function with pic_in set to NULL, until no more data is returned in the 758 * output parameters. 759 * 760 * The caller must not modify pic_in after passing it to this function. 761 * 762 * If data_out, pic_out and src_out are set to non-NULL values, the caller is 763 * responsible for calling chunk_free and picture_free on them. 764 * 765 * A null pointer may be passed in place of any of the parameters data_out, 766 * len_out, pic_out, src_out or info_out to skip returning the corresponding 767 * value. 768 * 769 * \param encoder encoder 770 * \param pic_in input frame or NULL 771 * \param data_out Returns the encoded data. 772 * \param len_out Returns number of bytes in the encoded data. 773 * \param pic_out Returns the reconstructed picture. 774 * \param src_out Returns the original picture. 775 * \param info_out Returns information about the encoded picture. 776 * \return 1 on success, 0 on error. 777 */ 778 int (*encoder_encode)(kvz_encoder *encoder, 779 kvz_picture *pic_in, 780 kvz_data_chunk **data_out, 781 uint32_t *len_out, 782 kvz_picture **pic_out, 783 kvz_picture **src_out, 784 kvz_frame_info *info_out); 785 786 /** 787 * \brief Allocate a kvz_picture. 788 * 789 * The returned kvz_picture should be deallocated by calling picture_free. 790 * 791 * \since 3.12.0 792 * \param chroma_fomat Chroma subsampling to use. 793 * \param width width of luma pixel array to allocate 794 * \param height height of luma pixel array to allocate 795 * \return allocated picture, or NULL if allocation failed. 796 */ 797 kvz_picture * (*picture_alloc_csp)(enum kvz_chroma_format chroma_fomat, int32_t width, int32_t height); 798 } kvz_api; 799 800 801 KVZ_PUBLIC const kvz_api * kvz_api_get(int bit_depth); 802 803 #ifdef __cplusplus 804 } 805 #endif 806 807 #endif // KVAZAAR_H_ 808