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 Codec
18 * @{
19 *
20 * @brief Defines APIs of the image Codec module.
21 *
22 * The Codec module provides APIs for image codec, setting codec parameters,
23 * and controlling and transferring image data.
24 *
25 * @since 4.0
26 * @version 2.0
27 */
28
29/**
30 * @file ICodecImage.idl
31 *
32 * @brief Declares the APIs for image codec.
33 *
34 *You can use these APIs to allocate input buffer, and decode image
35 *
36 * @since 4.0
37 * @version 2.0
38 */
39
40/**
41 * @brief Defines the path for the package of the image Codec module APIs.
42 *
43 * @since 4.0
44 * @version 2.0
45 */
46package ohos.hdi.codec.image.v2_0;
47
48import ohos.hdi.codec.image.v2_0.CodecImageType;
49
50interface ICodecImage {
51
52    /**
53     * @brief Obtains image codec capabilities.
54     *
55     * You can use this API to obtain the encoding and decoding capabilities provided by the image Codec module.
56     * For details, see {@link CodecImageCapability}.
57     *
58     * @param capList Indicates the image codec capabilities {@link CodecImageCapability} obtained.
59     *
60     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
61     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
62     *
63     * @since 4.0
64     * @version 1.0
65     */
66    GetImageCapability([out] struct CodecImageCapability[] capList);
67
68    /**
69     * @brief Image codec module init.
70     *
71     * You can use this API to init the Image Codec module.
72     *
73     * @param role Indicates the image codec role {@link CodecImageRole} obtained.
74     *
75     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
76     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
77     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
78     * see <b>HDF_STATUS</b> defined by HDF.
79     *
80     * @since 4.0
81     * @version 1.0
82     */
83    Init([in] enum CodecImageRole role);
84
85    /**
86     * @brief Image codec module deinit.
87     *
88     * You can use this API to deinit the Image Codec module.
89     *
90     * @param role Indicates the image codec role {@link CodecImageRole} obtained.
91     *
92     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
93     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
94     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
95     * see <b>HDF_STATUS</b> defined by HDF.
96     *
97     * @since 4.0
98     * @version 1.0
99     */
100    DeInit([in] enum CodecImageRole role);
101
102    /**
103     * @brief Start jpeg image decode.
104     *
105     * You can use this API to start jpeg image decode.
106     *
107     * @param inBuffer Indicates input buffer of the jpeg image decode {@link CodecImageBuffer} obtained.
108     * @param outBuffer Indicates output buffer of the jpeg image decode {@link CodecImageBuffer} obtained.
109     * @param decInfo Indicates decode information of the image decode {@link JpegDecInfo} obtained.
110     *
111     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
112     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
113     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
114     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
115     * see <b>HDF_STATUS</b> defined by HDF.
116     *
117     * @since 4.0
118     * @version 1.0
119     */
120    DoJpegDecode([in] struct CodecImageBuffer inBuffer, [in] struct CodecImageBuffer outBuffer,
121                 [in] struct CodecJpegDecInfo decInfo);
122
123    /**
124     * @brief Allocate input buffer.
125     *
126     * You can use this API to allocate input buffer for image codec.
127     * After input buffer is duplicated to proxy, stub will automatically free its own reference to input buffer.
128     *
129     * @param inBuffer Indicates input buffer of the image codec {@link CodecImageBuffer} obtained.
130     * @param size Indicates size of input buffer {@link CodecImageBuffer} obtained.
131     * @param role Indicates image codec role of input buffer {@link CodecImageRole} obtained.
132     *
133     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
134     * @return Returns <b>HDF_ERR_INVALID_PARAM</b> if the operation fails due to invalid parameters.
135     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
136     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
137     * see <b>HDF_STATUS</b> defined by HDF.
138     *
139     * @since 4.0
140     * @version 1.0
141     */
142    AllocateInBuffer([out] struct CodecImageBuffer inBuffer, [in] unsigned int size, [in] CodecImageRole role);
143
144    /**
145     * @brief Free input buffer.
146     *
147     * You can use this API to free input buffer for image decode.
148     *
149     * @param buffer Indicates input buffer of the image codec {@link CodecImageBuffer} obtained.
150     *
151     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
152     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
153     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
154     * see <b>HDF_STATUS</b> defined by HDF.
155     *
156     * @since 4.0
157     * @version 1.0
158     * @deprecated
159     * @stub no longer hold reference to input buffer, no need to free.
160     */
161    FreeInBuffer([in] struct CodecImageBuffer inBuffer);
162
163    /**
164     * @brief Start heif image encode.
165     *
166     * You can use this API to start heif image encode.
167     *
168     * @param inputImgs Indicates input images for the heif image encode {@link ImageItem} obtained.
169     * @param inputMetas Indicates encode parameters of the image encode {@link MetaItem} obtained.
170     * @param refs Indicates reference relations of the heif image encode {@link ItemRef} obtained.
171     * @param output Indicates output buffer of the heif image encode {@link SharedBuffer} obtained.
172     * @param filledLen Indicates filled length of output buffer if heif image encode succeed.
173     *
174     * @return Returns <b>HDF_SUCCESS</b> if the operation is successful.
175     * @return Returns <b>HDF_FAILURE</b> if the execution fails.
176     * @return Returns other values if the underlying layer returns a failure. For details about the error codes,
177     * see <b>HDF_STATUS</b> defined by HDF.
178     *
179     * @since 5.0
180     * @version 2.0
181     */
182    DoHeifEncode([in] ImageItem[] inputImgs, [in] MetaItem[] inputMetas,
183                 [in] ItemRef[] refs, [in] SharedBuffer output, [out] unsigned int filledLen);
184}
185