aomcx.h 26.6 KB
Newer Older
John Koleszar's avatar
John Koleszar committed
1
/*
Yaowu Xu's avatar
Yaowu Xu committed
2
 * Copyright (c) 2016, Alliance for Open Media. All rights reserved
John Koleszar's avatar
John Koleszar committed
3
 *
Yaowu Xu's avatar
Yaowu Xu committed
4
5
6
7
8
9
 * This source code is subject to the terms of the BSD 2 Clause License and
 * the Alliance for Open Media Patent License 1.0. If the BSD 2 Clause License
 * was not distributed with this source code in the LICENSE file, you can
 * obtain it at www.aomedia.org/license/software. If the Alliance for Open
 * Media Patent License 1.0 was not distributed with this source code in the
 * PATENTS file, you can obtain it at www.aomedia.org/license/patent.
John Koleszar's avatar
John Koleszar committed
10
 */
Yaowu Xu's avatar
Yaowu Xu committed
11
12
#ifndef AOM_AOMCX_H_
#define AOM_AOMCX_H_
John Koleszar's avatar
John Koleszar committed
13

Yaowu Xu's avatar
Yaowu Xu committed
14
15
/*!\defgroup aom_encoder AOMedia AOM/AV1 Encoder
 * \ingroup aom
John Koleszar's avatar
John Koleszar committed
16
17
18
 *
 * @{
 */
Yaowu Xu's avatar
Yaowu Xu committed
19
20
#include "./aom.h"
#include "./aom_encoder.h"
John Koleszar's avatar
John Koleszar committed
21

James Zern's avatar
James Zern committed
22
/*!\file
Yaowu Xu's avatar
Yaowu Xu committed
23
 * \brief Provides definitions for using AOM or AV1 encoder algorithm within the
Yaowu Xu's avatar
Yaowu Xu committed
24
 *        aom Codec Interface.
John Koleszar's avatar
John Koleszar committed
25
 */
26
27
28
29

#ifdef __cplusplus
extern "C" {
#endif
John Koleszar's avatar
John Koleszar committed
30

Yaowu Xu's avatar
Yaowu Xu committed
31
/*!\name Algorithm interface for AV1
Jingning Han's avatar
Jingning Han committed
32
 *
Yaowu Xu's avatar
Yaowu Xu committed
33
 * This interface provides the capability to encode raw AV1 streams.
Jingning Han's avatar
Jingning Han committed
34
35
 * @{
 */
Yaowu Xu's avatar
Yaowu Xu committed
36
37
extern aom_codec_iface_t aom_codec_av1_cx_algo;
extern aom_codec_iface_t *aom_codec_av1_cx(void);
Jingning Han's avatar
Jingning Han committed
38
/*!@} - end algorithm interface member group*/
39

John Koleszar's avatar
John Koleszar committed
40
41
42
43
44
45
46
47
48
49
/*
 * Algorithm Flags
 */

/*!\brief Don't reference the last frame
 *
 * When this flag is set, the encoder will not use the last frame as a
 * predictor. When not set, the encoder will choose whether to use the
 * last frame or not automatically.
 */
Yaowu Xu's avatar
Yaowu Xu committed
50
#define AOM_EFLAG_NO_REF_LAST (1 << 16)
John Koleszar's avatar
John Koleszar committed
51
52
53
54
55
56
57

/*!\brief Don't reference the golden frame
 *
 * When this flag is set, the encoder will not use the golden frame as a
 * predictor. When not set, the encoder will choose whether to use the
 * golden frame or not automatically.
 */
Yaowu Xu's avatar
Yaowu Xu committed
58
#define AOM_EFLAG_NO_REF_GF (1 << 17)
John Koleszar's avatar
John Koleszar committed
59
60
61
62
63
64
65

/*!\brief Don't reference the alternate reference frame
 *
 * When this flag is set, the encoder will not use the alt ref frame as a
 * predictor. When not set, the encoder will choose whether to use the
 * alt ref frame or not automatically.
 */
Yaowu Xu's avatar
Yaowu Xu committed
66
#define AOM_EFLAG_NO_REF_ARF (1 << 21)
John Koleszar's avatar
John Koleszar committed
67
68
69
70
71
72

/*!\brief Don't update the last frame
 *
 * When this flag is set, the encoder will not update the last frame with
 * the contents of the current frame.
 */
Yaowu Xu's avatar
Yaowu Xu committed
73
#define AOM_EFLAG_NO_UPD_LAST (1 << 18)
John Koleszar's avatar
John Koleszar committed
74
75
76
77
78
79

/*!\brief Don't update the golden frame
 *
 * When this flag is set, the encoder will not update the golden frame with
 * the contents of the current frame.
 */
Yaowu Xu's avatar
Yaowu Xu committed
80
#define AOM_EFLAG_NO_UPD_GF (1 << 22)
John Koleszar's avatar
John Koleszar committed
81
82
83
84
85
86

/*!\brief Don't update the alternate reference frame
 *
 * When this flag is set, the encoder will not update the alt ref frame with
 * the contents of the current frame.
 */
Yaowu Xu's avatar
Yaowu Xu committed
87
#define AOM_EFLAG_NO_UPD_ARF (1 << 23)
John Koleszar's avatar
John Koleszar committed
88
89
90
91
92
93

/*!\brief Force golden frame update
 *
 * When this flag is set, the encoder copy the contents of the current frame
 * to the golden frame buffer.
 */
Yaowu Xu's avatar
Yaowu Xu committed
94
#define AOM_EFLAG_FORCE_GF (1 << 19)
John Koleszar's avatar
John Koleszar committed
95
96
97
98
99
100

/*!\brief Force alternate reference frame update
 *
 * When this flag is set, the encoder copy the contents of the current frame
 * to the alternate reference frame buffer.
 */
Yaowu Xu's avatar
Yaowu Xu committed
101
#define AOM_EFLAG_FORCE_ARF (1 << 24)
John Koleszar's avatar
John Koleszar committed
102
103
104
105
106
107

/*!\brief Disable entropy update
 *
 * When this flag is set, the encoder will not update its internal entropy
 * model based on the entropy of this frame.
 */
Yaowu Xu's avatar
Yaowu Xu committed
108
#define AOM_EFLAG_NO_UPD_ENTROPY (1 << 20)
John Koleszar's avatar
John Koleszar committed
109

Yaowu Xu's avatar
Yaowu Xu committed
110
/*!\brief AVx encoder control functions
John Koleszar's avatar
John Koleszar committed
111
 *
Yaowu Xu's avatar
Yaowu Xu committed
112
 * This set of macros define the control functions available for AVx
113
114
 * encoder interface.
 *
Yaowu Xu's avatar
Yaowu Xu committed
115
 * \sa #aom_codec_control
John Koleszar's avatar
John Koleszar committed
116
 */
Yaowu Xu's avatar
Yaowu Xu committed
117
enum aome_enc_control_id {
Yunqing Wang's avatar
Yunqing Wang committed
118
119
  /*!\brief Codec control function to set which reference frame encoder can use.
   */
Yaowu Xu's avatar
Yaowu Xu committed
120
  AOME_USE_REFERENCE = 7,
Yunqing Wang's avatar
Yunqing Wang committed
121

122
123
  /*!\brief Codec control function to pass an ROI map to encoder.
   */
Yaowu Xu's avatar
Yaowu Xu committed
124
  AOME_SET_ROI_MAP = 8,
125
126
127

  /*!\brief Codec control function to pass an Active map to encoder.
   */
Yaowu Xu's avatar
Yaowu Xu committed
128
  AOME_SET_ACTIVEMAP,
129
130
131

  /*!\brief Codec control function to set encoder scaling mode.
   */
Yaowu Xu's avatar
Yaowu Xu committed
132
  AOME_SET_SCALEMODE = 11,
133
134

  /*!\brief Codec control function to set encoder internal speed settings.
John Koleszar's avatar
John Koleszar committed
135
136
137
138
139
   *
   * Changes in this value influences, among others, the encoder's selection
   * of motion estimation methods. Values greater than 0 will increase encoder
   * speed at the expense of quality.
   *
140
   * \note Valid range: 0..8
John Koleszar's avatar
John Koleszar committed
141
   */
Yaowu Xu's avatar
Yaowu Xu committed
142
  AOME_SET_CPUUSED = 13,
143
144
145

  /*!\brief Codec control function to enable automatic set and use alf frames.
   */
Yaowu Xu's avatar
Yaowu Xu committed
146
  AOME_SET_ENABLEAUTOALTREF,
147
148
149

  /*!\brief Codec control function to set sharpness.
   */
150
  AOME_SET_SHARPNESS = AOME_SET_ENABLEAUTOALTREF + 2,
151
152
153

  /*!\brief Codec control function to set the threshold for MBs treated static.
   */
Yaowu Xu's avatar
Yaowu Xu committed
154
  AOME_SET_STATIC_THRESHOLD,
155
156
157
158
159

  /*!\brief Codec control function to get last quantizer chosen by the encoder.
   *
   * Return value uses internal quantizer scale defined by the codec.
   */
160
  AOME_GET_LAST_QUANTIZER = AOME_SET_STATIC_THRESHOLD + 2,
161
162
163
164
165
166

  /*!\brief Codec control function to get last quantizer chosen by the encoder.
   *
   * Return value uses the 0..63 scale as used by the rc_*_quantizer config
   * parameters.
   */
Yaowu Xu's avatar
Yaowu Xu committed
167
  AOME_GET_LAST_QUANTIZER_64,
168
169
170

  /*!\brief Codec control function to set the max no of frames to create arf.
   */
Yaowu Xu's avatar
Yaowu Xu committed
171
  AOME_SET_ARNR_MAXFRAMES,
172
173
174

  /*!\brief Codec control function to set the filter strength for the arf.
   */
Yaowu Xu's avatar
Yaowu Xu committed
175
  AOME_SET_ARNR_STRENGTH,
176
177
178

  /*!\brief Codec control function to set visual tuning.
   */
179
  AOME_SET_TUNING = AOME_SET_ARNR_STRENGTH + 2,
180
181

  /*!\brief Codec control function to set constrained quality level.
John Koleszar's avatar
John Koleszar committed
182
   *
Yaowu Xu's avatar
Yaowu Xu committed
183
184
   * \attention For this value to be used aom_codec_enc_cfg_t::g_usage must be
   *            set to #AOM_CQ.
John Koleszar's avatar
John Koleszar committed
185
186
   * \note Valid range: 0..63
   */
Yaowu Xu's avatar
Yaowu Xu committed
187
  AOME_SET_CQ_LEVEL,
John Koleszar's avatar
John Koleszar committed
188

189
  /*!\brief Codec control function to set Max data rate for Intra frames.
John Koleszar's avatar
John Koleszar committed
190
191
192
193
194
195
196
197
198
199
   *
   * This value controls additional clamping on the maximum size of a
   * keyframe. It is expressed as a percentage of the average
   * per-frame bitrate, with the special (and default) value 0 meaning
   * unlimited, or no additional clamping beyond the codec's built-in
   * algorithm.
   *
   * For example, to allocate no more than 4.5 frames worth of bitrate
   * to a keyframe, set this to 450.
   */
Yaowu Xu's avatar
Yaowu Xu committed
200
  AOME_SET_MAX_INTRA_BITRATE_PCT,
John Koleszar's avatar
John Koleszar committed
201

202
  /*!\brief Codec control function to set max data rate for Inter frames.
203
204
205
206
207
208
209
210
211
212
   *
   * This value controls additional clamping on the maximum size of an
   * inter frame. It is expressed as a percentage of the average
   * per-frame bitrate, with the special (and default) value 0 meaning
   * unlimited, or no additional clamping beyond the codec's built-in
   * algorithm.
   *
   * For example, to allow no more than 4.5 frames worth of bitrate
   * to an inter frame, set this to 450.
   */
213
  AV1E_SET_MAX_INTER_BITRATE_PCT = AOME_SET_MAX_INTRA_BITRATE_PCT + 2,
214

215
  /*!\brief Boost percentage for Golden Frame in CBR mode.
216
217
218
219
220
221
222
223
224
225
   *
   * This value controls the amount of boost given to Golden Frame in
   * CBR mode. It is expressed as a percentage of the average
   * per-frame bitrate, with the special (and default) value 0 meaning
   * the feature is off, i.e., no golden frame boost in CBR mode and
   * average bitrate target is used.
   *
   * For example, to allow 100% more bits, i.e, 2X, in a golden frame
   * than average frame, set this to 100.
   */
Yaowu Xu's avatar
Yaowu Xu committed
226
  AV1E_SET_GF_CBR_BOOST_PCT,
John Koleszar's avatar
John Koleszar committed
227

228
  /*!\brief Codec control function to set lossless encoding mode.
Yaowu Xu's avatar
Yaowu Xu committed
229
   *
Yaowu Xu's avatar
Yaowu Xu committed
230
   * AV1 can operate in lossless encoding mode, in which the bitstream
Yaowu Xu's avatar
Yaowu Xu committed
231
232
233
234
235
236
237
238
   * produced will be able to decode and reconstruct a perfect copy of
   * input source. This control function provides a mean to switch encoder
   * into lossless coding mode(1) or normal coding mode(0) that may be lossy.
   *                          0 = lossy coding mode
   *                          1 = lossless coding mode
   *
   *  By default, encoder operates in normal coding mode (maybe lossy).
   */
239
  AV1E_SET_LOSSLESS = AV1E_SET_GF_CBR_BOOST_PCT + 2,
240

241
  /*!\brief Codec control function to set number of tile columns.
Yaowu Xu's avatar
Yaowu Xu committed
242
   *
Yaowu Xu's avatar
Yaowu Xu committed
243
   * In encoding and decoding, AV1 allows an input image frame be partitioned
Yaowu Xu's avatar
Yaowu Xu committed
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
   * into separated vertical tile columns, which can be encoded or decoded
   * independently. This enables easy implementation of parallel encoding and
   * decoding. This control requests the encoder to use column tiles in
   * encoding an input frame, with number of tile columns (in Log2 unit) as
   * the parameter:
   *             0 = 1 tile column
   *             1 = 2 tile columns
   *             2 = 4 tile columns
   *             .....
   *             n = 2**n tile columns
   * The requested tile columns will be capped by encoder based on image size
   * limitation (The minimum width of a tile column is 256 pixel, the maximum
   * is 4096).
   *
   * By default, the value is 0, i.e. one single column tile for entire image.
   */
Yaowu Xu's avatar
Yaowu Xu committed
260
  AV1E_SET_TILE_COLUMNS,
Yaowu Xu's avatar
Yaowu Xu committed
261

262
  /*!\brief Codec control function to set number of tile rows.
Yaowu Xu's avatar
Yaowu Xu committed
263
   *
Yaowu Xu's avatar
Yaowu Xu committed
264
   * In encoding and decoding, AV1 allows an input image frame be partitioned
Yaowu Xu's avatar
Yaowu Xu committed
265
266
267
268
269
270
271
272
273
274
275
276
277
   * into separated horizontal tile rows. Tile rows are encoded or decoded
   * sequentially. Even though encoding/decoding of later tile rows depends on
   * earlier ones, this allows the encoder to output data packets for tile rows
   * prior to completely processing all tile rows in a frame, thereby reducing
   * the latency in processing between input and output. The parameter
   * for this control describes the number of tile rows, which has a valid
   * range [0, 2]:
   *            0 = 1 tile row
   *            1 = 2 tile rows
   *            2 = 4 tile rows
   *
   * By default, the value is 0, i.e. one single row tile for entire image.
   */
Yaowu Xu's avatar
Yaowu Xu committed
278
  AV1E_SET_TILE_ROWS,
279

280
  /*!\brief Codec control function to enable frame parallel decoding feature.
Yaowu Xu's avatar
Yaowu Xu committed
281
   *
Yaowu Xu's avatar
Yaowu Xu committed
282
   * AV1 has a bitstream feature to reduce decoding dependency between frames
Yaowu Xu's avatar
Yaowu Xu committed
283
284
285
286
287
288
289
   * by turning off backward update of probability context used in encoding
   * and decoding. This allows staged parallel processing of more than one
   * video frames in the decoder. This control function provides a mean to
   * turn this feature on or off for bitstreams produced by encoder.
   *
   * By default, this feature is off.
   */
Yaowu Xu's avatar
Yaowu Xu committed
290
  AV1E_SET_FRAME_PARALLEL_DECODING,
Yaowu Xu's avatar
Yaowu Xu committed
291

292
  /*!\brief Codec control function to set adaptive quantization mode.
Yaowu Xu's avatar
Yaowu Xu committed
293
   *
Yaowu Xu's avatar
Yaowu Xu committed
294
   * AV1 has a segment based feature that allows encoder to adaptively change
Yaowu Xu's avatar
Yaowu Xu committed
295
296
297
298
299
300
   * quantization parameter for each segment within a frame to improve the
   * subjective quality. This control makes encoder operate in one of the
   * several AQ_modes supported.
   *
   * By default, encoder operates with AQ_Mode 0(adaptive quantization off).
   */
Yaowu Xu's avatar
Yaowu Xu committed
301
  AV1E_SET_AQ_MODE,
302

303
  /*!\brief Codec control function to enable/disable periodic Q boost.
304
   *
Yaowu Xu's avatar
Yaowu Xu committed
305
   * One AV1 encoder speed feature is to enable quality boost by lowering
306
307
308
309
310
311
312
313
   * frame level Q periodically. This control function provides a mean to
   * turn on/off this feature.
   *               0 = off
   *               1 = on
   *
   * By default, the encoder is allowed to use this feature for appropriate
   * encoding modes.
   */
Yaowu Xu's avatar
Yaowu Xu committed
314
  AV1E_SET_FRAME_PERIODIC_BOOST,
315

316
  /*!\brief Codec control function to set noise sensitivity.
317
   *
318
   *  0: off, 1: On(YOnly)
319
   */
Yaowu Xu's avatar
Yaowu Xu committed
320
  AV1E_SET_NOISE_SENSITIVITY,
321

322
  /*!\brief Codec control function to set content type.
323
   * \note Valid parameter range:
Yaowu Xu's avatar
Yaowu Xu committed
324
325
   *              AOM_CONTENT_DEFAULT = Regular video content (Default)
   *              AOM_CONTENT_SCREEN  = Screen capture content
326
   */
Yaowu Xu's avatar
Yaowu Xu committed
327
  AV1E_SET_TUNE_CONTENT,
328

329
  /*!\brief Codec control function to set color space info.
330
   * \note Valid ranges: 0..9, default is "UNKNOWN".
331
332
333
334
335
   *                     0 = UNKNOWN,
   *                     1 = BT_601
   *                     2 = BT_709
   *                     3 = SMPTE_170
   *                     4 = SMPTE_240
336
337
   *                     5 = BT_2020_NCL
   *                     6 = BT_2020_CL
338
   *                     7 = SRGB
339
340
   *                     8 = ICtCp
   *                     9 = RESERVED
341
   */
Yaowu Xu's avatar
Yaowu Xu committed
342
  AV1E_SET_COLOR_SPACE,
343

344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
  /*!\brief Codec control function to set transfer function info.
   * \note Valid ranges: 0..4, default is "UNKNOWN".
   *                     0 = UNKNOWN,
   *                     1 = BT_709
   *                     2 = PQ
   *                     3 = HLG
   *                     4 = RESERVED
   */
  AV1E_SET_TRANSFER_FUNCTION,

  /*!\brief Codec control function to set chroma 4:2:0 sample position info.
   * \note Valid ranges: 0..3, default is "UNKNOWN".
   *                     0 = UNKNOWN,
   *                     1 = VERTICAL
   *                     2 = COLOCATED
   *                     3 = RESERVED
   */
  AV1E_SET_CHROMA_SAMPLE_POSITION,

363
364
365
366
  /*!\brief Codec control function to set minimum interval between GF/ARF frames
   *
   * By default the value is set as 4.
   */
Yaowu Xu's avatar
Yaowu Xu committed
367
  AV1E_SET_MIN_GF_INTERVAL,
368
369
370
371
372

  /*!\brief Codec control function to set minimum interval between GF/ARF frames
   *
   * By default the value is set as 16.
   */
Yaowu Xu's avatar
Yaowu Xu committed
373
  AV1E_SET_MAX_GF_INTERVAL,
374

375
376
  /*!\brief Codec control function to get an Active map back from the encoder.
   */
Yaowu Xu's avatar
Yaowu Xu committed
377
  AV1E_GET_ACTIVEMAP,
378
379
380
381
382
383

  /*!\brief Codec control function to set color range bit.
   * \note Valid ranges: 0..1, default is 0
   *                     0 = Limited range (16..235 or HBD equivalent)
   *                     1 = Full range (0..255 or HBD equivalent)
   */
Yaowu Xu's avatar
Yaowu Xu committed
384
  AV1E_SET_COLOR_RANGE,
385
386
387
388
389

  /*!\brief Codec control function to set intended rendering image size.
   *
   * By default, this is identical to the image size in pixels.
   */
Yaowu Xu's avatar
Yaowu Xu committed
390
  AV1E_SET_RENDER_SIZE,
391

392
393
394
395
396
  /*!\brief Codec control function to set target level.
   *
   * 255: off (default); 0: only keep level stats; 10: target for level 1.0;
   * 11: target for level 1.1; ... 62: target for level 6.2
   */
Yaowu Xu's avatar
Yaowu Xu committed
397
  AV1E_SET_TARGET_LEVEL,
398
399
400

  /*!\brief Codec control function to get bitstream level.
   */
Yaowu Xu's avatar
Yaowu Xu committed
401
  AV1E_GET_LEVEL,
402

403
404
405
406
  /*!\brief Codec control function to set intended superblock size.
   *
   * By default, the superblock size is determined separately for each
   * frame by the encoder.
407
408
   *
   * Experiment: EXT_PARTITION
409
   */
Yaowu Xu's avatar
Yaowu Xu committed
410
  AV1E_SET_SUPERBLOCK_SIZE,
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458

  /*!\brief Codec control function to enable automatic set and use
   * bwd-pred frames.
   *
   * Experiment: EXT_REFS
   */
  AOME_SET_ENABLEAUTOBWDREF,

  /*!\brief Codec control function to encode with quantisation matrices.
   *
   * AOM can operate with default quantisation matrices dependent on
   * quantisation level and block type.
   *                          0 = do not use quantisation matrices
   *                          1 = use quantisation matrices
   *
   *  By default, the encoder operates without quantisation matrices.
   *
   * Experiment: AOM_QM
   */
  AV1E_SET_ENABLE_QM,

  /*!\brief Codec control function to set the min quant matrix flatness.
   *
   * AOM can operate with different ranges of quantisation matrices.
   * As quantisation levels increase, the matrices get flatter. This
   * control sets the minimum level of flatness from which the matrices
   * are determined.
   *
   *  By default, the encoder sets this minimum at half the available
   *  range.
   *
   * Experiment: AOM_QM
   */
  AV1E_SET_QM_MIN,

  /*!\brief Codec control function to set the max quant matrix flatness.
   *
   * AOM can operate with different ranges of quantisation matrices.
   * As quantisation levels increase, the matrices get flatter. This
   * control sets the maximum level of flatness possible.
   *
   * By default, the encoder sets this maximum at the top of the
   * available range.
   *
   * Experiment: AOM_QM
   */
  AV1E_SET_QM_MAX,

459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
  /*!\brief Codec control function to encode with dist_8x8.
   *
   *  The dist_8x8 is enabled automatically for model tuning parameters that
   *  require measuring distortion at the 8x8 level. This control also allows
   *  measuring distortion at the 8x8 level for other tuning options
   *  (e.g., PSNR), for testing purposes.
   *                          0 = do not use dist_8x8
   *                          1 = use dist_8x8
   *
   *  By default, the encoder does not use dist_8x8
   *
   * Experiment: DIST_8X8
   */
  AV1E_SET_ENABLE_DIST_8X8,

474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
  /*!\brief Codec control function to set a maximum number of tile groups.
   *
   * This will set the maximum number of tile groups. This will be
   * overridden if an MTU size is set. The default value is 1.
   *
   * Experiment: TILE_GROUPS
   */
  AV1E_SET_NUM_TG,

  /*!\brief Codec control function to set an MTU size for a tile group.
   *
   * This will set the maximum number of bytes in a tile group. This can be
   * exceeded only if a single tile is larger than this amount.
   *
   * By default, the value is 0, in which case a fixed number of tile groups
   * is used.
   *
   * Experiment: TILE_GROUPS
   */
  AV1E_SET_MTU,
494

495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
  /*!\brief Codec control function to set tile_width.
   *
   * In encoding this sets expilcit tiles of the given tile width
   *
   * By default, the value is 0 and explicit tiles are disabled.
   *
   * Experiment: MAX_TILE
   */
  AV1E_SET_TILE_WIDTH,

  /*!\brief Codec control function to set tile_height.
   *
   * In encoding this sets expilcit tiles of the given tile height
   *
   * By default, the value is 0 and explicit tiles are disabled.
   *
   * Experiment: MAX_TILE
   */
  AV1E_SET_TILE_HEIGHT,

515
516
517
518
519
520
521
522
523
524
525
526
  /*!\brief Codec control function to set dependent_horz_tiles.
  *
  * In encoding and decoding, AV1 allows enabling dependent horizontal tile
  * The parameter for this control describes the value of this flag,
  * which has a valid range [0, 1]:
  *            0 = disable dependent horizontal tile
  *            1 = enable dependent horizontal tile,
  *
  * By default, the value is 0, i.e. disable dependent horizontal tile.
  */
  AV1E_SET_TILE_DEPENDENT_ROWS,

527
528
529
530
531
532
533
534
535
536
537
  /*!\brief Codec control function to set the number of symbols in an ANS data
   * window.
   *
   * The number of ANS symbols (both boolean and non-booleans alphabets) in an
   * ANS data window is set to 1 << value.
   *
   * \note Valid range: [8, 23]
   *
   * Experiment: ANS
   */
  AV1E_SET_ANS_WINDOW_SIZE_LOG2,
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560

  /*!\brief Codec control function to set temporal mv prediction
  * enabling/disabling.
  *
  * This will enable or disable temporal mv predicton. The default value is 0.
  *
  * Experiment: TEMPMV_SIGNALING
  */
  AV1E_SET_DISABLE_TEMPMV,

  /*!\brief Codec control function to set loop_filter_across_tiles_enabled.
   *
   * In encoding and decoding, AV1 allows disabling loop filter across tile
   * boundary The parameter for this control describes the value of this flag,
   * which has a valid range [0, 1]:
   *            0 = disable loop filter across tile boundary
   *            1 = enable loop filter across tile boundary
   *
   * By default, the value is 1, i.e. enable loop filter across tile boundary.
   *
   * Experiment: LOOPFILTERING_ACROSS_TILES
   */
  AV1E_SET_TILE_LOOPFILTER,
561

Fangwen Fu's avatar
Fangwen Fu committed
562
563
564
565
566
567
568
569
570
571
572
573
  /*!\brief Codec control function to set the delta q mode
  *
  * AV1 has a segment based feature that allows encoder to adaptively change
  * quantization parameter for each segment within a frame to improve the
  * subjective quality. the delta q mode is added on top of segment based
  * feature, and allows control per 64x64 q and lf delta.This control makes
  * encoder operate in one of the several DELTA_Q_modes supported.
  *
  * By default, encoder operates with DELTAQ_Mode 0(deltaq signaling off).
  */
  AV1E_SET_DELTAQ_MODE,

574
575
  /*!\brief Codec control function to set the single tile decoding mode to 0 or
   * 1.
576
   *
577
578
   * 0 means that the single tile decoding is off, and 1 means that the single
   * tile decoding is on.
579
580
581
   *
   * Experiment: EXT_TILE
   */
582
  AV1E_SET_SINGLE_TILE_DECODING,
Yunqing Wang's avatar
Yunqing Wang committed
583
584
585
586
587
588
589

  /*!\brief Codec control function to enable the extreme motion vector unit test
   * in AV1. Please note that this is only used in motion vector unit test.
   *
   * 0 : off, 1 : MAX_EXTREME_MV, 2 : MIN_EXTREME_MV
   */
  AV1E_ENABLE_MOTION_VECTOR_UNIT_TEST,
John Koleszar's avatar
John Koleszar committed
590
};
John Koleszar's avatar
John Koleszar committed
591

Yaowu Xu's avatar
Yaowu Xu committed
592
/*!\brief aom 1-D scaling mode
John Koleszar's avatar
John Koleszar committed
593
 *
Yaowu Xu's avatar
Yaowu Xu committed
594
 * This set of constants define 1-D aom scaling modes
John Koleszar's avatar
John Koleszar committed
595
 */
Yaowu Xu's avatar
Yaowu Xu committed
596
597
598
599
600
601
602
typedef enum aom_scaling_mode_1d {
  AOME_NORMAL = 0,
  AOME_FOURFIVE = 1,
  AOME_THREEFIVE = 2,
  AOME_ONETWO = 3
} AOM_SCALING_MODE;

603
604
605
606
607
608
609
610
611
/*!\brief Max number of segments
 *
 * This is the limit of number of segments allowed within a frame.
 *
 * Currently same as "MAX_SEGMENTS" in AV1, the maximum that AV1 supports.
 *
 */
#define AOM_MAX_SEGMENTS 8

Yaowu Xu's avatar
Yaowu Xu committed
612
/*!\brief  aom region of interest map
John Koleszar's avatar
John Koleszar committed
613
614
615
 *
 * These defines the data structures for the region of interest map
 *
616
617
 * TODO(yaowu): create a unit test for ROI map related APIs
 *
John Koleszar's avatar
John Koleszar committed
618
 */
Yaowu Xu's avatar
Yaowu Xu committed
619
typedef struct aom_roi_map {
620
  /*! An id between 0 and 7 for each 8x8 region within a frame. */
Adrian Grange's avatar
Adrian Grange committed
621
  unsigned char *roi_map;
622
623
624
625
  unsigned int rows;              /**< Number of rows. */
  unsigned int cols;              /**< Number of columns. */
  int delta_q[AOM_MAX_SEGMENTS];  /**< Quantizer deltas. */
  int delta_lf[AOM_MAX_SEGMENTS]; /**< Loop filter deltas. */
Adrian Grange's avatar
Adrian Grange committed
626
  /*! Static breakout threshold for each segment. */
627
  unsigned int static_threshold[AOM_MAX_SEGMENTS];
Yaowu Xu's avatar
Yaowu Xu committed
628
} aom_roi_map_t;
John Koleszar's avatar
John Koleszar committed
629

Yaowu Xu's avatar
Yaowu Xu committed
630
/*!\brief  aom active region map
John Koleszar's avatar
John Koleszar committed
631
632
633
634
635
 *
 * These defines the data structures for active region map
 *
 */

Yaowu Xu's avatar
Yaowu Xu committed
636
typedef struct aom_active_map {
clang-format's avatar
clang-format committed
637
638
639
640
  /*!\brief specify an on (1) or off (0) each 16x16 region within a frame */
  unsigned char *active_map;
  unsigned int rows; /**< number of rows */
  unsigned int cols; /**< number of cols */
Yaowu Xu's avatar
Yaowu Xu committed
641
} aom_active_map_t;
John Koleszar's avatar
John Koleszar committed
642

Yaowu Xu's avatar
Yaowu Xu committed
643
/*!\brief  aom image scaling mode
John Koleszar's avatar
John Koleszar committed
644
645
646
647
 *
 * This defines the data structure for image scaling mode
 *
 */
Yaowu Xu's avatar
Yaowu Xu committed
648
649
650
651
typedef struct aom_scaling_mode {
  AOM_SCALING_MODE h_scaling_mode; /**< horizontal scaling mode */
  AOM_SCALING_MODE v_scaling_mode; /**< vertical scaling mode   */
} aom_scaling_mode_t;
John Koleszar's avatar
John Koleszar committed
652

Yaowu Xu's avatar
Yaowu Xu committed
653
/*!brief AV1 encoder content type */
654
typedef enum {
Yaowu Xu's avatar
Yaowu Xu committed
655
656
657
658
  AOM_CONTENT_DEFAULT,
  AOM_CONTENT_SCREEN,
  AOM_CONTENT_INVALID
} aom_tune_content;
John Koleszar's avatar
John Koleszar committed
659

660
/*!\brief Model tuning parameters
John Koleszar's avatar
John Koleszar committed
661
662
663
664
 *
 * Changes the encoder to tune for certain types of input material.
 *
 */
665
666
667
668
669
670
671
672
typedef enum {
  AOM_TUNE_PSNR,
  AOM_TUNE_SSIM,
#ifdef CONFIG_DIST_8X8
  AOM_TUNE_CDEF_DIST,
  AOM_TUNE_DAALA_DIST
#endif
} aom_tune_metric;
John Koleszar's avatar
John Koleszar committed
673

674
/*!\cond */
675
/*!\brief Encoder control function parameter type
John Koleszar's avatar
John Koleszar committed
676
 *
677
 * Defines the data types that AOME/AV1E control functions take. Note that
Yaowu Xu's avatar
Yaowu Xu committed
678
 * additional common controls are defined in aom.h
John Koleszar's avatar
John Koleszar committed
679
680
681
 *
 */

682
AOM_CTRL_USE_TYPE(AOME_USE_REFERENCE, int)
Yaowu Xu's avatar
Yaowu Xu committed
683
684
685
686
687
688
689
690
691
692
693
694
#define AOM_CTRL_AOME_USE_REFERENCE
AOM_CTRL_USE_TYPE(AOME_SET_ROI_MAP, aom_roi_map_t *)
#define AOM_CTRL_AOME_SET_ROI_MAP
AOM_CTRL_USE_TYPE(AOME_SET_ACTIVEMAP, aom_active_map_t *)
#define AOM_CTRL_AOME_SET_ACTIVEMAP
AOM_CTRL_USE_TYPE(AOME_SET_SCALEMODE, aom_scaling_mode_t *)
#define AOM_CTRL_AOME_SET_SCALEMODE

AOM_CTRL_USE_TYPE(AOME_SET_CPUUSED, int)
#define AOM_CTRL_AOME_SET_CPUUSED
AOM_CTRL_USE_TYPE(AOME_SET_ENABLEAUTOALTREF, unsigned int)
#define AOM_CTRL_AOME_SET_ENABLEAUTOALTREF
695

Yaowu Xu's avatar
Yaowu Xu committed
696
697
AOM_CTRL_USE_TYPE(AOME_SET_ENABLEAUTOBWDREF, unsigned int)
#define AOM_CTRL_AOME_SET_ENABLEAUTOBWDREF
698

Yaowu Xu's avatar
Yaowu Xu committed
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
AOM_CTRL_USE_TYPE(AOME_SET_SHARPNESS, unsigned int)
#define AOM_CTRL_AOME_SET_SHARPNESS
AOM_CTRL_USE_TYPE(AOME_SET_STATIC_THRESHOLD, unsigned int)
#define AOM_CTRL_AOME_SET_STATIC_THRESHOLD

AOM_CTRL_USE_TYPE(AOME_SET_ARNR_MAXFRAMES, unsigned int)
#define AOM_CTRL_AOME_SET_ARNR_MAXFRAMES
AOM_CTRL_USE_TYPE(AOME_SET_ARNR_STRENGTH, unsigned int)
#define AOM_CTRL_AOME_SET_ARNR_STRENGTH
AOM_CTRL_USE_TYPE(AOME_SET_TUNING, int) /* aom_tune_metric */
#define AOM_CTRL_AOME_SET_TUNING
AOM_CTRL_USE_TYPE(AOME_SET_CQ_LEVEL, unsigned int)
#define AOM_CTRL_AOME_SET_CQ_LEVEL

AOM_CTRL_USE_TYPE(AV1E_SET_TILE_COLUMNS, int)
#define AOM_CTRL_AV1E_SET_TILE_COLUMNS
AOM_CTRL_USE_TYPE(AV1E_SET_TILE_ROWS, int)
#define AOM_CTRL_AV1E_SET_TILE_ROWS
717

718
719
720
721
722
AOM_CTRL_USE_TYPE(AV1E_SET_TILE_WIDTH, int)
#define AOM_CTRL_AV1E_SET_TILE_WIDTH
AOM_CTRL_USE_TYPE(AV1E_SET_TILE_HEIGHT, int)
#define AOM_CTRL_AV1E_SET_TILE_HEIGHT

723
724
725
AOM_CTRL_USE_TYPE(AV1E_SET_TILE_DEPENDENT_ROWS, int)
#define AOM_CTRL_AV1E_SET_TILE_DEPENDENT_ROWS

726
727
AOM_CTRL_USE_TYPE(AV1E_SET_TILE_LOOPFILTER, int)
#define AOM_CTRL_AV1E_SET_TILE_LOOPFILTER
Yaowu Xu's avatar
Yaowu Xu committed
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743

AOM_CTRL_USE_TYPE(AOME_GET_LAST_QUANTIZER, int *)
#define AOM_CTRL_AOME_GET_LAST_QUANTIZER
AOM_CTRL_USE_TYPE(AOME_GET_LAST_QUANTIZER_64, int *)
#define AOM_CTRL_AOME_GET_LAST_QUANTIZER_64

AOM_CTRL_USE_TYPE(AOME_SET_MAX_INTRA_BITRATE_PCT, unsigned int)
#define AOM_CTRL_AOME_SET_MAX_INTRA_BITRATE_PCT
AOM_CTRL_USE_TYPE(AOME_SET_MAX_INTER_BITRATE_PCT, unsigned int)
#define AOM_CTRL_AOME_SET_MAX_INTER_BITRATE_PCT

AOM_CTRL_USE_TYPE(AV1E_SET_GF_CBR_BOOST_PCT, unsigned int)
#define AOM_CTRL_AV1E_SET_GF_CBR_BOOST_PCT

AOM_CTRL_USE_TYPE(AV1E_SET_LOSSLESS, unsigned int)
#define AOM_CTRL_AV1E_SET_LOSSLESS
744

Yaowu Xu's avatar
Yaowu Xu committed
745
746
AOM_CTRL_USE_TYPE(AV1E_SET_ENABLE_QM, unsigned int)
#define AOM_CTRL_AV1E_SET_ENABLE_QM
747

748
749
750
AOM_CTRL_USE_TYPE(AV1E_SET_ENABLE_DIST_8X8, unsigned int)
#define AOM_CTRL_AV1E_SET_ENABLE_DIST_8X8

Yaowu Xu's avatar
Yaowu Xu committed
751
752
AOM_CTRL_USE_TYPE(AV1E_SET_QM_MIN, unsigned int)
#define AOM_CTRL_AV1E_SET_QM_MIN
753

Yaowu Xu's avatar
Yaowu Xu committed
754
755
AOM_CTRL_USE_TYPE(AV1E_SET_QM_MAX, unsigned int)
#define AOM_CTRL_AV1E_SET_QM_MAX
756

757
758
759
760
761
AOM_CTRL_USE_TYPE(AV1E_SET_NUM_TG, unsigned int)
#define AOM_CTRL_AV1E_SET_NUM_TG
AOM_CTRL_USE_TYPE(AV1E_SET_MTU, unsigned int)
#define AOM_CTRL_AV1E_SET_MTU

762
763
764
AOM_CTRL_USE_TYPE(AV1E_SET_DISABLE_TEMPMV, unsigned int)
#define AOM_CTRL_AV1E_SET_DISABLE_TEMPMV

Yaowu Xu's avatar
Yaowu Xu committed
765
766
AOM_CTRL_USE_TYPE(AV1E_SET_FRAME_PARALLEL_DECODING, unsigned int)
#define AOM_CTRL_AV1E_SET_FRAME_PARALLEL_DECODING
767

Yaowu Xu's avatar
Yaowu Xu committed
768
769
AOM_CTRL_USE_TYPE(AV1E_SET_AQ_MODE, unsigned int)
#define AOM_CTRL_AV1E_SET_AQ_MODE
770

Fangwen Fu's avatar
Fangwen Fu committed
771
772
773
AOM_CTRL_USE_TYPE(AV1E_SET_DELTAQ_MODE, unsigned int)
#define AOM_CTRL_AV1E_SET_DELTAQ_MODE

Yaowu Xu's avatar
Yaowu Xu committed
774
775
AOM_CTRL_USE_TYPE(AV1E_SET_FRAME_PERIODIC_BOOST, unsigned int)
#define AOM_CTRL_AV1E_SET_FRAME_PERIODIC_BOOST
776

Yaowu Xu's avatar
Yaowu Xu committed
777
778
AOM_CTRL_USE_TYPE(AV1E_SET_NOISE_SENSITIVITY, unsigned int)
#define AOM_CTRL_AV1E_SET_NOISE_SENSITIVITY
779

Yaowu Xu's avatar
Yaowu Xu committed
780
781
AOM_CTRL_USE_TYPE(AV1E_SET_TUNE_CONTENT, int) /* aom_tune_content */
#define AOM_CTRL_AV1E_SET_TUNE_CONTENT
782

Yaowu Xu's avatar
Yaowu Xu committed
783
784
AOM_CTRL_USE_TYPE(AV1E_SET_COLOR_SPACE, int)
#define AOM_CTRL_AV1E_SET_COLOR_SPACE
785

786
787
788
789
790
791
AOM_CTRL_USE_TYPE(AV1E_SET_TRANSFER_FUNCTION, int)
#define AOM_CTRL_AV1E_SET_TRANSFER_FUNCTION

AOM_CTRL_USE_TYPE(AV1E_SET_CHROMA_SAMPLE_POSITION, int)
#define AOM_CTRL_AV1E_SET_CHROMA_SAMPLE_POSITION

Yaowu Xu's avatar
Yaowu Xu committed
792
793
AOM_CTRL_USE_TYPE(AV1E_SET_MIN_GF_INTERVAL, unsigned int)
#define AOM_CTRL_AV1E_SET_MIN_GF_INTERVAL
794

Yaowu Xu's avatar
Yaowu Xu committed
795
796
AOM_CTRL_USE_TYPE(AV1E_SET_MAX_GF_INTERVAL, unsigned int)
#define AOM_CTRL_AV1E_SET_MAX_GF_INTERVAL
797

Yaowu Xu's avatar
Yaowu Xu committed
798
799
AOM_CTRL_USE_TYPE(AV1E_GET_ACTIVEMAP, aom_active_map_t *)
#define AOM_CTRL_AV1E_GET_ACTIVEMAP
800

Yaowu Xu's avatar
Yaowu Xu committed
801
802
AOM_CTRL_USE_TYPE(AV1E_SET_COLOR_RANGE, int)
#define AOM_CTRL_AV1E_SET_COLOR_RANGE
803
804
805
806
807

/*!\brief
 *
 * TODO(rbultje) : add support of the control in ffmpeg
 */
Yaowu Xu's avatar
Yaowu Xu committed
808
809
#define AOM_CTRL_AV1E_SET_RENDER_SIZE
AOM_CTRL_USE_TYPE(AV1E_SET_RENDER_SIZE, int *)
810

Yaowu Xu's avatar
Yaowu Xu committed
811
812
AOM_CTRL_USE_TYPE(AV1E_SET_SUPERBLOCK_SIZE, unsigned int)
#define AOM_CTRL_AV1E_SET_SUPERBLOCK_SIZE
813

Yaowu Xu's avatar
Yaowu Xu committed
814
815
AOM_CTRL_USE_TYPE(AV1E_SET_TARGET_LEVEL, unsigned int)
#define AOM_CTRL_AV1E_SET_TARGET_LEVEL
816

Yaowu Xu's avatar
Yaowu Xu committed
817
818
AOM_CTRL_USE_TYPE(AV1E_GET_LEVEL, int *)
#define AOM_CTRL_AV1E_GET_LEVEL
819
820
821

AOM_CTRL_USE_TYPE(AV1E_SET_ANS_WINDOW_SIZE_LOG2, unsigned int)
#define AOM_CTRL_AV1E_SET_ANS_WINDOW_SIZE_LOG2
822

823
824
AOM_CTRL_USE_TYPE(AV1E_SET_SINGLE_TILE_DECODING, unsigned int)
#define AOM_CTRL_AV1E_SET_SINGLE_TILE_DECODING
Yunqing Wang's avatar
Yunqing Wang committed
825
826
827
828

AOM_CTRL_USE_TYPE(AV1E_ENABLE_MOTION_VECTOR_UNIT_TEST, unsigned int)
#define AOM_CTRL_AV1E_ENABLE_MOTION_VECTOR_UNIT_TEST

829
/*!\endcond */
Alex Converse's avatar
Alex Converse committed
830
/*! @} - end defgroup aom_encoder */
831
832
833
834
#ifdef __cplusplus
}  // extern "C"
#endif

Yaowu Xu's avatar
Yaowu Xu committed
835
#endif  // AOM_AOMCX_H_