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 effect. 21 * 22 * @since 12 23 */ 24 25 /** 26 * @file image_effect.h 27 * 28 * @brief Declares the functions for rendering image. 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_H 37 #define NATIVE_IMAGE_EFFECT_H 38 39 #include "image_effect_errors.h" 40 #include "image_effect_filter.h" 41 #include "native_buffer/native_buffer.h" 42 #include "native_window/external_window.h" 43 #include "multimedia/image_framework/image/picture_native.h" 44 45 #ifdef __cplusplus 46 extern "C" { 47 #endif 48 49 /** 50 * @brief Define the new type name OH_ImageEffect for struct OH_ImageEffect 51 * 52 * @syscap SystemCapability.Multimedia.ImageEffect.Core 53 * @since 12 54 */ 55 typedef struct OH_ImageEffect OH_ImageEffect; 56 57 /** 58 * @brief Create an OH_ImageEffect instance. It should be noted that the life cycle of the OH_ImageEffect instance 59 * pointed to by the return value * needs to be manually released by {@link OH_ImageEffect_Release} 60 * 61 * @syscap SystemCapability.Multimedia.ImageEffect.Core 62 * @param name The name of image effect 63 * @return Returns a pointer to an OH_ImageEffect instance if the execution is successful, otherwise returns nullptr 64 * @since 12 65 */ 66 OH_ImageEffect *OH_ImageEffect_Create(const char *name); 67 68 /** 69 * @brief Create and add the OH_EffectFilter to the OH_ImageEffect 70 * 71 * @syscap SystemCapability.Multimedia.ImageEffect.Core 72 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 73 * @param filterName Indicates the name of the filter that can be customized by the developer or supported by the system 74 * @return Returns a pointer to an OH_EffectFilter instance if the filter name is valid, otherwise returns nullptr 75 * @since 12 76 */ 77 OH_EffectFilter *OH_ImageEffect_AddFilter(OH_ImageEffect *imageEffect, const char *filterName); 78 79 /** 80 * @brief Add the OH_EffectFilter to the OH_ImageEffect by the OH_EffectFilter instance pointer 81 * 82 * @syscap SystemCapability.Multimedia.ImageEffect.Core 83 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 84 * @param filter Indicates the filter instance that created by invoking OH_EffectFilter_Create 85 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 86 * {@link ImageEffect_ErrorCode} 87 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer 88 * @since 12 89 */ 90 ImageEffect_ErrorCode OH_ImageEffect_AddFilterByFilter(OH_ImageEffect *imageEffect, OH_EffectFilter *filter); 91 92 /** 93 * @brief Create and add the OH_EffectFilter to the OH_ImageEffect by specified position 94 * 95 * @syscap SystemCapability.Multimedia.ImageEffect.Core 96 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 97 * @param index Indicates the position of the OH_EffectFilter witch is created and added 98 * @param filterName Indicates the name of the filter that can be customized by the developer or supported by the system 99 * @return Returns a pointer to an OH_EffectFilter instance if the index and filter name is valid, otherwise returns 100 * nullptr 101 * @since 12 102 */ 103 OH_EffectFilter *OH_ImageEffect_InsertFilter(OH_ImageEffect *imageEffect, uint32_t index, const char *filterName); 104 105 /** 106 * @brief Insert the OH_EffectFilter to the OH_ImageEffect by the OH_EffectFilter instance pointer 107 * 108 * @syscap SystemCapability.Multimedia.ImageEffect.Core 109 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 110 * @param index Indicates the position of the OH_EffectFilter witch is added 111 * @param filter Indicates the filter instance that created by invoking OH_EffectFilter_Create 112 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 113 * {@link ImageEffect_ErrorCode} 114 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer or the index is invalid value 115 * @since 12 116 */ 117 ImageEffect_ErrorCode OH_ImageEffect_InsertFilterByFilter(OH_ImageEffect *imageEffect, uint32_t index, 118 OH_EffectFilter *filter); 119 120 /** 121 * @brief Remove all filters of the specified filter name 122 * 123 * @syscap SystemCapability.Multimedia.ImageEffect.Core 124 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 125 * @param filterName Indicates the name of the filter that can be customized by the developer or supported by the system 126 * @return Returns the number of the filters that matches the specified filter name 127 * @since 12 128 */ 129 int32_t OH_ImageEffect_RemoveFilter(OH_ImageEffect *imageEffect, const char *filterName); 130 131 /** 132 * @brief Remove the filter of the specified position 133 * 134 * @syscap SystemCapability.Multimedia.ImageEffect.Core 135 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 136 * @param index Indicates the position of the OH_EffectFilter witch is removed 137 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 138 * {@link ImageEffect_ErrorCode} 139 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer or the index is invalid value 140 * @since 12 141 */ 142 ImageEffect_ErrorCode OH_ImageEffect_RemoveFilterByIndex(OH_ImageEffect *imageEffect, uint32_t index); 143 144 /** 145 * @brief Create and replace the OH_EffectFilter in the OH_ImageEffect by the filter name 146 * 147 * @syscap SystemCapability.Multimedia.ImageEffect.Core 148 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 149 * @param index Indicates the position of the OH_EffectFilter witch is created and replaced 150 * @param filterName Indicates the name of the filter that can be customized by the developer or supported by the system 151 * @return Returns a pointer to an OH_EffectFilter instance if the index and filter name is valid, otherwise returns 152 * nullptr 153 * @since 12 154 */ 155 OH_EffectFilter *OH_ImageEffect_ReplaceFilter(OH_ImageEffect *imageEffect, uint32_t index, const char *filterName); 156 157 /** 158 * @brief Replace the OH_EffectFilter in the OH_ImageEffect by the OH_EffectFilter instance pointer 159 * 160 * @syscap SystemCapability.Multimedia.ImageEffect.Core 161 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 162 * @param index Indicates the position of the OH_EffectFilter witch is replaced 163 * @param filter Indicates the filter instance that created by invoking OH_EffectFilter_Create 164 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 165 * {@link ImageEffect_ErrorCode} 166 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer or the index is invalid value 167 * @since 12 168 */ 169 ImageEffect_ErrorCode OH_ImageEffect_ReplaceFilterByFilter(OH_ImageEffect *imageEffect, uint32_t index, 170 OH_EffectFilter *filter); 171 172 /** 173 * @brief Get the number of the filters in OH_ImageEffect 174 * 175 * @syscap SystemCapability.Multimedia.ImageEffect.Core 176 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 177 * @return Returns the number of the filters in OH_ImageEffect 178 * @since 12 179 */ 180 int32_t OH_ImageEffect_GetFilterCount(OH_ImageEffect *imageEffect); 181 182 /** 183 * @brief Get an OH_EffectFilter instance that add to OH_ImageEffect by the index 184 * 185 * @syscap SystemCapability.Multimedia.ImageEffect.Core 186 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 187 * @param index Indicates the position of the OH_EffectFilter that add to OH_ImageEffect 188 * @return Returns a pointer to an OH_EffectFilter instance if the index is valid, otherwise returns nullptr 189 * @since 12 190 */ 191 OH_EffectFilter *OH_ImageEffect_GetFilter(OH_ImageEffect *imageEffect, uint32_t index); 192 193 /** 194 * @brief Set configuration information to the OH_ImageEffect 195 * 196 * @syscap SystemCapability.Multimedia.ImageEffect.Core 197 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 198 * @param key Indicates the key of the configuration 199 * @param value Indicates the value corresponding to the key of the configuration 200 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 201 * {@link ImageEffect_ErrorCode} 202 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 203 * {@link EFFECT_KEY_ERROR}, the key of the configuration parameter is invalid. 204 * {@link EFFECT_PARAM_ERROR}, the value of the configuration parameter is invalid. 205 * @since 12 206 */ 207 ImageEffect_ErrorCode OH_ImageEffect_Configure(OH_ImageEffect *imageEffect, const char *key, 208 const ImageEffect_Any *value); 209 210 /** 211 * @brief Set the Surface to the image effect, this interface must be called before 212 * @{link OH_ImageEffect_GetInputSurface} is called 213 * 214 * @syscap SystemCapability.Multimedia.ImageEffect.Core 215 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 216 * @param nativeWindow A pointer to a OHNativeWindow instance, see {@link OHNativeWindow} 217 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 218 * {@link ImageEffect_ErrorCode} 219 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 220 * @since 12 221 */ 222 ImageEffect_ErrorCode OH_ImageEffect_SetOutputSurface(OH_ImageEffect *imageEffect, OHNativeWindow *nativeWindow); 223 224 /** 225 * @brief Get the input Surface from the image effect, this interface must be called after 226 * @{link OH_ImageEffect_SetOutputSurface} is called 227 * 228 * @syscap SystemCapability.Multimedia.ImageEffect.Core 229 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 230 * @param nativeWindow A pointer to a OHNativeWindow instance, see {@link OHNativeWindow} 231 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 232 * {@link ImageEffect_ErrorCode} 233 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 234 * @since 12 235 */ 236 ImageEffect_ErrorCode OH_ImageEffect_GetInputSurface(OH_ImageEffect *imageEffect, OHNativeWindow **nativeWindow); 237 238 /** 239 * @brief Set input pixelmap that contains the image information. It should be noted that the input pixel map will be 240 * directly rendered and modified if the output is not set 241 * 242 * @syscap SystemCapability.Multimedia.ImageEffect.Core 243 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 244 * @param pixelmap Indicates the OH_PixelmapNative that contains the image information 245 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 246 * {@link ImageEffect_ErrorCode} 247 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 248 * @since 12 249 */ 250 ImageEffect_ErrorCode OH_ImageEffect_SetInputPixelmap(OH_ImageEffect *imageEffect, OH_PixelmapNative *pixelmap); 251 252 /** 253 * @brief Set output pixelmap that contains the image information 254 * 255 * @syscap SystemCapability.Multimedia.ImageEffect.Core 256 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 257 * @param pixelmap Indicates the OH_PixelmapNative that contains the image information 258 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 259 * {@link ImageEffect_ErrorCode} 260 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 261 * @since 12 262 */ 263 ImageEffect_ErrorCode OH_ImageEffect_SetOutputPixelmap(OH_ImageEffect *imageEffect, OH_PixelmapNative *pixelmap); 264 265 /** 266 * @brief Set input NativeBuffer that contains the image information. It should be noted that the input NativeBuffer 267 * will be directly rendered and modified if the output is not set 268 * 269 * @syscap SystemCapability.Multimedia.ImageEffect.Core 270 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 271 * @param nativeBuffer Indicates the NativeBuffer that contains the image information 272 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 273 * {@link ImageEffect_ErrorCode} 274 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 275 * @since 12 276 */ 277 ImageEffect_ErrorCode OH_ImageEffect_SetInputNativeBuffer(OH_ImageEffect *imageEffect, OH_NativeBuffer *nativeBuffer); 278 279 /** 280 * @brief Set output NativeBuffer that contains the image information 281 * 282 * @syscap SystemCapability.Multimedia.ImageEffect.Core 283 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 284 * @param nativeBuffer Indicates the NativeBuffer that contains the image information 285 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 286 * {@link ImageEffect_ErrorCode} 287 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 288 * @since 12 289 */ 290 ImageEffect_ErrorCode OH_ImageEffect_SetOutputNativeBuffer(OH_ImageEffect *imageEffect, OH_NativeBuffer *nativeBuffer); 291 292 /** 293 * @brief Set input URI of the image. It should be noted that the image resource will be directly rendered and modified 294 * if the output is not set 295 * 296 * @syscap SystemCapability.Multimedia.ImageEffect.Core 297 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 298 * @param uri An URI for a image resource 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_ImageEffect_SetInputUri(OH_ImageEffect *imageEffect, const char *uri); 305 306 /** 307 * @brief Set output URI of the image 308 * 309 * @syscap SystemCapability.Multimedia.ImageEffect.Core 310 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 311 * @param uri An URI for a image resource 312 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 313 * {@link ImageEffect_ErrorCode} 314 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 315 * @since 12 316 */ 317 ImageEffect_ErrorCode OH_ImageEffect_SetOutputUri(OH_ImageEffect *imageEffect, const char *uri); 318 319 /** 320 * @brief Set input picture that contains the image information. It should be noted that the input picture will be 321 * directly rendered and modified if the output is not set 322 * 323 * @syscap SystemCapability.Multimedia.ImageEffect.Core 324 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 325 * @param picture Indicates the OH_PictureNative that contains the image information 326 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 327 * {@link ImageEffect_ErrorCode} 328 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 329 * @since 13 330 */ 331 ImageEffect_ErrorCode OH_ImageEffect_SetInputPicture(OH_ImageEffect *imageEffect, OH_PictureNative *picture); 332 333 /** 334 * @brief Set output picture that contains the image information 335 * 336 * @syscap SystemCapability.Multimedia.ImageEffect.Core 337 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 338 * @param picture Indicates the OH_PictureNative that contains the image information 339 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 340 * {@link ImageEffect_ErrorCode} 341 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 342 * @since 13 343 */ 344 ImageEffect_ErrorCode OH_ImageEffect_SetOutputPicture(OH_ImageEffect *imageEffect, OH_PictureNative *picture); 345 346 /** 347 * @brief Sets the ID of the input texture that contains the image information. 348 * 349 * @syscap SystemCapability.Multimedia.ImageEffect.Core 350 * @param { OH_ImageEffect } imageEffect Pointer to an instance of the OH_ImageEffect struct. 351 * @param textureId ID of the texture that contains the image information. This ID must be valid and have been 352 * bound bound to a texture of a GL_TEXTURE_2D type. 353 * @param colorSpace Color space of the image. 354 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 355 * parameter parameter is missing or incorrect. 356 * @since 20 357 */ 358 ImageEffect_ErrorCode OH_ImageEffect_SetInputTextureId(OH_ImageEffect *imageEffect, int32_t textureId, 359 int32_t colorSpace); 360 361 /** 362 * @brief Sets the ID of the output texture that contains the rendered image information. 363 * 364 * @syscap SystemCapability.Multimedia.ImageEffect.Core 365 * @param imageEffect Pointer to an instance of the OH_ImageEffect struct. 366 * @param textureId ID of the texture that contains the rendered image information. This ID must be valid. If 367 * it it is not bound to a texture, it will automatically be bound to a GL_TEXTURE_2D type. If the texture is 368 * already already bound and the size is inappropriate, the rendered result may be cropped or partially filled 369 * into into this texture. 370 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 371 * parameter parameter is missing or incorrect. 372 * @since 20 373 */ 374 ImageEffect_ErrorCode OH_ImageEffect_SetOutputTextureId(OH_ImageEffect *imageEffect, int32_t textureId); 375 376 /** 377 * @brief Render the filter effects that can be a single filter or a chain of filters 378 * 379 * @syscap SystemCapability.Multimedia.ImageEffect.Core 380 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 381 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 382 * {@link ImageEffect_ErrorCode} 383 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 384 * {@link EFFECT_INPUT_OUTPUT_NOT_SUPPORTED}, the data types of the input and output images 385 * to be processed are different. 386 * {@link EFFECT_COLOR_SPACE_NOT_MATCH}, the color spaces of the input and output images are different. 387 * {@link EFFECT_ALLOCATE_MEMORY_FAILED}, the buffer fails to be allocated. 388 * @since 12 389 */ 390 ImageEffect_ErrorCode OH_ImageEffect_Start(OH_ImageEffect *imageEffect); 391 392 /** 393 * @brief Stop rendering the filter effects for next image frame data 394 * 395 * @syscap SystemCapability.Multimedia.ImageEffect.Core 396 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 397 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 398 * {@link ImageEffect_ErrorCode} 399 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 400 * @since 12 401 */ 402 ImageEffect_ErrorCode OH_ImageEffect_Stop(OH_ImageEffect *imageEffect); 403 404 /** 405 * @brief Clear the internal resources of the OH_ImageEffect and destroy the OH_ImageEffect instance 406 * 407 * @syscap SystemCapability.Multimedia.ImageEffect.Core 408 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 409 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 410 * {@link ImageEffect_ErrorCode} 411 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 412 * @since 12 413 */ 414 ImageEffect_ErrorCode OH_ImageEffect_Release(OH_ImageEffect *imageEffect); 415 416 /** 417 * @brief Convert the OH_ImageEffect and the information of the filters in OH_ImageEffect to JSON string 418 * 419 * @syscap SystemCapability.Multimedia.ImageEffect.Core 420 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 421 * @param info Indicates the serialized information that is obtained by converting the information of the filters in 422 * OH_ImageEffect to JSON string 423 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 424 * {@link ImageEffect_ErrorCode} 425 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 426 * @since 12 427 */ 428 ImageEffect_ErrorCode OH_ImageEffect_Save(OH_ImageEffect *imageEffect, char **info); 429 430 /** 431 * @brief Create an OH_ImageEffect instance by deserializing the JSON string info 432 * 433 * @syscap SystemCapability.Multimedia.ImageEffect.Core 434 * @param info Indicates the serialized information that is obtained by converting the information of the filters in 435 * OH_ImageEffect to JSON string 436 * @return Returns a pointer to an OH_ImageEffect instance if the execution is successful, otherwise returns nullptr 437 * @since 12 438 */ 439 OH_ImageEffect *OH_ImageEffect_Restore(const char *info); 440 441 #ifdef __cplusplus 442 } 443 #endif 444 #endif // NATIVE_IMAGE_EFFECT_H 445 /** @} */