1 /* 2 * Copyright (c) 2024 Huawei Device Co., Ltd. 3 * Licensed under the Apache License, Version 2.0 (the "License"); 4 * you may not use this file except in compliance with the License. 5 * You may obtain a copy of the License at 6 * 7 * http://www.apache.org/licenses/LICENSE-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, software 10 * distributed under the License is distributed on an "AS IS" BASIS, 11 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 * See the License for the specific language governing permissions and 13 * limitations under the License. 14 */ 15 16 /** 17 * @addtogroup ImageEffect 18 * @{ 19 * 20 * @brief Provides APIs for obtaining and using a image filter. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file image_effect_filter.h 27 * 28 * @brief Declares the functions for setting filter parameters, registering custom filter and filter lookup information. 29 * 30 * @library libimage_effect.so 31 * @kit ImageKit 32 * @syscap SystemCapability.Multimedia.ImageEffect.Core 33 * @since 12 34 */ 35 36 #ifndef NATIVE_IMAGE_EFFECT_FILTER_H 37 #define NATIVE_IMAGE_EFFECT_FILTER_H 38 39 #include <stdbool.h> 40 #include <stdint.h> 41 #include "image_effect_errors.h" 42 #include "multimedia/image_framework/image/pixelmap_native.h" 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 /** 49 * @brief Define the new type name OH_EffectFilter for struct OH_EffectFilter 50 * 51 * @syscap SystemCapability.Multimedia.ImageEffect.Core 52 * @since 12 53 */ 54 typedef struct OH_EffectFilter OH_EffectFilter; 55 56 /** 57 * @brief Define the brightness filter name that contain the parameter matched with the key refer to 58 * OH_EFFECT_FILTER_INTENSITY_KEY and the value refer to {@link ImageEffect_Any} that contain the data type of 59 * {@link EFFECT_DATA_TYPE_FLOAT} 60 * 61 * @syscap SystemCapability.Multimedia.ImageEffect.Core 62 * @since 12 63 */ 64 #define OH_EFFECT_BRIGHTNESS_FILTER "Brightness" 65 66 /** 67 * @brief Define the contrast filter name that contain the parameter matched with the key refer to 68 * OH_EFFECT_FILTER_INTENSITY_KEY and the value refer to {@link ImageEffect_Any} that contain the data type of 69 * {@link EFFECT_DATA_TYPE_FLOAT} 70 * 71 * @syscap SystemCapability.Multimedia.ImageEffect.Core 72 * @since 12 73 */ 74 #define OH_EFFECT_CONTRAST_FILTER "Contrast" 75 76 /** 77 * @brief Define the crop filter name that contain the parameter matched with the key refer to 78 * OH_EFFECT_FILTER_REGION_KEY and the value refer to {@link ImageEffect_Any} that contain the data type of 79 * {@link EFFECT_DATA_TYPE_PTR} for {@link ImageEffect_Region} 80 * 81 * @syscap SystemCapability.Multimedia.ImageEffect.Core 82 * @since 12 83 */ 84 #define OH_EFFECT_CROP_FILTER "Crop" 85 86 /** 87 * @brief Define the key that means intensity 88 * 89 * @syscap SystemCapability.Multimedia.ImageEffect.Core 90 * @since 12 91 */ 92 #define OH_EFFECT_FILTER_INTENSITY_KEY "FilterIntensity" 93 94 /** 95 * @brief Define the key that means region and matches the value ref to {@link ImageEffect_Any} contain the data type of 96 * {@link EFFECT_DATA_TYPE_PTR} for {@link ImageEffect_Region} 97 * 98 * @syscap SystemCapability.Multimedia.ImageEffect.Core 99 * @since 12 100 */ 101 #define OH_EFFECT_FILTER_REGION_KEY "FilterRegion" 102 103 /** 104 * @brief Enumerates the data type 105 * 106 * @syscap SystemCapability.Multimedia.ImageEffect.Core 107 * @since 12 108 */ 109 typedef enum ImageEffect_DataType { 110 /** unknown data type */ 111 EFFECT_DATA_TYPE_UNKNOWN = 0, 112 /** int32_t data type */ 113 EFFECT_DATA_TYPE_INT32 = 1, 114 /** float data type */ 115 EFFECT_DATA_TYPE_FLOAT = 2, 116 /** double data type */ 117 EFFECT_DATA_TYPE_DOUBLE = 3, 118 /** char data type */ 119 EFFECT_DATA_TYPE_CHAR = 4, 120 /** long data type */ 121 EFFECT_DATA_TYPE_LONG = 5, 122 /** bool data type */ 123 EFFECT_DATA_TYPE_BOOL = 6, 124 /** point data type */ 125 EFFECT_DATA_TYPE_PTR = 7, 126 } ImageEffect_DataType; 127 128 /** 129 * @brief Data value for the union 130 * 131 * @syscap SystemCapability.Multimedia.ImageEffect.Core 132 * @since 12 133 */ 134 typedef union ImageEffect_DataValue { 135 /** Parameter of 32-bit integer value matches with {@link EFFECT_DATA_TYPE_INT32} */ 136 int32_t int32Value; 137 /** Parameter of float value matches with {@link EFFECT_DATA_TYPE_FLOAT} */ 138 float floatValue; 139 /** Parameter of double value matches with {@link EFFECT_DATA_TYPE_DOUBLE} */ 140 double doubleValue; 141 /** Parameter of character value matches with {@link EFFECT_DATA_TYPE_CHAR} */ 142 char charValue; 143 /** Parameter of long integer value matches with {@link EFFECT_DATA_TYPE_LONG} */ 144 long longValue; 145 /** Parameter of bool value matches with {@link EFFECT_DATA_TYPE_BOOL} */ 146 bool boolValue; 147 /** Parameter of point value matches with {@link EFFECT_DATA_TYPE_PTR} */ 148 void *ptrValue; 149 } ImageEffect_DataValue; 150 151 #ifdef __cplusplus 152 /** 153 * @brief Data parameter struct information 154 * 155 * @syscap SystemCapability.Multimedia.ImageEffect.Core 156 * @since 12 157 */ 158 typedef struct ImageEffect_Any { 159 /** Effect any data type */ 160 ImageEffect_DataType dataType = ImageEffect_DataType::EFFECT_DATA_TYPE_UNKNOWN; 161 /** Effect any data value */ 162 ImageEffect_DataValue dataValue = { 0 }; 163 } ImageEffect_Any; 164 #else 165 /** 166 * @brief Data parameter struct information 167 * 168 * @syscap SystemCapability.Multimedia.ImageEffect.Core 169 * @since 12 170 */ 171 typedef struct ImageEffect_Any { 172 /** Effect any data type */ 173 ImageEffect_DataType dataType; 174 /** Effect any data value */ 175 ImageEffect_DataValue dataValue; 176 } ImageEffect_Any; 177 #endif 178 179 /** 180 * @brief Enumerates the pixel format type 181 * 182 * @syscap SystemCapability.Multimedia.ImageEffect.Core 183 * @since 12 184 */ 185 typedef enum ImageEffect_Format { 186 /** Unknown pixel format */ 187 EFFECT_PIXEL_FORMAT_UNKNOWN = 0, 188 /** RGBA8888 pixel format */ 189 EFFECT_PIXEL_FORMAT_RGBA8888 = 1, 190 /** NV21 pixel format */ 191 EFFECT_PIXEL_FORMAT_NV21 = 2, 192 /** NV12 pixel format */ 193 EFFECT_PIXEL_FORMAT_NV12 = 3, 194 /** RGBA 10bit pixel format */ 195 EFFECT_PIXEL_FORMAT_RGBA1010102 = 4, 196 /** YCBCR420 semi-planar 10bit pixel format */ 197 EFFECT_PIXEL_FORMAT_YCBCR_P010 = 5, 198 /** YCRCB420 semi-planar 10bit pixel format */ 199 EFFECT_PIXEL_FORMAT_YCRCB_P010 = 6, 200 } ImageEffect_Format; 201 202 /** 203 * @brief Enumerates the effect buffer type 204 * 205 * @syscap SystemCapability.Multimedia.ImageEffect.Core 206 * @since 12 207 */ 208 typedef enum ImageEffect_BufferType { 209 /** Unknown buffer type */ 210 EFFECT_BUFFER_TYPE_UNKNOWN = 0, 211 /** Pixel buffer type */ 212 EFFECT_BUFFER_TYPE_PIXEL = 1, 213 /** Texture buffer type */ 214 EFFECT_BUFFER_TYPE_TEXTURE = 2, 215 } ImageEffect_BufferType; 216 217 /** 218 * @brief Define the new type name OH_EffectFilterInfo for struct OH_EffectFilterInfo 219 * 220 * @syscap SystemCapability.Multimedia.ImageEffect.Core 221 * @since 12 222 */ 223 typedef struct OH_EffectFilterInfo OH_EffectFilterInfo; 224 225 /** 226 * @brief Create an OH_EffectFilterInfo instance. It should be noted that the life cycle of the OH_EffectFilterInfo 227 * instance pointed to by the return value * needs to be manually released by {@link OH_EffectFilterInfo_Release} 228 * 229 * @syscap SystemCapability.Multimedia.ImageEffect.Core 230 * @return Returns a pointer to an OH_EffectFilterInfo instance if the execution is successful, otherwise returns 231 * nullptr 232 * @since 12 233 */ 234 OH_EffectFilterInfo *OH_EffectFilterInfo_Create(); 235 236 /** 237 * @brief Set the filter name for OH_EffectFilterInfo structure 238 * 239 * @syscap SystemCapability.Multimedia.ImageEffect.Core 240 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 241 * @param name Indicates the filter name 242 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 243 * {@link ImageEffect_ErrorCode} 244 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 245 * @since 12 246 */ 247 ImageEffect_ErrorCode OH_EffectFilterInfo_SetFilterName(OH_EffectFilterInfo *info, const char *name); 248 249 /** 250 * @brief Get the filter name from OH_EffectFilterInfo structure 251 * 252 * @syscap SystemCapability.Multimedia.ImageEffect.Core 253 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 254 * @param name Indicates the filter name 255 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 256 * {@link ImageEffect_ErrorCode} 257 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 258 * @since 12 259 */ 260 ImageEffect_ErrorCode OH_EffectFilterInfo_GetFilterName(OH_EffectFilterInfo *info, char **name); 261 262 /** 263 * @brief Set the supported buffer types for OH_EffectFilterInfo structure 264 * 265 * @syscap SystemCapability.Multimedia.ImageEffect.Core 266 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 267 * @param size The size of {@link ImageEffect_BufferType} that can be supported 268 * @param bufferTypeArray Array of {@link ImageEffect_BufferType} that can be supported 269 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 270 * {@link ImageEffect_ErrorCode} 271 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 272 * @since 12 273 */ 274 ImageEffect_ErrorCode OH_EffectFilterInfo_SetSupportedBufferTypes(OH_EffectFilterInfo *info, uint32_t size, 275 ImageEffect_BufferType *bufferTypeArray); 276 277 /** 278 * @brief Get the supported buffer types from OH_EffectFilterInfo structure 279 * 280 * @syscap SystemCapability.Multimedia.ImageEffect.Core 281 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 282 * @param size The size of {@link OH_EffectBufferInfoType} that can be supported 283 * @param bufferTypeArray Array of {@link OH_EffectBufferInfoType} that can be supported 284 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 285 * {@link ImageEffect_ErrorCode} 286 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 287 * @since 12 288 */ 289 ImageEffect_ErrorCode OH_EffectFilterInfo_GetSupportedBufferTypes(OH_EffectFilterInfo *info, uint32_t *size, 290 ImageEffect_BufferType **bufferTypeArray); 291 292 /** 293 * @brief Set the supported formats for OH_EffectFilterInfo structure 294 * 295 * @syscap SystemCapability.Multimedia.ImageEffect.Core 296 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 297 * @param size The size of {@link ImageEffect_Format} that can be supported 298 * @param formatArray Array of {@link ImageEffect_Format} that can be supported 299 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 300 * {@link ImageEffect_ErrorCode} 301 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 302 * @since 12 303 */ 304 ImageEffect_ErrorCode OH_EffectFilterInfo_SetSupportedFormats(OH_EffectFilterInfo *info, uint32_t size, 305 ImageEffect_Format *formatArray); 306 307 /** 308 * @brief Get the supported formats from OH_EffectFilterInfo structure 309 * 310 * @syscap SystemCapability.Multimedia.ImageEffect.Core 311 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 312 * @param size The size of {@link ImageEffect_Format} that can be supported 313 * @param formatArray Array of {@link ImageEffect_Format} that can be supported 314 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 315 * {@link ImageEffect_ErrorCode} 316 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 317 * @since 12 318 */ 319 ImageEffect_ErrorCode OH_EffectFilterInfo_GetSupportedFormats(OH_EffectFilterInfo *info, uint32_t *size, 320 ImageEffect_Format **formatArray); 321 322 /** 323 * @brief Clear the internal resources of the OH_EffectFilterInfo and destroy the OH_EffectFilterInfo instance 324 * 325 * @syscap SystemCapability.Multimedia.ImageEffect.Core 326 * @param info Encapsulate OH_EffectFilterInfo structure instance pointer 327 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 328 * {@link ImageEffect_ErrorCode} 329 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 330 * @since 12 331 */ 332 ImageEffect_ErrorCode OH_EffectFilterInfo_Release(OH_EffectFilterInfo *info); 333 334 #ifdef __cplusplus 335 /** 336 * @brief EffectFilter names information 337 * 338 * @syscap SystemCapability.Multimedia.ImageEffect.Core 339 * @since 12 340 */ 341 typedef struct ImageEffect_FilterNames { 342 /** EffectFilter names array size */ 343 uint32_t size = 0; 344 /** EffectFilter names memory block */ 345 const char **nameList = nullptr; 346 } ImageEffect_FilterNames; 347 #else 348 /** 349 * @brief EffectFilter names information 350 * 351 * @syscap SystemCapability.Multimedia.ImageEffect.Core 352 * @since 12 353 */ 354 typedef struct ImageEffect_FilterNames { 355 /** EffectFilter names array size */ 356 uint32_t size; 357 /** EffectFilter names memory block */ 358 const char **nameList; 359 } ImageEffect_FilterNames; 360 #endif 361 362 /** 363 * @brief Define the new type name OH_EffectBufferInfo for struct OH_EffectBufferInfo 364 * 365 * @syscap SystemCapability.Multimedia.ImageEffect.Core 366 * @since 12 367 */ 368 typedef struct OH_EffectBufferInfo OH_EffectBufferInfo; 369 370 /** 371 * @brief Create an OH_EffectBufferInfo instance. It should be noted that the life cycle of the OH_EffectBufferInfo 372 * instance pointed to by the return value * needs to be manually released by {@link OH_EffectBufferInfo_Release} 373 * 374 * @syscap SystemCapability.Multimedia.ImageEffect.Core 375 * @return Returns a pointer to an OH_EffectBufferInfo instance if the execution is successful, otherwise returns 376 * nullptr 377 * @since 12 378 */ 379 OH_EffectBufferInfo *OH_EffectBufferInfo_Create(); 380 381 /** 382 * @brief Set access to the address of the image in memory 383 * 384 * @syscap SystemCapability.Multimedia.ImageEffect.Core 385 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 386 * @param addr Indicates the address of the image in memory 387 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 388 * {@link ImageEffect_ErrorCode} 389 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 390 * @since 12 391 */ 392 ImageEffect_ErrorCode OH_EffectBufferInfo_SetAddr(OH_EffectBufferInfo *info, void *addr); 393 394 /** 395 * @brief Provide direct access to the address of the image in memory for rendering the filter effects 396 * 397 * @syscap SystemCapability.Multimedia.ImageEffect.Core 398 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 399 * @param addr Indicates the address of the image in memory 400 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 401 * {@link ImageEffect_ErrorCode} 402 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 403 * @since 12 404 */ 405 ImageEffect_ErrorCode OH_EffectBufferInfo_GetAddr(OH_EffectBufferInfo *info, void **addr); 406 407 /** 408 * @brief Set the width of the image in pixels 409 * 410 * @syscap SystemCapability.Multimedia.ImageEffect.Core 411 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 412 * @param width Indicates the width of the image 413 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 414 * {@link ImageEffect_ErrorCode} 415 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 416 * @since 12 417 */ 418 ImageEffect_ErrorCode OH_EffectBufferInfo_SetWidth(OH_EffectBufferInfo *info, int32_t width); 419 420 /** 421 * @brief Get the width of the image in pixels 422 * 423 * @syscap SystemCapability.Multimedia.ImageEffect.Core 424 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 425 * @param width Indicates the width of the image 426 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 427 * {@link ImageEffect_ErrorCode} 428 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 429 * @since 12 430 */ 431 ImageEffect_ErrorCode OH_EffectBufferInfo_GetWidth(OH_EffectBufferInfo *info, int32_t *width); 432 433 /** 434 * @brief Set the height of the image in pixels 435 * 436 * @syscap SystemCapability.Multimedia.ImageEffect.Core 437 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 438 * @param height Indicates the height of the image 439 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 440 * {@link ImageEffect_ErrorCode} 441 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 442 * @since 12 443 */ 444 ImageEffect_ErrorCode OH_EffectBufferInfo_SetHeight(OH_EffectBufferInfo *info, int32_t height); 445 446 /** 447 * @brief Get the height of the image in pixels 448 * 449 * @syscap SystemCapability.Multimedia.ImageEffect.Core 450 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 451 * @param height Indicates the height of the image 452 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 453 * {@link ImageEffect_ErrorCode} 454 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 455 * @since 12 456 */ 457 ImageEffect_ErrorCode OH_EffectBufferInfo_GetHeight(OH_EffectBufferInfo *info, int32_t *height); 458 459 /** 460 * @brief Set number of bytes per row for the image 461 * 462 * @syscap SystemCapability.Multimedia.ImageEffect.Core 463 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 464 * @param rowSize Indicates number of bytes per row 465 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 466 * {@link ImageEffect_ErrorCode} 467 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 468 * @since 12 469 */ 470 ImageEffect_ErrorCode OH_EffectBufferInfo_SetRowSize(OH_EffectBufferInfo *info, int32_t rowSize); 471 472 /** 473 * @brief Get number of bytes per row for the image 474 * 475 * @syscap SystemCapability.Multimedia.ImageEffect.Core 476 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 477 * @param rowSize Indicates number of bytes per row 478 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 479 * {@link ImageEffect_ErrorCode} 480 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 481 * @since 12 482 */ 483 ImageEffect_ErrorCode OH_EffectBufferInfo_GetRowSize(OH_EffectBufferInfo *info, int32_t *rowSize); 484 485 /** 486 * @brief Set the format of the image for OH_EffectBufferInfo 487 * 488 * @syscap SystemCapability.Multimedia.ImageEffect.Core 489 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 490 * @param format Indicates {@link ImageEffect_Format} of the image 491 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 492 * {@link ImageEffect_ErrorCode} 493 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 494 * @since 12 495 */ 496 ImageEffect_ErrorCode OH_EffectBufferInfo_SetEffectFormat(OH_EffectBufferInfo *info, ImageEffect_Format format); 497 498 /** 499 * @brief Get the format of the image from OH_EffectBufferInfo 500 * 501 * @syscap SystemCapability.Multimedia.ImageEffect.Core 502 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 503 * @param format Indicates {@link ImageEffect_Format} of the image 504 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 505 * {@link ImageEffect_ErrorCode} 506 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 507 * @since 12 508 */ 509 ImageEffect_ErrorCode OH_EffectBufferInfo_GetEffectFormat(OH_EffectBufferInfo *info, ImageEffect_Format *format); 510 511 /** 512 * @brief Set the timestamp of the image for OH_EffectBufferInfo 513 * 514 * @syscap SystemCapability.Multimedia.ImageEffect.Core 515 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 516 * @param timestamp Indicates the timestamp of the image frame data for the OHNativeWindow input type. 517 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 518 * {@link ImageEffect_ErrorCode} 519 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 520 * @since 12 521 */ 522 ImageEffect_ErrorCode OH_EffectBufferInfo_SetTimestamp(OH_EffectBufferInfo *info, int64_t timestamp); 523 524 /** 525 * @brief Get the timestamp of the image from OH_EffectBufferInfo 526 * 527 * @syscap SystemCapability.Multimedia.ImageEffect.Core 528 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 529 * @param timestamp Indicates the timestamp of the image frame data for the OHNativeWindow input type. 530 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 531 * {@link ImageEffect_ErrorCode} 532 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 533 * @since 12 534 */ 535 ImageEffect_ErrorCode OH_EffectBufferInfo_GetTimestamp(OH_EffectBufferInfo *info, int64_t *timestamp); 536 537 /** 538 * @brief Sets the texture ID of the image for an OH_EffectBufferInfo struct. 539 * 540 * @syscap SystemCapability.Multimedia.ImageEffect.Core 541 * @param info Pointer to an instance of the OH_EffectBufferInfo struct. 542 * @param textureId Pointer to the texture ID of the image. 543 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 544 * parameter parameter is missing. 545 * @since 20 546 */ 547 ImageEffect_ErrorCode OH_EffectBufferInfo_SetTextureId(OH_EffectBufferInfo *info, int32_t textureId); 548 549 /** 550 * @brief Obtains the texture ID of an image from an OH_EffectBufferInfo struct. 551 * 552 * @syscap SystemCapability.Multimedia.ImageEffect.Core 553 * @param info Pointer to an instance of the OH_EffectBufferInfo struct. 554 * @param textureId Texture ID of the image. 555 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 556 * parameter parameter is missing. 557 * @since 20 558 */ 559 ImageEffect_ErrorCode OH_EffectBufferInfo_GetTextureId(OH_EffectBufferInfo *info, int32_t *textureId); 560 561 /** 562 * @brief Clear the internal resources of the OH_EffectBufferInfo and destroy the OH_EffectBufferInfo instance 563 * 564 * @syscap SystemCapability.Multimedia.ImageEffect.Core 565 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 566 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 567 * {@link ImageEffect_ErrorCode} 568 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 569 * @since 12 570 */ 571 ImageEffect_ErrorCode OH_EffectBufferInfo_Release(OH_EffectBufferInfo *info); 572 573 /** 574 * @brief When executing the method of {@link OH_EffectFilter_SetValue} for the delegate filter, the function pointer 575 * will be called for checking the parameters is valid for the delegate filter 576 * 577 * @syscap SystemCapability.Multimedia.ImageEffect.Core 578 * @param filter Encapsulate OH_EffectFilter structure instance pointer 579 * @param key Indicates the key of the filter 580 * @param value Indicates the value corresponding to the key of the filter 581 * @return Returns true if the parameter is valid, otherwise returns false 582 * @since 12 583 */ 584 typedef bool (*OH_EffectFilterDelegate_SetValue)(OH_EffectFilter *filter, const char *key, 585 const ImageEffect_Any *value); 586 587 /** 588 * @brief Actively execute this callback function at the end of invoking the method of 589 * {@link OH_EffectFilterDelegate_Render} for passing possible new OH_EffectBufferInfo to the next filter. It should be 590 * noted that when passing new OH_EffectBufferInfo, the buffer in OH_EffectBufferInfo needs to be manually released 591 * after the execution of the function ends 592 * 593 * @syscap SystemCapability.Multimedia.ImageEffect.Core 594 * @param filter Encapsulate OH_EffectFilter structure instance pointer 595 * @param info Indicates the information of the image, such as width, height, etc. See {@link OH_EffectBufferInfo} 596 * @since 12 597 */ 598 typedef void (*OH_EffectFilterDelegate_PushData)(OH_EffectFilter *filter, OH_EffectBufferInfo *info); 599 600 /** 601 * @brief When the method of OH_ImageEffect_Start is executed on delegate filter that is contained in OH_ImageEffect, 602 * the function pointer will be called for rendering the delegate filter effects 603 * 604 * @syscap SystemCapability.Multimedia.ImageEffect.Core 605 * @param filter Encapsulate OH_EffectFilter structure instance pointer 606 * @param info Indicates the information of the image, such as width, height, etc. See {@link OH_EffectBufferInfo} 607 * @param pushData Indicates the callback function for passing possible new OH_EffectBufferInfo to the next filter. See 608 * {@link OH_EffectFilterDelegate_PushData} 609 * @return Returns true if this function point is executed successfully, otherwise returns false 610 * @since 12 611 */ 612 typedef bool (*OH_EffectFilterDelegate_Render)(OH_EffectFilter *filter, OH_EffectBufferInfo *info, 613 OH_EffectFilterDelegate_PushData pushData); 614 615 /** 616 * @brief When the method of OH_ImageEffect_Save is executed on delegate filter that is contained in OH_ImageEffect, 617 * the function pointer will be called for serializing the delegate filter parameters 618 * 619 * @syscap SystemCapability.Multimedia.ImageEffect.Core 620 * @param filter Encapsulate OH_EffectFilter structure instance pointer 621 * @param info Indicates the serialized information that is obtained by converting the delegate filter parameters to 622 * JSON string 623 * @return Returns true if this function point is executed successfully, otherwise returns false 624 * @since 12 625 */ 626 typedef bool (*OH_EffectFilterDelegate_Save)(OH_EffectFilter *filter, char **info); 627 628 /** 629 * @brief When the method of OH_ImageEffect_Restore is executed on delegate filter that is contained in OH_ImageEffect, 630 * the function pointer will be called for deserializing the delegate filter parameters 631 * 632 * @syscap SystemCapability.Multimedia.ImageEffect.Core 633 * @param info Indicates the serialized information that is obtained by converting the delegate filter parameters to 634 * JSON string 635 * @return Returns a pointer to an OH_EffectFilter instance if the execution is successful, otherwise returns nullptr 636 * @since 12 637 */ 638 typedef OH_EffectFilter *(*OH_EffectFilterDelegate_Restore)(const char *info); 639 640 /** 641 * @brief A collection of all callback function pointers in OH_EffectFilter. Register an instance of this structure to 642 * the OH_EffectFilter instance by invoking {@link OH_EffectFilter_Register}, and perform related rendering operations 643 * through the callback 644 * 645 * @syscap SystemCapability.Multimedia.ImageEffect.Core 646 * @since 12 647 */ 648 typedef struct ImageEffect_FilterDelegate { 649 /** Monitor checking parameters */ 650 OH_EffectFilterDelegate_SetValue setValue; 651 /** Monitor render */ 652 OH_EffectFilterDelegate_Render render; 653 /** Monitor serialize */ 654 OH_EffectFilterDelegate_Save save; 655 /** Monitor deserialize */ 656 OH_EffectFilterDelegate_Restore restore; 657 } ImageEffect_FilterDelegate; 658 659 /** 660 * @brief Describes the region information 661 * 662 * @syscap SystemCapability.Multimedia.ImageEffect.Core 663 * @since 12 664 */ 665 typedef struct ImageEffect_Region { 666 /** X coordinate of the start point of a line */ 667 int32_t x0; 668 /** Y coordinate of the start point of a line */ 669 int32_t y0; 670 /** X coordinate of the end point of a line */ 671 int32_t x1; 672 /** Y coordinate of the end point of a line */ 673 int32_t y1; 674 } ImageEffect_Region; 675 676 /** 677 * @brief Describes the image size information 678 * 679 * @syscap SystemCapability.Multimedia.ImageEffect.Core 680 * @since 12 681 */ 682 typedef struct ImageEffect_Size { 683 /** Image width, in pixels */ 684 int32_t width; 685 /** Image height, in pixels */ 686 int32_t height; 687 } ImageEffect_Size; 688 689 /** 690 * @brief Create an OH_EffectFilter instance. It should be noted that the life cycle of the OH_EffectFilter instance 691 * pointed to by the return value * needs to be manually released by {@link OH_EffectFilter_Release} 692 * 693 * @syscap SystemCapability.Multimedia.ImageEffect.Core 694 * @param name Indicates the filter name. For example, see {@link OH_EFFECT_BRIGHTNESS_FILTER} 695 * @return Returns a pointer to an OH_EffectFilter instance if the execution is successful, otherwise returns nullptr 696 * @since 12 697 */ 698 OH_EffectFilter *OH_EffectFilter_Create(const char *name); 699 700 /** 701 * @brief Set the filter parameter. It can be set multiple parameters by invoking this function multiple times 702 * 703 * @syscap SystemCapability.Multimedia.ImageEffect.Core 704 * @param filter Encapsulate OH_EffectFilter structure instance pointer 705 * @param key Indicates the key of the filter. For example, see {@link OH_EFFECT_FILTER_INTENSITY_KEY} 706 * @param value Indicates the value corresponding to the key of the filter 707 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 708 * {@link ImageEffect_ErrorCode} 709 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 710 * {@link EFFECT_KEY_ERROR}, the key of the filter parameter is invalid. 711 * {@link EFFECT_PARAM_ERROR}, the value of the filter parameter is invalid. 712 * @since 12 713 */ 714 ImageEffect_ErrorCode OH_EffectFilter_SetValue(OH_EffectFilter *filter, const char *key, const ImageEffect_Any *value); 715 716 /** 717 * @brief Get the filter parameter 718 * 719 * @syscap SystemCapability.Multimedia.ImageEffect.Core 720 * @param filter Encapsulate OH_EffectFilter structure instance pointer 721 * @param key Indicates the key of the filter 722 * @param value Indicates the value corresponding to the key of the filter 723 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 724 * {@link ImageEffect_ErrorCode} 725 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 726 * {@link EFFECT_KEY_ERROR}, the key of the filter parameter is invalid. 727 * @since 12 728 */ 729 ImageEffect_ErrorCode OH_EffectFilter_GetValue(OH_EffectFilter *filter, const char *key, ImageEffect_Any *value); 730 731 /** 732 * @brief Register the delegate filter 733 * 734 * @syscap SystemCapability.Multimedia.ImageEffect.Core 735 * @param info Indicates the capabilities supported by delegate filter, see {@link OH_EffectFilterInfo} 736 * @param delegate A collection of all callback functions, see {@link ImageEffect_FilterDelegate} 737 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 738 * {@link ImageEffect_ErrorCode} 739 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 740 * @since 12 741 */ 742 ImageEffect_ErrorCode OH_EffectFilter_Register(const OH_EffectFilterInfo *info, 743 const ImageEffect_FilterDelegate *delegate); 744 745 /** 746 * @brief Lookup for the filter names that matches the lookup condition. It should be noted that the allocated memory of 747 * ImageEffect_FilterNames can be manually released by invoking {@link OH_EffectFilter_ReleaseFilterNames} if need 748 * 749 * @syscap SystemCapability.Multimedia.ImageEffect.Core 750 * @param key Indicates the lookup condition 751 * @return Returns Filter name array that matches the key, see {@link ImageEffect_FilterNames} 752 * @since 12 753 */ 754 ImageEffect_FilterNames *OH_EffectFilter_LookupFilters(const char *key); 755 756 /** 757 * @brief Clear the internal cached resources of the ImageEffect_FilterNames 758 * 759 * @syscap SystemCapability.Multimedia.ImageEffect.Core 760 * @since 12 761 */ 762 void OH_EffectFilter_ReleaseFilterNames(); 763 764 /** 765 * @brief Lookup for the capabilities that supported by the filter 766 * 767 * @syscap SystemCapability.Multimedia.ImageEffect.Core 768 * @param name Indicates the filter name 769 * @param info Indicates the capabilities supported by the filter, see {@link OH_EffectFilterInfo} 770 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 771 * {@link ImageEffect_ErrorCode} 772 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 773 * @since 12 774 */ 775 ImageEffect_ErrorCode OH_EffectFilter_LookupFilterInfo(const char *name, OH_EffectFilterInfo *info); 776 777 /** 778 * @brief Render the filter effects. The function is designed to support the same input and output image 779 * 780 * @syscap SystemCapability.Multimedia.ImageEffect.Core 781 * @param filter Encapsulate OH_EffectFilter structure instance pointer 782 * @param inputPixelmap Indicates the input image 783 * @param outputPixelmap Indicates the output image 784 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 785 * {@link ImageEffect_ErrorCode} 786 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 787 * @since 12 788 */ 789 ImageEffect_ErrorCode OH_EffectFilter_Render(OH_EffectFilter *filter, OH_PixelmapNative *inputPixelmap, 790 OH_PixelmapNative *outputPixelmap); 791 792 /** 793 * @brief Applies the filter effect using texture IDs. This function does not support using the same texture 794 * for for both input and output. 795 * 796 * @syscap SystemCapability.Multimedia.ImageEffect.Core 797 * @param filter Pointer to an instance of the OH_EffectFilter struct. 798 * @param inputTextureId ID of the input texture. This ID must be valid and bound to a texture of the 799 * GL_TEXTURE_2D GL_TEXTURE_2D type. 800 * @param outputTextureId ID of the output texture. This ID must be valid. If it is not bound to a texture, it 801 * will will automatically be bound to a GL_TEXTURE_2D type. If the texture is already bound and the size is 802 * inappropriate, inappropriate, the rendered result may be cropped or partially filled into this texture. 803 * @param colorSpace Color space of the image. 804 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 805 * parameter parameter is missing. 806 * @since 20 807 */ 808 ImageEffect_ErrorCode OH_EffectFilter_RenderWithTextureId(OH_EffectFilter *filter, int32_t inputTextureId, 809 int32_t outputTextureId, int32_t colorSpace); 810 811 /** 812 * @brief Clear the internal resources of the OH_EffectFilter and destroy the OH_EffectFilter instance 813 * 814 * @syscap SystemCapability.Multimedia.ImageEffect.Core 815 * @param filter Encapsulate OH_EffectFilter structure instance pointer 816 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 817 * {@link ImageEffect_ErrorCode} 818 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 819 * @since 12 820 */ 821 ImageEffect_ErrorCode OH_EffectFilter_Release(OH_EffectFilter *filter); 822 823 #ifdef __cplusplus 824 } 825 #endif 826 #endif // NATIVE_IMAGE_EFFECT_FILTER_H 827 /** @} */