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_interface.h 27 * 28 * @brief Declares the functions for rendering image. 29 * 30 * @library libimage_effect.so 31 * @syscap SystemCapability.Multimedia.ImageEffect.Core 32 * @since 12 33 */ 34 35 #ifndef NATIVE_IMAGE_EFFECT_H 36 #define NATIVE_IMAGE_EFFECT_H 37 38 #include "image_effect_errors.h" 39 #include "image_effect_filter.h" 40 41 #ifdef __cplusplus 42 extern "C" { 43 #endif 44 45 typedef struct OH_NativeBuffer OH_NativeBuffer; 46 typedef struct NativeWindow OHNativeWindow; 47 typedef struct OH_PictureNative OH_PictureNative; 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 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 Add the OH_EffectFilter to the OH_ImageEffect by specified position 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 to the OH_ImageEffect by specified position 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 to the OH_ImageEffect by specified position 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 * @since 12 203 */ 204 ImageEffect_ErrorCode OH_ImageEffect_Configure(OH_ImageEffect *imageEffect, const char *key, 205 const ImageEffect_Any *value); 206 207 /** 208 * @brief Set the Surface to the image effect, this interface must be called before 209 * @{link OH_ImageEffect_GetInputSurface} is called 210 * 211 * @syscap SystemCapability.Multimedia.ImageEffect.Core 212 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 213 * @param nativeWindow A pointer to a OHNativeWindow instance, see {@link OHNativeWindow} 214 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 215 * {@link ImageEffect_ErrorCode} 216 * @since 12 217 */ 218 ImageEffect_ErrorCode OH_ImageEffect_SetOutputSurface(OH_ImageEffect *imageEffect, OHNativeWindow *nativeWindow); 219 220 /** 221 * @brief Get the input Surface from the image effect, this interface must be called after 222 * @{link OH_ImageEffect_SetOutputSurface} is called 223 * 224 * @syscap SystemCapability.Multimedia.ImageEffect.Core 225 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 226 * @param nativeWindow A pointer to a OHNativeWindow instance, see {@link OHNativeWindow} 227 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 228 * {@link ImageEffect_ErrorCode} 229 * @since 12 230 */ 231 ImageEffect_ErrorCode OH_ImageEffect_GetInputSurface(OH_ImageEffect *imageEffect, OHNativeWindow **nativeWindow); 232 233 /** 234 * @brief Set input pixelmap that contains the image information. It should be noted that the input pixel map will be 235 * directly rendered and modified if the output is not set 236 * 237 * @syscap SystemCapability.Multimedia.ImageEffect.Core 238 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 239 * @param pixelmap Indicates the OH_PixelmapNative that contains the image information 240 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 241 * {@link ImageEffect_ErrorCode} 242 * @since 12 243 */ 244 ImageEffect_ErrorCode OH_ImageEffect_SetInputPixelmap(OH_ImageEffect *imageEffect, OH_PixelmapNative *pixelmap); 245 246 /** 247 * @brief Set output pixelmap that contains the image information 248 * 249 * @syscap SystemCapability.Multimedia.ImageEffect.Core 250 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 251 * @param pixelmap Indicates the OH_PixelmapNative that contains the image information 252 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 253 * {@link ImageEffect_ErrorCode} 254 * @since 12 255 */ 256 ImageEffect_ErrorCode OH_ImageEffect_SetOutputPixelmap(OH_ImageEffect *imageEffect, OH_PixelmapNative *pixelmap); 257 258 /** 259 * @brief Set input NativeBuffer that contains the image information. It should be noted that the input NativeBuffer 260 * will be directly rendered and modified if the output is not set 261 * 262 * @syscap SystemCapability.Multimedia.ImageEffect.Core 263 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 264 * @param nativeBuffer Indicates the NativeBuffer that contains the image information 265 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 266 * {@link ImageEffect_ErrorCode} 267 * @since 12 268 */ 269 ImageEffect_ErrorCode OH_ImageEffect_SetInputNativeBuffer(OH_ImageEffect *imageEffect, OH_NativeBuffer *nativeBuffer); 270 271 /** 272 * @brief Set output NativeBuffer that contains the image information 273 * 274 * @syscap SystemCapability.Multimedia.ImageEffect.Core 275 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 276 * @param nativeBuffer Indicates the NativeBuffer that contains the image information 277 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 278 * {@link ImageEffect_ErrorCode} 279 * @since 12 280 */ 281 ImageEffect_ErrorCode OH_ImageEffect_SetOutputNativeBuffer(OH_ImageEffect *imageEffect, OH_NativeBuffer *nativeBuffer); 282 283 /** 284 * @brief Set input URI of the image. It should be noted that the image resource will be directly rendered and modified 285 * if the output is not set 286 * 287 * @syscap SystemCapability.Multimedia.ImageEffect.Core 288 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 289 * @param uri An URI for a image resource 290 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 291 * {@link ImageEffect_ErrorCode} 292 * @since 12 293 */ 294 ImageEffect_ErrorCode OH_ImageEffect_SetInputUri(OH_ImageEffect *imageEffect, const char *uri); 295 296 /** 297 * @brief Set output URI of the image 298 * 299 * @syscap SystemCapability.Multimedia.ImageEffect.Core 300 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 301 * @param uri An URI for a image resource 302 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 303 * {@link ImageEffect_ErrorCode} 304 * @since 12 305 */ 306 ImageEffect_ErrorCode OH_ImageEffect_SetOutputUri(OH_ImageEffect *imageEffect, const char *uri); 307 308 /** 309 * @brief Set input picture that contains the image information. It should be noted that the input picture will be 310 * directly rendered and modified if the output is not set 311 * 312 * @syscap SystemCapability.Multimedia.ImageEffect.Core 313 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 314 * @param picture Indicates the OH_PictureNative that contains the image information 315 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 316 * {@link ImageEffect_ErrorCode} 317 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 318 * @since 13 319 */ 320 ImageEffect_ErrorCode OH_ImageEffect_SetInputPicture(OH_ImageEffect *imageEffect, OH_PictureNative *picture); 321 322 /** 323 * @brief Set output picture that contains the image information 324 * 325 * @syscap SystemCapability.Multimedia.ImageEffect.Core 326 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 327 * @param picture Indicates the OH_PictureNative that contains the image information 328 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 329 * {@link ImageEffect_ErrorCode} 330 * {@link EFFECT_ERROR_PARAM_INVALID}, the input parameter is a null pointer. 331 * @since 13 332 */ 333 ImageEffect_ErrorCode OH_ImageEffect_SetOutputPicture(OH_ImageEffect *imageEffect, OH_PictureNative *picture); 334 335 /** 336 * @brief Sets the ID of the input texture that contains the image information. 337 * 338 * @syscap SystemCapability.Multimedia.ImageEffect.Core 339 * @param { OH_ImageEffect } imageEffect Pointer to an instance of the OH_ImageEffect struct. 340 * @param textureId ID of the texture that contains the image information. This ID must be valid and have been 341 * bound to a texture of a GL_TEXTURE_2D type. 342 * @param colorSpace Color space of the image. 343 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 344 * parameter is missing or incorrect. 345 * @since 20 346 */ 347 ImageEffect_ErrorCode OH_ImageEffect_SetInputTextureId(OH_ImageEffect *imageEffect, int32_t textureId, 348 int32_t colorSpace); 349 350 /** 351 * @brief Sets the ID of the output texture that contains the rendered image information. 352 * 353 * @syscap SystemCapability.Multimedia.ImageEffect.Core 354 * @param imageEffect Pointer to an instance of the OH_ImageEffect struct. 355 * @param textureId ID of the texture that contains the rendered image information. This ID must be valid. If 356 * it is not bound to a texture, it will automatically be bound to a GL_TEXTURE_2D type. If the texture is 357 * already bound and the size is inappropriate, the rendered result may be cropped or partially filled 358 * into this texture. 359 * @return Returns EFFECT_SUCCESS if the operation is successful; returns EFFECT_ERROR_PARAM_INVALID if the 360 * parameter is missing or incorrect. 361 * @since 20 362 */ 363 ImageEffect_ErrorCode OH_ImageEffect_SetOutputTextureId(OH_ImageEffect *imageEffect, int32_t textureId); 364 365 /** 366 * @brief Render the filter effects that can be a single filter or a chain of filters 367 * 368 * @syscap SystemCapability.Multimedia.ImageEffect.Core 369 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 370 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 371 * {@link ImageEffect_ErrorCode} 372 * @since 12 373 */ 374 ImageEffect_ErrorCode OH_ImageEffect_Start(OH_ImageEffect *imageEffect); 375 376 /** 377 * @brief Stop rendering the filter effects for next image frame data 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 * @since 12 384 */ 385 ImageEffect_ErrorCode OH_ImageEffect_Stop(OH_ImageEffect *imageEffect); 386 387 /** 388 * @brief Clear the internal resources of the OH_ImageEffect and destroy the OH_ImageEffect instance 389 * 390 * @syscap SystemCapability.Multimedia.ImageEffect.Core 391 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 392 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 393 * {@link ImageEffect_ErrorCode} 394 * @since 12 395 */ 396 ImageEffect_ErrorCode OH_ImageEffect_Release(OH_ImageEffect *imageEffect); 397 398 /** 399 * @brief Convert the OH_ImageEffect and the information of the filters in OH_ImageEffect to JSON string 400 * 401 * @syscap SystemCapability.Multimedia.ImageEffect.Core 402 * @param imageEffect Encapsulate OH_ImageEffect structure instance pointer 403 * @param info Indicates the serialized information that is obtained by converting the information of the filters in 404 * OH_ImageEffect to JSON string 405 * @return Returns EFFECT_SUCCESS if the execution is successful, otherwise returns a specific error code, refer to 406 * {@link ImageEffect_ErrorCode} 407 * @since 12 408 */ 409 ImageEffect_ErrorCode OH_ImageEffect_Save(OH_ImageEffect *imageEffect, char **info); 410 411 /** 412 * @brief Create an OH_ImageEffect instance by deserializing the JSON string info 413 * 414 * @syscap SystemCapability.Multimedia.ImageEffect.Core 415 * @param info Indicates the serialized information that is obtained by converting the information of the filters in 416 * OH_ImageEffect to JSON string 417 * @return Returns a pointer to an OH_ImageEffect instance if the execution is successful, otherwise returns nullptr 418 * @since 12 419 */ 420 OH_ImageEffect *OH_ImageEffect_Restore(const char *info); 421 422 #ifdef __cplusplus 423 } 424 #endif 425 #endif // NATIVE_IMAGE_EFFECT_H 426 /** @} */