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