1 /* 2 * Copyright (c) 2010 The WebM project authors. All Rights Reserved. 3 * 4 * Use of this source code is governed by a BSD-style license 5 * that can be found in the LICENSE file in the root of the source 6 * tree. An additional intellectual property rights grant can be found 7 * in the file PATENTS. All contributing project authors may 8 * be found in the AUTHORS file in the root of the source tree. 9 */ 10 11 /*!\defgroup encoder Encoder Algorithm Interface 12 * \ingroup codec 13 * This abstraction allows applications using this encoder to easily support 14 * multiple video formats with minimal code duplication. This section describes 15 * the interface common to all encoders. 16 * @{ 17 */ 18 19 /*!\file 20 * \brief Describes the encoder algorithm interface to applications. 21 * 22 * This file describes the interface between an application and a 23 * video encoder algorithm. 24 * 25 */ 26 27 module libvpx.vpx.vpx_encoder; 28 29 import std.stdint; 30 import libvpx.vpx.vpx_codec; 31 import libvpx.vpx.vpx_image; 32 33 extern (C) { 34 35 /*! Temporal Scalability: Maximum length of the sequence defining frame 36 * layer membership 37 */ 38 enum VPX_TS_MAX_PERIODICITY = 16; 39 40 /*! Temporal Scalability: Maximum number of coding layers */ 41 enum VPX_TS_MAX_LAYERS = 5; 42 43 /*!\deprecated Use #VPX_TS_MAX_PERIODICITY instead. */ 44 enum MAX_PERIODICITY = VPX_TS_MAX_PERIODICITY; 45 46 /*!\deprecated Use #VPX_TS_MAX_LAYERS instead. */ 47 enum MAX_LAYERS = VPX_TS_MAX_LAYERS; 48 49 /*! Spatial Scalability: Maximum number of coding layers */ 50 enum VPX_SS_MAX_LAYERS = 5; 51 52 /*! Spatial Scalability: Default number of coding layers */ 53 enum VPX_SS_DEFAULT_LAYERS = 3; 54 55 /*!\brief Current ABI version number 56 * 57 * \internal 58 * If this file is altered in any way that changes the ABI, this value 59 * must be bumped. Examples include, but are not limited to, changing 60 * types, removing or reassigning enums, adding/removing/rearranging 61 * fields to structures 62 */ 63 enum VPX_ENCODER_ABI_VERSION = (3 + VPX_CODEC_ABI_VERSION); /**<\hideinitializer*/ 64 65 66 /*! \brief Encoder capabilities bitfield 67 * 68 * Each encoder advertises the capabilities it supports as part of its 69 * ::vpx_codec_iface_t interface structure. Capabilities are extra 70 * interfaces or functionality, and are not required to be supported 71 * by an encoder. 72 * 73 * The available flags are specified by VPX_CODEC_CAP_* defines. 74 */ 75 enum VPX_CODEC_CAP_PSNR = 0x10000; /**< Can issue PSNR packets */ 76 77 /*! Can output one partition at a time. Each partition is returned in its 78 * own VPX_CODEC_CX_FRAME_PKT, with the FRAME_IS_FRAGMENT flag set for 79 * every partition but the last. In this mode all frames are always 80 * returned partition by partition. 81 */ 82 enum VPX_CODEC_CAP_OUTPUT_PARTITION = 0x20000; 83 84 85 /*! \brief Initialization-time Feature Enabling 86 * 87 * Certain codec features must be known at initialization time, to allow 88 * for proper memory allocation. 89 * 90 * The available flags are specified by VPX_CODEC_USE_* defines. 91 */ 92 enum VPX_CODEC_USE_PSNR = 0x10000; /**< Calculate PSNR on each frame */ 93 enum VPX_CODEC_USE_OUTPUT_PARTITION = 0x20000; /**< Make the encoder output one 94 partition at a time. */ 95 96 97 /*!\brief Generic fixed size buffer structure 98 * 99 * This structure is able to hold a reference to any fixed size buffer. 100 */ 101 struct vpx_fixed_buf { 102 void *buf; /**< Pointer to the data */ 103 size_t sz; /**< Length of the buffer, in chars */ 104 } 105 alias vpx_fixed_buf_t = vpx_fixed_buf; /**< alias for struct vpx_fixed_buf */ 106 107 108 /*!\brief Time Stamp Type 109 * 110 * An integer, which when multiplied by the stream's time base, provides 111 * the absolute time of a sample. 112 */ 113 alias vpx_codec_pts_t = int64_t; 114 115 116 /*!\brief Compressed Frame Flags 117 * 118 * This type represents a bitfield containing information about a compressed 119 * frame that may be useful to an application. The most significant 16 bits 120 * can be used by an algorithm to provide additional detail, for example to 121 * support frame types that are codec specific (MPEG-1 D-frames for example) 122 */ 123 alias vpx_codec_frame_flags_t = uint32_t; 124 enum VPX_FRAME_IS_KEY = 0x1; /**< frame is the start of a GOP */ 125 enum VPX_FRAME_IS_DROPPABLE = 0x2; /**< frame can be dropped without affecting 126 the stream (no future frame depends on 127 this one) */ 128 enum VPX_FRAME_IS_INVISIBLE = 0x4; /**< frame should be decoded but will not 129 be shown */ 130 enum VPX_FRAME_IS_FRAGMENT = 0x8; /**< this is a fragment of the encoded 131 frame */ 132 133 /*!\brief Error Resilient flags 134 * 135 * These flags define which error resilient features to enable in the 136 * encoder. The flags are specified through the 137 * vpx_codec_enc_cfg::g_error_resilient variable. 138 */ 139 alias vpx_codec_er_flags_t = uint32_t; 140 enum VPX_ERROR_RESILIENT_DEFAULT = 0x1; /**< Improve resiliency against 141 losses of whole frames */ 142 enum VPX_ERROR_RESILIENT_PARTITIONS = 0x2; /**< The frame partitions are 143 independently decodable by the 144 bool decoder, meaning that 145 partitions can be decoded even 146 though earlier partitions have 147 been lost. Note that intra 148 predicition is still done over 149 the partition boundary. */ 150 151 /*!\brief Encoder output packet variants 152 * 153 * This enumeration lists the different kinds of data packets that can be 154 * returned by calls to vpx_codec_get_cx_data(). Algorithms \ref MAY 155 * extend this list to provide additional functionality. 156 */ 157 enum vpx_codec_cx_pkt_kind { 158 VPX_CODEC_CX_FRAME_PKT, /**< Compressed video frame */ 159 VPX_CODEC_STATS_PKT, /**< Two-pass statistics for this frame */ 160 VPX_CODEC_PSNR_PKT, /**< PSNR statistics for this frame */ 161 VPX_CODEC_CUSTOM_PKT = 256 /**< Algorithm extensions */ 162 }; 163 164 165 /*!\brief Encoder output packet 166 * 167 * This structure contains the different kinds of output data the encoder 168 * may produce while compressing a frame. 169 */ 170 struct vpx_codec_cx_pkt { 171 vpx_codec_cx_pkt_kind kind; /**< packet variant */ 172 173 private union vpx_codec_cx_data { 174 private struct vpx_codec_frame_pkt { 175 void *buf; /**< compressed data buffer */ 176 size_t sz; /**< length of compressed data */ 177 vpx_codec_pts_t pts; /**< time stamp to show frame 178 (in timebase units) */ 179 ulong duration; /**< duration to show frame 180 (in timebase units) */ 181 vpx_codec_frame_flags_t flags; /**< flags for this frame */ 182 int partition_id; /**< the partition id 183 defines the decoding order 184 of the partitions. Only 185 applicable when "output partition" 186 mode is enabled. First partition 187 has id 0.*/ 188 189 } /**< data for compressed frame packet */ 190 191 private struct vpx_psnr_pkt { 192 uint samples[4]; /**< Number of samples, total/y/u/v */ 193 uint64_t sse[4]; /**< sum squared error, total/y/u/v */ 194 double psnr[4]; /**< PSNR, total/y/u/v */ 195 } /**< data for PSNR packet */ 196 197 vpx_codec_frame_pkt frame; 198 vpx_psnr_pkt psnr; 199 vpx_fixed_buf twopass_stats; /**< data for two-pass packet */ 200 vpx_fixed_buf raw; /**< data for arbitrary packets */ 201 202 /* This packet size is fixed to allow codecs to extend this 203 * interface without having to manage storage for raw packets, 204 * i.e., if it's smaller than 128 bytes, you can store in the 205 * packet list directly. 206 */ 207 char pad[128 - vpx_codec_cx_pkt_kind.sizeof]; /**< fixed sz */ 208 } 209 210 vpx_codec_cx_data data; /**< packet data */ 211 } 212 alias vpx_codec_cx_pkt_t = vpx_codec_cx_pkt; /**< alias for struct vpx_codec_cx_pkt */ 213 214 215 /*!\brief Rational Number 216 * 217 * This structure holds a fractional value. 218 */ 219 struct vpx_rational { 220 int num; /**< fraction numerator */ 221 int den; /**< fraction denominator */ 222 } /**< alias for struct vpx_rational */ 223 alias vpx_rational_t = vpx_rational; 224 225 /*!\brief Multi-pass Encoding Pass */ 226 enum vpx_enc_pass { 227 VPX_RC_ONE_PASS, /**< Single pass mode */ 228 VPX_RC_FIRST_PASS, /**< First pass of multi-pass mode */ 229 VPX_RC_LAST_PASS /**< Final pass of multi-pass mode */ 230 } 231 232 233 /*!\brief Rate control mode */ 234 enum vpx_rc_mode { 235 VPX_VBR, /**< Variable Bit Rate (VBR) mode */ 236 VPX_CBR, /**< Constant Bit Rate (CBR) mode */ 237 VPX_CQ, /**< Constrained Quality (CQ) mode */ 238 VPX_Q, /**< Constant Quality (Q) mode */ 239 } 240 241 242 /*!\brief Keyframe placement mode. 243 * 244 * This enumeration determines whether keyframes are placed automatically by 245 * the encoder or whether this behavior is disabled. Older releases of this 246 * SDK were implemented such that VPX_KF_FIXED meant keyframes were disabled. 247 * This name is confusing for this behavior, so the new symbols to be used 248 * are VPX_KF_AUTO and VPX_KF_DISABLED. 249 */ 250 enum vpx_kf_mode { 251 VPX_KF_FIXED, /**< deprecated, implies VPX_KF_DISABLED */ 252 VPX_KF_AUTO, /**< Encoder determines optimal placement automatically */ 253 VPX_KF_DISABLED = 0 /**< Encoder does not place keyframes. */ 254 } 255 256 257 /*!\brief Encoded Frame Flags 258 * 259 * This type indicates a bitfield to be passed to vpx_codec_encode(), defining 260 * per-frame boolean values. By convention, bits common to all codecs will be 261 * named VPX_EFLAG_*, and bits specific to an algorithm will be named 262 * /algo/_eflag_*. The lower order 16 bits are reserved for common use. 263 */ 264 alias vpx_enc_frame_flags_t = long; 265 enum VPX_EFLAG_FORCE_KF = (1<<0); /**< Force this frame to be a keyframe */ 266 267 268 /*!\brief Encoder configuration structure 269 * 270 * This structure contains the encoder settings that have common representations 271 * across all codecs. This doesn't imply that all codecs support all features, 272 * however. 273 */ 274 struct vpx_codec_enc_cfg { 275 /* 276 * generic settings (g) 277 */ 278 279 /*!\brief Algorithm specific "usage" value 280 * 281 * Algorithms may define multiple values for usage, which may convey the 282 * intent of how the application intends to use the stream. If this value 283 * is non-zero, consult the documentation for the codec to determine its 284 * meaning. 285 */ 286 uint g_usage; 287 288 289 /*!\brief Maximum number of threads to use 290 * 291 * For multi-threaded implementations, use no more than this number of 292 * threads. The codec may use fewer threads than allowed. The value 293 * 0 is equivalent to the value 1. 294 */ 295 uint g_threads; 296 297 298 /*!\brief Bitstream profile to use 299 * 300 * Some codecs support a notion of multiple bitstream profiles. Typically 301 * this maps to a set of features that are turned on or off. Often the 302 * profile to use is determined by the features of the intended decoder. 303 * Consult the documentation for the codec to determine the valid values 304 * for this parameter, or set to zero for a sane default. 305 */ 306 uint g_profile; /**< profile of bitstream to use */ 307 308 309 310 /*!\brief Width of the frame 311 * 312 * This value identifies the presentation resolution of the frame, 313 * in pixels. Note that the frames passed as input to the encoder must 314 * have this resolution. Frames will be presented by the decoder in this 315 * resolution, independent of any spatial resampling the encoder may do. 316 */ 317 uint g_w; 318 319 320 /*!\brief Height of the frame 321 * 322 * This value identifies the presentation resolution of the frame, 323 * in pixels. Note that the frames passed as input to the encoder must 324 * have this resolution. Frames will be presented by the decoder in this 325 * resolution, independent of any spatial resampling the encoder may do. 326 */ 327 uint g_h; 328 329 330 /*!\brief Stream timebase units 331 * 332 * Indicates the smallest interval of time, in seconds, used by the stream. 333 * For fixed frame rate material, or variable frame rate material where 334 * frames are timed at a multiple of a given clock (ex: video capture), 335 * the \ref RECOMMENDED method is to set the timebase to the reciprocal 336 * of the frame rate (ex: 1001/30000 for 29.970 Hz NTSC). This allows the 337 * pts to correspond to the frame number, which can be handy. For 338 * re-encoding video from containers with absolute time timestamps, the 339 * \ref RECOMMENDED method is to set the timebase to that of the parent 340 * container or multimedia framework (ex: 1/1000 for ms, as in FLV). 341 */ 342 vpx_rational g_timebase; 343 344 345 /*!\brief Enable error resilient modes. 346 * 347 * The error resilient bitfield indicates to the encoder which features 348 * it should enable to take measures for streaming over lossy or noisy 349 * links. 350 */ 351 vpx_codec_er_flags_t g_error_resilient; 352 353 354 /*!\brief Multi-pass Encoding Mode 355 * 356 * This value should be set to the current phase for multi-pass encoding. 357 * For single pass, set to #VPX_RC_ONE_PASS. 358 */ 359 vpx_enc_pass g_pass; 360 361 362 /*!\brief Allow lagged encoding 363 * 364 * If set, this value allows the encoder to consume a number of input 365 * frames before producing output frames. This allows the encoder to 366 * base decisions for the current frame on future frames. This does 367 * increase the latency of the encoding pipeline, so it is not appropriate 368 * in all situations (ex: realtime encoding). 369 * 370 * Note that this is a maximum value -- the encoder may produce frames 371 * sooner than the given limit. Set this value to 0 to disable this 372 * feature. 373 */ 374 uint g_lag_in_frames; 375 376 377 /* 378 * rate control settings (rc) 379 */ 380 381 /*!\brief Temporal resampling configuration, if supported by the codec. 382 * 383 * Temporal resampling allows the codec to "drop" frames as a strategy to 384 * meet its target data rate. This can cause temporal discontinuities in 385 * the encoded video, which may appear as stuttering during playback. This 386 * trade-off is often acceptable, but for many applications is not. It can 387 * be disabled in these cases. 388 * 389 * Note that not all codecs support this feature. All vpx VPx codecs do. 390 * For other codecs, consult the documentation for that algorithm. 391 * 392 * This threshold is described as a percentage of the target data buffer. 393 * When the data buffer falls below this percentage of fullness, a 394 * dropped frame is indicated. Set the threshold to zero (0) to disable 395 * this feature. 396 */ 397 uint rc_dropframe_thresh; 398 399 400 /*!\brief Enable/disable spatial resampling, if supported by the codec. 401 * 402 * Spatial resampling allows the codec to compress a lower resolution 403 * version of the frame, which is then upscaled by the encoder to the 404 * correct presentation resolution. This increases visual quality at 405 * low data rates, at the expense of CPU time on the encoder/decoder. 406 */ 407 uint rc_resize_allowed; 408 409 410 /*!\brief Spatial resampling up watermark. 411 * 412 * This threshold is described as a percentage of the target data buffer. 413 * When the data buffer rises above this percentage of fullness, the 414 * encoder will step up to a higher resolution version of the frame. 415 */ 416 uint rc_resize_up_thresh; 417 418 419 /*!\brief Spatial resampling down watermark. 420 * 421 * This threshold is described as a percentage of the target data buffer. 422 * When the data buffer falls below this percentage of fullness, the 423 * encoder will step down to a lower resolution version of the frame. 424 */ 425 uint rc_resize_down_thresh; 426 427 428 /*!\brief Rate control algorithm to use. 429 * 430 * Indicates whether the end usage of this stream is to be streamed over 431 * a bandwidth constrained link, indicating that Constant Bit Rate (CBR) 432 * mode should be used, or whether it will be played back on a high 433 * bandwidth link, as from a local disk, where higher variations in 434 * bitrate are acceptable. 435 */ 436 vpx_rc_mode rc_end_usage; 437 438 439 /*!\brief Two-pass stats buffer. 440 * 441 * A buffer containing all of the stats packets produced in the first 442 * pass, concatenated. 443 */ 444 vpx_fixed_buf rc_twopass_stats_in; 445 446 447 /*!\brief Target data rate 448 * 449 * Target bandwidth to use for this stream, in kilobits per second. 450 */ 451 uint rc_target_bitrate; 452 453 454 /* 455 * quantizer settings 456 */ 457 458 459 /*!\brief Minimum (Best Quality) Quantizer 460 * 461 * The quantizer is the most direct control over the quality of the 462 * encoded image. The range of valid values for the quantizer is codec 463 * specific. Consult the documentation for the codec to determine the 464 * values to use. To determine the range programmatically, call 465 * vpx_codec_enc_config_default() with a usage value of 0. 466 */ 467 uint rc_min_quantizer; 468 469 470 /*!\brief Maximum (Worst Quality) Quantizer 471 * 472 * The quantizer is the most direct control over the quality of the 473 * encoded image. The range of valid values for the quantizer is codec 474 * specific. Consult the documentation for the codec to determine the 475 * values to use. To determine the range programmatically, call 476 * vpx_codec_enc_config_default() with a usage value of 0. 477 */ 478 uint rc_max_quantizer; 479 480 481 /* 482 * bitrate tolerance 483 */ 484 485 486 /*!\brief Rate control adaptation undershoot control 487 * 488 * This value, expressed as a percentage of the target bitrate, 489 * controls the maximum allowed adaptation speed of the codec. 490 * This factor controls the maximum amount of bits that can 491 * be subtracted from the target bitrate in order to compensate 492 * for prior overshoot. 493 * 494 * Valid values in the range 0-1000. 495 */ 496 uint rc_undershoot_pct; 497 498 499 /*!\brief Rate control adaptation overshoot control 500 * 501 * This value, expressed as a percentage of the target bitrate, 502 * controls the maximum allowed adaptation speed of the codec. 503 * This factor controls the maximum amount of bits that can 504 * be added to the target bitrate in order to compensate for 505 * prior undershoot. 506 * 507 * Valid values in the range 0-1000. 508 */ 509 uint rc_overshoot_pct; 510 511 512 /* 513 * decoder buffer model parameters 514 */ 515 516 517 /*!\brief Decoder Buffer Size 518 * 519 * This value indicates the amount of data that may be buffered by the 520 * decoding application. Note that this value is expressed in units of 521 * time (milliseconds). For example, a value of 5000 indicates that the 522 * client will buffer (at least) 5000ms worth of encoded data. Use the 523 * target bitrate (#rc_target_bitrate) to convert to bits/bytes, if 524 * necessary. 525 */ 526 uint rc_buf_sz; 527 528 529 /*!\brief Decoder Buffer Initial Size 530 * 531 * This value indicates the amount of data that will be buffered by the 532 * decoding application prior to beginning playback. This value is 533 * expressed in units of time (milliseconds). Use the target bitrate 534 * (#rc_target_bitrate) to convert to bits/bytes, if necessary. 535 */ 536 uint rc_buf_initial_sz; 537 538 539 /*!\brief Decoder Buffer Optimal Size 540 * 541 * This value indicates the amount of data that the encoder should try 542 * to maintain in the decoder's buffer. This value is expressed in units 543 * of time (milliseconds). Use the target bitrate (#rc_target_bitrate) 544 * to convert to bits/bytes, if necessary. 545 */ 546 uint rc_buf_optimal_sz; 547 548 549 /* 550 * 2 pass rate control parameters 551 */ 552 553 554 /*!\brief Two-pass mode CBR/VBR bias 555 * 556 * Bias, expressed on a scale of 0 to 100, for determining target size 557 * for the current frame. The value 0 indicates the optimal CBR mode 558 * value should be used. The value 100 indicates the optimal VBR mode 559 * value should be used. Values in between indicate which way the 560 * encoder should "lean." 561 */ 562 uint rc_2pass_vbr_bias_pct; /**< RC mode bias between CBR and VBR(0-100: 0->CBR, 100->VBR) */ 563 564 565 /*!\brief Two-pass mode per-GOP minimum bitrate 566 * 567 * This value, expressed as a percentage of the target bitrate, indicates 568 * the minimum bitrate to be used for a single GOP (aka "section") 569 */ 570 uint rc_2pass_vbr_minsection_pct; 571 572 573 /*!\brief Two-pass mode per-GOP maximum bitrate 574 * 575 * This value, expressed as a percentage of the target bitrate, indicates 576 * the maximum bitrate to be used for a single GOP (aka "section") 577 */ 578 uint rc_2pass_vbr_maxsection_pct; 579 580 581 /* 582 * keyframing settings (kf) 583 */ 584 585 /*!\brief Keyframe placement mode 586 * 587 * This value indicates whether the encoder should place keyframes at a 588 * fixed interval, or determine the optimal placement automatically 589 * (as governed by the #kf_min_dist and #kf_max_dist parameters) 590 */ 591 vpx_kf_mode kf_mode; 592 593 594 /*!\brief Keyframe minimum interval 595 * 596 * This value, expressed as a number of frames, prevents the encoder from 597 * placing a keyframe nearer than kf_min_dist to the previous keyframe. At 598 * least kf_min_dist frames non-keyframes will be coded before the next 599 * keyframe. Set kf_min_dist equal to kf_max_dist for a fixed interval. 600 */ 601 uint kf_min_dist; 602 603 604 /*!\brief Keyframe maximum interval 605 * 606 * This value, expressed as a number of frames, forces the encoder to code 607 * a keyframe if one has not been coded in the last kf_max_dist frames. 608 * A value of 0 implies all frames will be keyframes. Set kf_min_dist 609 * equal to kf_max_dist for a fixed interval. 610 */ 611 uint kf_max_dist; 612 613 /* 614 * Spatial scalability settings (ss) 615 */ 616 617 /*!\brief Number of spatial coding layers. 618 * 619 * This value specifies the number of spatial coding layers to be used. 620 */ 621 uint ss_number_layers; 622 623 /*!\brief Number of temporal coding layers. 624 * 625 * This value specifies the number of temporal layers to be used. 626 */ 627 uint ts_number_layers; 628 629 /*!\brief Target bitrate for each temporal layer. 630 * 631 * These values specify the target coding bitrate to be used for each 632 * temporal layer. 633 */ 634 uint ts_target_bitrate[VPX_TS_MAX_LAYERS]; 635 636 /*!\brief Frame rate decimation factor for each temporal layer. 637 * 638 * These values specify the frame rate decimation factors to apply 639 * to each temporal layer. 640 */ 641 uint ts_rate_decimator[VPX_TS_MAX_LAYERS]; 642 643 /*!\brief Length of the sequence defining frame temporal layer membership. 644 * 645 * This value specifies the length of the sequence that defines the 646 * membership of frames to temporal layers. For example, if the 647 * ts_periodicity = 8, then the frames are assigned to coding layers with a 648 * repeated sequence of length 8. 649 */ 650 uint ts_periodicity; 651 652 /*!\brief Template defining the membership of frames to temporal layers. 653 * 654 * This array defines the membership of frames to temporal coding layers. 655 * For a 2-layer encoding that assigns even numbered frames to one temporal 656 * layer (0) and odd numbered frames to a second temporal layer (1) with 657 * ts_periodicity=8, then ts_layer_id = (0,1,0,1,0,1,0,1). 658 */ 659 uint ts_layer_id[VPX_TS_MAX_PERIODICITY]; 660 } 661 662 alias vpx_codec_enc_cfg_t = vpx_codec_enc_cfg; /**< alias for struct vpx_codec_enc_cfg */ 663 664 665 /*!\brief Initialize an encoder instance 666 * 667 * Initializes a encoder context using the given interface. Applications 668 * should call the vpx_codec_enc_init convenience macro instead of this 669 * function directly, to ensure that the ABI version number parameter 670 * is properly initialized. 671 * 672 * If the library was configured with --disable-multithread, this call 673 * is not thread safe and should be guarded with a lock if being used 674 * in a multithreaded context. 675 * 676 * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags 677 * parameter), the storage pointed to by the cfg parameter must be 678 * kept readable and stable until all memory maps have been set. 679 * 680 * \param[in] ctx Pointer to this instance's context. 681 * \param[in] iface Pointer to the algorithm interface to use. 682 * \param[in] cfg Configuration to use, if known. May be NULL. 683 * \param[in] flags Bitfield of VPX_CODEC_USE_* flags 684 * \param[in] ver ABI version number. Must be set to 685 * VPX_ENCODER_ABI_VERSION 686 * \retval #VPX_CODEC_OK 687 * The decoder algorithm initialized. 688 * \retval #VPX_CODEC_MEM_ERROR 689 * Memory allocation failed. 690 */ 691 vpx_codec_err_t vpx_codec_enc_init_ver(vpx_codec_ctx_t *ctx, 692 vpx_codec_iface_t *iface, 693 vpx_codec_enc_cfg_t *cfg, 694 vpx_codec_flags_t flags, 695 int ver); 696 697 698 /*!\brief Convenience macro for vpx_codec_enc_init_ver() 699 * 700 * Ensures the ABI version parameter is properly set. 701 */ 702 enum vpx_codec_enc_init = 703 (vpx_codec_ctx_t *ctx, 704 vpx_codec_iface_t *iface, 705 vpx_codec_enc_cfg_t *cfg, 706 vpx_codec_flags_t flags) => 707 vpx_codec_enc_init_ver(ctx, iface, cfg, flags, VPX_ENCODER_ABI_VERSION); 708 709 710 /*!\brief Initialize multi-encoder instance 711 * 712 * Initializes multi-encoder context using the given interface. 713 * Applications should call the vpx_codec_enc_init_multi convenience macro 714 * instead of this function directly, to ensure that the ABI version number 715 * parameter is properly initialized. 716 * 717 * In XMA mode (activated by setting VPX_CODEC_USE_XMA in the flags 718 * parameter), the storage pointed to by the cfg parameter must be 719 * kept readable and stable until all memory maps have been set. 720 * 721 * \param[in] ctx Pointer to this instance's context. 722 * \param[in] iface Pointer to the algorithm interface to use. 723 * \param[in] cfg Configuration to use, if known. May be NULL. 724 * \param[in] num_enc Total number of encoders. 725 * \param[in] flags Bitfield of VPX_CODEC_USE_* flags 726 * \param[in] dsf Pointer to down-sampling factors. 727 * \param[in] ver ABI version number. Must be set to 728 * VPX_ENCODER_ABI_VERSION 729 * \retval #VPX_CODEC_OK 730 * The decoder algorithm initialized. 731 * \retval #VPX_CODEC_MEM_ERROR 732 * Memory allocation failed. 733 */ 734 vpx_codec_err_t vpx_codec_enc_init_multi_ver(vpx_codec_ctx_t *ctx, 735 vpx_codec_iface_t *iface, 736 vpx_codec_enc_cfg_t *cfg, 737 int num_enc, 738 vpx_codec_flags_t flags, 739 vpx_rational_t *dsf, 740 int ver); 741 742 743 /*!\brief Convenience macro for vpx_codec_enc_init_multi_ver() 744 * 745 * Ensures the ABI version parameter is properly set. 746 */ 747 enum vpx_codec_enc_init_multi = 748 (vpx_codec_ctx_t *ctx, 749 vpx_codec_iface_t *iface, 750 vpx_codec_enc_cfg_t *cfg, 751 int num_enc, 752 vpx_codec_flags_t flags, 753 vpx_rational_t *dsf) => 754 vpx_codec_enc_init_multi_ver(ctx, iface, cfg, num_enc, flags, dsf, VPX_ENCODER_ABI_VERSION); 755 756 757 /*!\brief Get a default configuration 758 * 759 * Initializes a encoder configuration structure with default values. Supports 760 * the notion of "usages" so that an algorithm may offer different default 761 * settings depending on the user's intended goal. This function \ref SHOULD 762 * be called by all applications to initialize the configuration structure 763 * before specializing the configuration with application specific values. 764 * 765 * \param[in] iface Pointer to the algorithm interface to use. 766 * \param[out] cfg Configuration buffer to populate 767 * \param[in] usage End usage. Set to 0 or use codec specific values. 768 * 769 * \retval #VPX_CODEC_OK 770 * The configuration was populated. 771 * \retval #VPX_CODEC_INCAPABLE 772 * Interface is not an encoder interface. 773 * \retval #VPX_CODEC_INVALID_PARAM 774 * A parameter was NULL, or the usage value was not recognized. 775 */ 776 vpx_codec_err_t vpx_codec_enc_config_default(vpx_codec_iface_t *iface, 777 vpx_codec_enc_cfg_t *cfg, 778 uint usage); 779 780 781 /*!\brief Set or change configuration 782 * 783 * Reconfigures an encoder instance according to the given configuration. 784 * 785 * \param[in] ctx Pointer to this instance's context 786 * \param[in] cfg Configuration buffer to use 787 * 788 * \retval #VPX_CODEC_OK 789 * The configuration was populated. 790 * \retval #VPX_CODEC_INCAPABLE 791 * Interface is not an encoder interface. 792 * \retval #VPX_CODEC_INVALID_PARAM 793 * A parameter was NULL, or the usage value was not recognized. 794 */ 795 vpx_codec_err_t vpx_codec_enc_config_set(vpx_codec_ctx_t *ctx, 796 const vpx_codec_enc_cfg_t *cfg); 797 798 799 /*!\brief Get global stream headers 800 * 801 * Retrieves a stream level global header packet, if supported by the codec. 802 * 803 * \param[in] ctx Pointer to this instance's context 804 * 805 * \retval NULL 806 * Encoder does not support global header 807 * \retval Non-NULL 808 * Pointer to buffer containing global header packet 809 */ 810 vpx_fixed_buf_t *vpx_codec_get_global_headers(vpx_codec_ctx_t *ctx); 811 812 813 enum VPX_DL_REALTIME = (1); /**< deadline parameter analogous to 814 * VPx REALTIME mode. */ 815 enum VPX_DL_GOOD_QUALITY = (1000000); /**< deadline parameter analogous to 816 * VPx GOOD QUALITY mode. */ 817 enum VPX_DL_BEST_QUALITY = (0); /**< deadline parameter analogous to 818 * VPx BEST QUALITY mode. */ 819 /*!\brief Encode a frame 820 * 821 * Encodes a video frame at the given "presentation time." The presentation 822 * time stamp (PTS) \ref MUST be strictly increasing. 823 * 824 * The encoder supports the notion of a soft real-time deadline. Given a 825 * non-zero value to the deadline parameter, the encoder will make a "best 826 * effort" guarantee to return before the given time slice expires. It is 827 * implicit that limiting the available time to encode will degrade the 828 * output quality. The encoder can be given an unlimited time to produce the 829 * best possible frame by specifying a deadline of '0'. This deadline 830 * supercedes the VPx notion of "best quality, good quality, realtime". 831 * Applications that wish to map these former settings to the new deadline 832 * based system can use the symbols #VPX_DL_REALTIME, #VPX_DL_GOOD_QUALITY, 833 * and #VPX_DL_BEST_QUALITY. 834 * 835 * When the last frame has been passed to the encoder, this function should 836 * continue to be called, with the img parameter set to NULL. This will 837 * signal the end-of-stream condition to the encoder and allow it to encode 838 * any held buffers. Encoding is complete when vpx_codec_encode() is called 839 * and vpx_codec_get_cx_data() returns no data. 840 * 841 * \param[in] ctx Pointer to this instance's context 842 * \param[in] img Image data to encode, NULL to flush. 843 * \param[in] pts Presentation time stamp, in timebase units. 844 * \param[in] duration Duration to show frame, in timebase units. 845 * \param[in] flags Flags to use for encoding this frame. 846 * \param[in] deadline Time to spend encoding, in microseconds. (0=infinite) 847 * 848 * \retval #VPX_CODEC_OK 849 * The configuration was populated. 850 * \retval #VPX_CODEC_INCAPABLE 851 * Interface is not an encoder interface. 852 * \retval #VPX_CODEC_INVALID_PARAM 853 * A parameter was NULL, the image format is unsupported, etc. 854 */ 855 vpx_codec_err_t vpx_codec_encode(vpx_codec_ctx_t *ctx, 856 const vpx_image_t *img, 857 vpx_codec_pts_t pts, 858 ulong duration, 859 vpx_enc_frame_flags_t flags, 860 ulong deadline); 861 862 /*!\brief Set compressed data output buffer 863 * 864 * Sets the buffer that the codec should output the compressed data 865 * into. This call effectively sets the buffer pointer returned in the 866 * next VPX_CODEC_CX_FRAME_PKT packet. Subsequent packets will be 867 * appended into this buffer. The buffer is preserved across frames, 868 * so applications must periodically call this function after flushing 869 * the accumulated compressed data to disk or to the network to reset 870 * the pointer to the buffer's head. 871 * 872 * `pad_before` bytes will be skipped before writing the compressed 873 * data, and `pad_after` bytes will be appended to the packet. The size 874 * of the packet will be the sum of the size of the actual compressed 875 * data, pad_before, and pad_after. The padding bytes will be preserved 876 * (not overwritten). 877 * 878 * Note that calling this function does not guarantee that the returned 879 * compressed data will be placed into the specified buffer. In the 880 * event that the encoded data will not fit into the buffer provided, 881 * the returned packet \ref MAY point to an internal buffer, as it would 882 * if this call were never used. In this event, the output packet will 883 * NOT have any padding, and the application must free space and copy it 884 * to the proper place. This is of particular note in configurations 885 * that may output multiple packets for a single encoded frame (e.g., lagged 886 * encoding) or if the application does not reset the buffer periodically. 887 * 888 * Applications may restore the default behavior of the codec providing 889 * the compressed data buffer by calling this function with a NULL 890 * buffer. 891 * 892 * Applications \ref MUSTNOT call this function during iteration of 893 * vpx_codec_get_cx_data(). 894 * 895 * \param[in] ctx Pointer to this instance's context 896 * \param[in] buf Buffer to store compressed data into 897 * \param[in] pad_before Bytes to skip before writing compressed data 898 * \param[in] pad_after Bytes to skip after writing compressed data 899 * 900 * \retval #VPX_CODEC_OK 901 * The buffer was set successfully. 902 * \retval #VPX_CODEC_INVALID_PARAM 903 * A parameter was NULL, the image format is unsupported, etc. 904 */ 905 vpx_codec_err_t vpx_codec_set_cx_data_buf(vpx_codec_ctx_t *ctx, 906 const vpx_fixed_buf_t *buf, 907 uint pad_before, 908 uint pad_after); 909 910 911 /*!\brief Encoded data iterator 912 * 913 * Iterates over a list of data packets to be passed from the encoder to the 914 * application. The different kinds of packets available are enumerated in 915 * #vpx_codec_cx_pkt_kind. 916 * 917 * #VPX_CODEC_CX_FRAME_PKT packets should be passed to the application's 918 * muxer. Multiple compressed frames may be in the list. 919 * #VPX_CODEC_STATS_PKT packets should be appended to a global buffer. 920 * 921 * The application \ref MUST silently ignore any packet kinds that it does 922 * not recognize or support. 923 * 924 * The data buffers returned from this function are only guaranteed to be 925 * valid until the application makes another call to any vpx_codec_* function. 926 * 927 * \param[in] ctx Pointer to this instance's context 928 * \param[in,out] iter Iterator storage, initialized to NULL 929 * 930 * \return Returns a pointer to an output data packet (compressed frame data, 931 * two-pass statistics, etc.) or NULL to signal end-of-list. 932 * 933 */ 934 const vpx_codec_cx_pkt_t *vpx_codec_get_cx_data(vpx_codec_ctx_t *ctx, 935 vpx_codec_iter_t *iter); 936 937 938 /*!\brief Get Preview Frame 939 * 940 * Returns an image that can be used as a preview. Shows the image as it would 941 * exist at the decompressor. The application \ref MUST NOT write into this 942 * image buffer. 943 * 944 * \param[in] ctx Pointer to this instance's context 945 * 946 * \return Returns a pointer to a preview image, or NULL if no image is 947 * available. 948 * 949 */ 950 const vpx_image_t *vpx_codec_get_preview_frame(vpx_codec_ctx_t *ctx); 951 952 953 /*!@} - end defgroup encoder*/ 954 }