1 /* 2 * Copyright (C) 2024 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 #pragma once 18 19 #include <sys/cdefs.h> 20 #include <errno.h> 21 #include <stdint.h> 22 23 #include <android/api-level.h> 24 #include <android/hardware_buffer.h> 25 #include <android/versioning.h> 26 27 __BEGIN_DECLS 28 29 /** 30 * An API to access and operate codecs implemented within an APEX module, 31 * used only by the OS when using the codecs within a client process 32 * (instead of via a HAL). 33 * 34 * NOTE: Many of the constants and types mirror the ones in the Codec 2.0 API. 35 */ 36 37 /** 38 * Error code for ApexCodec APIs. 39 * 40 * Introduced in API 36. 41 */ 42 typedef enum ApexCodec_Status : int32_t { 43 APEXCODEC_STATUS_OK = 0, 44 45 /* bad input */ 46 APEXCODEC_STATUS_BAD_VALUE = EINVAL, 47 APEXCODEC_STATUS_BAD_INDEX = ENXIO, 48 APEXCODEC_STATUS_CANNOT_DO = ENOTSUP, 49 50 /* bad sequencing of events */ 51 APEXCODEC_STATUS_DUPLICATE = EEXIST, 52 APEXCODEC_STATUS_NOT_FOUND = ENOENT, 53 APEXCODEC_STATUS_BAD_STATE = EPERM, 54 APEXCODEC_STATUS_BLOCKING = EWOULDBLOCK, 55 APEXCODEC_STATUS_CANCELED = EINTR, 56 57 /* bad environment */ 58 APEXCODEC_STATUS_NO_MEMORY = ENOMEM, 59 APEXCODEC_STATUS_REFUSED = EACCES, 60 61 APEXCODEC_STATUS_TIMED_OUT = ETIMEDOUT, 62 63 /* bad versioning */ 64 APEXCODEC_STATUS_OMITTED = ENOSYS, 65 66 /* unknown fatal */ 67 APEXCODEC_STATUS_CORRUPTED = EFAULT, 68 APEXCODEC_STATUS_NO_INIT = ENODEV, 69 } ApexCodec_Status; 70 71 /** 72 * Enum that represents the kind of component 73 * 74 * Introduced in API 36. 75 */ 76 typedef enum ApexCodec_Kind : uint32_t { 77 /** 78 * The component is of a kind that is not listed below. 79 */ 80 APEXCODEC_KIND_OTHER = 0x0, 81 /** 82 * The component is a decoder, which decodes coded bitstream 83 * into raw buffers. 84 * 85 * Introduced in API 36. 86 */ 87 APEXCODEC_KIND_DECODER = 0x1, 88 /** 89 * The component is an encoder, which encodes raw buffers 90 * into coded bitstream. 91 * 92 * Introduced in API 36. 93 */ 94 APEXCODEC_KIND_ENCODER = 0x2, 95 } ApexCodec_Kind; 96 97 typedef enum ApexCodec_Domain : uint32_t { 98 /** 99 * A component domain that is not listed below. 100 * 101 * Introduced in API 36. 102 */ 103 APEXCODEC_DOMAIN_OTHER = 0x0, 104 /** 105 * A component domain that operates on video. 106 * 107 * Introduced in API 36. 108 */ 109 APEXCODEC_DOMAIN_VIDEO = 0x1, 110 /** 111 * A component domain that operates on audio. 112 * 113 * Introduced in API 36. 114 */ 115 APEXCODEC_DOMAIN_AUDIO = 0x2, 116 /** 117 * A component domain that operates on image. 118 * 119 * Introduced in API 36. 120 */ 121 APEXCODEC_DOMAIN_IMAGE = 0x3, 122 } ApexCodec_Domain; 123 124 /** 125 * Handle for component traits such as name, media type, kind (decoder/encoder), 126 * domain (audio/video/image), etc. 127 * 128 * Introduced in API 36. 129 */ 130 typedef struct ApexCodec_ComponentTraits { 131 /** 132 * The name of the component. 133 */ 134 const char *name; 135 /** 136 * The supported media type of the component. 137 */ 138 const char *mediaType; 139 /** 140 * The kind of the component. 141 */ 142 ApexCodec_Kind kind; 143 /** 144 * The domain on which the component operates. 145 */ 146 ApexCodec_Domain domain; 147 } ApexCodec_ComponentTraits; 148 149 /** 150 * An opaque struct that represents a component store. 151 * 152 * Introduced in API 36. 153 */ 154 typedef struct ApexCodec_ComponentStore ApexCodec_ComponentStore; 155 156 /** 157 * Get the component store object. This function never fails. 158 * 159 * \return component store object. 160 */ 161 ApexCodec_ComponentStore *ApexCodec_GetComponentStore() 162 __INTRODUCED_IN(36); 163 164 /** 165 * Get the traits object of a component at given index. ApexCodecs_Traits_* 166 * functions are used to extract information from the traits object. 167 * 168 * Returns nullptr if index is out of bounds. The returned object is owned by 169 * ApexCodec_ComponentStore object and the client should not delete it. 170 * 171 * The client can iterate through the traits objects by calling this function 172 * with an index incrementing from 0 until it gets a nullptr. 173 * 174 * \param index index of the traits object to query 175 * \return traits object at the index, or nullptr if the index is out of bounds. 176 */ 177 ApexCodec_ComponentTraits *ApexCodec_Traits_get( 178 ApexCodec_ComponentStore *store, size_t index) __INTRODUCED_IN(36); 179 180 /** 181 * An opaque struct that represents a codec. 182 */ 183 typedef struct ApexCodec_Component ApexCodec_Component; 184 185 /** 186 * Create a component by the name. 187 * 188 * \param store the component store 189 * \param name the name of the component 190 * \param component out-param to be filled with the component; must not be null 191 * \return APEXCODEC_STATUS_OK if successful 192 * APEXCODEC_STATUS_NOT_FOUND if the name is not found 193 */ 194 ApexCodec_Status ApexCodec_Component_create( 195 ApexCodec_ComponentStore *store, const char *name, ApexCodec_Component **comp) 196 __INTRODUCED_IN(36); 197 198 /** 199 * Destroy the component by the handle. It is invalid to call component methods on the handle 200 * after calling this method. It is no-op to call this method with |comp| == nullptr. 201 * 202 * \param comp the handle for the component 203 */ 204 void ApexCodec_Component_destroy(ApexCodec_Component *comp) __INTRODUCED_IN(36); 205 206 /** 207 * Start the component. The component is ready to process buffers after this call. 208 * 209 * \param comp the handle for the component 210 */ 211 ApexCodec_Status ApexCodec_Component_start( 212 ApexCodec_Component *comp) __INTRODUCED_IN(36); 213 214 /** 215 * Flush the component's internal states. This operation preserves the existing configurations. 216 * 217 * \param comp the handle for the component 218 */ 219 ApexCodec_Status ApexCodec_Component_flush( 220 ApexCodec_Component *comp) __INTRODUCED_IN(36); 221 222 /** 223 * Resets the component to the initial state, right after creation. Note that the configuration 224 * will also revert to the initial state, so if there are configurations required those should be 225 * set again to use the component. 226 * 227 * \param comp the handle for the component 228 */ 229 ApexCodec_Status ApexCodec_Component_reset( 230 ApexCodec_Component *comp) __INTRODUCED_IN(36); 231 232 /** 233 * An opaque struct that represents a configurable part of the component. 234 * 235 * Introduced in API 36. 236 */ 237 typedef struct ApexCodec_Configurable ApexCodec_Configurable; 238 239 /** 240 * Return the configurable object for the given ApexCodec_Component. 241 * The returned object has the same lifecycle as |comp|. 242 * 243 * \param comp the handle for the component 244 * \return the configurable object handle 245 */ 246 ApexCodec_Configurable *ApexCodec_Component_getConfigurable( 247 ApexCodec_Component *comp) __INTRODUCED_IN(36); 248 249 /** 250 * Enum that represents the flags for ApexCodec_Buffer. 251 * 252 * Introduced in API 36. 253 */ 254 typedef enum ApexCodec_BufferFlags : uint32_t { 255 APEXCODEC_FLAG_DROP_FRAME = (1 << 0), 256 APEXCODEC_FLAG_END_OF_STREAM = (1 << 1), 257 APEXCODEC_FLAG_DISCARD_FRAME = (1 << 2), 258 APEXCODEC_FLAG_INCOMPLETE = (1 << 3), 259 APEXCODEC_FLAG_CORRECTED = (1 << 4), 260 APEXCODEC_FLAG_CORRUPT = (1 << 5), 261 APEXCODEC_FLAG_CODEC_CONFIG = (1u << 31), 262 } ApexCodec_BufferFlags; 263 264 /** 265 * Enum that represents the type of buffer. 266 * 267 * Introduced in API 36. 268 */ 269 typedef enum ApexCodec_BufferType : uint32_t { 270 APEXCODEC_BUFFER_TYPE_INVALID, 271 APEXCODEC_BUFFER_TYPE_LINEAR, 272 APEXCODEC_BUFFER_TYPE_LINEAR_CHUNKS, 273 APEXCODEC_BUFFER_TYPE_GRAPHIC, 274 APEXCODEC_BUFFER_TYPE_GRAPHIC_CHUNKS, 275 } ApexCodec_BufferType; 276 277 /** 278 * Struct that represents the memory for ApexCodec_Buffer. 279 * 280 * All memory regions have the simple 1D representation. 281 * 282 * Introduced in API 36. 283 */ 284 typedef struct ApexCodec_LinearBuffer { 285 /** 286 * A pointer to the start of the buffer. This is not aligned. 287 */ 288 uint8_t *data; 289 /** 290 * Size of the buffer. The memory region between |data| (inclusive) and 291 * |data + size| (exclusive) is assumed to be valid for read/write. 292 */ 293 size_t size; 294 } ApexCodec_LinearBuffer; 295 296 /** 297 * Struct that represents a buffer for ApexCodec_Component. 298 * 299 * Introduced in API 36. 300 */ 301 typedef struct ApexCodec_Buffer { 302 /** 303 * Flags associated with the buffer. 304 */ 305 ApexCodec_BufferFlags flags; 306 /** 307 * For input buffers client assign a unique sequential index for each buffer. For output buffers 308 * it is the same as the associated input buffer's frame index. 309 */ 310 uint64_t frameIndex; 311 /** 312 * A timestamp associated with the buffer in microseconds. 313 */ 314 uint64_t timestampUs; 315 /** 316 * The type of the buffer. The component may reject request to process a buffer with the wrong 317 * type. For example, a video decoder will reject an input buffer with type BUFFER_TYPE_GRAPHIC, 318 * or an output buffer with type BUFFER_TYPE_LINEAR. 319 */ 320 ApexCodec_BufferType type; 321 /** 322 * The actual memory for the buffer. 323 */ 324 union { 325 ApexCodec_LinearBuffer linear; 326 AHardwareBuffer *graphic; 327 } memory; 328 /** 329 * Config updates associated with the buffer. For input buffers these are sent to the component 330 * at the specific input frame. For output buffers these are config updates as a result of 331 * processing the buffer. 332 */ 333 ApexCodec_LinearBuffer configUpdates; 334 } ApexCodec_Buffer; 335 336 /** 337 * Enum that represents the query type for the supported values. 338 * 339 * Introduced in API 36. 340 */ 341 typedef enum ApexCodec_SupportedValuesQueryType : uint32_t { 342 /** Query all possible supported values regardless of current configuration */ 343 APEXCODEC_SUPPORTED_VALUES_QUERY_POSSIBLE, 344 /** Query supported values at current configuration */ 345 APEXCODEC_SUPPORTED_VALUES_QUERY_CURRENT, 346 } ApexCodec_SupportedValuesQueryType; 347 348 /** 349 * Enum that represents the type of the supported values. 350 * 351 * Introduced in API 36. 352 */ 353 typedef enum ApexCodec_SupportedValuesType : uint32_t { 354 /** The supported values are empty. */ 355 APEXCODEC_SUPPORTED_VALUES_EMPTY, 356 /** 357 * The supported values are represented by a range defined with {min, max, step, num, den}. 358 * 359 * If step is 0 and num and denom are both 1, the supported values are any value, for which 360 * min <= value <= max. 361 * 362 * Otherwise, the range represents a geometric/arithmetic/multiply-accumulate series, where 363 * successive supported values can be derived from previous values (starting at min), using the 364 * following formula: 365 * v[0] = min 366 * v[i] = v[i-1] * num / denom + step for i >= 1, while min < v[i] <= max. 367 */ 368 APEXCODEC_SUPPORTED_VALUES_RANGE, 369 /** The supported values are represented by a list of values. */ 370 APEXCODEC_SUPPORTED_VALUES_VALUES, 371 /** The supported values are represented by a list of flags. */ 372 APEXCODEC_SUPPORTED_VALUES_FLAGS, 373 } ApexCodec_SupportedValuesType; 374 375 /** 376 * Enum that represents numeric types of the supported values. 377 * 378 * Introduced in API 36. 379 */ 380 typedef enum ApexCodec_SupportedValuesNumberType : uint32_t { 381 APEXCODEC_SUPPORTED_VALUES_TYPE_NONE = 0, 382 APEXCODEC_SUPPORTED_VALUES_TYPE_INT32 = 1, 383 APEXCODEC_SUPPORTED_VALUES_TYPE_UINT32 = 2, 384 // RESERVED = 3, 385 APEXCODEC_SUPPORTED_VALUES_TYPE_INT64 = 4, 386 APEXCODEC_SUPPORTED_VALUES_TYPE_UINT64 = 5, 387 // RESERVED = 6, 388 APEXCODEC_SUPPORTED_VALUES_TYPE_FLOAT = 7, 389 } ApexCodec_SupportedValuesNumberType; 390 391 /** 392 * Union of primitive types. 393 * 394 * Introduced in API 36. 395 */ 396 typedef union { 397 int32_t i32; 398 uint32_t u32; 399 int64_t i64; 400 uint64_t u64; 401 float f; 402 } ApexCodec_Value; 403 404 /** 405 * An opaque struct that represents the supported values of a parameter. 406 * 407 * Introduced in API 36. 408 */ 409 typedef struct ApexCodec_SupportedValues ApexCodec_SupportedValues; 410 411 /** 412 * Extract information from ApexCodec_SupportedValues object. 413 * 414 * \param [in] supportedValues the supported values object 415 * \param [out] type pointer to be filled with the type of the supported values 416 * \param [out] numberType pointer to be filled with the numeric type of the supported values 417 * \param [out] values pointer to be filled with the array of the actual supported values. 418 * if type == APEXCODEC_SUPPORTED_VALUES_EMPTY: nullptr 419 * if type == APEXCODEC_SUPPORTED_VALUES_RANGE: {min, max, step, num, den} 420 * if type == APEXCODEC_SUPPORTED_VALUES_VALUES/_FLAGS: 421 * the array of supported values/flags 422 * the array is owned by the |supportedValues| object and the client 423 * should not free it. 424 * \param [out] numValues pointer to be filled with the number of values. 425 * if type == APEXCODEC_SUPPORTED_VALUES_EMPTY: 0 426 * if type == APEXCODEC_SUPPORTED_VALUES_RANGE: 5 427 * if type == APEXCODEC_SUPPORTED_VALUES_VALUES/_FLAGS: varies 428 */ 429 ApexCodec_Status ApexCodec_SupportedValues_getTypeAndValues( 430 ApexCodec_SupportedValues *supportedValues, 431 ApexCodec_SupportedValuesType *type, 432 ApexCodec_SupportedValuesNumberType *numberType, 433 ApexCodec_Value **values, 434 uint32_t *numValues) __INTRODUCED_IN(36); 435 436 /** 437 * Release the supported values object. 438 * 439 * \param values the supported values object 440 */ 441 void ApexCodec_SupportedValues_release( 442 ApexCodec_SupportedValues *values) __INTRODUCED_IN(36); 443 444 /** 445 * Struct that represents the result of ApexCodec_Configurable_config. 446 * 447 * Introduced in API 36. 448 */ 449 typedef struct ApexCodec_SettingResults ApexCodec_SettingResults; 450 451 /** 452 * Enum that represents the failure code of ApexCodec_SettingResults. 453 * 454 * Introduced in API 36. 455 */ 456 typedef enum ApexCodec_SettingResultFailure : uint32_t { 457 /** parameter type is not supported */ 458 APEXCODEC_SETTING_RESULT_BAD_TYPE, 459 /** parameter is not supported on the specific port */ 460 APEXCODEC_SETTING_RESULT_BAD_PORT, 461 /** parameter is not supported on the specific stream */ 462 APEXCODEC_SETTING_RESULT_BAD_INDEX, 463 /** parameter is read-only */ 464 APEXCODEC_SETTING_RESULT_READ_ONLY, 465 /** parameter mismatches input data */ 466 APEXCODEC_SETTING_RESULT_MISMATCH, 467 /** strict parameter does not accept value for the field at all */ 468 APEXCODEC_SETTING_RESULT_BAD_VALUE, 469 /** strict parameter field value conflicts with another settings */ 470 APEXCODEC_SETTING_RESULT_CONFLICT, 471 /** strict parameter field is out of range due to other settings */ 472 APEXCODEC_SETTING_RESULT_UNSUPPORTED, 473 /** 474 * field does not accept the requested parameter value at all. It has been corrected to 475 * the closest supported value. This failure mode is provided to give guidance as to what 476 * are the currently supported values for this field (which may be a subset of the at-all- 477 * potential values) 478 */ 479 APEXCODEC_SETTING_RESULT_INFO_BAD_VALUE, 480 /** 481 * requested parameter value is in conflict with an/other setting(s) 482 * and has been corrected to the closest supported value. This failure 483 * mode is given to provide guidance as to what are the currently supported values as well 484 * as to optionally provide suggestion to the client as to how to enable the requested 485 * parameter value. 486 */ 487 APEXCODEC_SETTING_RESULT_INFO_CONFLICT, 488 } ApexCodec_SettingResultFailure; 489 490 /** 491 * Struct that represents a field and its supported values of a parameter. 492 * 493 * The offset and size of the field are where the field is located in the blob representation of 494 * the parameter, as used in the ApexCodec_Configurable_query() and ApexCodec_Configurable_config(), 495 * for example. 496 * 497 * Introduced in API 36. 498 */ 499 typedef struct ApexCodec_ParamFieldValues { 500 /** index of the param */ 501 uint32_t index; 502 /** offset of the param field */ 503 uint32_t offset; 504 /** size of the param field */ 505 uint32_t size; 506 /** currently supported values of the param field */ 507 ApexCodec_SupportedValues *values; 508 } ApexCodec_ParamFieldValues; 509 510 /** 511 * Extract the result of ApexCodec_Configurable_config. 512 * The client can iterate through the results with index starting from 0 until this function returns 513 * APEXCODEC_STATUS_NOT_FOUND. 514 * 515 * \param [in] result the result object 516 * \param [in] index the index of the result to extract, starts from 0. 517 * \param [out] failure pointer to be filled with the failure code 518 * \param [out] field pointer to be filled with the field that failed. 519 * |field->value| is owned by the |result| object and the client should not 520 * free it. 521 * \param [out] conflicts pointer to be filled with the array of conflicts. 522 * nullptr if |numConflicts| is 0. 523 * the array and its content is owned by the |result| object and the client 524 * should not free it. 525 * \param [out] numConflicts pointer to be filled with the number of conflicts 526 * may be 0 if there are no conflicts 527 * \return APEXCODEC_STATUS_OK if successful 528 * \return APEXCODEC_STATUS_NOT_FOUND if index is out of range 529 */ 530 ApexCodec_Status ApexCodec_SettingResults_getResultAtIndex( 531 ApexCodec_SettingResults *results, 532 size_t index, 533 ApexCodec_SettingResultFailure *failure, 534 ApexCodec_ParamFieldValues *field, 535 ApexCodec_ParamFieldValues **conflicts, 536 size_t *numConflicts) __INTRODUCED_IN(36); 537 538 /** 539 * Release the setting result object. 540 * 541 * \param result the setting result object 542 */ 543 void ApexCodec_SettingResults_release( 544 ApexCodec_SettingResults *results) __INTRODUCED_IN(36); 545 546 /** 547 * Process one frame from |input|, and produce one frame to |output| if possible. 548 * When successfully filled, |output->memory.linear| has the size adjusted to the produced 549 * output size, in case of linear buffers. |input->configUpdates| is applied with the input 550 * buffer; |output->configUpdates| contains config updates as a result of processing the frame. 551 * 552 * \param comp the component to process the buffers 553 * \param input the input buffer; when nullptr, the component should fill |output| if there are 554 * any pending output buffers. 555 * \param output the output buffer, should not be nullptr. 556 * \param consumed the number of consumed bytes from the input buffer 557 * set to 0 if no input buffer has been consumed, including |input| is nullptr. 558 * for graphic buffers, any non-zero value means that the input buffer is consumed. 559 * \param produced the number of bytes produced on the output buffer 560 * set to 0 if no output buffer has been produced. 561 * for graphic buffers, any non-zero value means that the output buffer is filled. 562 * \return APEXCODEC_STATUS_OK if successful 563 * \return APEXCODEC_STATUS_NO_MEMORY if the output buffer is not suitable to hold the output frame 564 * the client should retry with a new output buffer; 565 * configUpdates should have the information to update 566 * the buffer size. 567 * \return APEXCODEC_STATUS_BAD_VALUE if the parameters are bad 568 * \return APEXCODEC_STATUS_BAD_STATE if the component is not in the right state 569 * to process the frame 570 * \return APEXCODEC_STATUS_CORRUPTED if unexpected error has occurred 571 */ 572 ApexCodec_Status ApexCodec_Component_process( 573 ApexCodec_Component *comp, 574 const ApexCodec_Buffer *input, 575 ApexCodec_Buffer *output, 576 size_t *consumed, 577 size_t *produced) __INTRODUCED_IN(36); 578 579 /** 580 * Configure the component with the given config. 581 * 582 * Configurations are Codec 2.0 configs in binary blobs, 583 * concatenated if there are multiple configs. 584 * 585 * frameworks/av/media/codec2/core/include/C2Param.h contains more details about the configuration 586 * blob layout. 587 * 588 * The component may correct the configured parameters to the closest supported values, and could 589 * fail in case there are no values that the component can auto-correct to. |result| contains the 590 * information about the failures. See ApexCodec_SettingResultFailure and ApexCodec_SettingResults 591 * for more details. 592 * 593 * \param [in] comp the handle for the component 594 * \param [inout] config the config blob; after the call, the config blob is updated to the actual 595 * config by the component. 596 * \param [out] result the result of the configuration. 597 * the client should call ApexCodec_SettingResult_getResultAtIndex() 598 * to extract the result. The result object is owned by the client and should 599 * be released with ApexCodec_SettingResult_release(). 600 * |result| may be nullptr if empty. 601 * \return APEXCODEC_STATUS_OK if successful 602 * \return APEXCODEC_STATUS_BAD_VALUE if the config is invalid 603 * \return APEXCODEC_STATUS_BAD_STATE if the component is not in the right state to be configured 604 * \return APEXCODEC_STATUS_CORRUPTED if unexpected error has occurred 605 */ 606 ApexCodec_Status ApexCodec_Configurable_config( 607 ApexCodec_Configurable *comp, 608 ApexCodec_LinearBuffer *config, 609 ApexCodec_SettingResults **results) __INTRODUCED_IN(36); 610 611 /** 612 * Query the component for the given indices. 613 * 614 * Parameter indices are defined in frameworks/av/media/codec2/core/include/C2Config.h. 615 * 616 * \param [in] comp the handle for the component 617 * \param [in] indices the array of indices to query 618 * \param [in] numIndices the size of the indices array 619 * \param [inout] config the output buffer for the config blob, allocated by the client. 620 * if the |config->size| was insufficient, it is set to the required size 621 * and |config->data| remains unchanged. 622 * \param [out] written the number of bytes written to |config|. 623 * \return APEXCODEC_STATUS_OK if successful 624 * \return APEXCODEC_STATUS_NO_MEMORY if |config.size| is too small; |config.size| is updated to the 625 * requested buffer size. 626 * \return APEXCODEC_STATUS_BAD_VALUE if the parameters are bad. e.g. |indices|, |config|, 627 * |config->data| or |written| is nullptr. 628 */ 629 ApexCodec_Status ApexCodec_Configurable_query( 630 ApexCodec_Configurable *comp, 631 uint32_t indices[], 632 size_t numIndices, 633 ApexCodec_LinearBuffer *config, 634 size_t *written) __INTRODUCED_IN(36); 635 636 /** 637 * Struct that represents a parameter descriptor. 638 * 639 * Introduced in API 36. 640 */ 641 typedef struct ApexCodec_ParamDescriptors ApexCodec_ParamDescriptors; 642 643 /** 644 * Enum that represents the attributes of a parameter. 645 * 646 * Introduced in API 36. 647 */ 648 typedef enum ApexCodec_ParamAttribute : uint32_t { 649 /** parameter is required to be specified */ 650 APEXCODEC_PARAM_IS_REQUIRED = 1u << 0, 651 /** parameter retains its value */ 652 APEXCODEC_PARAM_IS_PERSISTENT = 1u << 1, 653 /** parameter is strict */ 654 APEXCODEC_PARAM_IS_STRICT = 1u << 2, 655 /** parameter is read-only */ 656 APEXCODEC_PARAM_IS_READ_ONLY = 1u << 3, 657 /** parameter shall not be visible to clients */ 658 APEXCODEC_PARAM_IS_HIDDEN = 1u << 4, 659 /** parameter shall not be used by framework (other than testing) */ 660 APEXCODEC_PARAM_IS_INTERNAL = 1u << 5, 661 /** parameter is publicly const (hence read-only) */ 662 APEXCODEC_PARAM_IS_CONST = 1u << 6 | APEXCODEC_PARAM_IS_READ_ONLY, 663 } ApexCodec_ParamAttribute; 664 665 /** 666 * Get the parameter indices of the param descriptors. 667 * 668 * \param [in] descriptors the param descriptors object 669 * \param [out] indices the pointer to be filled with the array of the indices; 670 * the array is owned by |descriptors| and should not be freed by the client. 671 * \param [out] numIndices the size of the indices array 672 * \return APEXCODEC_STATUS_OK if successful 673 * \return APEXCODEC_STATUS_BAD_VALUE if parameters are bad. e.g. |descriptors|, |indices| or 674 * |numIndices| is nullptr. 675 */ 676 ApexCodec_Status ApexCodec_ParamDescriptors_getIndices( 677 ApexCodec_ParamDescriptors *descriptors, 678 uint32_t **indices, 679 size_t *numIndices) __INTRODUCED_IN(36); 680 681 /** 682 * Get the descriptor of the param. 683 * 684 * \param [in] descriptors the param descriptors object 685 * \param [in] index the index of the param 686 * \param [out] attr the attribute of the param 687 * \param [out] name the pointer to be filled with the name of the param 688 * the string is owned by |descriptors| and should not be freed by the client. 689 * \param [out] dependencies the pointer to be filled with an array of the parameter indices 690 * that the parameter with |index| depends on. 691 * may be null if empty. 692 * the array is owned by |descriptors| and should not be freed by the client. 693 * \param [out] numDependencies the number of dependencies 694 * \return APEXCODEC_STATUS_OK if successful 695 * \return APEXCODEC_STATUS_BAD_VALUE if parameters are bad. e.g. |descriptors|, |attr|, |name|, 696 * |dependencies| or |numDependencies| is nullptr. 697 * \return APEXCODEC_STATUS_BAD_INDEX if the index is not included in the param descriptors. 698 */ 699 ApexCodec_Status ApexCodec_ParamDescriptors_getDescriptor( 700 ApexCodec_ParamDescriptors *descriptors, 701 uint32_t index, 702 ApexCodec_ParamAttribute *attr, 703 const char **name, 704 uint32_t **dependencies, 705 size_t *numDependencies) __INTRODUCED_IN(36); 706 707 /** 708 * Release the param descriptors object. 709 * 710 * \param descriptors the param descriptors object 711 */ 712 ApexCodec_Status ApexCodec_ParamDescriptors_release( 713 ApexCodec_ParamDescriptors *descriptors) __INTRODUCED_IN(36); 714 715 /** 716 * Query the component for the supported parameters. 717 * 718 * \param comp the handle for the component 719 * \param descriptors the pointer to be filled with the param descriptors object 720 * the object should be released with ApexCodec_ParamDescriptors_release(). 721 * \return APEXCODEC_STATUS_OK if successful 722 * \return APEXCODEC_STATUS_BAD_VALUE if parameters are bad. e.g. |descriptors| is nullptr. 723 */ 724 ApexCodec_Status ApexCodec_Configurable_querySupportedParams( 725 ApexCodec_Configurable *comp, 726 ApexCodec_ParamDescriptors **descriptors) __INTRODUCED_IN(36); 727 728 /** 729 * Struct that represents the query for the supported values of a parameter. 730 * 731 * The offset of the field can be found in the layout of the parameter blob. 732 * 733 * Introduced in API 36. 734 */ 735 typedef struct ApexCodec_SupportedValuesQuery { 736 /* in-params */ 737 738 /** index of the param */ 739 uint32_t index; 740 /** offset to the param field */ 741 size_t offset; 742 /** query type */ 743 ApexCodec_SupportedValuesQueryType type; 744 745 /* out-params */ 746 747 /** status of the query */ 748 ApexCodec_Status status; 749 750 /** supported values. must be released with ApexCodec_SupportedValues_release(). */ 751 ApexCodec_SupportedValues *values; 752 } ApexCodec_SupportedValuesQuery; 753 754 /** 755 * Query the component for the supported values of the given indices. 756 * 757 * \param comp the handle for the component 758 * \param queries the array of queries 759 * \param numQueries the size of the queries array 760 * \return APEXCODEC_STATUS_OK if successful 761 * APEXCODEC_STATUS_CORRUPTED if unexpected error has occurred 762 */ 763 ApexCodec_Status ApexCodec_Configurable_querySupportedValues( 764 ApexCodec_Configurable *comp, 765 ApexCodec_SupportedValuesQuery *queries, 766 size_t numQueries) __INTRODUCED_IN(36); 767 768 __END_DECLS