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 Render the filter effects that can be a single filter or a chain of filters 348 * 349 * @syscap SystemCapability.Multimedia.ImageEffect.Core 350 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 351 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 352 * {@link ImageEffect_ErrorCode} 353 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 354 * {@link EFFECT_INPUT_OUTPUT_NOT_SUPPORTED}, the data types of the input and output images 355 * to be processed are different. 356 * {@link EFFECT_COLOR_SPACE_NOT_MATCH}, the color spaces of the input and output images are different. 357 * {@link EFFECT_ALLOCATE_MEMORY_FAILED}, the buffer fails to be allocated. 358 * @since 12 359 */ 360 ImageEffect_ErrorCode OH_ImageEffect_Start(OH_ImageEffect *imageEffect); 361 362 /** 363 * @brief Stop rendering the filter effects for next image frame data 364 * 365 * @syscap SystemCapability.Multimedia.ImageEffect.Core 366 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 367 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 368 * {@link ImageEffect_ErrorCode} 369 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 370 * @since 12 371 */ 372 ImageEffect_ErrorCode OH_ImageEffect_Stop(OH_ImageEffect *imageEffect); 373 374 /** 375 * @brief Clear the internal resources of the OH_ImageEffect and destroy the OH_ImageEffect instance 376 * 377 * @syscap SystemCapability.Multimedia.ImageEffect.Core 378 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 379 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 380 * {@link ImageEffect_ErrorCode} 381 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 382 * @since 12 383 */ 384 ImageEffect_ErrorCode OH_ImageEffect_Release(OH_ImageEffect *imageEffect); 385 386 /** 387 * @brief Convert the OH_ImageEffect and the information of the filters in OH_ImageEffect to JSON string 388 * 389 * @syscap SystemCapability.Multimedia.ImageEffect.Core 390 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 391 * @param info Indicates the serialized information that is obtained by converting the information of the filters in 392 * OH_ImageEffect to JSON string 393 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 394 * {@link ImageEffect_ErrorCode} 395 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 396 * @since 12 397 */ 398 ImageEffect_ErrorCode OH_ImageEffect_Save(OH_ImageEffect *imageEffect, char **info); 399 400 /** 401 * @brief Create an OH_ImageEffect instance by deserializing the JSON string info 402 * 403 * @syscap SystemCapability.Multimedia.ImageEffect.Core 404 * @param info Indicates the serialized information that is obtained by converting the information of the filters in 405 * OH_ImageEffect to JSON string 406 * @return Returns a pointer to an OH_ImageEffect instance if the execution is successful, otherwise returns nullptr 407 * @since 12 408 */ 409 OH_ImageEffect *OH_ImageEffect_Restore(const char *info); 410 411 #ifdef __cplusplus 412 } 413 #endif 414 #endif // NATIVE_IMAGE_EFFECT_H 415 /** @} */