1/*
2 * Copyright (C) 2023 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 image
18 * @{
19 *
20 * @brief Provides APIs for access to the image interface.
21 *
22 * @Syscap SystemCapability.Multimedia.Image
23 * @since 10
24 * @version 2.0
25 */
26
27/**
28 * @file image_mdk.h
29 *
30 * @brief Declares functions that access the image rectangle, size, format, and component data.
31 * Need link <b>libimagendk.z.so</b>
32 *
33 * @kit ImageKit
34 * @since 10
35 * @version 2.0
36 */
37
38#ifndef INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_MDK_H_
39#define INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_MDK_H_
40#include "napi/native_api.h"
41#include "image_mdk_common.h"
42
43#ifdef __cplusplus
44extern "C" {
45#endif
46
47struct ImageNative_;
48
49/**
50 * @brief Defines an image object at the native layer for the image interface.
51 *
52 * @since 10
53 * @version 2.0
54 */
55typedef struct ImageNative_ ImageNative;
56
57/**
58 * @brief Enumerates the image formats.
59 *
60 * @since 10
61 * @version 2.0
62 */
63enum {
64    /** YCbCr422 semi-planar format. */
65    OHOS_IMAGE_FORMAT_YCBCR_422_SP = 1000,
66    /** JPEG encoding format. */
67    OHOS_IMAGE_FORMAT_JPEG = 2000
68};
69
70/**
71 * @brief Enumerates the image components.
72 *
73 * @since 10
74 * @version 2.0
75 */
76enum {
77    /** Luminance component. */
78    OHOS_IMAGE_COMPONENT_FORMAT_YUV_Y = 1,
79    /** Chrominance component - blue projection. */
80    OHOS_IMAGE_COMPONENT_FORMAT_YUV_U = 2,
81    /** Chrominance component - red projection. */
82    OHOS_IMAGE_COMPONENT_FORMAT_YUV_V = 3,
83    /** JPEG format. */
84    OHOS_IMAGE_COMPONENT_FORMAT_JPEG = 4,
85};
86
87/**
88 * @brief Defines the information about an image rectangle.
89 *
90 * @since 10
91 * @version 2.0
92 */
93struct OhosImageRect {
94    /** X coordinate of the rectangle. */
95    int32_t x;
96    /** Y coordinate of the rectangle. */
97    int32_t y;
98    /** Width of the rectangle, in pixels. */
99    int32_t width;
100    /** Height of the rectangle, in pixels. */
101    int32_t height;
102};
103
104/**
105 * @brief Defines the image composition information.
106 *
107 * @since 10
108 * @version 2.0
109 */
110struct OhosImageComponent {
111    /** Buffer that stores the pixel data. */
112    uint8_t* byteBuffer;
113    /** Size of the pixel data in the memory. */
114    size_t size;
115    /** Type of the pixel data. */
116    int32_t componentType;
117    /** Row stride of the pixel data. */
118    int32_t rowStride;
119    /** Pixel stride of the pixel data */
120    int32_t pixelStride;
121};
122
123/**
124 * @brief Parses an {@link ImageNative} object at the native layer from a JavaScript native API <b>image </b> object.
125 *
126 * @param env Indicates the pointer to the Java Native Interface (JNI) environment.
127 * @param source Indicates a JavaScript native API <b>image </b> object.
128 * @return Returns an {@link ImageNative} pointer object if the operation is successful
129 * returns a null pointer otherwise.
130 * @see ImageNative, OH_Image_Release
131 * @since 10
132 * @version 2.0
133 */
134ImageNative* OH_Image_InitImageNative(napi_env env, napi_value source);
135
136/**
137 * @brief Obtains {@link OhosImageRect} of an {@link ImageNative} at the native layer.
138 *
139 * @param native Indicates the pointer to an {@link ImageNative} object at the native layer.
140 * @param rect Indicates the pointer to the {@link OhosImageRect} object obtained.
141 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful.
142 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment.
143 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter.
144 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface.
145 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter.
146 * @see ImageNative, OhosImageRect
147 * @since 10
148 * @version 2.0
149 */
150int32_t OH_Image_ClipRect(const ImageNative* native, struct OhosImageRect* rect);
151
152/**
153 * @brief Obtains {@link OhosImageSize} of an {@link ImageNative} object at the native layer.
154 *
155 * @param native Indicates the pointer to an {@link ImageNative} object at the native layer.
156 * @param size Indicates the pointer to the {@link OhosImageSize} object obtained.
157 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful.
158 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment.
159 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter.
160 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface.
161 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter.
162 * @see ImageNative, OhosImageSize
163 * @since 10
164 * @version 2.0
165 */
166int32_t OH_Image_Size(const ImageNative* native, struct OhosImageSize* size);
167
168/**
169 * @brief Obtains the image format of an {@link ImageNative} object at the native layer.
170 *
171 * @param native Indicates the pointer to an {@link ImageNative} object at the native layer.
172 * @param format Indicates the pointer to the image format obtained.
173 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful.
174 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment.
175 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter.
176 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface.
177 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter.
178 * @see ImageNative
179 * @since 10
180 * @version 2.0
181 */
182int32_t OH_Image_Format(const ImageNative* native, int32_t* format);
183
184/**
185 * @brief Obtains {@link OhosImageComponent} of an {@link ImageNative} object at the native layer.
186 *
187 * @param native Indicates the pointer to an {@link ImageNative} object at the native layer.
188 * @param componentType Indicates the type of the required component.
189 * @param componentNative Indicates the pointer to the {@link OhosImageComponent} object obtained.
190 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful.
191 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment.
192 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter.
193 * returns {@link IRNdkErrCode} IMAGE_RESULT_SURFACE_GET_PARAMETER_FAILED - if Failed to obtain parameters for surface.
194 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter.
195 * @see ImageNative, OhosImageComponent
196 * @since 10
197 * @version 2.0
198 */
199int32_t OH_Image_GetComponent(const ImageNative* native,
200    int32_t componentType, struct OhosImageComponent* componentNative);
201
202/**
203 * @brief Releases an {@link ImageNative} object at the native layer.
204 * Note: This API is not used to release a JavaScript native API <b>Image</b> object.
205 * It is used to release the object {@link ImageNative} at the native layer
206 * parsed by calling {@link OH_Image_InitImageNative}.
207 *
208 * @param native Indicates the pointer to an {@link ImageNative} object at the native layer.
209 * @return Returns {@link IRNdkErrCode} IMAGE_RESULT_SUCCESS - if the operation is successful.
210 * returns {@link IRNdkErrCode} IMAGE_RESULT_JNI_ENV_ABNORMAL - if Abnormal JNI environment.
211 * returns {@link IRNdkErrCode} IMAGE_RESULT_INVALID_PARAMETER - if invalid parameter.
212 * returns {@link IRNdkErrCode} IMAGE_RESULT_BAD_PARAMETER - if bad parameter.
213 * @see ImageNative, OH_Image_InitImageNative
214 * @since 10
215 * @version 2.0
216 */
217int32_t OH_Image_Release(ImageNative* native);
218#ifdef __cplusplus
219};
220#endif
221/** @} */
222#endif // INTERFACES_KITS_NATIVE_INCLUDE_IMAGE_MDK_H_
223