register_state_check.h: add compiler barrier
[platform/upstream/libvpx.git] / vpx / vp8cx.h
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 #ifndef VPX_VPX_VP8CX_H_
11 #define VPX_VPX_VP8CX_H_
12
13 /*!\defgroup vp8_encoder WebM VP8/VP9 Encoder
14  * \ingroup vp8
15  *
16  * @{
17  */
18 #include "./vp8.h"
19 #include "./vpx_encoder.h"
20 #include "./vpx_ext_ratectrl.h"
21
22 /*!\file
23  * \brief Provides definitions for using VP8 or VP9 encoder algorithm within the
24  *        vpx Codec Interface.
25  */
26
27 #ifdef __cplusplus
28 extern "C" {
29 #endif
30
31 /*!\name Algorithm interface for VP8
32  *
33  * This interface provides the capability to encode raw VP8 streams.
34  * @{
35  */
36 extern vpx_codec_iface_t vpx_codec_vp8_cx_algo;
37 extern vpx_codec_iface_t *vpx_codec_vp8_cx(void);
38 /*!@} - end algorithm interface member group*/
39
40 /*!\name Algorithm interface for VP9
41  *
42  * This interface provides the capability to encode raw VP9 streams.
43  * @{
44  */
45 extern vpx_codec_iface_t vpx_codec_vp9_cx_algo;
46 extern vpx_codec_iface_t *vpx_codec_vp9_cx(void);
47 /*!@} - end algorithm interface member group*/
48
49 /*
50  * Algorithm Flags
51  */
52
53 /*!\brief Don't reference the last frame
54  *
55  * When this flag is set, the encoder will not use the last frame as a
56  * predictor. When not set, the encoder will choose whether to use the
57  * last frame or not automatically.
58  */
59 #define VP8_EFLAG_NO_REF_LAST (1 << 16)
60
61 /*!\brief Don't reference the golden frame
62  *
63  * When this flag is set, the encoder will not use the golden frame as a
64  * predictor. When not set, the encoder will choose whether to use the
65  * golden frame or not automatically.
66  */
67 #define VP8_EFLAG_NO_REF_GF (1 << 17)
68
69 /*!\brief Don't reference the alternate reference frame
70  *
71  * When this flag is set, the encoder will not use the alt ref frame as a
72  * predictor. When not set, the encoder will choose whether to use the
73  * alt ref frame or not automatically.
74  */
75 #define VP8_EFLAG_NO_REF_ARF (1 << 21)
76
77 /*!\brief Don't update the last frame
78  *
79  * When this flag is set, the encoder will not update the last frame with
80  * the contents of the current frame.
81  */
82 #define VP8_EFLAG_NO_UPD_LAST (1 << 18)
83
84 /*!\brief Don't update the golden frame
85  *
86  * When this flag is set, the encoder will not update the golden frame with
87  * the contents of the current frame.
88  */
89 #define VP8_EFLAG_NO_UPD_GF (1 << 22)
90
91 /*!\brief Don't update the alternate reference frame
92  *
93  * When this flag is set, the encoder will not update the alt ref frame with
94  * the contents of the current frame.
95  */
96 #define VP8_EFLAG_NO_UPD_ARF (1 << 23)
97
98 /*!\brief Force golden frame update
99  *
100  * When this flag is set, the encoder copy the contents of the current frame
101  * to the golden frame buffer.
102  */
103 #define VP8_EFLAG_FORCE_GF (1 << 19)
104
105 /*!\brief Force alternate reference frame update
106  *
107  * When this flag is set, the encoder copy the contents of the current frame
108  * to the alternate reference frame buffer.
109  */
110 #define VP8_EFLAG_FORCE_ARF (1 << 24)
111
112 /*!\brief Disable entropy update
113  *
114  * When this flag is set, the encoder will not update its internal entropy
115  * model based on the entropy of this frame.
116  */
117 #define VP8_EFLAG_NO_UPD_ENTROPY (1 << 20)
118
119 /*!\brief VPx encoder control functions
120  *
121  * This set of macros define the control functions available for VPx
122  * encoder interface.
123  *
124  * \sa #vpx_codec_control
125  */
126 enum vp8e_enc_control_id {
127   /*!\brief Codec control function to pass an ROI map to encoder.
128    *
129    * Supported in codecs: VP8
130    */
131   VP8E_SET_ROI_MAP = 8,
132
133   /*!\brief Codec control function to pass an Active map to encoder.
134    *
135    * Supported in codecs: VP8, VP9
136    */
137   VP8E_SET_ACTIVEMAP,
138
139   /*!\brief Codec control function to set encoder scaling mode.
140    *
141    * Supported in codecs: VP8, VP9
142    */
143   VP8E_SET_SCALEMODE = 11,
144
145   /*!\brief Codec control function to set encoder internal speed settings.
146    *
147    * Changes in this value influences, among others, the encoder's selection
148    * of motion estimation methods. Values greater than 0 will increase encoder
149    * speed at the expense of quality.
150    *
151    * \note Valid range for VP8: -16..16
152    * \note Valid range for VP9: -9..9
153    *
154    * Supported in codecs: VP8, VP9
155    */
156   VP8E_SET_CPUUSED = 13,
157
158   /*!\brief Codec control function to enable automatic use of arf frames.
159    *
160    * \note Valid range for VP8: 0..1
161    * \note Valid range for VP9: 0..6
162    *
163    * Supported in codecs: VP8, VP9
164    */
165   VP8E_SET_ENABLEAUTOALTREF,
166
167   /*!\brief control function to set noise sensitivity
168    *
169    * 0: off, 1: OnYOnly, 2: OnYUV,
170    * 3: OnYUVAggressive, 4: Adaptive
171    *
172    * Supported in codecs: VP8
173    */
174   VP8E_SET_NOISE_SENSITIVITY,
175
176   /*!\brief Codec control function to set higher sharpness at the expense
177    * of a lower PSNR.
178    *
179    * \note Valid range: 0..7
180    *
181    * Supported in codecs: VP8, VP9
182    */
183   VP8E_SET_SHARPNESS,
184
185   /*!\brief Codec control function to set the threshold for MBs treated static.
186    *
187    * Supported in codecs: VP8, VP9
188    */
189   VP8E_SET_STATIC_THRESHOLD,
190
191   /*!\brief Codec control function to set the number of token partitions.
192    *
193    * Supported in codecs: VP8
194    */
195   VP8E_SET_TOKEN_PARTITIONS,
196
197   /*!\brief Codec control function to get last quantizer chosen by the encoder.
198    *
199    * Return value uses internal quantizer scale defined by the codec.
200    *
201    * Supported in codecs: VP8, VP9
202    */
203   VP8E_GET_LAST_QUANTIZER,
204
205   /*!\brief Codec control function to get last quantizer chosen by the encoder.
206    *
207    * Return value uses the 0..63 scale as used by the rc_*_quantizer config
208    * parameters.
209    *
210    * Supported in codecs: VP8, VP9
211    */
212   VP8E_GET_LAST_QUANTIZER_64,
213
214   /*!\brief Codec control function to set the max no of frames to create arf.
215    *
216    * Supported in codecs: VP8, VP9
217    */
218   VP8E_SET_ARNR_MAXFRAMES,
219
220   /*!\brief Codec control function to set the filter strength for the arf.
221    *
222    * Supported in codecs: VP8, VP9
223    */
224   VP8E_SET_ARNR_STRENGTH,
225
226   /*!\deprecated control function to set the filter type to use for the arf. */
227   VP8E_SET_ARNR_TYPE,
228
229   /*!\brief Codec control function to set visual tuning.
230    *
231    * Supported in codecs: VP8, VP9
232    */
233   VP8E_SET_TUNING,
234
235   /*!\brief Codec control function to set constrained / constant quality level.
236    *
237    * \attention For this value to be used vpx_codec_enc_cfg_t::rc_end_usage must
238    *            be set to #VPX_CQ or #VPX_Q
239    * \note Valid range: 0..63
240    *
241    * Supported in codecs: VP8, VP9
242    */
243   VP8E_SET_CQ_LEVEL,
244
245   /*!\brief Codec control function to set Max data rate for Intra frames.
246    *
247    * This value controls additional clamping on the maximum size of a
248    * keyframe. It is expressed as a percentage of the average
249    * per-frame bitrate, with the special (and default) value 0 meaning
250    * unlimited, or no additional clamping beyond the codec's built-in
251    * algorithm.
252    *
253    * For example, to allocate no more than 4.5 frames worth of bitrate
254    * to a keyframe, set this to 450.
255    *
256    * Supported in codecs: VP8, VP9
257    */
258   VP8E_SET_MAX_INTRA_BITRATE_PCT,
259
260   /*!\brief Codec control function to set reference and update frame flags.
261    *
262    *  Supported in codecs: VP8
263    */
264   VP8E_SET_FRAME_FLAGS,
265
266   /*!\brief Codec control function to set max data rate for Inter frames.
267    *
268    * This value controls additional clamping on the maximum size of an
269    * inter frame. It is expressed as a percentage of the average
270    * per-frame bitrate, with the special (and default) value 0 meaning
271    * unlimited, or no additional clamping beyond the codec's built-in
272    * algorithm.
273    *
274    * For example, to allow no more than 4.5 frames worth of bitrate
275    * to an inter frame, set this to 450.
276    *
277    * Supported in codecs: VP9
278    */
279   VP9E_SET_MAX_INTER_BITRATE_PCT,
280
281   /*!\brief Boost percentage for Golden Frame in CBR mode.
282    *
283    * This value controls the amount of boost given to Golden Frame in
284    * CBR mode. It is expressed as a percentage of the average
285    * per-frame bitrate, with the special (and default) value 0 meaning
286    * the feature is off, i.e., no golden frame boost in CBR mode and
287    * average bitrate target is used.
288    *
289    * For example, to allow 100% more bits, i.e, 2X, in a golden frame
290    * than average frame, set this to 100.
291    *
292    * Supported in codecs: VP9
293    */
294   VP9E_SET_GF_CBR_BOOST_PCT,
295
296   /*!\brief Codec control function to set the temporal layer id.
297    *
298    * For temporal scalability: this control allows the application to set the
299    * layer id for each frame to be encoded. Note that this control must be set
300    * for every frame prior to encoding. The usage of this control function
301    * supersedes the internal temporal pattern counter, which is now deprecated.
302    *
303    * Supported in codecs: VP8
304    */
305   VP8E_SET_TEMPORAL_LAYER_ID,
306
307   /*!\brief Codec control function to set encoder screen content mode.
308    *
309    * 0: off, 1: On, 2: On with more aggressive rate control.
310    *
311    * Supported in codecs: VP8
312    */
313   VP8E_SET_SCREEN_CONTENT_MODE,
314
315   /*!\brief Codec control function to set lossless encoding mode.
316    *
317    * VP9 can operate in lossless encoding mode, in which the bitstream
318    * produced will be able to decode and reconstruct a perfect copy of
319    * input source. This control function provides a mean to switch encoder
320    * into lossless coding mode(1) or normal coding mode(0) that may be lossy.
321    *                          0 = lossy coding mode
322    *                          1 = lossless coding mode
323    *
324    *  By default, encoder operates in normal coding mode (maybe lossy).
325    *
326    * Supported in codecs: VP9
327    */
328   VP9E_SET_LOSSLESS,
329
330   /*!\brief Codec control function to set number of tile columns.
331    *
332    * In encoding and decoding, VP9 allows an input image frame be partitioned
333    * into separated vertical tile columns, which can be encoded or decoded
334    * independently. This enables easy implementation of parallel encoding and
335    * decoding. This control requests the encoder to use column tiles in
336    * encoding an input frame, with number of tile columns (in Log2 unit) as
337    * the parameter:
338    *             0 = 1 tile column
339    *             1 = 2 tile columns
340    *             2 = 4 tile columns
341    *             .....
342    *             n = 2**n tile columns
343    * The requested tile columns will be capped by the encoder based on image
344    * size limitations (The minimum width of a tile column is 256 pixels, the
345    * maximum is 4096).
346    *
347    * By default, the value is 6, i.e., the maximum number of tiles supported by
348    * the resolution.
349    *
350    * Supported in codecs: VP9
351    */
352   VP9E_SET_TILE_COLUMNS,
353
354   /*!\brief Codec control function to set number of tile rows.
355    *
356    * In encoding and decoding, VP9 allows an input image frame be partitioned
357    * into separated horizontal tile rows. Tile rows are encoded or decoded
358    * sequentially. Even though encoding/decoding of later tile rows depends on
359    * earlier ones, this allows the encoder to output data packets for tile rows
360    * prior to completely processing all tile rows in a frame, thereby reducing
361    * the latency in processing between input and output. The parameter
362    * for this control describes the number of tile rows, which has a valid
363    * range [0, 2]:
364    *            0 = 1 tile row
365    *            1 = 2 tile rows
366    *            2 = 4 tile rows
367    *
368    * By default, the value is 0, i.e. one single row tile for entire image.
369    *
370    * Supported in codecs: VP9
371    */
372   VP9E_SET_TILE_ROWS,
373
374   /*!\brief Codec control function to enable frame parallel decoding feature.
375    *
376    * VP9 has a bitstream feature to reduce decoding dependency between frames
377    * by turning off backward update of probability context used in encoding
378    * and decoding. This allows staged parallel processing of more than one
379    * video frame in the decoder. This control function provides a means to
380    * turn this feature on or off for bitstreams produced by encoder.
381    *
382    * By default, this feature is on.
383    *
384    * Supported in codecs: VP9
385    */
386   VP9E_SET_FRAME_PARALLEL_DECODING,
387
388   /*!\brief Codec control function to set adaptive quantization mode.
389    *
390    * VP9 has a segment based feature that allows encoder to adaptively change
391    * quantization parameter for each segment within a frame to improve the
392    * subjective quality. This control makes encoder operate in one of the
393    * several AQ_modes supported.
394    *
395    * By default, encoder operates with AQ_Mode 0(adaptive quantization off).
396    *
397    * Supported in codecs: VP9
398    */
399   VP9E_SET_AQ_MODE,
400
401   /*!\brief Codec control function to enable/disable periodic Q boost.
402    *
403    * One VP9 encoder speed feature is to enable quality boost by lowering
404    * frame level Q periodically. This control function provides a mean to
405    * turn on/off this feature.
406    *               0 = off
407    *               1 = on
408    *
409    * By default, the encoder is allowed to use this feature for appropriate
410    * encoding modes.
411    *
412    * Supported in codecs: VP9
413    */
414   VP9E_SET_FRAME_PERIODIC_BOOST,
415
416   /*!\brief Codec control function to set noise sensitivity.
417    *
418    *  0: off, 1: On(YOnly), 2: For SVC only, on top two spatial layers(YOnly)
419    *
420    * Supported in codecs: VP9
421    */
422   VP9E_SET_NOISE_SENSITIVITY,
423
424   /*!\brief Codec control function to turn on/off SVC in encoder.
425    * \note Return value is VPX_CODEC_INVALID_PARAM if the encoder does not
426    *       support SVC in its current encoding mode
427    *  0: off, 1: on
428    *
429    * Supported in codecs: VP9
430    */
431   VP9E_SET_SVC,
432
433   /*!\brief Codec control function to pass an ROI map to encoder.
434    *
435    * Supported in codecs: VP9
436    */
437   VP9E_SET_ROI_MAP,
438
439   /*!\brief Codec control function to set parameters for SVC.
440    * \note Parameters contain min_q, max_q, scaling factor for each of the
441    *       SVC layers.
442    *
443    * Supported in codecs: VP9
444    */
445   VP9E_SET_SVC_PARAMETERS,
446
447   /*!\brief Codec control function to set svc layer for spatial and temporal.
448    * \note Valid ranges: 0..#vpx_codec_enc_cfg::ss_number_layers for spatial
449    *                     layer and 0..#vpx_codec_enc_cfg::ts_number_layers for
450    *                     temporal layer.
451    *
452    * Supported in codecs: VP9
453    */
454   VP9E_SET_SVC_LAYER_ID,
455
456   /*!\brief Codec control function to set content type.
457    * \note Valid parameter range:
458    *              VP9E_CONTENT_DEFAULT = Regular video content (Default)
459    *              VP9E_CONTENT_SCREEN  = Screen capture content
460    *              VP9E_CONTENT_FILM    = Film content: improves grain retention
461    *
462    * Supported in codecs: VP9
463    */
464   VP9E_SET_TUNE_CONTENT,
465
466   /*!\brief Codec control function to get svc layer ID.
467    * \note The layer ID returned is for the data packet from the registered
468    *       callback function.
469    *
470    * Supported in codecs: VP9
471    */
472   VP9E_GET_SVC_LAYER_ID,
473
474   /*!\brief Codec control function to register callback to get per layer packet.
475    * \note Parameter for this control function is a structure with a callback
476    *       function and a pointer to private data used by the callback.
477    *
478    * Supported in codecs: VP9
479    */
480   VP9E_REGISTER_CX_CALLBACK,
481
482   /*!\brief Codec control function to set color space info.
483    * \note Valid ranges: 0..7, default is "UNKNOWN".
484    *                     0 = UNKNOWN,
485    *                     1 = BT_601
486    *                     2 = BT_709
487    *                     3 = SMPTE_170
488    *                     4 = SMPTE_240
489    *                     5 = BT_2020
490    *                     6 = RESERVED
491    *                     7 = SRGB
492    *
493    * Supported in codecs: VP9
494    */
495   VP9E_SET_COLOR_SPACE,
496
497   /*!\brief Codec control function to set minimum interval between GF/ARF frames
498    *
499    * By default the value is set as 4.
500    *
501    * Supported in codecs: VP9
502    */
503   VP9E_SET_MIN_GF_INTERVAL,
504
505   /*!\brief Codec control function to set minimum interval between GF/ARF frames
506    *
507    * By default the value is set as 16.
508    *
509    * Supported in codecs: VP9
510    */
511   VP9E_SET_MAX_GF_INTERVAL,
512
513   /*!\brief Codec control function to get an Active map back from the encoder.
514    *
515    * Supported in codecs: VP9
516    */
517   VP9E_GET_ACTIVEMAP,
518
519   /*!\brief Codec control function to set color range bit.
520    * \note Valid ranges: 0..1, default is 0
521    *                     0 = Limited range (16..235 or HBD equivalent)
522    *                     1 = Full range (0..255 or HBD equivalent)
523    *
524    * Supported in codecs: VP9
525    */
526   VP9E_SET_COLOR_RANGE,
527
528   /*!\brief Codec control function to set the frame flags and buffer indices
529    * for spatial layers. The frame flags and buffer indices are set using the
530    * struct #vpx_svc_ref_frame_config defined below.
531    *
532    * Supported in codecs: VP9
533    */
534   VP9E_SET_SVC_REF_FRAME_CONFIG,
535
536   /*!\brief Codec control function to set intended rendering image size.
537    *
538    * By default, this is identical to the image size in pixels.
539    *
540    * Supported in codecs: VP9
541    */
542   VP9E_SET_RENDER_SIZE,
543
544   /*!\brief Codec control function to set target level.
545    *
546    * 255: off (default); 0: only keep level stats; 10: target for level 1.0;
547    * 11: target for level 1.1; ... 62: target for level 6.2
548    *
549    * Supported in codecs: VP9
550    */
551   VP9E_SET_TARGET_LEVEL,
552
553   /*!\brief Codec control function to set row level multi-threading.
554    *
555    * 0 : off, 1 : on
556    *
557    * Supported in codecs: VP9
558    */
559   VP9E_SET_ROW_MT,
560
561   /*!\brief Codec control function to get bitstream level.
562    *
563    * Supported in codecs: VP9
564    */
565   VP9E_GET_LEVEL,
566
567   /*!\brief Codec control function to enable/disable special mode for altref
568    *        adaptive quantization. You can use it with --aq-mode concurrently.
569    *
570    * Enable special adaptive quantization for altref frames based on their
571    * expected prediction quality for the future frames.
572    *
573    * Supported in codecs: VP9
574    */
575   VP9E_SET_ALT_REF_AQ,
576
577   /*!\brief Boost percentage for Golden Frame in CBR mode.
578    *
579    * This value controls the amount of boost given to Golden Frame in
580    * CBR mode. It is expressed as a percentage of the average
581    * per-frame bitrate, with the special (and default) value 0 meaning
582    * the feature is off, i.e., no golden frame boost in CBR mode and
583    * average bitrate target is used.
584    *
585    * For example, to allow 100% more bits, i.e, 2X, in a golden frame
586    * than average frame, set this to 100.
587    *
588    * Supported in codecs: VP8
589    */
590   VP8E_SET_GF_CBR_BOOST_PCT,
591
592   /*!\brief Codec control function to enable the extreme motion vector unit test
593    * in VP9. Please note that this is only used in motion vector unit test.
594    *
595    * 0 : off, 1 : MAX_EXTREME_MV, 2 : MIN_EXTREME_MV
596    *
597    * Supported in codecs: VP9
598    */
599   VP9E_ENABLE_MOTION_VECTOR_UNIT_TEST,
600
601   /*!\brief Codec control function to constrain the inter-layer prediction
602    * (prediction of lower spatial resolution) in VP9 SVC.
603    *
604    * 0 : inter-layer prediction on, 1 : off, 2 : off only on non-key frames
605    *
606    * Supported in codecs: VP9
607    */
608   VP9E_SET_SVC_INTER_LAYER_PRED,
609
610   /*!\brief Codec control function to set mode and thresholds for frame
611    *  dropping in SVC. Drop frame thresholds are set per-layer. Mode is set as:
612    * 0 : layer-dependent dropping, 1 : constrained dropping, current layer drop
613    * forces drop on all upper layers. Default mode is 0.
614    *
615    * Supported in codecs: VP9
616    */
617   VP9E_SET_SVC_FRAME_DROP_LAYER,
618
619   /*!\brief Codec control function to get the refresh and reference flags and
620    * the buffer indices, up to the last encoded spatial layer.
621    *
622    * Supported in codecs: VP9
623    */
624   VP9E_GET_SVC_REF_FRAME_CONFIG,
625
626   /*!\brief Codec control function to enable/disable use of golden reference as
627    * a second temporal reference for SVC. Only used when inter-layer prediction
628    * is disabled on INTER frames.
629    *
630    * 0: Off, 1: Enabled (default)
631    *
632    * Supported in codecs: VP9
633    */
634   VP9E_SET_SVC_GF_TEMPORAL_REF,
635
636   /*!\brief Codec control function to enable spatial layer sync frame, for any
637    * spatial layer. Enabling it for layer k means spatial layer k will disable
638    * all temporal prediction, but keep the inter-layer prediction. It will
639    * refresh any temporal reference buffer for that layer, and reset the
640    * temporal layer for the superframe to 0. Setting the layer sync for base
641    * spatial layer forces a key frame. Default is off (0) for all spatial
642    * layers. Spatial layer sync flag is reset to 0 after each encoded layer,
643    * so when control is invoked it is only used for the current superframe.
644    *
645    * 0: Off (default), 1: Enabled
646    *
647    * Supported in codecs: VP9
648    */
649   VP9E_SET_SVC_SPATIAL_LAYER_SYNC,
650
651   /*!\brief Codec control function to enable temporal dependency model.
652    *
653    * Vp9 allows the encoder to run temporal dependency model and use it to
654    * improve the compression performance. To enable, set this parameter to be
655    * 1. The default value is set to be 1.
656    */
657   VP9E_SET_TPL,
658
659   /*!\brief Codec control function to enable postencode frame drop.
660    *
661    * This will allow encoder to drop frame after it's encoded.
662    *
663    * 0: Off (default), 1: Enabled
664    *
665    * Supported in codecs: VP9
666    */
667   VP9E_SET_POSTENCODE_DROP,
668
669   /*!\brief Codec control function to set delta q for uv.
670    *
671    * Cap it at +/-15.
672    *
673    * Supported in codecs: VP9
674    */
675   VP9E_SET_DELTA_Q_UV,
676
677   /*!\brief Codec control function to disable increase Q on overshoot in CBR.
678    *
679    * 0: On (default), 1: Disable.
680    *
681    * Supported in codecs: VP9
682    */
683   VP9E_SET_DISABLE_OVERSHOOT_MAXQ_CBR,
684
685   /*!\brief Codec control function to disable loopfilter.
686    *
687    * 0: Loopfilter on all frames, 1: Disable on non reference frames.
688    * 2: Disable on all frames.
689    *
690    * Supported in codecs: VP9
691    */
692   VP9E_SET_DISABLE_LOOPFILTER,
693
694   /*!\brief Codec control function to enable external rate control library.
695    *
696    * args[0]: path of the rate control library
697    *
698    * args[1]: private config of the rate control library
699    *
700    * Supported in codecs: VP9
701    */
702   VP9E_SET_EXTERNAL_RATE_CONTROL,
703
704   /*!\brief Codec control to disable internal features in rate control.
705    *
706    * This will do 3 things, only for 1 pass:
707    *  - Turn off low motion computation
708    *  - Turn off gf update constraint on key frame frequency
709    *  - Turn off content mode for cyclic refresh
710    *
711    * With those, the rate control is expected to work exactly the same as the
712    * interface provided in ratectrl_rtc.cc/h
713    *
714    * Supported in codecs: VP9
715    */
716   VP9E_SET_RTC_EXTERNAL_RATECTRL,
717
718   /*!\brief Codec control function to get loopfilter level in the encoder.
719    *
720    * Supported in codecs: VP9
721    */
722   VP9E_GET_LOOPFILTER_LEVEL,
723
724   /*!\brief Codec control to get last quantizers for all spatial layers.
725    *
726    * Return value uses an array of internal quantizers scale defined by the
727    * codec, for all spatial layers.
728    * The size of the array passed in should be #VPX_SS_MAX_LAYERS.
729    *
730    * Supported in codecs: VP9
731    */
732   VP9E_GET_LAST_QUANTIZER_SVC_LAYERS,
733
734   /*!\brief Codec control to disable internal features in rate control.
735    *
736    * This will turn off cyclic refresh for vp8.
737    *
738    * With this, the rate control is expected to work exactly the same as the
739    * interface provided in vp8_ratectrl_rtc.cc/h
740    *
741    * Supported in codecs: VP8
742    */
743   VP8E_SET_RTC_EXTERNAL_RATECTRL,
744 };
745
746 /*!\brief vpx 1-D scaling mode
747  *
748  * This set of constants define 1-D vpx scaling modes
749  */
750 typedef enum vpx_scaling_mode_1d {
751   VP8E_NORMAL = 0,
752   VP8E_FOURFIVE = 1,
753   VP8E_THREEFIVE = 2,
754   VP8E_ONETWO = 3
755 } VPX_SCALING_MODE;
756
757 /*!\brief Temporal layering mode enum for VP9 SVC.
758  *
759  * This set of macros define the different temporal layering modes.
760  * Supported codecs: VP9 (in SVC mode)
761  *
762  */
763 typedef enum vp9e_temporal_layering_mode {
764   /*!\brief No temporal layering.
765    * Used when only spatial layering is used.
766    */
767   VP9E_TEMPORAL_LAYERING_MODE_NOLAYERING = 0,
768
769   /*!\brief Bypass mode.
770    * Used when application needs to control temporal layering.
771    * This will only work when the number of spatial layers equals 1.
772    */
773   VP9E_TEMPORAL_LAYERING_MODE_BYPASS = 1,
774
775   /*!\brief 0-1-0-1... temporal layering scheme with two temporal layers.
776    */
777   VP9E_TEMPORAL_LAYERING_MODE_0101 = 2,
778
779   /*!\brief 0-2-1-2... temporal layering scheme with three temporal layers.
780    */
781   VP9E_TEMPORAL_LAYERING_MODE_0212 = 3
782 } VP9E_TEMPORAL_LAYERING_MODE;
783
784 /*!\brief  vpx region of interest map
785  *
786  * These defines the data structures for the region of interest map
787  *
788  */
789
790 typedef struct vpx_roi_map {
791   /*! If ROI is enabled. */
792   uint8_t enabled;
793   /*! An id between 0-3 (0-7 for vp9) for each 16x16 (8x8 for VP9)
794    * region within a frame. */
795   unsigned char *roi_map;
796   unsigned int rows; /**< Number of rows. */
797   unsigned int cols; /**< Number of columns. */
798   /*! VP8 only uses the first 4 segments. VP9 uses 8 segments. */
799   int delta_q[8];  /**< Quantizer deltas. Valid range: [-63, 63].*/
800   int delta_lf[8]; /**< Loop filter deltas. Valid range: [-63, 63].*/
801   /*! skip and ref frame segment is only used in VP9. */
802   int skip[8];      /**< Skip this block. */
803   int ref_frame[8]; /**< Reference frame for this block. */
804   /*! Static breakout threshold for each segment. Only used in VP8. */
805   unsigned int static_threshold[4];
806 } vpx_roi_map_t;
807
808 /*!\brief  vpx active region map
809  *
810  * These defines the data structures for active region map
811  *
812  */
813
814 typedef struct vpx_active_map {
815   /*!\brief specify an on (1) or off (0) each 16x16 region within a frame */
816   unsigned char *active_map;
817   unsigned int rows; /**< number of rows */
818   unsigned int cols; /**< number of cols */
819 } vpx_active_map_t;
820
821 /*!\brief  vpx image scaling mode
822  *
823  * This defines the data structure for image scaling mode
824  *
825  */
826 typedef struct vpx_scaling_mode {
827   VPX_SCALING_MODE h_scaling_mode; /**< horizontal scaling mode */
828   VPX_SCALING_MODE v_scaling_mode; /**< vertical scaling mode   */
829 } vpx_scaling_mode_t;
830
831 /*!\brief VP8 token partition mode
832  *
833  * This defines VP8 partitioning mode for compressed data, i.e., the number of
834  * sub-streams in the bitstream. Used for parallelized decoding.
835  *
836  */
837
838 typedef enum {
839   VP8_ONE_TOKENPARTITION = 0,
840   VP8_TWO_TOKENPARTITION = 1,
841   VP8_FOUR_TOKENPARTITION = 2,
842   VP8_EIGHT_TOKENPARTITION = 3
843 } vp8e_token_partitions;
844
845 /*!brief VP9 encoder content type */
846 typedef enum {
847   VP9E_CONTENT_DEFAULT,
848   VP9E_CONTENT_SCREEN,
849   VP9E_CONTENT_FILM,
850   VP9E_CONTENT_INVALID
851 } vp9e_tune_content;
852
853 /*!\brief VP8 model tuning parameters
854  *
855  * Changes the encoder to tune for certain types of input material.
856  *
857  */
858 typedef enum { VP8_TUNE_PSNR, VP8_TUNE_SSIM } vp8e_tuning;
859
860 /*!\brief  vp9 svc layer parameters
861  *
862  * This defines the spatial and temporal layer id numbers for svc encoding.
863  * This is used with the #VP9E_SET_SVC_LAYER_ID control to set the spatial and
864  * temporal layer id for the current frame.
865  *
866  */
867 typedef struct vpx_svc_layer_id {
868   int spatial_layer_id; /**< First spatial layer to start encoding. */
869   // TODO(jianj): Deprecated, to be removed.
870   int temporal_layer_id; /**< Temporal layer id number. */
871   int temporal_layer_id_per_spatial[VPX_SS_MAX_LAYERS]; /**< Temp layer id. */
872 } vpx_svc_layer_id_t;
873
874 /*!\brief vp9 svc frame flag parameters.
875  *
876  * This defines the frame flags and buffer indices for each spatial layer for
877  * svc encoding.
878  * This is used with the #VP9E_SET_SVC_REF_FRAME_CONFIG control to set frame
879  * flags and buffer indices for each spatial layer for the current (super)frame.
880  *
881  */
882 typedef struct vpx_svc_ref_frame_config {
883   int lst_fb_idx[VPX_SS_MAX_LAYERS];         /**< Last buffer index. */
884   int gld_fb_idx[VPX_SS_MAX_LAYERS];         /**< Golden buffer index. */
885   int alt_fb_idx[VPX_SS_MAX_LAYERS];         /**< Altref buffer index. */
886   int update_buffer_slot[VPX_SS_MAX_LAYERS]; /**< Update reference frames. */
887   // TODO(jianj): Remove update_last/golden/alt_ref, these are deprecated.
888   int update_last[VPX_SS_MAX_LAYERS];       /**< Update last. */
889   int update_golden[VPX_SS_MAX_LAYERS];     /**< Update golden. */
890   int update_alt_ref[VPX_SS_MAX_LAYERS];    /**< Update altref. */
891   int reference_last[VPX_SS_MAX_LAYERS];    /**< Last as reference. */
892   int reference_golden[VPX_SS_MAX_LAYERS];  /**< Golden as reference. */
893   int reference_alt_ref[VPX_SS_MAX_LAYERS]; /**< Altref as reference. */
894   int64_t duration[VPX_SS_MAX_LAYERS];      /**< Duration per spatial layer. */
895 } vpx_svc_ref_frame_config_t;
896
897 /*!\brief VP9 svc frame dropping mode.
898  *
899  * This defines the frame drop mode for SVC.
900  *
901  */
902 typedef enum {
903   CONSTRAINED_LAYER_DROP,
904   /**< Upper layers are constrained to drop if current layer drops. */
905   LAYER_DROP,           /**< Any spatial layer can drop. */
906   FULL_SUPERFRAME_DROP, /**< Only full superframe can drop. */
907   CONSTRAINED_FROM_ABOVE_DROP,
908   /**< Lower layers are constrained to drop if current layer drops. */
909 } SVC_LAYER_DROP_MODE;
910
911 /*!\brief vp9 svc frame dropping parameters.
912  *
913  * This defines the frame drop thresholds for each spatial layer, and
914  * the frame dropping mode: 0 = layer based frame dropping (default),
915  * 1 = constrained dropping where current layer drop forces all upper
916  * spatial layers to drop.
917  */
918 typedef struct vpx_svc_frame_drop {
919   int framedrop_thresh[VPX_SS_MAX_LAYERS]; /**< Frame drop thresholds */
920   SVC_LAYER_DROP_MODE
921   framedrop_mode;      /**< Layer-based or constrained dropping. */
922   int max_consec_drop; /**< Maximum consecutive drops, for any layer. */
923 } vpx_svc_frame_drop_t;
924
925 /*!\brief vp9 svc spatial layer sync parameters.
926  *
927  * This defines the spatial layer sync flag, defined per spatial layer.
928  *
929  */
930 typedef struct vpx_svc_spatial_layer_sync {
931   int spatial_layer_sync[VPX_SS_MAX_LAYERS]; /**< Sync layer flags */
932   int base_layer_intra_only; /**< Flag for setting Intra-only frame on base */
933 } vpx_svc_spatial_layer_sync_t;
934
935 /*!\cond */
936 /*!\brief VP8 encoder control function parameter type
937  *
938  * Defines the data types that VP8E control functions take. Note that
939  * additional common controls are defined in vp8.h
940  *
941  */
942
943 VPX_CTRL_USE_TYPE(VP8E_SET_ROI_MAP, vpx_roi_map_t *)
944 #define VPX_CTRL_VP8E_SET_ROI_MAP
945 VPX_CTRL_USE_TYPE(VP8E_SET_ACTIVEMAP, vpx_active_map_t *)
946 #define VPX_CTRL_VP8E_SET_ACTIVEMAP
947 VPX_CTRL_USE_TYPE(VP8E_SET_SCALEMODE, vpx_scaling_mode_t *)
948 #define VPX_CTRL_VP8E_SET_SCALEMODE
949 VPX_CTRL_USE_TYPE(VP8E_SET_CPUUSED, int)
950 #define VPX_CTRL_VP8E_SET_CPUUSED
951 VPX_CTRL_USE_TYPE(VP8E_SET_ENABLEAUTOALTREF, unsigned int)
952 #define VPX_CTRL_VP8E_SET_ENABLEAUTOALTREF
953 VPX_CTRL_USE_TYPE(VP8E_SET_NOISE_SENSITIVITY, unsigned int)
954 #define VPX_CTRL_VP8E_SET_NOISE_SENSITIVITY
955 VPX_CTRL_USE_TYPE(VP8E_SET_SHARPNESS, unsigned int)
956 #define VPX_CTRL_VP8E_SET_SHARPNESS
957 VPX_CTRL_USE_TYPE(VP8E_SET_STATIC_THRESHOLD, unsigned int)
958 #define VPX_CTRL_VP8E_SET_STATIC_THRESHOLD
959 VPX_CTRL_USE_TYPE(VP8E_SET_TOKEN_PARTITIONS, int) /* vp8e_token_partitions */
960 #define VPX_CTRL_VP8E_SET_TOKEN_PARTITIONS
961 VPX_CTRL_USE_TYPE(VP8E_GET_LAST_QUANTIZER, int *)
962 #define VPX_CTRL_VP8E_GET_LAST_QUANTIZER
963 VPX_CTRL_USE_TYPE(VP8E_GET_LAST_QUANTIZER_64, int *)
964 #define VPX_CTRL_VP8E_GET_LAST_QUANTIZER_64
965 VPX_CTRL_USE_TYPE(VP8E_SET_ARNR_MAXFRAMES, unsigned int)
966 #define VPX_CTRL_VP8E_SET_ARNR_MAXFRAMES
967 VPX_CTRL_USE_TYPE(VP8E_SET_ARNR_STRENGTH, unsigned int)
968 #define VPX_CTRL_VP8E_SET_ARNR_STRENGTH
969 VPX_CTRL_USE_TYPE_DEPRECATED(VP8E_SET_ARNR_TYPE, unsigned int)
970 #define VPX_CTRL_VP8E_SET_ARNR_TYPE
971 VPX_CTRL_USE_TYPE(VP8E_SET_TUNING, int) /* vp8e_tuning */
972 #define VPX_CTRL_VP8E_SET_TUNING
973 VPX_CTRL_USE_TYPE(VP8E_SET_CQ_LEVEL, unsigned int)
974 #define VPX_CTRL_VP8E_SET_CQ_LEVEL
975 VPX_CTRL_USE_TYPE(VP8E_SET_MAX_INTRA_BITRATE_PCT, unsigned int)
976 #define VPX_CTRL_VP8E_SET_MAX_INTRA_BITRATE_PCT
977 VPX_CTRL_USE_TYPE(VP8E_SET_FRAME_FLAGS, int)
978 #define VPX_CTRL_VP8E_SET_FRAME_FLAGS
979 VPX_CTRL_USE_TYPE(VP9E_SET_MAX_INTER_BITRATE_PCT, unsigned int)
980 #define VPX_CTRL_VP9E_SET_MAX_INTER_BITRATE_PCT
981 VPX_CTRL_USE_TYPE(VP9E_SET_GF_CBR_BOOST_PCT, unsigned int)
982 #define VPX_CTRL_VP9E_SET_GF_CBR_BOOST_PCT
983 VPX_CTRL_USE_TYPE(VP8E_SET_TEMPORAL_LAYER_ID, int)
984 #define VPX_CTRL_VP8E_SET_TEMPORAL_LAYER_ID
985 VPX_CTRL_USE_TYPE(VP8E_SET_SCREEN_CONTENT_MODE, unsigned int)
986 #define VPX_CTRL_VP8E_SET_SCREEN_CONTENT_MODE
987 VPX_CTRL_USE_TYPE(VP9E_SET_LOSSLESS, unsigned int)
988 #define VPX_CTRL_VP9E_SET_LOSSLESS
989 VPX_CTRL_USE_TYPE(VP9E_SET_TILE_COLUMNS, int)
990 #define VPX_CTRL_VP9E_SET_TILE_COLUMNS
991 VPX_CTRL_USE_TYPE(VP9E_SET_TILE_ROWS, int)
992 #define VPX_CTRL_VP9E_SET_TILE_ROWS
993 VPX_CTRL_USE_TYPE(VP9E_SET_FRAME_PARALLEL_DECODING, unsigned int)
994 #define VPX_CTRL_VP9E_SET_FRAME_PARALLEL_DECODING
995 VPX_CTRL_USE_TYPE(VP9E_SET_AQ_MODE, unsigned int)
996 #define VPX_CTRL_VP9E_SET_AQ_MODE
997 VPX_CTRL_USE_TYPE(VP9E_SET_FRAME_PERIODIC_BOOST, unsigned int)
998 #define VPX_CTRL_VP9E_SET_FRAME_PERIODIC_BOOST
999 VPX_CTRL_USE_TYPE(VP9E_SET_NOISE_SENSITIVITY, unsigned int)
1000 #define VPX_CTRL_VP9E_SET_NOISE_SENSITIVITY
1001 VPX_CTRL_USE_TYPE(VP9E_SET_SVC, int)
1002 #define VPX_CTRL_VP9E_SET_SVC
1003 VPX_CTRL_USE_TYPE(VP9E_SET_ROI_MAP, vpx_roi_map_t *)
1004 #define VPX_CTRL_VP9E_SET_ROI_MAP
1005 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_PARAMETERS, void *)
1006 #define VPX_CTRL_VP9E_SET_SVC_PARAMETERS
1007 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_LAYER_ID, vpx_svc_layer_id_t *)
1008 #define VPX_CTRL_VP9E_SET_SVC_LAYER_ID
1009 VPX_CTRL_USE_TYPE(VP9E_SET_TUNE_CONTENT, int) /* vp9e_tune_content */
1010 #define VPX_CTRL_VP9E_SET_TUNE_CONTENT
1011 VPX_CTRL_USE_TYPE(VP9E_GET_SVC_LAYER_ID, vpx_svc_layer_id_t *)
1012 #define VPX_CTRL_VP9E_GET_SVC_LAYER_ID
1013 VPX_CTRL_USE_TYPE(VP9E_REGISTER_CX_CALLBACK, void *)
1014 #define VPX_CTRL_VP9E_REGISTER_CX_CALLBACK
1015 VPX_CTRL_USE_TYPE(VP9E_SET_COLOR_SPACE, int)
1016 #define VPX_CTRL_VP9E_SET_COLOR_SPACE
1017 VPX_CTRL_USE_TYPE(VP9E_SET_MIN_GF_INTERVAL, unsigned int)
1018 #define VPX_CTRL_VP9E_SET_MIN_GF_INTERVAL
1019 VPX_CTRL_USE_TYPE(VP9E_SET_MAX_GF_INTERVAL, unsigned int)
1020 #define VPX_CTRL_VP9E_SET_MAX_GF_INTERVAL
1021 VPX_CTRL_USE_TYPE(VP9E_GET_ACTIVEMAP, vpx_active_map_t *)
1022 #define VPX_CTRL_VP9E_GET_ACTIVEMAP
1023 VPX_CTRL_USE_TYPE(VP9E_SET_COLOR_RANGE, int)
1024 #define VPX_CTRL_VP9E_SET_COLOR_RANGE
1025 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_REF_FRAME_CONFIG, vpx_svc_ref_frame_config_t *)
1026 #define VPX_CTRL_VP9E_SET_SVC_REF_FRAME_CONFIG
1027 VPX_CTRL_USE_TYPE(VP9E_SET_RENDER_SIZE, int *)
1028 #define VPX_CTRL_VP9E_SET_RENDER_SIZE
1029 VPX_CTRL_USE_TYPE(VP9E_SET_TARGET_LEVEL, unsigned int)
1030 #define VPX_CTRL_VP9E_SET_TARGET_LEVEL
1031 VPX_CTRL_USE_TYPE(VP9E_SET_ROW_MT, unsigned int)
1032 #define VPX_CTRL_VP9E_SET_ROW_MT
1033 VPX_CTRL_USE_TYPE(VP9E_GET_LEVEL, int *)
1034 #define VPX_CTRL_VP9E_GET_LEVEL
1035 VPX_CTRL_USE_TYPE(VP9E_SET_ALT_REF_AQ, int)
1036 #define VPX_CTRL_VP9E_SET_ALT_REF_AQ
1037 VPX_CTRL_USE_TYPE(VP8E_SET_GF_CBR_BOOST_PCT, unsigned int)
1038 #define VPX_CTRL_VP8E_SET_GF_CBR_BOOST_PCT
1039 VPX_CTRL_USE_TYPE(VP9E_ENABLE_MOTION_VECTOR_UNIT_TEST, unsigned int)
1040 #define VPX_CTRL_VP9E_ENABLE_MOTION_VECTOR_UNIT_TEST
1041 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_INTER_LAYER_PRED, unsigned int)
1042 #define VPX_CTRL_VP9E_SET_SVC_INTER_LAYER_PRED
1043 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_FRAME_DROP_LAYER, vpx_svc_frame_drop_t *)
1044 #define VPX_CTRL_VP9E_SET_SVC_FRAME_DROP_LAYER
1045 VPX_CTRL_USE_TYPE(VP9E_GET_SVC_REF_FRAME_CONFIG, vpx_svc_ref_frame_config_t *)
1046 #define VPX_CTRL_VP9E_GET_SVC_REF_FRAME_CONFIG
1047 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_GF_TEMPORAL_REF, unsigned int)
1048 #define VPX_CTRL_VP9E_SET_SVC_GF_TEMPORAL_REF
1049 VPX_CTRL_USE_TYPE(VP9E_SET_SVC_SPATIAL_LAYER_SYNC,
1050                   vpx_svc_spatial_layer_sync_t *)
1051 #define VPX_CTRL_VP9E_SET_SVC_SPATIAL_LAYER_SYNC
1052 VPX_CTRL_USE_TYPE(VP9E_SET_TPL, int)
1053 #define VPX_CTRL_VP9E_SET_TPL
1054 VPX_CTRL_USE_TYPE(VP9E_SET_POSTENCODE_DROP, unsigned int)
1055 #define VPX_CTRL_VP9E_SET_POSTENCODE_DROP
1056 VPX_CTRL_USE_TYPE(VP9E_SET_DELTA_Q_UV, int)
1057 #define VPX_CTRL_VP9E_SET_DELTA_Q_UV
1058 VPX_CTRL_USE_TYPE(VP9E_SET_DISABLE_OVERSHOOT_MAXQ_CBR, int)
1059 #define VPX_CTRL_VP9E_SET_DISABLE_OVERSHOOT_MAXQ_CBR
1060 VPX_CTRL_USE_TYPE(VP9E_SET_DISABLE_LOOPFILTER, int)
1061 #define VPX_CTRL_VP9E_SET_DISABLE_LOOPFILTER
1062 VPX_CTRL_USE_TYPE(VP9E_SET_EXTERNAL_RATE_CONTROL, vpx_rc_funcs_t *)
1063 #define VPX_CTRL_VP9E_SET_EXTERNAL_RATE_CONTROL
1064 VPX_CTRL_USE_TYPE(VP9E_SET_RTC_EXTERNAL_RATECTRL, int)
1065 #define VPX_CTRL_VP9E_SET_RTC_EXTERNAL_RATECTRL
1066 VPX_CTRL_USE_TYPE(VP9E_GET_LOOPFILTER_LEVEL, int *)
1067 #define VPX_CTRL_VP9E_GET_LOOPFILTER_LEVEL
1068 VPX_CTRL_USE_TYPE(VP9E_GET_LAST_QUANTIZER_SVC_LAYERS, int *)
1069 #define VPX_CTRL_VP9E_GET_LAST_QUANTIZER_SVC_LAYERS
1070 VPX_CTRL_USE_TYPE(VP8E_SET_RTC_EXTERNAL_RATECTRL, int)
1071 #define VPX_CTRL_VP8E_SET_RTC_EXTERNAL_RATECTRL
1072
1073 /*!\endcond */
1074 /*! @} - end defgroup vp8_encoder */
1075 #ifdef __cplusplus
1076 }  // extern "C"
1077 #endif
1078
1079 #endif  // VPX_VPX_VP8CX_H_