1 /*
2  * Copyright (C) 2016 The Android Open Source Project
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  *      http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15  */
16 
17 #ifndef C2CONFIG_H_
18 #define C2CONFIG_H_
19 
20 #include <C2.h>
21 #include <C2Component.h>
22 #include <C2Enum.h>
23 #include <C2ParamDef.h>
24 
25 /// \defgroup config Component configuration
26 /// @{
27 
28 /**
29  * Enumerated boolean.
30  */
31 C2ENUM(c2_bool_t, uint32_t,
32     C2_FALSE, ///< true
33     C2_TRUE,  ///< false
34 )
35 
36 typedef C2SimpleValueStruct<c2_bool_t> C2BoolValue;
37 
38 typedef C2SimpleValueStruct<C2EasyEnum<c2_bool_t>> C2EasyBoolValue;
39 
40 /**
41  * Enumerated set tri-state.
42  *
43  * Used for optional configurations to distinguish between values set by the client,
44  * default values set by the component, or unset values.
45  */
46 C2ENUM(c2_set_t, uint32_t,
47     C2_UNSET,   // parameter is unset and has no value
48     C2_SET,     // parameter is/has been set by the client
49     C2_DEFAULT, // parameter has not been set by the client, but is set by the component
50 )
51 
52 /** Enumerations used by configuration parameters */
53 struct C2Config {
54     enum aac_packaging_t : uint32_t;        ///< AAC packaging (RAW vs ADTS)
55     enum aac_sbr_mode_t : uint32_t;         ///< AAC SBR mode
56     enum api_feature_t : uint64_t;          ///< API features
57     enum api_level_t : uint32_t;            ///< API level
58     enum bitrate_mode_t : uint32_t;         ///< bitrate control mode
59     enum drc_compression_mode_t : int32_t;  ///< DRC compression mode
60     enum drc_effect_type_t : int32_t;       ///< DRC effect type
61     enum intra_refresh_mode_t : uint32_t;   ///< intra refresh modes
62     enum level_t : uint32_t;                ///< coding level
63     enum ordinal_key_t : uint32_t;          ///< work ordering keys
64     enum pcm_encoding_t : uint32_t;         ///< PCM encoding
65     enum picture_type_t : uint32_t;         ///< picture types
66     enum platform_feature_t : uint64_t;     ///< platform features
67     enum platform_level_t : uint32_t;       ///< platform level
68     enum prepend_header_mode_t : uint32_t;  ///< prepend header operational modes
69     enum profile_t : uint32_t;              ///< coding profile
70     enum scaling_method_t : uint32_t;       ///< scaling methods
71     enum scan_order_t : uint32_t;           ///< scan orders
72     enum secure_mode_t : uint32_t;          ///< secure/protected modes
73     enum supplemental_info_t : uint32_t;    ///< supplemental information types
74     enum tiling_mode_t : uint32_t;          ///< tiling modes
75 };
76 
77 namespace {
78 
79 enum C2ParamIndexKind : C2Param::type_index_t {
80     C2_PARAM_INDEX_INVALID             = 0x0,    ///< do not use
81     C2_PARAM_INDEX_STRUCT_START        = 0x1,    ///< struct only indices
82     C2_PARAM_INDEX_PARAM_START         = 0x800,  ///< regular parameters
83     C2_PARAM_INDEX_CODER_PARAM_START   = 0x1000, ///< en/transcoder parameters
84     C2_PARAM_INDEX_PICTURE_PARAM_START = 0x1800, ///< image/video parameters
85     C2_PARAM_INDEX_VIDEO_PARAM_START   = 0x2000, ///< video parameters
86     C2_PARAM_INDEX_IMAGE_PARAM_START   = 0x2800, ///< image parameters
87     C2_PARAM_INDEX_AUDIO_PARAM_START   = 0x3000, ///< image parameters
88     C2_PARAM_INDEX_PLATFORM_START      = 0x4000, ///< platform-defined parameters
89 
90     /* =================================== structure indices =================================== */
91 
92     kParamIndexColorXy = C2_PARAM_INDEX_STRUCT_START,
93     kParamIndexMasteringDisplayColorVolume,
94     kParamIndexChromaOffset,
95     kParamIndexGopLayer,
96 
97     /* =================================== parameter indices =================================== */
98 
99     kParamIndexApiLevel = C2_PARAM_INDEX_PARAM_START,
100     kParamIndexApiFeatures,
101 
102     /* ------------------------------------ all components ------------------------------------ */
103 
104     /* generic component characteristics */
105     kParamIndexName,
106     kParamIndexAliases,
107     kParamIndexKind,
108     kParamIndexDomain,
109     kParamIndexAttributes,
110     kParamIndexTimeStretch,
111 
112     /* coding characteristics */
113     kParamIndexProfileLevel,
114     kParamIndexInitData,
115     kParamIndexSupplementalData,
116     kParamIndexSubscribedSupplementalData,
117 
118     /* pipeline characteristics */
119     kParamIndexMediaType,
120     __kParamIndexRESERVED_0,
121     kParamIndexDelay,
122     kParamIndexMaxReferenceAge,
123     kParamIndexMaxReferenceCount,
124     kParamIndexReorderBufferDepth,
125     kParamIndexReorderKey,
126     kParamIndexStreamCount,
127     kParamIndexSubscribedParamIndices,
128     kParamIndexSuggestedBufferCount,
129     kParamIndexBatchSize,
130     kParamIndexCurrentWork,
131     kParamIndexLastWorkQueued,
132 
133     /* memory allocation */
134     kParamIndexAllocators,
135     kParamIndexBlockPools,
136     kParamIndexBufferType,
137     kParamIndexUsage,
138     kParamIndexOutOfMemory,
139     kParamIndexMaxBufferSize,
140 
141     /* misc. state */
142     kParamIndexTripped,
143     kParamIndexConfigCounter,
144 
145     /* resources */
146     kParamIndexResourcesNeeded,
147     kParamIndexResourcesReserved,
148     kParamIndexOperatingRate,
149     kParamIndexRealTimePriority,
150 
151     /* protected content */
152     kParamIndexSecureMode,
153 
154     // deprecated
155     kParamIndexDelayRequest = kParamIndexDelay | C2Param::CoreIndex::IS_REQUEST_FLAG,
156 
157     /* ------------------------------------ (trans/en)coders ------------------------------------ */
158 
159     kParamIndexBitrate = C2_PARAM_INDEX_CODER_PARAM_START,
160     kParamIndexBitrateMode,
161     kParamIndexQuality,
162     kParamIndexComplexity,
163     kParamIndexPrependHeaderMode,
164 
165     /* --------------------------------- image/video components --------------------------------- */
166 
167     kParamIndexPictureSize = C2_PARAM_INDEX_PICTURE_PARAM_START,
168     kParamIndexCropRect,
169     kParamIndexPixelFormat,
170     kParamIndexRotation,
171     kParamIndexPixelAspectRatio,
172     kParamIndexScaledPictureSize,
173     kParamIndexScaledCropRect,
174     kParamIndexScalingMethod,
175     kParamIndexColorInfo,
176     kParamIndexColorAspects,
177     kParamIndexHdrStaticMetadata,
178     kParamIndexDefaultColorAspects,
179 
180     kParamIndexBlockSize,
181     kParamIndexBlockCount,
182     kParamIndexBlockRate,
183 
184     kParamIndexPictureTypeMask,
185     kParamIndexPictureType,
186     kParamIndexHdr10PlusMetadata,
187 
188     /* ------------------------------------ video components ------------------------------------ */
189 
190     kParamIndexFrameRate = C2_PARAM_INDEX_VIDEO_PARAM_START,
191     kParamIndexMaxBitrate,
192     kParamIndexMaxFrameRate,
193     kParamIndexMaxPictureSize,
194     kParamIndexGop,
195     kParamIndexSyncFrameInterval,
196     kParamIndexRequestSyncFrame,
197     kParamIndexTemporalLayering,
198     kParamIndexLayerIndex,
199     kParamIndexLayerCount,
200     kParamIndexIntraRefresh,
201 
202     /* ------------------------------------ image components ------------------------------------ */
203 
204     kParamIndexTileLayout = C2_PARAM_INDEX_IMAGE_PARAM_START,
205     kParamIndexTileHandling,
206 
207     /* ------------------------------------ audio components ------------------------------------ */
208 
209     kParamIndexSampleRate = C2_PARAM_INDEX_AUDIO_PARAM_START,
210     kParamIndexChannelCount,
211     kParamIndexPcmEncoding,
212     kParamIndexAacPackaging,
213     kParamIndexMaxChannelCount,
214     kParamIndexAacSbrMode, // aac encode, enum
215     kParamIndexDrcEncodedTargetLevel,  // drc, float (dBFS)
216     kParamIndexDrcTargetReferenceLevel, // drc, float (dBFS)
217     kParamIndexDrcCompression, // drc, enum
218     kParamIndexDrcBoostFactor, // drc, float (0-1)
219     kParamIndexDrcAttenuationFactor, // drc, float (0-1)
220     kParamIndexDrcEffectType, // drc, enum
221 
222     /* ============================== platform-defined parameters ============================== */
223 
224     kParamIndexPlatformLevel = C2_PARAM_INDEX_PLATFORM_START, // all, u32
225     kParamIndexPlatformFeatures, // all, u64 mask
226     kParamIndexStoreIonUsage, // store, struct
227     kParamIndexAspectsToDataSpace, // store, struct
228     kParamIndexFlexiblePixelFormatDescriptor, // store, struct
229     kParamIndexFlexiblePixelFormatDescriptors, // store, struct[]
230     kParamIndexDataSpaceToAspects, // store, struct
231     kParamIndexDataSpace, // u32
232     kParamIndexSurfaceScaling, // u32
233 
234     // input surface
235     kParamIndexInputSurfaceEos, // input-surface, eos
236     kParamIndexTimedControl, // struct
237     kParamIndexStartAt, // input-surface, struct
238     kParamIndexSuspendAt, // input-surface, struct
239     kParamIndexResumeAt, // input-surface, struct
240     kParamIndexStopAt, // input-surface, struct
241     kParamIndexTimeOffset, // input-surface, struct
242     kParamIndexMinFrameRate, // input-surface, float
243     kParamIndexTimestampGapAdjustment, // input-surface, struct
244 
245     kParamIndexSurfaceAllocator, // u32
246 };
247 
248 }
249 
250 /**
251  * Codec 2.0 parameter types follow the following naming convention:
252  *
253  * C2<group><domain><index><type>
254  *
255  * E.g. C2StreamPictureSizeInfo: group="" domain="Stream" index="PictureSize" type="Info".
256  * Group is somewhat arbitrary, but denotes kind of objects the parameter is defined.
257  * At this point we use Component and Store to distinguish basic component/store parameters.
258  *
259  * Parameter keys are named C2_PARAMKEY_[<group>_]<domain>_<index> as type is not expected
260  * to distinguish parameters. E.g. a component could change the type of the parameter and it
261  * is not expected users would need to change the key.
262  */
263 
264 /* ----------------------------------------- API level ----------------------------------------- */
265 
266 enum C2Config::api_level_t : uint32_t {
267     API_L0_1 = 0,   ///< support for API level 0.1
268 };
269 
270 // read-only
271 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Config::api_level_t>, kParamIndexApiLevel>
272         C2ApiLevelSetting;
273 constexpr char C2_PARAMKEY_API_LEVEL[] = "api.level";
274 
275 enum C2Config::api_feature_t : uint64_t {
276     API_REFLECTION       = (1U << 0),  ///< ability to list supported parameters
277     API_VALUES           = (1U << 1),  ///< ability to list supported values for each parameter
278     API_CURRENT_VALUES   = (1U << 2),  ///< ability to list currently supported values for each parameter
279     API_DEPENDENCY       = (1U << 3),  ///< have a defined parameter dependency
280 
281     API_STREAMS          = (1ULL << 32),  ///< supporting variable number of streams
282 
283     API_TUNNELING        = (1ULL << 48),  ///< tunneling API
284 };
285 
286 // read-only
287 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Config::api_feature_t>, kParamIndexApiFeatures>
288         C2ApiFeaturesSetting;
289 constexpr char C2_PARAMKEY_API_FEATURES[] = "api.features";
290 
291 /* ----------------------------- generic component characteristics ----------------------------- */
292 
293 /**
294  * The name of the component.
295  *
296  * This must contain only alphanumeric characters or dot '.', hyphen '-', plus '+', or
297  * underline '_'. The name of each component must be unique.
298  *
299  * For Android: Component names must start with 'c2.' followed by the company name or abbreviation
300  * and another dot, e.g. 'c2.android.'. Use of lowercase is preferred but not required.
301  */
302 // read-only
303 typedef C2GlobalParam<C2Setting, C2StringValue, kParamIndexName> C2ComponentNameSetting;
304 constexpr char C2_PARAMKEY_COMPONENT_NAME[]  = "component.name";
305 
306 /**
307  * Alternate names (aliases) of the component.
308  *
309  * This is a comma ',' separated list of alternate component names. Unlike component names that
310  * must be unique, multiple components can have the same alias.
311  */
312 // read-only
313 typedef C2GlobalParam<C2Setting, C2StringValue, kParamIndexAliases> C2ComponentAliasesSetting;
314 constexpr char C2_PARAMKEY_COMPONENT_ALIASES[]  = "component.aliases";
315 
316 /**
317  * Component kind.
318  */
319 // read-only
320 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Component::kind_t>, kParamIndexKind>
321         C2ComponentKindSetting;
322 constexpr char C2_PARAMKEY_COMPONENT_KIND[]  = "component.kind";
323 
324 /**
325  * Component domain.
326  */
327 // read-only
328 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Component::domain_t>, kParamIndexDomain>
329         C2ComponentDomainSetting;
330 constexpr char C2_PARAMKEY_COMPONENT_DOMAIN[]  = "component.domain";
331 
332 /**
333  * Component attributes.
334  *
335  * These are a set of flags provided by the component characterizing its processing algorithm.
336  */
337 C2ENUM(C2Component::attrib_t, uint64_t,
338     ATTRIB_IS_TEMPORAL = 1u << 0, ///< component input ordering matters for processing
339 )
340 
341 // read-only
342 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Component::attrib_t>, kParamIndexAttributes>
343         C2ComponentAttributesSetting;
344 constexpr char C2_PARAMKEY_COMPONENT_ATTRIBUTES[] = "component.attributes";
345 
346 /**
347  * Time stretching.
348  *
349  * This is the ratio between the rate of the input timestamp, and the rate of the output timestamp.
350  * E.g. if this is 4.0, for every 1 seconds of input timestamp difference, the output shall differ
351  * by 4 seconds.
352  */
353 typedef C2GlobalParam<C2Tuning, C2FloatValue, kParamIndexTimeStretch> C2ComponentTimeStretchTuning;
354 constexpr char C2_PARAMKEY_TIME_STRETCH[]  = "algo.time-stretch";
355 
356 /* ----------------------------------- coding characteristics ----------------------------------- */
357 
358 /**
359  * Profile and level.
360  *
361  * Profile determines the tools used by the component.
362  * Level determines the level of resources used by the component.
363  */
364 
365 namespace {
366 
367 enum : uint32_t {
368     _C2_PL_MP2V_BASE = 0x1000,
369     _C2_PL_AAC_BASE  = 0x2000,
370     _C2_PL_H263_BASE = 0x3000,
371     _C2_PL_MP4V_BASE = 0x4000,
372     _C2_PL_AVC_BASE  = 0x5000,
373     _C2_PL_HEVC_BASE = 0x6000,
374     _C2_PL_VP9_BASE  = 0x7000,
375     _C2_PL_DV_BASE   = 0x8000,
376     _C2_PL_AV1_BASE  = 0x9000,
377 
378     C2_PROFILE_LEVEL_VENDOR_START = 0x70000000,
379 };
380 
381 }
382 
383 enum C2Config::profile_t : uint32_t {
384     PROFILE_UNUSED = 0,                         ///< profile is not used by this media type
385 
386     // AAC (MPEG-2 Part 7 and MPEG-4 Part 3) profiles
387     PROFILE_AAC_LC = _C2_PL_AAC_BASE,           ///< AAC Low-Complexity
388     PROFILE_AAC_MAIN,                           ///< AAC Main
389     PROFILE_AAC_SSR,                            ///< AAC Scalable Sampling Rate
390     PROFILE_AAC_LTP,                            ///< AAC Long Term Prediction
391     PROFILE_AAC_HE,                             ///< AAC High-Efficiency
392     PROFILE_AAC_SCALABLE,                       ///< AAC Scalable
393     PROFILE_AAC_ER_LC,                          ///< AAC Error Resilient Low-Complexity
394     PROFILE_AAC_ER_SCALABLE,                    ///< AAC Error Resilient Scalable
395     PROFILE_AAC_LD,                             ///< AAC Low Delay
396     PROFILE_AAC_HE_PS,                          ///< AAC High-Efficiency Parametric Stereo
397     PROFILE_AAC_ELD,                            ///< AAC Enhanced Low Delay
398     PROFILE_AAC_XHE,                            ///< AAC Extended High-Efficiency
399 
400     // MPEG-2 Video profiles
401     PROFILE_MP2V_SIMPLE = _C2_PL_MP2V_BASE,     ///< MPEG-2 Video (H.262) Simple
402     PROFILE_MP2V_MAIN,                          ///< MPEG-2 Video (H.262) Main
403     PROFILE_MP2V_SNR_SCALABLE,                  ///< MPEG-2 Video (H.262) SNR Scalable
404     PROFILE_MP2V_SPATIALLY_SCALABLE,            ///< MPEG-2 Video (H.262) Spatially Scalable
405     PROFILE_MP2V_HIGH,                          ///< MPEG-2 Video (H.262) High
406     PROFILE_MP2V_422,                           ///< MPEG-2 Video (H.262) 4:2:2
407     PROFILE_MP2V_MULTIVIEW,                     ///< MPEG-2 Video (H.262) Multi-view
408 
409     // H.263 profiles
410     PROFILE_H263_BASELINE = _C2_PL_H263_BASE,   ///< H.263 Baseline (Profile 0)
411     PROFILE_H263_H320,                          ///< H.263 H.320 Coding Efficiency Version 2 Backward-Compatibility (Profile 1)
412     PROFILE_H263_V1BC,                          ///< H.263 Version 1 Backward-Compatibility (Profile 2)
413     PROFILE_H263_ISWV2,                         ///< H.263 Version 2 Interactive and Streaming Wireless (Profile 3)
414     PROFILE_H263_ISWV3,                         ///< H.263 Version 3 Interactive and Streaming Wireless (Profile 4)
415     PROFILE_H263_HIGH_COMPRESSION,              ///< H.263 Conversational High Compression (Profile 5)
416     PROFILE_H263_INTERNET,                      ///< H.263 Conversational Internet (Profile 6)
417     PROFILE_H263_INTERLACE,                     ///< H.263 Conversational Interlace (Profile 7)
418     PROFILE_H263_HIGH_LATENCY,                  ///< H.263 High Latency (Profile 8)
419 
420     // MPEG-4 Part 2 (Video) Natural Visual Profiles
421     PROFILE_MP4V_SIMPLE,                        ///< MPEG-4 Video Simple
422     PROFILE_MP4V_SIMPLE_SCALABLE,               ///< MPEG-4 Video Simple Scalable
423     PROFILE_MP4V_CORE,                          ///< MPEG-4 Video Core
424     PROFILE_MP4V_MAIN,                          ///< MPEG-4 Video Main
425     PROFILE_MP4V_NBIT,                          ///< MPEG-4 Video N-Bit
426     PROFILE_MP4V_ARTS,                          ///< MPEG-4 Video Advanced Realtime Simple
427     PROFILE_MP4V_CORE_SCALABLE,                 ///< MPEG-4 Video Core Scalable
428     PROFILE_MP4V_ACE,                           ///< MPEG-4 Video Advanced Coding Efficiency
429     PROFILE_MP4V_ADVANCED_CORE,                 ///< MPEG-4 Video Advanced Core
430     PROFILE_MP4V_SIMPLE_STUDIO,                 ///< MPEG-4 Video Simple Studio
431     PROFILE_MP4V_CORE_STUDIO,                   ///< MPEG-4 Video Core Studio
432     PROFILE_MP4V_ADVANCED_SIMPLE,               ///< MPEG-4 Video Advanced Simple
433     PROFILE_MP4V_FGS,                           ///< MPEG-4 Video Fine Granularity Scalable
434 
435     // AVC / MPEG-4 Part 10 (H.264) profiles
436     PROFILE_AVC_BASELINE = _C2_PL_AVC_BASE,     ///< AVC (H.264) Baseline
437     PROFILE_AVC_CONSTRAINED_BASELINE,           ///< AVC (H.264) Constrained Baseline
438     PROFILE_AVC_MAIN,                           ///< AVC (H.264) Main
439     PROFILE_AVC_EXTENDED,                       ///< AVC (H.264) Extended
440     PROFILE_AVC_HIGH,                           ///< AVC (H.264) High
441     PROFILE_AVC_PROGRESSIVE_HIGH,               ///< AVC (H.264) Progressive High
442     PROFILE_AVC_CONSTRAINED_HIGH,               ///< AVC (H.264) Constrained High
443     PROFILE_AVC_HIGH_10,                        ///< AVC (H.264) High 10
444     PROFILE_AVC_PROGRESSIVE_HIGH_10,            ///< AVC (H.264) Progressive High 10
445     PROFILE_AVC_HIGH_422,                       ///< AVC (H.264) High 4:2:2
446     PROFILE_AVC_HIGH_444_PREDICTIVE,            ///< AVC (H.264) High 4:4:4 Predictive
447     PROFILE_AVC_HIGH_10_INTRA,                  ///< AVC (H.264) High 10 Intra
448     PROFILE_AVC_HIGH_422_INTRA,                 ///< AVC (H.264) High 4:2:2 Intra
449     PROFILE_AVC_HIGH_444_INTRA,                 ///< AVC (H.264) High 4:4:4 Intra
450     PROFILE_AVC_CAVLC_444_INTRA,                ///< AVC (H.264) CAVLC 4:4:4 Intra
451     PROFILE_AVC_SCALABLE_BASELINE = _C2_PL_AVC_BASE + 0x100,  ///< AVC (H.264) Scalable Baseline
452     PROFILE_AVC_SCALABLE_CONSTRAINED_BASELINE,  ///< AVC (H.264) Scalable Constrained Baseline
453     PROFILE_AVC_SCALABLE_HIGH,                  ///< AVC (H.264) Scalable High
454     PROFILE_AVC_SCALABLE_CONSTRAINED_HIGH,      ///< AVC (H.264) Scalable Constrained High
455     PROFILE_AVC_SCALABLE_HIGH_INTRA,            ///< AVC (H.264) Scalable High Intra
456     PROFILE_AVC_MULTIVIEW_HIGH = _C2_PL_AVC_BASE + 0x200,  ///< AVC (H.264) Multiview High
457     PROFILE_AVC_STEREO_HIGH,                    ///< AVC (H.264) Stereo High
458     PROFILE_AVC_MFC_HIGH,                       ///< AVC (H.264) MFC High
459     PROFILE_AVC_MULTIVIEW_DEPTH_HIGH = _C2_PL_AVC_BASE + 0x300,  ///< AVC (H.264) Multiview Depth High
460     PROFILE_AVC_MFC_DEPTH_HIGH,                 ///< AVC (H.264) MFC Depth High
461     PROFILE_AVC_ENHANCED_MULTIVIEW_DEPTH_HIGH = _C2_PL_AVC_BASE + 0x400,  ///< AVC (H.264) Enhanced Multiview Depth High
462 
463     // HEVC profiles
464     PROFILE_HEVC_MAIN = _C2_PL_HEVC_BASE,       ///< HEVC (H.265) Main
465     PROFILE_HEVC_MAIN_10,                       ///< HEVC (H.265) Main 10
466     PROFILE_HEVC_MAIN_STILL,                    ///< HEVC (H.265) Main Still Picture
467     PROFILE_HEVC_MONO = _C2_PL_HEVC_BASE + 0x100,  ///< HEVC (H.265) Monochrome
468     PROFILE_HEVC_MONO_12,                       ///< HEVC (H.265) Monochrome 12
469     PROFILE_HEVC_MONO_16,                       ///< HEVC (H.265) Monochrome 16
470     PROFILE_HEVC_MAIN_12,                       ///< HEVC (H.265) Main 12
471     PROFILE_HEVC_MAIN_422_10,                   ///< HEVC (H.265) Main 4:2:2 10
472     PROFILE_HEVC_MAIN_422_12,                   ///< HEVC (H.265) Main 4:2:2 12
473     PROFILE_HEVC_MAIN_444,                      ///< HEVC (H.265) Main 4:4:4
474     PROFILE_HEVC_MAIN_444_10,                   ///< HEVC (H.265) Main 4:4:4 10
475     PROFILE_HEVC_MAIN_444_12,                   ///< HEVC (H.265) Main 4:4:4 12
476     PROFILE_HEVC_MAIN_INTRA,                    ///< HEVC (H.265) Main Intra
477     PROFILE_HEVC_MAIN_10_INTRA,                 ///< HEVC (H.265) Main 10 Intra
478     PROFILE_HEVC_MAIN_12_INTRA,                 ///< HEVC (H.265) Main 12 Intra
479     PROFILE_HEVC_MAIN_422_10_INTRA,             ///< HEVC (H.265) Main 4:2:2 10 Intra
480     PROFILE_HEVC_MAIN_422_12_INTRA,             ///< HEVC (H.265) Main 4:2:2 12 Intra
481     PROFILE_HEVC_MAIN_444_INTRA,                ///< HEVC (H.265) Main 4:4:4 Intra
482     PROFILE_HEVC_MAIN_444_10_INTRA,             ///< HEVC (H.265) Main 4:4:4 10 Intra
483     PROFILE_HEVC_MAIN_444_12_INTRA,             ///< HEVC (H.265) Main 4:4:4 12 Intra
484     PROFILE_HEVC_MAIN_444_16_INTRA,             ///< HEVC (H.265) Main 4:4:4 16 Intra
485     PROFILE_HEVC_MAIN_444_STILL,                ///< HEVC (H.265) Main 4:4:4 Still Picture
486     PROFILE_HEVC_MAIN_444_16_STILL,             ///< HEVC (H.265) Main 4:4:4 16 Still Picture
487     PROFILE_HEVC_HIGH_444 = _C2_PL_HEVC_BASE + 0x200,  ///< HEVC (H.265) High Throughput 4:4:4
488     PROFILE_HEVC_HIGH_444_10,                   ///< HEVC (H.265) High Throughput 4:4:4 10
489     PROFILE_HEVC_HIGH_444_14,                   ///< HEVC (H.265) High Throughput 4:4:4 14
490     PROFILE_HEVC_HIGH_444_16_INTRA,             ///< HEVC (H.265) High Throughput 4:4:4 16 Intra
491     PROFILE_HEVC_SX_MAIN = _C2_PL_HEVC_BASE + 0x300,  ///< HEVC (H.265) Screen-Extended Main
492     PROFILE_HEVC_SX_MAIN_10,                    ///< HEVC (H.265) Screen-Extended Main 10
493     PROFILE_HEVC_SX_MAIN_444,                   ///< HEVC (H.265) Screen-Extended Main 4:4:4
494     PROFILE_HEVC_SX_MAIN_444_10,                ///< HEVC (H.265) Screen-Extended Main 4:4:4 10
495     PROFILE_HEVC_SX_HIGH_444,                   ///< HEVC (H.265) Screen-Extended High Throughput 4:4:4
496     PROFILE_HEVC_SX_HIGH_444_10,                ///< HEVC (H.265) Screen-Extended High Throughput 4:4:4 10
497     PROFILE_HEVC_SX_HIGH_444_14,                ///< HEVC (H.265) Screen-Extended High Throughput 4:4:4 14
498     PROFILE_HEVC_MULTIVIEW_MAIN = _C2_PL_HEVC_BASE + 0x400,  ///< HEVC (H.265) Multiview Main
499     PROFILE_HEVC_SCALABLE_MAIN = _C2_PL_HEVC_BASE + 0x500,  ///< HEVC (H.265) Scalable Main
500     PROFILE_HEVC_SCALABLE_MAIN_10,              ///< HEVC (H.265) Scalable Main 10
501     PROFILE_HEVC_SCALABLE_MONO = _C2_PL_HEVC_BASE + 0x600,  ///< HEVC (H.265) Scalable Monochrome
502     PROFILE_HEVC_SCALABLE_MONO_12,              ///< HEVC (H.265) Scalable Monochrome 12
503     PROFILE_HEVC_SCALABLE_MONO_16,              ///< HEVC (H.265) Scalable Monochrome 16
504     PROFILE_HEVC_SCALABLE_MAIN_444,             ///< HEVC (H.265) Scalable Main 4:4:4
505     PROFILE_HEVC_3D_MAIN = _C2_PL_HEVC_BASE + 0x700,  ///< HEVC (H.265) 3D Main
506 
507     // VP9 profiles
508     PROFILE_VP9_0 = _C2_PL_VP9_BASE,            ///< VP9 Profile 0 (4:2:0)
509     PROFILE_VP9_1,                              ///< VP9 Profile 1 (4:2:2 or 4:4:4)
510     PROFILE_VP9_2,                              ///< VP9 Profile 2 (4:2:0, 10 or 12 bit)
511     PROFILE_VP9_3,                              ///< VP9 Profile 3 (4:2:2 or 4:4:4, 10 or 12 bit)
512 
513     // Dolby Vision profiles
514     PROFILE_DV_AV_PER = _C2_PL_DV_BASE + 0,     ///< Dolby Vision dvav.per profile (deprecated)
515     PROFILE_DV_AV_PEN,                          ///< Dolby Vision dvav.pen profile (deprecated)
516     PROFILE_DV_HE_DER,                          ///< Dolby Vision dvhe.der profile (deprecated)
517     PROFILE_DV_HE_DEN,                          ///< Dolby Vision dvhe.den profile (deprecated)
518     PROFILE_DV_HE_04 = _C2_PL_DV_BASE + 4,      ///< Dolby Vision dvhe.04 profile
519     PROFILE_DV_HE_05 = _C2_PL_DV_BASE + 5,      ///< Dolby Vision dvhe.05 profile
520     PROFILE_DV_HE_DTH,                          ///< Dolby Vision dvhe.dth profile (deprecated)
521     PROFILE_DV_HE_07 = _C2_PL_DV_BASE + 7,      ///< Dolby Vision dvhe.07 profile
522     PROFILE_DV_HE_08 = _C2_PL_DV_BASE + 8,      ///< Dolby Vision dvhe.08 profile
523     PROFILE_DV_AV_09 = _C2_PL_DV_BASE + 9,      ///< Dolby Vision dvav.09 profile
524 
525     // AV1 profiles
526     PROFILE_AV1_0 = _C2_PL_AV1_BASE,            ///< AV1 Profile 0 (4:2:0, 8 to 10 bit)
527     PROFILE_AV1_1,                              ///< AV1 Profile 1 (8 to 10 bit)
528     PROFILE_AV1_2,                              ///< AV1 Profile 2 (8 to 12 bit)
529 };
530 
531 enum C2Config::level_t : uint32_t {
532     LEVEL_UNUSED = 0,                           ///< level is not used by this media type
533 
534     // MPEG-2 Video levels
535     LEVEL_MP2V_LOW = _C2_PL_MP2V_BASE,          ///< MPEG-2 Video (H.262) Low Level
536     LEVEL_MP2V_MAIN,                            ///< MPEG-2 Video (H.262) Main Level
537     LEVEL_MP2V_HIGH_1440,                       ///< MPEG-2 Video (H.262) High 1440 Level
538     LEVEL_MP2V_HIGH,                            ///< MPEG-2 Video (H.262) High Level
539     LEVEL_MP2V_HIGHP,                           ///< MPEG-2 Video (H.262) HighP Level
540 
541     // H.263 levels
542     LEVEL_H263_10 = _C2_PL_H263_BASE,           ///< H.263 Level 10
543     LEVEL_H263_20,                              ///< H.263 Level 20
544     LEVEL_H263_30,                              ///< H.263 Level 30
545     LEVEL_H263_40,                              ///< H.263 Level 40
546     LEVEL_H263_45,                              ///< H.263 Level 45
547     LEVEL_H263_50,                              ///< H.263 Level 50
548     LEVEL_H263_60,                              ///< H.263 Level 60
549     LEVEL_H263_70,                              ///< H.263 Level 70
550 
551     // MPEG-4 Part 2 (Video) levels
552     LEVEL_MP4V_0 = _C2_PL_MP4V_BASE,            ///< MPEG-4 Video Level 0
553     LEVEL_MP4V_0B,                              ///< MPEG-4 Video Level 0b
554     LEVEL_MP4V_1,                               ///< MPEG-4 Video Level 1
555     LEVEL_MP4V_2,                               ///< MPEG-4 Video Level 2
556     LEVEL_MP4V_3,                               ///< MPEG-4 Video Level 3
557     LEVEL_MP4V_3B,                              ///< MPEG-4 Video Level 3b
558     LEVEL_MP4V_4,                               ///< MPEG-4 Video Level 4
559     LEVEL_MP4V_4A,                              ///< MPEG-4 Video Level 4a
560     LEVEL_MP4V_5,                               ///< MPEG-4 Video Level 5
561     LEVEL_MP4V_6,                               ///< MPEG-4 Video Level 6
562 
563     // AVC / MPEG-4 Part 10 (H.264) levels
564     LEVEL_AVC_1 = _C2_PL_AVC_BASE,              ///< AVC (H.264) Level 1
565     LEVEL_AVC_1B,                               ///< AVC (H.264) Level 1b
566     LEVEL_AVC_1_1,                              ///< AVC (H.264) Level 1.1
567     LEVEL_AVC_1_2,                              ///< AVC (H.264) Level 1.2
568     LEVEL_AVC_1_3,                              ///< AVC (H.264) Level 1.3
569     LEVEL_AVC_2,                                ///< AVC (H.264) Level 2
570     LEVEL_AVC_2_1,                              ///< AVC (H.264) Level 2.1
571     LEVEL_AVC_2_2,                              ///< AVC (H.264) Level 2.2
572     LEVEL_AVC_3,                                ///< AVC (H.264) Level 3
573     LEVEL_AVC_3_1,                              ///< AVC (H.264) Level 3.1
574     LEVEL_AVC_3_2,                              ///< AVC (H.264) Level 3.2
575     LEVEL_AVC_4,                                ///< AVC (H.264) Level 4
576     LEVEL_AVC_4_1,                              ///< AVC (H.264) Level 4.1
577     LEVEL_AVC_4_2,                              ///< AVC (H.264) Level 4.2
578     LEVEL_AVC_5,                                ///< AVC (H.264) Level 5
579     LEVEL_AVC_5_1,                              ///< AVC (H.264) Level 5.1
580     LEVEL_AVC_5_2,                              ///< AVC (H.264) Level 5.2
581     LEVEL_AVC_6,                                ///< AVC (H.264) Level 6
582     LEVEL_AVC_6_1,                              ///< AVC (H.264) Level 6.1
583     LEVEL_AVC_6_2,                              ///< AVC (H.264) Level 6.2
584 
585     // HEVC (H.265) tiers and levels
586     LEVEL_HEVC_MAIN_1 = _C2_PL_HEVC_BASE,       ///< HEVC (H.265) Main Tier Level 1
587     LEVEL_HEVC_MAIN_2,                          ///< HEVC (H.265) Main Tier Level 2
588     LEVEL_HEVC_MAIN_2_1,                        ///< HEVC (H.265) Main Tier Level 2.1
589     LEVEL_HEVC_MAIN_3,                          ///< HEVC (H.265) Main Tier Level 3
590     LEVEL_HEVC_MAIN_3_1,                        ///< HEVC (H.265) Main Tier Level 3.1
591     LEVEL_HEVC_MAIN_4,                          ///< HEVC (H.265) Main Tier Level 4
592     LEVEL_HEVC_MAIN_4_1,                        ///< HEVC (H.265) Main Tier Level 4.1
593     LEVEL_HEVC_MAIN_5,                          ///< HEVC (H.265) Main Tier Level 5
594     LEVEL_HEVC_MAIN_5_1,                        ///< HEVC (H.265) Main Tier Level 5.1
595     LEVEL_HEVC_MAIN_5_2,                        ///< HEVC (H.265) Main Tier Level 5.2
596     LEVEL_HEVC_MAIN_6,                          ///< HEVC (H.265) Main Tier Level 6
597     LEVEL_HEVC_MAIN_6_1,                        ///< HEVC (H.265) Main Tier Level 6.1
598     LEVEL_HEVC_MAIN_6_2,                        ///< HEVC (H.265) Main Tier Level 6.2
599 
600     LEVEL_HEVC_HIGH_4 = _C2_PL_HEVC_BASE + 0x100,  ///< HEVC (H.265) High Tier Level 4
601     LEVEL_HEVC_HIGH_4_1,                        ///< HEVC (H.265) High Tier Level 4.1
602     LEVEL_HEVC_HIGH_5,                          ///< HEVC (H.265) High Tier Level 5
603     LEVEL_HEVC_HIGH_5_1,                        ///< HEVC (H.265) High Tier Level 5.1
604     LEVEL_HEVC_HIGH_5_2,                        ///< HEVC (H.265) High Tier Level 5.2
605     LEVEL_HEVC_HIGH_6,                          ///< HEVC (H.265) High Tier Level 6
606     LEVEL_HEVC_HIGH_6_1,                        ///< HEVC (H.265) High Tier Level 6.1
607     LEVEL_HEVC_HIGH_6_2,                        ///< HEVC (H.265) High Tier Level 6.2
608 
609     // VP9 levels
610     LEVEL_VP9_1 = _C2_PL_VP9_BASE,              ///< VP9 Level 1
611     LEVEL_VP9_1_1,                              ///< VP9 Level 1.1
612     LEVEL_VP9_2,                                ///< VP9 Level 2
613     LEVEL_VP9_2_1,                              ///< VP9 Level 2.1
614     LEVEL_VP9_3,                                ///< VP9 Level 3
615     LEVEL_VP9_3_1,                              ///< VP9 Level 3.1
616     LEVEL_VP9_4,                                ///< VP9 Level 4
617     LEVEL_VP9_4_1,                              ///< VP9 Level 4.1
618     LEVEL_VP9_5,                                ///< VP9 Level 5
619     LEVEL_VP9_5_1,                              ///< VP9 Level 5.1
620     LEVEL_VP9_5_2,                              ///< VP9 Level 5.2
621     LEVEL_VP9_6,                                ///< VP9 Level 6
622     LEVEL_VP9_6_1,                              ///< VP9 Level 6.1
623     LEVEL_VP9_6_2,                              ///< VP9 Level 6.2
624 
625     // Dolby Vision levels
626     LEVEL_DV_MAIN_HD_24 = _C2_PL_DV_BASE,       ///< Dolby Vision main tier hd24
627     LEVEL_DV_MAIN_HD_30,                        ///< Dolby Vision main tier hd30
628     LEVEL_DV_MAIN_FHD_24,                       ///< Dolby Vision main tier fhd24
629     LEVEL_DV_MAIN_FHD_30,                       ///< Dolby Vision main tier fhd30
630     LEVEL_DV_MAIN_FHD_60,                       ///< Dolby Vision main tier fhd60
631     LEVEL_DV_MAIN_UHD_24,                       ///< Dolby Vision main tier uhd24
632     LEVEL_DV_MAIN_UHD_30,                       ///< Dolby Vision main tier uhd30
633     LEVEL_DV_MAIN_UHD_48,                       ///< Dolby Vision main tier uhd48
634     LEVEL_DV_MAIN_UHD_60,                       ///< Dolby Vision main tier uhd60
635 
636     LEVEL_DV_HIGH_HD_24 = _C2_PL_DV_BASE + 0x100,  ///< Dolby Vision high tier hd24
637     LEVEL_DV_HIGH_HD_30,                        ///< Dolby Vision high tier hd30
638     LEVEL_DV_HIGH_FHD_24,                       ///< Dolby Vision high tier fhd24
639     LEVEL_DV_HIGH_FHD_30,                       ///< Dolby Vision high tier fhd30
640     LEVEL_DV_HIGH_FHD_60,                       ///< Dolby Vision high tier fhd60
641     LEVEL_DV_HIGH_UHD_24,                       ///< Dolby Vision high tier uhd24
642     LEVEL_DV_HIGH_UHD_30,                       ///< Dolby Vision high tier uhd30
643     LEVEL_DV_HIGH_UHD_48,                       ///< Dolby Vision high tier uhd48
644     LEVEL_DV_HIGH_UHD_60,                       ///< Dolby Vision high tier uhd60
645 
646     // AV1 levels
647     LEVEL_AV1_2    = _C2_PL_AV1_BASE ,          ///< AV1 Level 2
648     LEVEL_AV1_2_1,                              ///< AV1 Level 2.1
649     LEVEL_AV1_2_2,                              ///< AV1 Level 2.2
650     LEVEL_AV1_2_3,                              ///< AV1 Level 2.3
651     LEVEL_AV1_3,                                ///< AV1 Level 3
652     LEVEL_AV1_3_1,                              ///< AV1 Level 3.1
653     LEVEL_AV1_3_2,                              ///< AV1 Level 3.2
654     LEVEL_AV1_3_3,                              ///< AV1 Level 3.3
655     LEVEL_AV1_4,                                ///< AV1 Level 4
656     LEVEL_AV1_4_1,                              ///< AV1 Level 4.1
657     LEVEL_AV1_4_2,                              ///< AV1 Level 4.2
658     LEVEL_AV1_4_3,                              ///< AV1 Level 4.3
659     LEVEL_AV1_5,                                ///< AV1 Level 5
660     LEVEL_AV1_5_1,                              ///< AV1 Level 5.1
661     LEVEL_AV1_5_2,                              ///< AV1 Level 5.2
662     LEVEL_AV1_5_3,                              ///< AV1 Level 5.3
663     LEVEL_AV1_6,                                ///< AV1 Level 6
664     LEVEL_AV1_6_1,                              ///< AV1 Level 6.1
665     LEVEL_AV1_6_2,                              ///< AV1 Level 6.2
666     LEVEL_AV1_6_3,                              ///< AV1 Level 6.3
667     LEVEL_AV1_7,                                ///< AV1 Level 7
668     LEVEL_AV1_7_1,                              ///< AV1 Level 7.1
669     LEVEL_AV1_7_2,                              ///< AV1 Level 7.2
670     LEVEL_AV1_7_3,                              ///< AV1 Level 7.3
671 };
672 
673 struct C2ProfileLevelStruct {
674     C2Config::profile_t profile;  ///< coding profile
675     C2Config::level_t   level;    ///< coding level
676 
677     C2ProfileLevelStruct(
678             C2Config::profile_t profile_ = C2Config::PROFILE_UNUSED,
679             C2Config::level_t level_ = C2Config::LEVEL_UNUSED)
profileC2ProfileLevelStruct680         : profile(profile_), level(level_) { }
681 
682     DEFINE_AND_DESCRIBE_C2STRUCT(ProfileLevel)
683     C2FIELD(profile, "profile")
684     C2FIELD(level,   "level")
685 };
686 
687 // TODO: may need to make this explicit (have .set member)
688 typedef C2StreamParam<C2Info, C2ProfileLevelStruct, kParamIndexProfileLevel>
689         C2StreamProfileLevelInfo;
690 constexpr char C2_PARAMKEY_PROFILE_LEVEL[] = "coded.pl";
691 
692 /**
693  * Codec-specific initialization data.
694  *
695  * This is initialization data for the codec.
696  *
697  * For AVC/HEVC, these are the concatenated SPS/PPS/VPS NALs.
698  *
699  * TODO: define for other codecs.
700  */
701 typedef C2StreamParam<C2Info, C2BlobValue, kParamIndexInitData> C2StreamInitDataInfo;
702 constexpr char C2_PARAMKEY_INIT_DATA[] = "coded.init-data";
703 
704 /**
705  * Supplemental Data.
706  *
707  * This is coding-specific supplemental informational data, e.g. SEI for AVC/HEVC.
708  * This structure is not a configuration so it does not have a parameter key.
709  * This structure shall be returned in the configuration update, and can be repeated as needed
710  * in the same update.
711  */
712 C2ENUM(C2Config::supplemental_info_t, uint32_t,
713     INFO_NONE = 0,
714 
715     INFO_PREFIX_SEI_UNIT = 0x10000, ///< prefix SEI payload types add this flag
716     INFO_SUFFIX_SEI_UNIT = 0x20000, ///< suffix SEI payload types add this flag
717 
718     INFO_SEI_USER_DATA = INFO_PREFIX_SEI_UNIT | 4,    ///< closed-captioning data (ITU-T T35)
719     INFO_SEI_MDCV      = INFO_PREFIX_SEI_UNIT | 137,  ///< mastering display color volume
720     INFO_SET_USER_DATA_SFX = INFO_SUFFIX_SEI_UNIT | 4, ///< closed-captioning data (ITU-T T35)
721 
722     INFO_VENDOR_START = 0x70000000
723 )
724 
725 struct C2SupplementalDataStruct {
C2SupplementalDataStructC2SupplementalDataStruct726     C2SupplementalDataStruct()
727         : type_(INFO_NONE) { }
728 
C2SupplementalDataStructC2SupplementalDataStruct729     C2SupplementalDataStruct(
730             size_t flexCount, C2Config::supplemental_info_t type, std::vector<uint8_t> data_)
731         : type_(type) {
732             memcpy(data, &data_[0], c2_min(data_.size(), flexCount));
733     }
734 
735     C2Config::supplemental_info_t type_;
736     uint8_t data[];
737 
738     DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(SupplementalData, data)
739     C2FIELD(type_, "type")
740     C2FIELD(data, "data")
741 };
742 typedef C2StreamParam<C2Info, C2SupplementalDataStruct, kParamIndexSupplementalData>
743         C2StreamSupplementalDataInfo;
744 
745 /**
746  * Supplemental Data Subscription
747  */
748 typedef C2StreamParam<C2Tuning, C2SimpleArrayStruct<C2Config::supplemental_info_t>,
749                 kParamIndexSubscribedSupplementalData>
750         C2StreamSubscribedSupplementalDataTuning;
751 constexpr char C2_PARAMKEY_SUBSCRIBED_SUPPLEMENTAL_DATA[] = "output.subscribed-supplemental";
752 
753 /* ---------------------------------- pipeline characteristics ---------------------------------- */
754 
755 /**
756  * Media-type.
757  *
758  * This is defined for both port and stream, but stream media type may be a subtype of the
759  * port media type.
760  */
761 typedef C2PortParam<C2Setting, C2StringValue, kParamIndexMediaType> C2PortMediaTypeSetting;
762 constexpr char C2_PARAMKEY_INPUT_MEDIA_TYPE[] = "input.media-type";
763 constexpr char C2_PARAMKEY_OUTPUT_MEDIA_TYPE[] = "output.media-type";
764 
765 typedef C2StreamParam<C2Setting, C2StringValue, kParamIndexMediaType> C2StreamMediaTypeSetting;
766 
767 /**
768  * Pipeline delays.
769  *
770  * Input delay is the number of additional input frames requested by the component to process
771  * an input frame.
772  *
773  * Output delay is the number of additional output frames that need to be generated before an
774  * output can be released by the component.
775  *
776  * Pipeline delay is the number of additional frames that are processed at one time by the
777  * component.
778  *
779  * As these may vary from frame to frame, the number is the maximum required value. E.g. if
780  * input delay is 0, the component is expected to consume each frame queued even if no further
781  * frames are queued. Similarly, if input delay is 1, as long as there are always exactly 2
782  * outstanding input frames queued to the component, it shall produce output.
783  */
784 
785 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexDelay | C2Param::CoreIndex::IS_REQUEST_FLAG>
786         C2PortRequestedDelayTuning;
787 constexpr char C2_PARAMKEY_INPUT_DELAY_REQUEST[] = "input.delay"; // deprecated
788 constexpr char C2_PARAMKEY_OUTPUT_DELAY_REQUEST[] = "output.delay"; // deprecated
789 
790 typedef C2GlobalParam<C2Tuning, C2Uint32Value,
791                 kParamIndexDelay | C2Param::CoreIndex::IS_REQUEST_FLAG>
792         C2RequestedPipelineDelayTuning;
793 constexpr char C2_PARAMKEY_PIPELINE_DELAY_REQUEST[] = "algo.delay"; // deprecated
794 
795 // read-only
796 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexDelay> C2PortDelayTuning;
797 typedef C2PortDelayTuning C2PortActualDelayTuning; // deprecated
798 constexpr char C2_PARAMKEY_INPUT_DELAY[] = "input.delay";
799 constexpr char C2_PARAMKEY_OUTPUT_DELAY[] = "output.delay";
800 
801 // read-only
802 typedef C2GlobalParam<C2Tuning, C2Uint32Value, kParamIndexDelay> C2PipelineDelayTuning;
803 typedef C2PipelineDelayTuning C2ActualPipelineDelayTuning; // deprecated
804 constexpr char C2_PARAMKEY_PIPELINE_DELAY[] = "algo.delay";
805 
806 /**
807  * Reference characteristics.
808  *
809  * The component may hold onto input and output buffers even after completing the corresponding
810  * work item.
811  *
812  * Max reference age is the longest number of additional frame processing that a component may
813  * hold onto a buffer for. Max reference count is the number of buffers that a component may
814  * hold onto at the same time at the worst case. These numbers assume single frame per buffers.
815  *
816  * Use max-uint32 if there is no limit for the max age or count.
817  */
818 typedef C2StreamParam<C2Tuning, C2Uint32Value, kParamIndexMaxReferenceAge>
819         C2StreamMaxReferenceAgeTuning;
820 constexpr char C2_PARAMKEY_INPUT_MAX_REFERENCE_AGE[] = "input.reference.max-age";
821 constexpr char C2_PARAMKEY_OUTPUT_MAX_REFERENCE_AGE[] = "output.reference.max-age";
822 
823 typedef C2StreamParam<C2Tuning, C2Uint32Value, kParamIndexMaxReferenceCount>
824         C2StreamMaxReferenceCountTuning;
825 constexpr char C2_PARAMKEY_INPUT_MAX_REFERENCE_COUNT[] = "input.reference.max-count";
826 constexpr char C2_PARAMKEY_OUTPUT_MAX_REFERENCE_COUNT[] = "output.reference.max-count";
827 
828 /**
829  * Output reordering.
830  *
831  * The size of the window to use for output buffer reordering. 0 is interpreted as 1.
832  */
833 // output only
834 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexReorderBufferDepth>
835         C2PortReorderBufferDepthTuning;
836 constexpr char C2_PARAMKEY_OUTPUT_REORDER_DEPTH[] = "output.reorder.depth";
837 
838 C2ENUM(C2Config::ordinal_key_t, uint32_t,
839         ORDINAL,
840         TIMESTAMP,
841         CUSTOM)
842 
843 // read-only, output only
844 typedef C2PortParam<C2Setting, C2SimpleValueStruct<C2Config::ordinal_key_t>, kParamIndexReorderKey>
845         C2PortReorderKeySetting;
846 constexpr char C2_PARAMKEY_OUTPUT_REORDER_KEY[] = "output.reorder.key";
847 
848 /**
849  * Stream count.
850  */
851 // private
852 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexStreamCount> C2PortStreamCountTuning;
853 constexpr char C2_PARAMKEY_INPUT_STREAM_COUNT[] = "input.stream-count";
854 constexpr char C2_PARAMKEY_OUTPUT_STREAM_COUNT[] = "output.stream-count";
855 
856 /**
857  * Config update subscription.
858  */
859 // private
860 typedef C2GlobalParam<C2Tuning, C2Uint32Array, kParamIndexSubscribedParamIndices>
861         C2SubscribedParamIndicesTuning;
862 constexpr char C2_PARAMKEY_SUBSCRIBED_PARAM_INDICES[] = "output.subscribed-indices";
863 
864 /**
865  * Suggested buffer (C2Frame) count. This is a suggestion by the component for the number of
866  * input and output frames allocated for the component's use in the buffer pools.
867  *
868  * Component shall set the acceptable range of buffers allocated for it. E.g. client shall
869  * allocate at least the minimum required value.
870  */
871 // read-only
872 typedef C2PortParam<C2Tuning, C2Uint64Array, kParamIndexSuggestedBufferCount>
873         C2PortSuggestedBufferCountTuning;
874 constexpr char C2_PARAMKEY_INPUT_SUGGESTED_BUFFER_COUNT[] = "input.buffers.pool-size";
875 constexpr char C2_PARAMKEY_OUTPUT_SUGGESTED_BUFFER_COUNT[] = "output.buffers.pool-size";
876 
877 /**
878  * Input/output batching.
879  *
880  * For input, component requests that client batches work in batches of specified size. For output,
881  * client requests that the component batches work completion in given batch size.
882  * Value 0 means don't care.
883  */
884 typedef C2PortParam<C2Tuning, C2Uint64Array, kParamIndexBatchSize> C2PortBatchSizeTuning;
885 constexpr char C2_PARAMKEY_INPUT_BATCH_SIZE[] = "input.buffers.batch-size";
886 constexpr char C2_PARAMKEY_OUTPUT_BATCH_SIZE[] = "output.buffers.batch-size";
887 
888 /**
889  * Current & last work ordinals.
890  *
891  * input port: last work queued to component.
892  * output port: last work completed by component.
893  * global: current work.
894  */
895 typedef C2PortParam<C2Tuning, C2WorkOrdinalStruct, kParamIndexLastWorkQueued> C2LastWorkQueuedTuning;
896 typedef C2GlobalParam<C2Tuning, C2WorkOrdinalStruct, kParamIndexCurrentWork> C2CurrentWorkTuning;
897 
898 
899 /* ------------------------------------- memory allocation ------------------------------------- */
900 
901 /**
902  * Allocators to use.
903  *
904  * These are requested by the component.
905  *
906  * If none specified, client will use the default allocator ID based on the component domain and
907  * kind.
908  */
909 typedef C2PortParam<C2Tuning, C2SimpleArrayStruct<C2Allocator::id_t>, kParamIndexAllocators>
910         C2PortAllocatorsTuning;
911 constexpr char C2_PARAMKEY_INPUT_ALLOCATORS[] = "input.buffers.allocator-ids";
912 constexpr char C2_PARAMKEY_OUTPUT_ALLOCATORS[] = "output.buffers.allocator-ids";
913 
914 typedef C2GlobalParam<C2Tuning, C2SimpleArrayStruct<C2Allocator::id_t>, kParamIndexAllocators>
915         C2PrivateAllocatorsTuning;
916 constexpr char C2_PARAMKEY_PRIVATE_ALLOCATORS[] = "algo.buffers.allocator-ids";
917 
918 /**
919  * Allocator to use for outputting to surface.
920  *
921  * Components can optionally request allocator type for outputting to surface.
922  *
923  * If none specified, client will use the default BufferQueue-backed allocator ID for outputting to
924  * surface.
925  */
926 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexSurfaceAllocator>
927         C2PortSurfaceAllocatorTuning;
928 constexpr char C2_PARAMKEY_OUTPUT_SURFACE_ALLOCATOR[] = "output.buffers.surface-allocator-id";
929 
930 /**
931  * Block pools to use.
932  *
933  * These are allocated by the client for the component using the allocator IDs specified by the
934  * component. This is not used for the input port.
935  */
936 typedef C2PortParam<C2Tuning, C2SimpleArrayStruct<C2BlockPool::local_id_t>, kParamIndexBlockPools>
937         C2PortBlockPoolsTuning;
938 constexpr char C2_PARAMKEY_OUTPUT_BLOCK_POOLS[] = "output.buffers.pool-ids";
939 
940 typedef C2GlobalParam<C2Tuning, C2SimpleArrayStruct<C2BlockPool::local_id_t>, kParamIndexBlockPools>
941         C2PrivateBlockPoolsTuning;
942 constexpr char C2_PARAMKEY_PRIVATE_BLOCK_POOLS[] = "algo.buffers.pool-ids";
943 
944 /**
945  * The max number of private allocations at any one time by the component.
946  * (This is an array with a corresponding value for each private allocator)
947  */
948 typedef C2GlobalParam<C2Tuning, C2Uint32Array, kParamIndexMaxReferenceCount>
949         C2MaxPrivateBufferCountTuning;
950 constexpr char C2_PARAMKEY_MAX_PRIVATE_BUFFER_COUNT[] = "algo.buffers.max-count";
951 
952 /**
953  * Buffer type
954  *
955  * This is provided by the component for the client to allocate the proper buffer type for the
956  * input port, and can be provided by the client to control the buffer type for the output.
957  */
958 // private
959 typedef C2StreamParam<C2Setting, C2SimpleValueStruct<C2EasyEnum<C2BufferData::type_t>>,
960                 kParamIndexBufferType>
961         C2StreamBufferTypeSetting;
962 constexpr char C2_PARAMKEY_INPUT_STREAM_BUFFER_TYPE[] = "input.buffers.type";
963 constexpr char C2_PARAMKEY_OUTPUT_STREAM_BUFFER_TYPE[] = "output.buffers.type";
964 
965 /**
966  * Memory usage.
967  *
968  * Suggested by component for input and negotiated between client and component for output.
969  */
970 typedef C2StreamParam<C2Tuning, C2Uint64Value, kParamIndexUsage> C2StreamUsageTuning;
971 constexpr char C2_PARAMKEY_INPUT_STREAM_USAGE[] = "input.buffers.usage";
972 constexpr char C2_PARAMKEY_OUTPUT_STREAM_USAGE[] = "output.buffers.usage";
973 
974 /**
975  * Picture (video or image frame) size.
976  */
977 struct C2PictureSizeStruct {
C2PictureSizeStructC2PictureSizeStruct978     inline C2PictureSizeStruct()
979         : width(0), height(0) { }
980 
C2PictureSizeStructC2PictureSizeStruct981     inline C2PictureSizeStruct(uint32_t width_, uint32_t height_)
982         : width(width_), height(height_) { }
983 
984     uint32_t width;     ///< video width
985     uint32_t height;    ///< video height
986 
987     DEFINE_AND_DESCRIBE_C2STRUCT(PictureSize)
988     C2FIELD(width, "width")
989     C2FIELD(height, "height")
990 };
991 
992 /**
993  * Out of memory signaling
994  *
995  * This is a configuration for the client to mark that it cannot allocate necessary private and/
996  * or output buffers to continue operation, and to signal the failing configuration.
997  */
998 struct C2OutOfMemoryStruct {
999     C2BlockPool::local_id_t pool;   ///< pool ID that failed the allocation
1000     uint64_t usage;                 ///< memory usage used
1001     C2PictureSizeStruct planar;     ///< buffer dimensions to be allocated if 2D
1002     uint32_t format;                ///< pixel format to be used if 2D
1003     uint32_t capacity;              ///< buffer capacity to be allocated if 1D
1004     c2_bool_t outOfMemory;           ///< true if component is out of memory
1005 
1006     DEFINE_AND_DESCRIBE_C2STRUCT(OutOfMemory)
1007     C2FIELD(pool, "pool")
1008     C2FIELD(usage, "usage")
1009     C2FIELD(planar, "planar")
1010     C2FIELD(format, "format")
1011     C2FIELD(capacity, "capacity")
1012     C2FIELD(outOfMemory, "out-of-memory")
1013 };
1014 
1015 typedef C2GlobalParam<C2Tuning, C2OutOfMemoryStruct, kParamIndexOutOfMemory> C2OutOfMemoryTuning;
1016 constexpr char C2_PARAMKEY_OUT_OF_MEMORY[] = "algo.oom";
1017 
1018 /**
1019  * Max buffer size
1020  *
1021  * This is a hint provided by the component for the maximum buffer size expected on a stream for the
1022  * current configuration on its input and output streams. This is communicated to clients so they
1023  * can preallocate input buffers, or configure downstream components that require a maximum size on
1024  * their buffers.
1025  *
1026  * Read-only. Required to be provided by components on all compressed streams.
1027  */
1028 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexMaxBufferSize> C2StreamMaxBufferSizeInfo;
1029 constexpr char C2_PARAMKEY_INPUT_MAX_BUFFER_SIZE[] = "input.buffers.max-size";
1030 constexpr char C2_PARAMKEY_OUTPUT_MAX_BUFFER_SIZE[] = "output.buffers.max-size";
1031 
1032 /* ---------------------------------------- misc. state ---------------------------------------- */
1033 
1034 /**
1035  * Tripped state,
1036  *
1037  * This state exists to be able to provide reasoning for a tripped state during normal
1038  * interface operations, as well as to allow client to trip the component on demand.
1039  */
1040 typedef C2GlobalParam<C2Tuning, C2BoolValue, kParamIndexTripped>
1041         C2TrippedTuning;
1042 constexpr char C2_PARAMKEY_TRIPPED[] = "algo.tripped";
1043 
1044 /**
1045  * Configuration counters.
1046  *
1047  * Configurations are tracked using three counters. The input counter is incremented exactly
1048  * once with each work accepted by the component. The output counter is incremented exactly
1049  * once with each work completed by the component (in the order of work completion). The
1050  * global counter is incremented exactly once during to each config() call. These counters
1051  * shall be read-only.
1052  *
1053  * TODO: these should be counters.
1054  */
1055 typedef C2PortParam<C2Tuning, C2Uint64Value, kParamIndexConfigCounter> C2PortConfigCounterTuning;
1056 typedef C2GlobalParam<C2Tuning, C2Uint64Value, kParamIndexConfigCounter> C2ConfigCounterTuning;
1057 constexpr char C2_PARAMKEY_INPUT_COUNTER[] = "input.buffers.counter";
1058 constexpr char C2_PARAMKEY_OUTPUT_COUNTER[] = "output.buffers.counter";
1059 constexpr char C2_PARAMKEY_CONFIG_COUNTER[] = "algo.config.counter";
1060 
1061 /* ----------------------------------------- resources ----------------------------------------- */
1062 
1063 /**
1064  * Resources needed and resources reserved for current configuration.
1065  *
1066  * Resources are tracked as a vector of positive numbers. Available resources are defined by
1067  * the vendor.
1068  *
1069  * By default, no resources are reserved for a component. If resource reservation is successful,
1070  * the component shall be able to use those resources exclusively. If however, the component is
1071  * not using all of the reserved resources, those may be shared with other components.
1072  *
1073  * TODO: define some of the resources.
1074  */
1075 typedef C2GlobalParam<C2Tuning, C2Uint64Array, kParamIndexResourcesNeeded> C2ResourcesNeededTuning;
1076 typedef C2GlobalParam<C2Tuning, C2Uint64Array, kParamIndexResourcesReserved>
1077         C2ResourcesReservedTuning;
1078 constexpr char C2_PARAMKEY_RESOURCES_NEEDED[] = "resources.needed";
1079 constexpr char C2_PARAMKEY_RESOURCES_RESERVED[] = "resources.reserved";
1080 
1081 /**
1082  * Operating rate.
1083  *
1084  * Operating rate is the expected rate of work through the component. Negative values is
1085  * invalid.
1086  *
1087  * TODO: this could distinguish set value
1088  */
1089 typedef C2GlobalParam<C2Tuning, C2FloatValue, kParamIndexOperatingRate> C2OperatingRateTuning;
1090 constexpr char C2_PARAMKEY_OPERATING_RATE[] = "algo.rate";
1091 
1092 /**
1093  * Realtime / operating point.
1094  *
1095  * Priority value defines the operating point for the component. Operating points are defined by
1096  * the vendor. Priority value of 0 means that the client requires operation at the given operating
1097  * rate. Priority values -1 and below define operating points in decreasing performance. In this
1098  * case client expects best effort without exceeding the specific operating point. This allows
1099  * client to run components deeper in the background by using larger priority values. In these
1100  * cases operating rate is a hint for the maximum rate that the client anticipates.
1101  *
1102  * Operating rate and priority are used in tandem. E.g. if there are components that run at a
1103  * higher operating point (priority) it will make more resources available for components at
1104  * a lower operating point, so operating rate can be used to gate those components.
1105  *
1106  * Positive priority values are not defined at the moment and shall be treated equivalent to 0.
1107  */
1108 typedef C2GlobalParam<C2Tuning, C2Int32Value, kParamIndexRealTimePriority>
1109         C2RealTimePriorityTuning;
1110 constexpr char C2_PARAMKEY_PRIORITY[] = "algo.priority";
1111 
1112 /* ------------------------------------- protected content ------------------------------------- */
1113 
1114 /**
1115  * Secure mode.
1116  */
1117 C2ENUM(C2Config::secure_mode_t, uint32_t,
1118     SM_UNPROTECTED,    ///< no content protection
1119     SM_READ_PROTECTED, ///< input and output buffers shall be protected from reading
1120 )
1121 
1122 typedef C2GlobalParam<C2Tuning, C2SimpleValueStruct<C2Config::secure_mode_t>, kParamIndexSecureMode>
1123         C2SecureModeTuning;
1124 constexpr char C2_PARAMKEY_SECURE_MODE[] = "algo.secure-mode";
1125 
1126 /* ===================================== ENCODER COMPONENTS ===================================== */
1127 
1128 /**
1129  * Bitrate
1130  */
1131 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexBitrate> C2StreamBitrateInfo;
1132 constexpr char C2_PARAMKEY_BITRATE[] = "coded.bitrate";
1133 
1134 /**
1135  * Bitrate mode.
1136  *
1137  * TODO: refine this with bitrate ranges and suggested window
1138  */
1139 C2ENUM(C2Config::bitrate_mode_t, uint32_t,
1140     BITRATE_CONST_SKIP_ALLOWED = 0,      ///< constant bitrate, frame skipping allowed
1141     BITRATE_CONST = 1,                   ///< constant bitrate, keep all frames
1142     BITRATE_VARIABLE_SKIP_ALLOWED = 2,   ///< bitrate can vary, frame skipping allowed
1143     BITRATE_VARIABLE = 3,                ///< bitrate can vary, keep all frames
1144     BITRATE_IGNORE = 7,                  ///< bitrate can be exceeded at will to achieve
1145                                          ///< quality or other settings
1146 
1147     // bitrate modes are composed of the following flags
1148     BITRATE_FLAG_KEEP_ALL_FRAMES = 1,
1149     BITRATE_FLAG_CAN_VARY = 2,
1150     BITRATE_FLAG_CAN_EXCEED = 4,
1151 )
1152 
1153 typedef C2StreamParam<C2Tuning, C2SimpleValueStruct<C2Config::bitrate_mode_t>,
1154                 kParamIndexBitrateMode>
1155         C2StreamBitrateModeTuning;
1156 constexpr char C2_PARAMKEY_BITRATE_MODE[] = "algo.bitrate-mode";
1157 
1158 /**
1159  * Quality.
1160  *
1161  * This is defined by each component, the higher the better the output quality at the expense of
1162  * less compression efficiency. This setting is defined for the output streams in case the
1163  * component can support varying quality on each stream, or as an output port tuning in case the
1164  * quality is global to all streams.
1165  */
1166 typedef C2StreamParam<C2Tuning, C2Uint32Value, kParamIndexQuality> C2StreamQualityTuning;
1167 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexQuality> C2QualityTuning;
1168 constexpr char C2_PARAMKEY_QUALITY[] = "algo.quality";
1169 
1170 /**
1171  * Complexity.
1172  *
1173  * This is defined by each component, this higher the value, the more resources the component
1174  * will use to produce better quality at the same compression efficiency or better compression
1175  * efficiency at the same quality. This setting is defined for the output streams in case the
1176  * component can support varying complexity on each stream, or as an output port tuning in case the
1177  * quality is global to all streams
1178  */
1179 typedef C2StreamParam<C2Tuning, C2Uint32Value, kParamIndexComplexity> C2StreamComplexityTuning;
1180 typedef C2PortParam<C2Tuning, C2Uint32Value, kParamIndexComplexity> C2ComplexityTuning;
1181 constexpr char C2_PARAMKEY_COMPLEXITY[] = "algo.complexity";
1182 
1183 /**
1184  * Header (init-data) handling around sync frames.
1185  */
1186 C2ENUM(C2Config::prepend_header_mode_t, uint32_t,
1187     /**
1188      * don't prepend header. Signal header only through C2StreamInitDataInfo.
1189      */
1190     PREPEND_HEADER_TO_NONE,
1191 
1192     /**
1193      * prepend header before the first output frame and thereafter before the next sync frame
1194      * if it changes.
1195      */
1196     PREPEND_HEADER_ON_CHANGE,
1197 
1198     /**
1199      * prepend header before every sync frame.
1200      */
1201     PREPEND_HEADER_TO_ALL_SYNC,
1202 )
1203 
1204 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Config::prepend_header_mode_t>,
1205                 kParamIndexPrependHeaderMode>
1206         C2PrependHeaderModeSetting;
1207 constexpr char C2_PARAMKEY_PREPEND_HEADER_MODE[] = "output.buffers.prepend-header";
1208 
1209 /* =================================== IMAGE/VIDEO COMPONENTS =================================== */
1210 
1211 /*
1212  * Order of transformation is:
1213  *
1214  * crop => (scaling => scaled-crop) => sample-aspect-ratio => flip => rotation
1215  */
1216 
1217 /**
1218  * Picture (image- and video frame) size.
1219  *
1220  * This is used for the output of the video decoder, and the input of the video encoder.
1221  */
1222 typedef C2StreamParam<C2Info, C2PictureSizeStruct, kParamIndexPictureSize> C2StreamPictureSizeInfo;
1223 constexpr char C2_PARAMKEY_PICTURE_SIZE[] = "raw.size";
1224 
1225 /**
1226  * Crop rectangle.
1227  */
1228 struct C2RectStruct : C2Rect {
1229     C2RectStruct() = default;
C2RectStructC2RectStruct1230     C2RectStruct(const C2Rect &rect) : C2Rect(rect) { }
1231 
1232     bool operator==(const C2RectStruct &) = delete;
1233     bool operator!=(const C2RectStruct &) = delete;
1234 
1235     DEFINE_AND_DESCRIBE_BASE_C2STRUCT(Rect)
1236     C2FIELD(width, "width")
1237     C2FIELD(height, "height")
1238     C2FIELD(left, "left")
1239     C2FIELD(top, "top")
1240 };
1241 
1242 typedef C2StreamParam<C2Info, C2RectStruct, kParamIndexCropRect> C2StreamCropRectInfo;
1243 constexpr char C2_PARAMKEY_CROP_RECT[] = "raw.crop";
1244 constexpr char C2_PARAMKEY_CODED_CROP_RECT[] = "coded.crop";
1245 
1246 /**
1247  * Pixel format.
1248  */
1249 // TODO: define some
1250 
1251 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexPixelFormat> C2StreamPixelFormatInfo;
1252 constexpr char C2_PARAMKEY_PIXEL_FORMAT[] = "raw.pixel-format";
1253 
1254 /**
1255  * Extended rotation information also incorporating a flip.
1256  *
1257  * Rotation is counter clock-wise.
1258  */
1259 struct C2RotationStruct {
1260     C2RotationStruct(int32_t rotation = 0)
1261         : flip(0), value(rotation) { }
1262 
1263     int32_t flip;   ///< horizontal flip (left-right flip applied prior to rotation)
1264     int32_t value;  ///< rotation in degrees counter clockwise
1265 
1266     DEFINE_AND_DESCRIBE_BASE_C2STRUCT(Rotation)
1267     C2FIELD(flip, "flip")
1268     C2FIELD(value, "value")
1269 };
1270 
1271 typedef C2StreamParam<C2Info, C2RotationStruct, kParamIndexRotation> C2StreamRotationInfo;
1272 constexpr char C2_PARAMKEY_ROTATION[] = "raw.rotation";
1273 constexpr char C2_PARAMKEY_VUI_ROTATION[] = "coded.vui.rotation";
1274 
1275 /**
1276  * Pixel (sample) aspect ratio.
1277  */
1278 typedef C2StreamParam<C2Info, C2PictureSizeStruct, kParamIndexPixelAspectRatio>
1279         C2StreamPixelAspectRatioInfo;
1280 constexpr char C2_PARAMKEY_PIXEL_ASPECT_RATIO[] = "raw.sar";
1281 constexpr char C2_PARAMKEY_VUI_PIXEL_ASPECT_RATIO[] = "coded.vui.sar";
1282 
1283 /**
1284  * In-line scaling.
1285  *
1286  * Components can optionally support scaling of raw image/video frames.  Or scaling only a
1287  * portion of raw image/video frames (scaled-crop).
1288  */
1289 
1290 C2ENUM(C2Config::scaling_method_t, uint32_t,
1291     SCALING_ARBITRARY,   ///< arbitrary, unspecified
1292 )
1293 
1294 typedef C2StreamParam<C2Tuning, C2SimpleValueStruct<C2Config::scaling_method_t>,
1295                 kParamIndexScalingMethod>
1296         C2StreamScalingMethodTuning;
1297 constexpr char C2_PARAMKEY_SCALING_MODE[] = "raw.scaling-method";
1298 
1299 typedef C2StreamParam<C2Tuning, C2PictureSizeStruct, kParamIndexScaledPictureSize>
1300         C2StreamScaledPictureSizeTuning;
1301 constexpr char C2_PARAMKEY_SCALED_PICTURE_SIZE[] = "raw.scaled-size";
1302 
1303 typedef C2StreamParam<C2Tuning, C2RectStruct, kParamIndexScaledCropRect>
1304         C2StreamScaledCropRectTuning;
1305 constexpr char C2_PARAMKEY_SCALED_CROP_RECT[] = "raw.scaled-crop";
1306 
1307 /* ------------------------------------- color information ------------------------------------- */
1308 
1309 /**
1310  * Color Info
1311  *
1312  * Chroma location can vary for top and bottom fields, so use an array, that can have 0 to 2
1313  * values. Empty array is used for non YUV formats.
1314  */
1315 
1316 struct C2Color {
1317     enum matrix_t : uint32_t;  ///< matrix coefficient (YUV <=> RGB)
1318     enum plane_layout_t : uint32_t;  ///< plane layout for flexible formats
1319     enum primaries_t : uint32_t;  ///< color primaries and white point
1320     enum range_t : uint32_t;  ///< range of color component values
1321     enum subsampling_t : uint32_t;  ///< chroma subsampling
1322     enum transfer_t : uint32_t;  ///< transfer function
1323 };
1324 
1325 /// Chroma subsampling
1326 C2ENUM(C2Color::subsampling_t, uint32_t,
1327     MONOCHROME,     ///< there are no Cr nor Cb planes
1328     MONOCHROME_ALPHA, ///< there are no Cr nor Cb planes, but there is an alpha plane
1329     RGB,            ///< RGB
1330     RGBA,           ///< RGBA
1331     YUV_420,        ///< Cr and Cb planes are subsampled by 2 both horizontally and vertically
1332     YUV_422,        ///< Cr and Cb planes are subsampled horizontally
1333     YUV_444,        ///< Cr and Cb planes are not subsampled
1334     YUVA_444,       ///< Cr and Cb planes are not subsampled, there is an alpha plane
1335 )
1336 
1337 struct C2ChromaOffsetStruct {
1338     // chroma offsets defined by ITU
ITU_YUV_444C2ChromaOffsetStruct1339     constexpr static C2ChromaOffsetStruct ITU_YUV_444() { return { 0.0f, 0.0f }; }
ITU_YUV_422C2ChromaOffsetStruct1340     constexpr static C2ChromaOffsetStruct ITU_YUV_422() { return { 0.0f, 0.0f }; }
ITU_YUV_420_0C2ChromaOffsetStruct1341     constexpr static C2ChromaOffsetStruct ITU_YUV_420_0() { return { 0.0f, 0.5f }; }
ITU_YUV_420_1C2ChromaOffsetStruct1342     constexpr static C2ChromaOffsetStruct ITU_YUV_420_1() { return { 0.5f, 0.5f }; }
ITU_YUV_420_2C2ChromaOffsetStruct1343     constexpr static C2ChromaOffsetStruct ITU_YUV_420_2() { return { 0.0f, 0.0f }; }
ITU_YUV_420_3C2ChromaOffsetStruct1344     constexpr static C2ChromaOffsetStruct ITU_YUV_420_3() { return { 0.5f, 0.0f }; }
ITU_YUV_420_4C2ChromaOffsetStruct1345     constexpr static C2ChromaOffsetStruct ITU_YUV_420_4() { return { 0.0f, 1.0f }; }
ITU_YUV_420_5C2ChromaOffsetStruct1346     constexpr static C2ChromaOffsetStruct ITU_YUV_420_5() { return { 0.5f, 1.0f }; }
1347 
1348     float x;    ///< x offset in pixels (towards right)
1349     float y;    ///< y offset in pixels (towards down)
1350 
1351     DEFINE_AND_DESCRIBE_C2STRUCT(ChromaOffset)
1352     C2FIELD(x, "x")
1353     C2FIELD(y, "y")
1354 };
1355 
1356 struct C2ColorInfoStruct {
C2ColorInfoStructC2ColorInfoStruct1357     C2ColorInfoStruct()
1358         : bitDepth(8), subsampling(C2Color::YUV_420) { }
1359 
1360     uint32_t bitDepth;
1361     C2Color::subsampling_t subsampling;
1362     C2ChromaOffsetStruct locations[]; // max 2 elements
1363 
C2ColorInfoStructC2ColorInfoStruct1364     C2ColorInfoStruct(
1365             size_t /* flexCount */, uint32_t bitDepth_, C2Color::subsampling_t subsampling_)
1366         : bitDepth(bitDepth_), subsampling(subsampling_) { }
1367 
C2ColorInfoStructC2ColorInfoStruct1368     C2ColorInfoStruct(
1369             size_t flexCount, uint32_t bitDepth_, C2Color::subsampling_t subsampling_,
1370             std::initializer_list<C2ChromaOffsetStruct> locations_)
1371         : bitDepth(bitDepth_), subsampling(subsampling_) {
1372         size_t ix = 0;
1373         for (const C2ChromaOffsetStruct &location : locations_) {
1374             if (ix == flexCount) {
1375                 break;
1376             }
1377             locations[ix] = location;
1378             ++ix;
1379         }
1380     }
1381 
1382     DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(ColorInfo, locations)
1383     C2FIELD(bitDepth, "bit-depth")
1384     C2FIELD(subsampling, "subsampling")
1385     C2FIELD(locations, "locations")
1386 };
1387 
1388 typedef C2StreamParam<C2Info, C2ColorInfoStruct, kParamIndexColorInfo> C2StreamColorInfo;
1389 constexpr char C2_PARAMKEY_COLOR_INFO[] = "raw.color-format";
1390 constexpr char C2_PARAMKEY_CODED_COLOR_INFO[] = "coded.color-format";
1391 
1392 /**
1393  * Color Aspects
1394  */
1395 
1396 /* The meaning of the following enumerators is as described in ITU-T H.273. */
1397 
1398 /// Range
1399 C2ENUM(C2Color::range_t, uint32_t,
1400     RANGE_UNSPECIFIED,          ///< range is unspecified
1401     RANGE_FULL,                 ///< full range
1402     RANGE_LIMITED,              ///< limited range
1403 
1404     RANGE_VENDOR_START = 0x80,  ///< vendor-specific range values start here
1405     RANGE_OTHER = 0XFF          ///< max value, reserved for undefined values
1406 )
1407 
1408 /// Color primaries
1409 C2ENUM(C2Color::primaries_t, uint32_t,
1410     PRIMARIES_UNSPECIFIED,          ///< primaries are unspecified
1411     PRIMARIES_BT709,                ///< Rec.ITU-R BT.709-6 or equivalent
1412     PRIMARIES_BT470_M,              ///< Rec.ITU-R BT.470-6 System M or equivalent
1413     PRIMARIES_BT601_625,            ///< Rec.ITU-R BT.601-6 625 or equivalent
1414     PRIMARIES_BT601_525,            ///< Rec.ITU-R BT.601-6 525 or equivalent
1415     PRIMARIES_GENERIC_FILM,         ///< Generic Film
1416     PRIMARIES_BT2020,               ///< Rec.ITU-R BT.2020 or equivalent
1417     PRIMARIES_RP431,                ///< SMPTE RP 431-2 or equivalent
1418     PRIMARIES_EG432,                ///< SMPTE EG 432-1 or equivalent
1419     PRIMARIES_EBU3213,              ///< EBU Tech.3213-E or equivalent
1420                                     ///
1421     PRIMARIES_VENDOR_START = 0x80,  ///< vendor-specific primaries values start here
1422     PRIMARIES_OTHER = 0xff          ///< max value, reserved for undefined values
1423 )
1424 
1425 /// Transfer function
1426 C2ENUM(C2Color::transfer_t, uint32_t,
1427     TRANSFER_UNSPECIFIED,           ///< transfer is unspecified
1428     TRANSFER_LINEAR,                ///< Linear transfer characteristics
1429     TRANSFER_SRGB,                  ///< sRGB or equivalent
1430     TRANSFER_170M,                  ///< SMPTE 170M or equivalent (e.g. BT.601/709/2020)
1431     TRANSFER_GAMMA22,               ///< Assumed display gamma 2.2
1432     TRANSFER_GAMMA28,               ///< Assumed display gamma 2.8
1433     TRANSFER_ST2084,                ///< SMPTE ST 2084 for 10/12/14/16 bit systems
1434     TRANSFER_HLG,                   ///< ARIB STD-B67 hybrid-log-gamma
1435 
1436     TRANSFER_240M = 0x40,           ///< SMPTE 240M or equivalent
1437     TRANSFER_XVYCC,                 ///< IEC 61966-2-4 or equivalent
1438     TRANSFER_BT1361,                ///< Rec.ITU-R BT.1361 extended gamut
1439     TRANSFER_ST428,                 ///< SMPTE ST 428-1 or equivalent
1440                                     ///
1441     TRANSFER_VENDOR_START = 0x80,   ///< vendor-specific transfer values start here
1442     TRANSFER_OTHER = 0xff           ///< max value, reserved for undefined values
1443 )
1444 
1445 /// Matrix coefficient
1446 C2ENUM(C2Color::matrix_t, uint32_t,
1447     MATRIX_UNSPECIFIED,             ///< matrix coefficients are unspecified
1448     MATRIX_BT709,                   ///< Rec.ITU-R BT.709-5 or equivalent
1449     MATRIX_FCC47_73_682,            ///< FCC Title 47 CFR 73.682 or equivalent (KR=0.30, KB=0.11)
1450     MATRIX_BT601,                   ///< Rec.ITU-R BT.470, BT.601-6 625 or equivalent
1451     MATRIX_240M,                    ///< SMPTE 240M or equivalent
1452     MATRIX_BT2020,                  ///< Rec.ITU-R BT.2020 non-constant luminance
1453     MATRIX_BT2020_CONSTANT,         ///< Rec.ITU-R BT.2020 constant luminance
1454     MATRIX_VENDOR_START = 0x80,     ///< vendor-specific matrix coefficient values start here
1455     MATRIX_OTHER = 0xff,            ///< max value, reserved for undefined values
1456 )
1457 
1458 struct C2ColorAspectsStruct {
1459     C2Color::range_t range;
1460     C2Color::primaries_t primaries;
1461     C2Color::transfer_t transfer;
1462     C2Color::matrix_t matrix;
1463 
C2ColorAspectsStructC2ColorAspectsStruct1464     C2ColorAspectsStruct()
1465         : range(C2Color::RANGE_UNSPECIFIED),
1466           primaries(C2Color::PRIMARIES_UNSPECIFIED),
1467           transfer(C2Color::TRANSFER_UNSPECIFIED),
1468           matrix(C2Color::MATRIX_UNSPECIFIED) { }
1469 
C2ColorAspectsStructC2ColorAspectsStruct1470     C2ColorAspectsStruct(C2Color::range_t range_, C2Color::primaries_t primaries_,
1471                          C2Color::transfer_t transfer_, C2Color::matrix_t matrix_)
1472         : range(range_), primaries(primaries_), transfer(transfer_), matrix(matrix_) {}
1473 
1474     DEFINE_AND_DESCRIBE_C2STRUCT(ColorAspects)
1475     C2FIELD(range, "range")
1476     C2FIELD(primaries, "primaries")
1477     C2FIELD(transfer, "transfer")
1478     C2FIELD(matrix, "matrix")
1479 };
1480 
1481 typedef C2StreamParam<C2Info, C2ColorAspectsStruct, kParamIndexColorAspects>
1482         C2StreamColorAspectsInfo;
1483 constexpr char C2_PARAMKEY_COLOR_ASPECTS[] = "raw.color";
1484 constexpr char C2_PARAMKEY_VUI_COLOR_ASPECTS[] = "coded.vui.color";
1485 
1486 /**
1487  * Default color aspects to use. These come from the container or client and shall be handled
1488  * according to the coding standard.
1489  */
1490 typedef C2StreamParam<C2Tuning, C2ColorAspectsStruct, kParamIndexDefaultColorAspects>
1491         C2StreamColorAspectsTuning;
1492 constexpr char C2_PARAMKEY_DEFAULT_COLOR_ASPECTS[] = "default.color";
1493 
1494 /**
1495  * HDR Static Metadata Info.
1496  */
1497 struct C2ColorXyStruct {
1498     float x; ///< x color coordinate in xyY space [0-1]
1499     float y; ///< y color coordinate in xyY space [0-1]
1500 
1501     DEFINE_AND_DESCRIBE_C2STRUCT(ColorXy)
1502     C2FIELD(x, "x")
1503     C2FIELD(y, "y")
1504 };
1505 
1506 struct C2MasteringDisplayColorVolumeStruct {
1507     C2ColorXyStruct red;    ///< coordinates of red display primary
1508     C2ColorXyStruct green;  ///< coordinates of green display primary
1509     C2ColorXyStruct blue;   ///< coordinates of blue display primary
1510     C2ColorXyStruct white;  ///< coordinates of white point
1511 
1512     float maxLuminance;  ///< max display mastering luminance in cd/m^2
1513     float minLuminance;  ///< min display mastering luminance in cd/m^2
1514 
1515     DEFINE_AND_DESCRIBE_C2STRUCT(MasteringDisplayColorVolume)
1516     C2FIELD(red, "red")
1517     C2FIELD(green, "green")
1518     C2FIELD(blue, "blue")
1519     C2FIELD(white, "white")
1520 
1521     C2FIELD(maxLuminance, "max-luminance")
1522     C2FIELD(minLuminance, "min-luminance")
1523 };
1524 
1525 struct C2HdrStaticMetadataStruct {
1526     C2MasteringDisplayColorVolumeStruct mastering;
1527 
1528     // content descriptors
1529     float maxCll;  ///< max content light level (pixel luminance) in cd/m^2
1530     float maxFall; ///< max frame average light level (frame luminance) in cd/m^2
1531 
1532     DEFINE_AND_DESCRIBE_BASE_C2STRUCT(HdrStaticMetadata)
1533     C2FIELD(mastering, "mastering")
1534     C2FIELD(maxCll, "max-cll")
1535     C2FIELD(maxFall, "max-fall")
1536 };
1537 typedef C2StreamParam<C2Info, C2HdrStaticMetadataStruct, kParamIndexHdrStaticMetadata>
1538         C2StreamHdrStaticInfo;
1539 constexpr char C2_PARAMKEY_HDR_STATIC_INFO[] = "raw.hdr-static-info";
1540 
1541 /**
1542  * HDR10+ Metadata Info.
1543  */
1544 typedef C2StreamParam<C2Info, C2BlobValue, kParamIndexHdr10PlusMetadata>
1545         C2StreamHdr10PlusInfo;
1546 constexpr char C2_PARAMKEY_INPUT_HDR10_PLUS_INFO[] = "input.hdr10-plus-info";
1547 constexpr char C2_PARAMKEY_OUTPUT_HDR10_PLUS_INFO[] = "output.hdr10-plus-info";
1548 
1549 /* ------------------------------------ block-based coding ----------------------------------- */
1550 
1551 /**
1552  * Block-size, block count and block rate. Used to determine or communicate profile-level
1553  * requirements.
1554  */
1555 typedef C2StreamParam<C2Info, C2PictureSizeStruct, kParamIndexBlockSize> C2StreamBlockSizeInfo;
1556 constexpr char C2_PARAMKEY_BLOCK_SIZE[] = "coded.block-size";
1557 
1558 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexBlockCount> C2StreamBlockCountInfo;
1559 constexpr char C2_PARAMKEY_BLOCK_COUNT[] = "coded.block-count";
1560 
1561 typedef C2StreamParam<C2Info, C2FloatValue, kParamIndexBlockRate> C2StreamBlockRateInfo;
1562 constexpr char C2_PARAMKEY_BLOCK_RATE[] = "coded.block-rate";
1563 
1564 /* ====================================== VIDEO COMPONENTS ====================================== */
1565 
1566 /**
1567  * Frame rate (coded and port for raw data)
1568  *
1569  * Coded frame rates are what is represented in the compressed bitstream and should correspond to
1570  * the timestamp.
1571  *
1572  * Frame rates on raw ports should still correspond to the timestamps.
1573  *
1574  * For slow motion or timelapse recording, the timestamp shall be adjusted prior to feeding an
1575  * encoder, and the time stretch parameter should be used to signal the relationship between
1576  * timestamp and real-world time.
1577  */
1578 typedef C2StreamParam<C2Info, C2FloatValue, kParamIndexFrameRate> C2StreamFrameRateInfo;
1579 constexpr char C2_PARAMKEY_FRAME_RATE[] = "coded.frame-rate";
1580 
1581 typedef C2PortParam<C2Info, C2FloatValue, kParamIndexFrameRate> C2PortFrameRateInfo;
1582 constexpr char C2_PARAMKEY_INPUT_FRAME_RATE[] = "input.frame-rate";
1583 constexpr char C2_PARAMKEY_OUTPUT_FRAME_RATE[] = "output.frame-rate";
1584 
1585 /**
1586  * Time stretch. Ratio between real-world time and timestamp. E.g. time stretch of 4.0 means that
1587  * timestamp grows 1/4 the speed of real-world time (e.g. 4x slo-mo input). This can be used to
1588  * optimize encoding.
1589  */
1590 typedef C2PortParam<C2Info, C2FloatValue, kParamIndexTimeStretch> C2PortTimeStretchInfo;
1591 constexpr char C2_PARAMKEY_INPUT_TIME_STRETCH[] = "input.time-stretch";
1592 constexpr char C2_PARAMKEY_OUTPUT_TIME_STRETCH[] = "output.time-stretch";
1593 
1594 /**
1595  * Max video frame size.
1596  */
1597 typedef C2StreamParam<C2Tuning, C2PictureSizeStruct, kParamIndexMaxPictureSize>
1598         C2StreamMaxPictureSizeTuning;
1599 typedef C2StreamMaxPictureSizeTuning C2MaxVideoSizeHintPortSetting;
1600 constexpr char C2_PARAMKEY_MAX_PICTURE_SIZE[] = "raw.max-size";
1601 
1602 /**
1603  * Picture type mask.
1604  */
1605 C2ENUM(C2Config::picture_type_t, uint32_t,
1606     SYNC_FRAME = (1 << 0),  ///< sync frame, e.g. IDR
1607     I_FRAME    = (1 << 1),  ///< intra frame that is completely encoded
1608     P_FRAME    = (1 << 2),  ///< inter predicted frame from previous frames
1609     B_FRAME    = (1 << 3),  ///< backward predicted (out-of-order) frame
1610 )
1611 
1612 /**
1613  * Allowed picture types.
1614  */
1615 typedef C2StreamParam<C2Tuning, C2SimpleValueStruct<C2EasyEnum<C2Config::picture_type_t>>,
1616                 kParamIndexPictureTypeMask>
1617         C2StreamPictureTypeMaskTuning;
1618 constexpr char C2_PARAMKEY_PICTURE_TYPE_MASK[] = "coding.picture-type-mask";
1619 
1620 /**
1621  * Resulting picture type
1622  */
1623 typedef C2StreamParam<C2Info, C2SimpleValueStruct<C2EasyEnum<C2Config::picture_type_t>>,
1624                 kParamIndexPictureType>
1625         C2StreamPictureTypeInfo;
1626 typedef C2StreamPictureTypeInfo C2StreamPictureTypeMaskInfo;
1627 constexpr char C2_PARAMKEY_PICTURE_TYPE[] = "coded.picture-type";
1628 
1629 /**
1630  * GOP specification.
1631  *
1632  * GOP is specified in layers between sync frames, by specifying the number of specific type of
1633  * frames between the previous type (starting with sync frames for the first layer):
1634  *
1635  * E.g.
1636  *      - 4 I frames between each sync frame
1637  *      - 2 P frames between each I frame
1638  *      - 1 B frame between each P frame
1639  *
1640  *      [ { I, 4 }, { P, 2 }, { B, 1 } ] ==> (Sync)BPBPB IBPBPB IBPBPB IBPBPB IBPBPB (Sync)BPBPB
1641  *
1642  * For infinite GOP, I layer can be omitted (as the first frame is always a sync frame.):
1643  *
1644  *      [ { P, MAX_UINT } ]   ==> (Sync)PPPPPPPPPPPPPPPPPP...
1645  *
1646  * Sync frames can also be requested on demand, and as a time-based interval. For time-based
1647  * interval, if there hasn't been a sync frame in at least the given time, the next I frame shall
1648  * be encoded as a sync frame.  For sync request, the next I frame shall be encoded as a sync frame.
1649  *
1650  * Temporal layering will determine GOP structure other than the I frame count between sync
1651  * frames.
1652  */
1653 struct C2GopLayerStruct {
C2GopLayerStructC2GopLayerStruct1654     C2GopLayerStruct() : type_((C2Config::picture_type_t)0), count(0) {}
C2GopLayerStructC2GopLayerStruct1655     C2GopLayerStruct(C2Config::picture_type_t type, uint32_t count_)
1656         : type_(type), count(count_) { }
1657 
1658     C2Config::picture_type_t type_;
1659     uint32_t count;
1660 
1661     DEFINE_AND_DESCRIBE_C2STRUCT(GopLayer)
1662     C2FIELD(type_, "type")
1663     C2FIELD(count, "count")
1664 };
1665 
1666 typedef C2StreamParam<C2Tuning, C2SimpleArrayStruct<C2GopLayerStruct>, kParamIndexGop>
1667         C2StreamGopTuning;
1668 constexpr char C2_PARAMKEY_GOP[] = "coding.gop";
1669 
1670 /**
1671  * Sync frame can be requested on demand by the client.
1672  *
1673  * If true, the next I frame shall be encoded as a sync frame. This config can be passed
1674  * synchronously with the work, or directly to the component - leading to different result.
1675  * If it is passed with work, it shall take effect when that work item is being processed (so
1676  * the first I frame at or after that work item shall be a sync frame).
1677  */
1678 typedef C2StreamParam<C2Tuning, C2EasyBoolValue, kParamIndexRequestSyncFrame>
1679         C2StreamRequestSyncFrameTuning;
1680 constexpr char C2_PARAMKEY_REQUEST_SYNC_FRAME[] = "coding.request-sync-frame";
1681 
1682 /**
1683  * Sync frame interval in time domain (timestamp).
1684  *
1685  * If there hasn't been a sync frame in at least this value, the next intra frame shall be encoded
1686  * as a sync frame. The value of MAX_I64 or a negative value means no sync frames after the first
1687  * frame. A value of 0 means all sync frames.
1688  */
1689 typedef C2StreamParam<C2Tuning, C2Int64Value, kParamIndexSyncFrameInterval>
1690         C2StreamSyncFrameIntervalTuning;
1691 constexpr char C2_PARAMKEY_SYNC_FRAME_INTERVAL[] = "coding.sync-frame-interval";
1692 
1693 /**
1694  * Temporal layering
1695  *
1696  * Layer index is a value between 0 and layer count - 1. Layers with higher index have higher
1697  * frequency:
1698  *     0
1699  *   1   1
1700  *  2 2 2 2
1701  */
1702 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexLayerIndex> C2StreamLayerIndexInfo;
1703 constexpr char C2_PARAMKEY_LAYER_INDEX[] = "coded.layer-index";
1704 
1705 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexLayerCount> C2StreamLayerCountInfo;
1706 constexpr char C2_PARAMKEY_LAYER_COUNT[] = "coded.layer-count";
1707 
1708 struct C2TemporalLayeringStruct {
C2TemporalLayeringStructC2TemporalLayeringStruct1709     C2TemporalLayeringStruct()
1710         : layerCount(0), bLayerCount(0) { }
1711 
C2TemporalLayeringStructC2TemporalLayeringStruct1712     C2TemporalLayeringStruct(size_t /* flexCount */, uint32_t layerCount_, uint32_t bLayerCount_)
1713         : layerCount(layerCount_), bLayerCount(c2_min(layerCount_, bLayerCount_)) { }
1714 
C2TemporalLayeringStructC2TemporalLayeringStruct1715     C2TemporalLayeringStruct(size_t flexCount, uint32_t layerCount_, uint32_t bLayerCount_,
1716                              std::initializer_list<float> ratios)
1717         : layerCount(layerCount_), bLayerCount(c2_min(layerCount_, bLayerCount_)) {
1718         size_t ix = 0;
1719         for (float ratio : ratios) {
1720             if (ix == flexCount) {
1721                 break;
1722             }
1723             bitrateRatios[ix++] = ratio;
1724         }
1725     }
1726 
1727     uint32_t layerCount;     ///< total number of layers (0 means no temporal layering)
1728     uint32_t bLayerCount;    ///< total number of bidirectional layers (<= num layers)
1729     /**
1730      * Bitrate budgets for each layer and the layers below, given as a ratio of the total
1731      * stream bitrate. This can be omitted or partially specififed by the client while configuring,
1732      * in which case the component shall fill in appropriate values for the missing layers.
1733      * This must be provided by the component when queried for at least layer count - 1 (as the
1734      * last layer's budget is always 1.0).
1735      */
1736     float bitrateRatios[];   ///< 1.0-based
1737 
1738     DEFINE_AND_DESCRIBE_FLEX_C2STRUCT(TemporalLayering, bitrateRatios)
1739     C2FIELD(layerCount, "layer-count")
1740     C2FIELD(bLayerCount, "b-layer-count")
1741     C2FIELD(bitrateRatios, "bitrate-ratios")
1742 };
1743 
1744 typedef C2StreamParam<C2Tuning, C2TemporalLayeringStruct, kParamIndexTemporalLayering>
1745         C2StreamTemporalLayeringTuning;
1746 constexpr char C2_PARAMKEY_TEMPORAL_LAYERING[] = "coding.temporal-layering";
1747 
1748 /**
1749  * Intra-refresh.
1750  */
1751 
1752 C2ENUM(C2Config::intra_refresh_mode_t, uint32_t,
1753     INTRA_REFRESH_DISABLED,     ///< no intra refresh
1754     INTRA_REFRESH_ARBITRARY,    ///< arbitrary, unspecified
1755 )
1756 
1757 struct C2IntraRefreshStruct {
C2IntraRefreshStructC2IntraRefreshStruct1758     C2IntraRefreshStruct()
1759         : mode(C2Config::INTRA_REFRESH_DISABLED), period(0.) { }
1760 
C2IntraRefreshStructC2IntraRefreshStruct1761     C2IntraRefreshStruct(C2Config::intra_refresh_mode_t mode_, float period_)
1762         : mode(mode_), period(period_) { }
1763 
1764     C2Config::intra_refresh_mode_t mode; ///< refresh mode
1765     float period;         ///< intra refresh period in frames (must be >= 1), 0 means disabled
1766 
1767     DEFINE_AND_DESCRIBE_C2STRUCT(IntraRefresh)
1768     C2FIELD(mode, "mode")
1769     C2FIELD(period, "period")
1770 };
1771 
1772 typedef C2StreamParam<C2Tuning, C2IntraRefreshStruct, kParamIndexIntraRefresh>
1773         C2StreamIntraRefreshTuning;
1774 constexpr char C2_PARAMKEY_INTRA_REFRESH[] = "coding.intra-refresh";
1775 
1776 /* ====================================== IMAGE COMPONENTS ====================================== */
1777 
1778 /**
1779  * Tile layout.
1780  *
1781  * This described how the image is decomposed into tiles.
1782  */
1783 C2ENUM(C2Config::scan_order_t, uint32_t,
1784     SCAN_LEFT_TO_RIGHT_THEN_DOWN
1785 )
1786 
1787 struct C2TileLayoutStruct {
1788     C2PictureSizeStruct tile;       ///< tile size
1789     uint32_t columnCount;           ///< number of tiles horizontally
1790     uint32_t rowCount;              ///< number of tiles vertically
1791     C2Config::scan_order_t order;   ///< tile order
1792 
1793     DEFINE_AND_DESCRIBE_C2STRUCT(TileLayout)
1794     C2FIELD(tile, "tile")
1795     C2FIELD(columnCount, "columns")
1796     C2FIELD(rowCount, "rows")
1797     C2FIELD(order, "order")
1798 };
1799 
1800 typedef C2StreamParam<C2Info, C2TileLayoutStruct, kParamIndexTileLayout> C2StreamTileLayoutInfo;
1801 constexpr char C2_PARAMKEY_TILE_LAYOUT[] = "coded.tile-layout";
1802 
1803 /**
1804  * Tile handling.
1805  *
1806  * Whether to concatenate tiles or output them each.
1807  */
1808 C2ENUM(C2Config::tiling_mode_t, uint32_t,
1809     TILING_SEPARATE,    ///< output each tile in a separate onWorkDone
1810     TILING_CONCATENATE  ///< output one work completion per frame (concatenate tiles)
1811 )
1812 
1813 typedef C2StreamParam<C2Tuning, C2TileLayoutStruct, kParamIndexTileHandling>
1814         C2StreamTileHandlingTuning;
1815 constexpr char C2_PARAMKEY_TILE_HANDLING[] = "coding.tile-handling";
1816 
1817 /* ====================================== AUDIO COMPONENTS ====================================== */
1818 
1819 /**
1820  * Sample rate
1821  */
1822 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexSampleRate> C2StreamSampleRateInfo;
1823 constexpr char C2_PARAMKEY_SAMPLE_RATE[] = "raw.sample-rate";
1824 constexpr char C2_PARAMKEY_CODED_SAMPLE_RATE[] = "coded.sample-rate";
1825 
1826 /**
1827  * Channel count.
1828  */
1829 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexChannelCount> C2StreamChannelCountInfo;
1830 constexpr char C2_PARAMKEY_CHANNEL_COUNT[] = "raw.channel-count";
1831 constexpr char C2_PARAMKEY_CODED_CHANNEL_COUNT[] = "coded.channel-count";
1832 
1833 /**
1834  * Max channel count. Used to limit the number of coded or decoded channels.
1835  */
1836 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexMaxChannelCount> C2StreamMaxChannelCountInfo;
1837 constexpr char C2_PARAMKEY_MAX_CHANNEL_COUNT[] = "raw.max-channel-count";
1838 constexpr char C2_PARAMKEY_MAX_CODED_CHANNEL_COUNT[] = "coded.max-channel-count";
1839 
1840 /**
1841  * Audio sample format (PCM encoding)
1842  */
1843 C2ENUM(C2Config::pcm_encoding_t, uint32_t,
1844     PCM_16,
1845     PCM_8,
1846     PCM_FLOAT
1847 )
1848 
1849 typedef C2StreamParam<C2Info, C2SimpleValueStruct<C2Config::pcm_encoding_t>, kParamIndexPcmEncoding>
1850         C2StreamPcmEncodingInfo;
1851 constexpr char C2_PARAMKEY_PCM_ENCODING[] = "raw.pcm-encoding";
1852 constexpr char C2_PARAMKEY_CODED_PCM_ENCODING[] = "coded.pcm-encoding";
1853 
1854 /**
1855  * AAC SBR Mode. Used during encoding.
1856  */
1857 C2ENUM(C2Config::aac_sbr_mode_t, uint32_t,
1858     AAC_SBR_OFF,
1859     AAC_SBR_SINGLE_RATE,
1860     AAC_SBR_DUAL_RATE,
1861     AAC_SBR_AUTO ///< let the codec decide
1862 )
1863 
1864 typedef C2StreamParam<C2Info, C2SimpleValueStruct<C2Config::aac_sbr_mode_t>, kParamIndexAacSbrMode>
1865         C2StreamAacSbrModeTuning;
1866 constexpr char C2_PARAMKEY_AAC_SBR_MODE[] = "coding.aac-sbr-mode";
1867 
1868 /**
1869  * DRC Compression. Used during decoding.
1870  */
1871 C2ENUM(C2Config::drc_compression_mode_t, int32_t,
1872     DRC_COMPRESSION_ODM_DEFAULT, ///< odm's default
1873     DRC_COMPRESSION_NONE,
1874     DRC_COMPRESSION_LIGHT,
1875     DRC_COMPRESSION_HEAVY ///<
1876 )
1877 
1878 typedef C2StreamParam<C2Info, C2SimpleValueStruct<C2Config::drc_compression_mode_t>,
1879                 kParamIndexDrcCompression>
1880         C2StreamDrcCompressionModeTuning;
1881 constexpr char C2_PARAMKEY_DRC_COMPRESSION_MODE[] = "coding.drc.compression-mode";
1882 
1883 /**
1884  * DRC target reference level in dBFS. Used during decoding.
1885  */
1886 typedef C2StreamParam<C2Info, C2FloatValue, kParamIndexDrcTargetReferenceLevel>
1887         C2StreamDrcTargetReferenceLevelTuning;
1888 constexpr char C2_PARAMKEY_DRC_TARGET_REFERENCE_LEVEL[] = "coding.drc.reference-level";
1889 
1890 /**
1891  * DRC target reference level in dBFS. Used during decoding.
1892  */
1893 typedef C2StreamParam<C2Info, C2FloatValue, kParamIndexDrcEncodedTargetLevel>
1894         C2StreamDrcEncodedTargetLevelTuning;
1895 constexpr char C2_PARAMKEY_DRC_ENCODED_TARGET_LEVEL[] = "coding.drc.encoded-level";
1896 
1897 /**
1898  * DRC target reference level in dBFS. Used during decoding.
1899  */
1900 typedef C2StreamParam<C2Info, C2FloatValue, kParamIndexDrcBoostFactor>
1901         C2StreamDrcBoostFactorTuning;
1902 constexpr char C2_PARAMKEY_DRC_BOOST_FACTOR[] = "coding.drc.boost-factor";
1903 
1904 /**
1905  * DRC target reference level in dBFS. Used during decoding.
1906  */
1907 typedef C2StreamParam<C2Info, C2FloatValue, kParamIndexDrcAttenuationFactor>
1908         C2StreamDrcAttenuationFactorTuning;
1909 constexpr char C2_PARAMKEY_DRC_ATTENUATION_FACTOR[] = "coding.drc.attenuation-factor";
1910 
1911 /**
1912  * DRC Effect Type (see ISO 23003-4) Uniform Dynamic Range Control. Used during decoding.
1913  */
1914 C2ENUM(C2Config::drc_effect_type_t, int32_t,
1915     DRC_EFFECT_ODM_DEFAULT = -2, ///< odm's default
1916     DRC_EFFECT_OFF = -1,    ///< no DRC
1917     DRC_EFFECT_NONE = 0,    ///< no DRC except to prevent clipping
1918     DRC_EFFECT_LATE_NIGHT,
1919     DRC_EFFECT_NOISY_ENVIRONMENT,
1920     DRC_EFFECT_LIMITED_PLAYBACK_RANGE,
1921     DRC_EFFECT_LOW_PLAYBACK_LEVEL,
1922     DRC_EFFECT_DIALOG_ENHANCEMENT,
1923     DRC_EFFECT_GENERAL_COMPRESSION
1924 )
1925 
1926 typedef C2StreamParam<C2Info, C2SimpleValueStruct<C2Config::drc_effect_type_t>,
1927                 kParamIndexDrcEffectType>
1928         C2StreamDrcEffectTypeTuning;
1929 constexpr char C2_PARAMKEY_DRC_EFFECT_TYPE[] = "coding.drc.effect-type";
1930 
1931 /* --------------------------------------- AAC components --------------------------------------- */
1932 
1933 /**
1934  * AAC stream format
1935  */
1936 C2ENUM(C2Config::aac_packaging_t, uint32_t,
1937     AAC_PACKAGING_RAW,
1938     AAC_PACKAGING_ADTS
1939 )
1940 
1941 typedef C2StreamParam<C2Info, C2SimpleValueStruct<C2EasyEnum<C2Config::aac_packaging_t>>,
1942         kParamIndexAacPackaging> C2StreamAacPackagingInfo;
1943 typedef C2StreamAacPackagingInfo C2StreamAacFormatInfo;
1944 constexpr char C2_PARAMKEY_AAC_PACKAGING[] = "coded.aac-packaging";
1945 
1946 /* ================================ PLATFORM-DEFINED PARAMETERS ================================ */
1947 
1948 /**
1949  * Platform level and features.
1950  */
1951 enum C2Config::platform_level_t : uint32_t {
1952     PLATFORM_P,   ///< support for Android 9.0 feature set
1953 };
1954 
1955 // read-only
1956 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Config::platform_level_t>,
1957                 kParamIndexPlatformLevel>
1958         C2PlatformLevelSetting;
1959 constexpr char C2_PARAMKEY_PLATFORM_LEVEL[] = "api.platform-level";
1960 
1961 enum C2Config::platform_feature_t : uint64_t {
1962     // no platform-specific features have been defined
1963 };
1964 
1965 // read-only
1966 typedef C2GlobalParam<C2Setting, C2SimpleValueStruct<C2Config::platform_feature_t>,
1967                 kParamIndexPlatformFeatures>
1968         C2PlatformFeaturesSetting;
1969 constexpr char C2_PARAMKEY_PLATFORM_FEATURES[] = "api.platform-features";
1970 
1971 /**
1972  * This structure describes the preferred ion allocation parameters for a given memory usage.
1973  */
1974 struct C2StoreIonUsageStruct {
C2StoreIonUsageStructC2StoreIonUsageStruct1975     inline C2StoreIonUsageStruct() {
1976         memset(this, 0, sizeof(*this));
1977     }
1978 
C2StoreIonUsageStructC2StoreIonUsageStruct1979     inline C2StoreIonUsageStruct(uint64_t usage_, uint32_t capacity_)
1980         : usage(usage_), capacity(capacity_), heapMask(0), allocFlags(0), minAlignment(0) { }
1981 
1982     uint64_t usage;        ///< C2MemoryUsage
1983     uint32_t capacity;     ///< capacity
1984     int32_t heapMask;      ///< ion heapMask
1985     int32_t allocFlags;    ///< ion allocation flags
1986     uint32_t minAlignment; ///< minimum alignment
1987 
1988     DEFINE_AND_DESCRIBE_C2STRUCT(StoreIonUsage)
1989     C2FIELD(usage, "usage")
1990     C2FIELD(capacity, "capacity")
1991     C2FIELD(heapMask, "heap-mask")
1992     C2FIELD(allocFlags, "alloc-flags")
1993     C2FIELD(minAlignment, "min-alignment")
1994 };
1995 
1996 // store, private
1997 typedef C2GlobalParam<C2Info, C2StoreIonUsageStruct, kParamIndexStoreIonUsage>
1998         C2StoreIonUsageInfo;
1999 
2000 /**
2001  * Flexible pixel format descriptors
2002  */
2003 struct C2FlexiblePixelFormatDescriptorStruct {
2004     uint32_t pixelFormat;
2005     uint32_t bitDepth;
2006     C2Color::subsampling_t subsampling;
2007     C2Color::plane_layout_t layout;
2008 
2009     DEFINE_AND_DESCRIBE_C2STRUCT(FlexiblePixelFormatDescriptor)
2010     C2FIELD(pixelFormat, "pixel-format")
2011     C2FIELD(bitDepth, "bit-depth")
2012     C2FIELD(subsampling, "subsampling")
2013     C2FIELD(layout, "layout")
2014 };
2015 
2016 /**
2017  * Plane layout of flexible pixel formats.
2018  *
2019  * bpp: bytes per color component, e.g. 1 for 8-bit formats, and 2 for 10-16-bit formats.
2020  */
2021 C2ENUM(C2Color::plane_layout_t, uint32_t,
2022        /** Unknown layout */
2023        UNKNOWN_LAYOUT,
2024 
2025        /** Planar layout with rows of each plane packed (colInc = bpp) */
2026        PLANAR_PACKED,
2027 
2028        /** Semiplanar layout with rows of each plane packed (colInc_Y/A = bpp (planar),
2029         *  colInc_Cb/Cr = 2*bpp (interleaved). Used only for YUV(A) formats. */
2030        SEMIPLANAR_PACKED,
2031 
2032        /** Interleaved packed. colInc = N*bpp (N are the number of color components) */
2033        INTERLEAVED_PACKED,
2034 
2035        /** Interleaved aligned. colInc = smallest power of 2 >= N*bpp (N are the number of color
2036         *  components) */
2037        INTERLEAVED_ALIGNED
2038 )
2039 
2040 typedef C2GlobalParam<C2Info, C2SimpleArrayStruct<C2FlexiblePixelFormatDescriptorStruct>,
2041                 kParamIndexFlexiblePixelFormatDescriptors>
2042         C2StoreFlexiblePixelFormatDescriptorsInfo;
2043 
2044 /**
2045  * This structure describes the android dataspace for a raw video/image frame.
2046  */
2047 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexDataSpace> C2StreamDataSpaceInfo;
2048 constexpr char C2_PARAMKEY_DATA_SPACE[] = "raw.data-space";
2049 
2050 /**
2051  * This structure describes the android surface scaling mode for a raw video/image frame.
2052  */
2053 typedef C2StreamParam<C2Info, C2Uint32Value, kParamIndexSurfaceScaling> C2StreamSurfaceScalingInfo;
2054 constexpr char C2_PARAMKEY_SURFACE_SCALING_MODE[] = "raw.surface-scaling";
2055 
2056 /* ======================================= INPUT SURFACE ======================================= */
2057 
2058 /**
2059  * Input surface EOS
2060  */
2061 typedef C2GlobalParam<C2Tuning, C2EasyBoolValue, kParamIndexInputSurfaceEos>
2062         C2InputSurfaceEosTuning;
2063 constexpr char C2_PARAMKEY_INPUT_SURFACE_EOS[] = "input-surface.eos";
2064 
2065 /**
2066  * Start/suspend/resume/stop controls and timestamps for input surface.
2067  *
2068  * TODO: make these counters
2069  */
2070 
2071 struct C2TimedControlStruct {
2072     c2_bool_t enabled; ///< control is enabled
2073     int64_t timestamp; ///< if enabled, time the control should take effect
2074 
C2TimedControlStructC2TimedControlStruct2075     C2TimedControlStruct()
2076         : enabled(C2_FALSE), timestamp(0) { }
2077 
C2TimedControlStructC2TimedControlStruct2078     /* implicit */ C2TimedControlStruct(uint64_t timestamp_)
2079         : enabled(C2_TRUE), timestamp(timestamp_) { }
2080 
2081     DEFINE_AND_DESCRIBE_C2STRUCT(TimedControl)
2082     C2FIELD(enabled,   "enabled")
2083     C2FIELD(timestamp, "timestamp")
2084 };
2085 
2086 typedef C2PortParam<C2Tuning, C2TimedControlStruct, kParamIndexStartAt>
2087         C2PortStartTimestampTuning;
2088 constexpr char C2_PARAMKEY_INPUT_SURFACE_START_AT[] = "input-surface.start";
2089 typedef C2PortParam<C2Tuning, C2TimedControlStruct, kParamIndexSuspendAt>
2090         C2PortSuspendTimestampTuning;
2091 constexpr char C2_PARAMKEY_INPUT_SURFACE_SUSPEND_AT[] = "input-surface.suspend";
2092 typedef C2PortParam<C2Tuning, C2TimedControlStruct, kParamIndexResumeAt>
2093         C2PortResumeTimestampTuning;
2094 constexpr char C2_PARAMKEY_INPUT_SURFACE_RESUME_AT[] = "input-surface.resume";
2095 typedef C2PortParam<C2Tuning, C2TimedControlStruct, kParamIndexStopAt>
2096         C2PortStopTimestampTuning;
2097 constexpr char C2_PARAMKEY_INPUT_SURFACE_STOP_AT[] = "input-surface.stop";
2098 
2099 /**
2100  * Time offset for input surface. Input timestamp to codec is surface buffer timestamp plus this
2101  * time offset.
2102  */
2103 typedef C2GlobalParam<C2Tuning, C2Int64Value, kParamIndexTimeOffset> C2ComponentTimeOffsetTuning;
2104 constexpr char C2_PARAMKEY_INPUT_SURFACE_TIME_OFFSET[] = "input-surface.time-offset";
2105 
2106 /**
2107  * Minimum fps for input surface.
2108  *
2109  * Repeat frame to meet this.
2110  */
2111 typedef C2PortParam<C2Tuning, C2FloatValue, kParamIndexMinFrameRate> C2PortMinFrameRateTuning;
2112 constexpr char C2_PARAMKEY_INPUT_SURFACE_MIN_FRAME_RATE[] = "input-surface.min-frame-rate";
2113 
2114 /**
2115  * Timestamp adjustment (override) for input surface buffers. These control the input timestamp
2116  * fed to the codec, but do not impact the output timestamp.
2117  */
2118 struct C2TimestampGapAdjustmentStruct {
2119     /// control modes
2120     enum mode_t : uint32_t;
2121 
2122     inline C2TimestampGapAdjustmentStruct();
2123 
C2TimestampGapAdjustmentStructC2TimestampGapAdjustmentStruct2124     inline C2TimestampGapAdjustmentStruct(mode_t mode_, uint64_t value_)
2125         : mode(mode_), value(value_) { }
2126 
2127     mode_t mode;    ///< control mode
2128     uint64_t value; ///< control value for gap between two timestamp
2129 
2130     DEFINE_AND_DESCRIBE_C2STRUCT(TimestampGapAdjustment)
2131     C2FIELD(mode, "mode")
2132     C2FIELD(value, "value")
2133 };
2134 
2135 C2ENUM(C2TimestampGapAdjustmentStruct::mode_t, uint32_t,
2136     NONE,
2137     MIN_GAP,
2138     FIXED_GAP,
2139 );
2140 
C2TimestampGapAdjustmentStruct()2141 inline C2TimestampGapAdjustmentStruct::C2TimestampGapAdjustmentStruct()
2142     : mode(C2TimestampGapAdjustmentStruct::NONE), value(0) { }
2143 
2144 typedef C2PortParam<C2Tuning, C2TimestampGapAdjustmentStruct> C2PortTimestampGapTuning;
2145 constexpr char C2_PARAMKEY_INPUT_SURFACE_TIMESTAMP_ADJUSTMENT[] = "input-surface.timestamp-adjustment";
2146 
2147 /// @}
2148 
2149 #endif  // C2CONFIG_H_
2150