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 Clear the internal resources of the OH_EffectBufferInfo and destroy the OH_EffectBufferInfo instance 539 * 540 * @syscap SystemCapability.Multimedia.ImageEffect.Core 541 * @param info Encapsulate OH_EffectBufferInfo structure instance pointer 542 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 543 * {@link ImageEffect_ErrorCode} 544 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 545 * @since 12 546 */ 547 ImageEffect_ErrorCode OH_EffectBufferInfo_Release(OH_EffectBufferInfo *info); 548 549 /** 550 * @brief When executing the method of {@link OH_EffectFilter_SetValue} for the delegate filter, the function pointer 551 * will be called for checking the parameters is valid for the delegate filter 552 * 553 * @syscap SystemCapability.Multimedia.ImageEffect.Core 554 * @param filter Encapsulate OH_EffectFilter structure instance pointer 555 * @param key Indicates the key of the filter 556 * @param value Indicates the value corresponding to the key of the filter 557 * @return Returns true if the parameter is valid, otherwise returns false 558 * @since 12 559 */ 560 typedef bool (*OH_EffectFilterDelegate_SetValue)(OH_EffectFilter *filter, const char *key, 561 const ImageEffect_Any *value); 562 563 /** 564 * @brief Actively execute this callback function at the end of invoking the method of 565 * {@link OH_EffectFilterDelegate_Render} for passing possible new OH_EffectBufferInfo to the next filter. It should be 566 * noted that when passing new OH_EffectBufferInfo, the buffer in OH_EffectBufferInfo needs to be manually released 567 * after the execution of the function ends 568 * 569 * @syscap SystemCapability.Multimedia.ImageEffect.Core 570 * @param filter Encapsulate OH_EffectFilter structure instance pointer 571 * @param info Indicates the information of the image, such as width, height, etc. See {@link OH_EffectBufferInfo} 572 * @since 12 573 */ 574 typedef void (*OH_EffectFilterDelegate_PushData)(OH_EffectFilter *filter, OH_EffectBufferInfo *info); 575 576 /** 577 * @brief When the method of OH_ImageEffect_Start is executed on delegate filter that is contained in OH_ImageEffect, 578 * the function pointer will be called for rendering the delegate filter effects 579 * 580 * @syscap SystemCapability.Multimedia.ImageEffect.Core 581 * @param filter Encapsulate OH_EffectFilter structure instance pointer 582 * @param info Indicates the information of the image, such as width, height, etc. See {@link OH_EffectBufferInfo} 583 * @param pushData Indicates the callback function for passing possible new OH_EffectBufferInfo to the next filter. See 584 * {@link OH_EffectFilterDelegate_PushData} 585 * @return Returns true if this function point is executed successfully, otherwise returns false 586 * @since 12 587 */ 588 typedef bool (*OH_EffectFilterDelegate_Render)(OH_EffectFilter *filter, OH_EffectBufferInfo *info, 589 OH_EffectFilterDelegate_PushData pushData); 590 591 /** 592 * @brief When the method of OH_ImageEffect_Save is executed on delegate filter that is contained in OH_ImageEffect, 593 * the function pointer will be called for serializing the delegate filter parameters 594 * 595 * @syscap SystemCapability.Multimedia.ImageEffect.Core 596 * @param filter Encapsulate OH_EffectFilter structure instance pointer 597 * @param info Indicates the serialized information that is obtained by converting the delegate filter parameters to 598 * JSON string 599 * @return Returns true if this function point is executed successfully, otherwise returns false 600 * @since 12 601 */ 602 typedef bool (*OH_EffectFilterDelegate_Save)(OH_EffectFilter *filter, char **info); 603 604 /** 605 * @brief When the method of OH_ImageEffect_Restore is executed on delegate filter that is contained in OH_ImageEffect, 606 * the function pointer will be called for deserializing the delegate filter parameters 607 * 608 * @syscap SystemCapability.Multimedia.ImageEffect.Core 609 * @param info Indicates the serialized information that is obtained by converting the delegate filter parameters to 610 * JSON string 611 * @return Returns a pointer to an OH_EffectFilter instance if the execution is successful, otherwise returns nullptr 612 * @since 12 613 */ 614 typedef OH_EffectFilter *(*OH_EffectFilterDelegate_Restore)(const char *info); 615 616 /** 617 * @brief A collection of all callback function pointers in OH_EffectFilter. Register an instance of this structure to 618 * the OH_EffectFilter instance by invoking {@link OH_EffectFilter_Register}, and perform related rendering operations 619 * through the callback 620 * 621 * @syscap SystemCapability.Multimedia.ImageEffect.Core 622 * @since 12 623 */ 624 typedef struct ImageEffect_FilterDelegate { 625 /** Monitor checking parameters */ 626 OH_EffectFilterDelegate_SetValue setValue; 627 /** Monitor render */ 628 OH_EffectFilterDelegate_Render render; 629 /** Monitor serialize */ 630 OH_EffectFilterDelegate_Save save; 631 /** Monitor deserialize */ 632 OH_EffectFilterDelegate_Restore restore; 633 } ImageEffect_FilterDelegate; 634 635 /** 636 * @brief Describes the region information 637 * 638 * @syscap SystemCapability.Multimedia.ImageEffect.Core 639 * @since 12 640 */ 641 typedef struct ImageEffect_Region { 642 /** X coordinate of the start point of a line */ 643 int32_t x0; 644 /** Y coordinate of the start point of a line */ 645 int32_t y0; 646 /** X coordinate of the end point of a line */ 647 int32_t x1; 648 /** Y coordinate of the end point of a line */ 649 int32_t y1; 650 } ImageEffect_Region; 651 652 /** 653 * @brief Describes the image size information 654 * 655 * @syscap SystemCapability.Multimedia.ImageEffect.Core 656 * @since 12 657 */ 658 typedef struct ImageEffect_Size { 659 /** Image width, in pixels */ 660 int32_t width; 661 /** Image height, in pixels */ 662 int32_t height; 663 } ImageEffect_Size; 664 665 /** 666 * @brief Create an OH_EffectFilter instance. It should be noted that the life cycle of the OH_EffectFilter instance 667 * pointed to by the return value * needs to be manually released by {@link OH_EffectFilter_Release} 668 * 669 * @syscap SystemCapability.Multimedia.ImageEffect.Core 670 * @param name Indicates the filter name. For example, see {@link OH_EFFECT_BRIGHTNESS_FILTER} 671 * @return Returns a pointer to an OH_EffectFilter instance if the execution is successful, otherwise returns nullptr 672 * @since 12 673 */ 674 OH_EffectFilter *OH_EffectFilter_Create(const char *name); 675 676 /** 677 * @brief Set the filter parameter. It can be set multiple parameters by invoking this function multiple times 678 * 679 * @syscap SystemCapability.Multimedia.ImageEffect.Core 680 * @param filter Encapsulate OH_EffectFilter structure instance pointer 681 * @param key Indicates the key of the filter. For example, see {@link OH_EFFECT_FILTER_INTENSITY_KEY} 682 * @param value Indicates the value corresponding to the key of the filter 683 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 684 * {@link ImageEffect_ErrorCode} 685 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 686 * {@link EFFECT_KEY_ERROR}, the key of the filter parameter is invalid. 687 * {@link EFFECT_PARAM_ERROR}, the value of the filter parameter is invalid. 688 * @since 12 689 */ 690 ImageEffect_ErrorCode OH_EffectFilter_SetValue(OH_EffectFilter *filter, const char *key, const ImageEffect_Any *value); 691 692 /** 693 * @brief Get the filter parameter 694 * 695 * @syscap SystemCapability.Multimedia.ImageEffect.Core 696 * @param filter Encapsulate OH_EffectFilter structure instance pointer 697 * @param key Indicates the key of the filter 698 * @param value Indicates the value corresponding to the key of the filter 699 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 700 * {@link ImageEffect_ErrorCode} 701 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 702 * {@link EFFECT_KEY_ERROR}, the key of the filter parameter is invalid. 703 * @since 12 704 */ 705 ImageEffect_ErrorCode OH_EffectFilter_GetValue(OH_EffectFilter *filter, const char *key, ImageEffect_Any *value); 706 707 /** 708 * @brief Register the delegate filter 709 * 710 * @syscap SystemCapability.Multimedia.ImageEffect.Core 711 * @param info Indicates the capabilities supported by delegate filter, see {@link OH_EffectFilterInfo} 712 * @param delegate A collection of all callback functions, see {@link ImageEffect_FilterDelegate} 713 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 714 * {@link ImageEffect_ErrorCode} 715 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 716 * @since 12 717 */ 718 ImageEffect_ErrorCode OH_EffectFilter_Register(const OH_EffectFilterInfo *info, 719 const ImageEffect_FilterDelegate *delegate); 720 721 /** 722 * @brief Lookup for the filter names that matches the lookup condition. It should be noted that the allocated memory of 723 * ImageEffect_FilterNames can be manually released by invoking {@link OH_EffectFilter_ReleaseFilterNames} if need 724 * 725 * @syscap SystemCapability.Multimedia.ImageEffect.Core 726 * @param key Indicates the lookup condition 727 * @return Returns Filter name array that matches the key, see {@link ImageEffect_FilterNames} 728 * @since 12 729 */ 730 ImageEffect_FilterNames *OH_EffectFilter_LookupFilters(const char *key); 731 732 /** 733 * @brief Clear the internal cached resources of the ImageEffect_FilterNames 734 * 735 * @syscap SystemCapability.Multimedia.ImageEffect.Core 736 * @since 12 737 */ 738 void OH_EffectFilter_ReleaseFilterNames(); 739 740 /** 741 * @brief Lookup for the capabilities that supported by the filter 742 * 743 * @syscap SystemCapability.Multimedia.ImageEffect.Core 744 * @param name Indicates the filter name 745 * @param info Indicates the capabilities supported by the filter, see {@link OH_EffectFilterInfo} 746 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 747 * {@link ImageEffect_ErrorCode} 748 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 749 * @since 12 750 */ 751 ImageEffect_ErrorCode OH_EffectFilter_LookupFilterInfo(const char *name, OH_EffectFilterInfo *info); 752 753 /** 754 * @brief Render the filter effects. The function is designed to support the same input and output image 755 * 756 * @syscap SystemCapability.Multimedia.ImageEffect.Core 757 * @param filter Encapsulate OH_EffectFilter structure instance pointer 758 * @param inputPixelmap Indicates the input image 759 * @param outputPixelmap Indicates the output image 760 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 761 * {@link ImageEffect_ErrorCode} 762 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 763 * @since 12 764 */ 765 ImageEffect_ErrorCode OH_EffectFilter_Render(OH_EffectFilter *filter, OH_PixelmapNative *inputPixelmap, 766 OH_PixelmapNative *outputPixelmap); 767 768 /** 769 * @brief Clear the internal resources of the OH_EffectFilter and destroy the OH_EffectFilter instance 770 * 771 * @syscap SystemCapability.Multimedia.ImageEffect.Core 772 * @param filter Encapsulate OH_EffectFilter structure instance pointer 773 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 774 * {@link ImageEffect_ErrorCode} 775 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 776 * @since 12 777 */ 778 ImageEffect_ErrorCode OH_EffectFilter_Release(OH_EffectFilter *filter); 779 780 #ifdef __cplusplus 781 } 782 #endif 783 #endif // NATIVE_IMAGE_EFFECT_FILTER_H 784 /** @} */