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
46extern "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 */
55typedef 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 */
66OH_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 */
77OH_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 */
90ImageEffect_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 */
103OH_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 */
117ImageEffect_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 */
129int32_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 */
142ImageEffect_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 */
155OH_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 */
169ImageEffect_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 */
180int32_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 */
191OH_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 */
207ImageEffect_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 */
222ImageEffect_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 */
236ImageEffect_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 */
250ImageEffect_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 */
263ImageEffect_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 */
277ImageEffect_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 */
290ImageEffect_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 */
304ImageEffect_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 */
317ImageEffect_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 */
331ImageEffect_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 */
344ImageEffect_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 */
360ImageEffect_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 */
372ImageEffect_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 */
384ImageEffect_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 */
398ImageEffect_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 */
409OH_ImageEffect *OH_ImageEffect_Restore(const char *info);
410
411#ifdef __cplusplus
412}
413#endif
414#endif // NATIVE_IMAGE_EFFECT_H
415/** @} */