1 /* 2 * Copyright (c) 2022 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 OH_NativeImage 18 * @{ 19 * 20 * @brief Provides the native image capability. 21 * 22 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 23 * @since 9 24 * @version 1.0 25 */ 26 27 /** 28 * @file native_image.h 29 * 30 * @brief Defines the functions for obtaining and using a native image. 31 * 32 * @library libnative_image.so 33 * @since 9 34 * @version 1.0 35 */ 36 37 #ifndef NDK_INCLUDE_NATIVE_IMAGE_H_ 38 #define NDK_INCLUDE_NATIVE_IMAGE_H_ 39 40 #include <stdint.h> 41 42 #ifdef __cplusplus 43 extern "C" { 44 #endif 45 46 struct OH_NativeImage; 47 typedef struct OH_NativeImage OH_NativeImage; 48 typedef struct NativeWindow OHNativeWindow; 49 /** 50 * @brief define the new type name OHNativeWindowBuffer for struct NativeWindowBuffer. 51 * @since 12 52 */ 53 typedef struct NativeWindowBuffer OHNativeWindowBuffer; 54 55 /** 56 * @brief The callback function of frame available. 57 * 58 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 59 * @param context User defined context, returned to the user in the callback function 60 * @since 11 61 * @version 1.0 62 */ 63 typedef void (*OH_OnFrameAvailable)(void *context); 64 65 /** 66 * @brief A listener for native image, use <b>OH_NativeImage_SetOnFrameAvailableListener</b> to register \n 67 * the listener object to <b>OH_NativeImage</b>, the callback will be triggered when there is available frame 68 * 69 * @since 11 70 * @version 1.0 71 */ 72 typedef struct OH_OnFrameAvailableListener { 73 void *context; 74 OH_OnFrameAvailable onFrameAvailable; 75 } OH_OnFrameAvailableListener; 76 77 78 /** 79 * @brief Create a <b>OH_NativeImage</b> related to an Opengl ES texture and target. \n 80 * 81 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 82 * @param textureId Indicates the id of the Opengl ES texture which the native image attached to. 83 * @param textureTarget Indicates the Opengl ES target. 84 * @return Returns the pointer to the <b>OH_NativeImage</b> instance created if the operation is successful, \n 85 * returns <b>NULL</b> otherwise. 86 * @since 9 87 * @version 1.0 88 */ 89 OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget); 90 91 /** 92 * @brief Acquire the OHNativeWindow for the OH_NativeImage. 93 * 94 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 95 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 96 * @return Returns the pointer to the OHNativeWindow if the operation is successful, returns <b>NULL</b> otherwise. 97 * @since 9 98 * @version 1.0 99 */ 100 OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image); 101 102 /** 103 * @brief Attach the OH_NativeImage to Opengl ES context, and the Opengl ES texture is bound to the \n 104 * GL_TEXTURE_EXTERNAL_OES, which will update by the OH_NativeImage. 105 * 106 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 107 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 108 * @param textureId Indicates the id of the Opengl ES texture which the native image attached to. 109 * @return Returns an error code, 0 is success, otherwise, failed. 110 * @since 9 111 * @version 1.0 112 */ 113 int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId); 114 115 /** 116 * @brief Detach the OH_NativeImage from the Opengl ES context. 117 * 118 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 119 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 120 * @return Returns an error code, 0 is success, otherwise, failed. 121 * @since 9 122 * @version 1.0 123 */ 124 125 int32_t OH_NativeImage_DetachContext(OH_NativeImage* image); 126 127 /** 128 * @brief Update the related Opengl ES texture with the OH_NativeImage acquired buffer. 129 * 130 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 131 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 132 * @return Returns an error code, 0 is success, otherwise, failed. 133 * @since 9 134 * @version 1.0 135 */ 136 int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image); 137 138 /** 139 * @brief Get the timestamp of the texture image set by the most recent call to OH_NativeImage_UpdateSurfaceImage. 140 * 141 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 142 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 143 * @return Returns the timestamp associated to the texture image. 144 * @since 9 145 * @version 1.0 146 */ 147 int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image); 148 149 /** 150 * @brief Obtains the transform matrix of the texture image set by the most recent call to \n 151 * OH_NativeImage_UpdateSurfaceImage. 152 * 153 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 154 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 155 * @param matrix Indicates the retrieved 4*4 transform matrix . 156 * @return Returns an error code, 0 is success, otherwise, failed. 157 * @since 9 158 * @version 1.0 159 * @deprecated since 12 160 * @useinstead OH_NativeImage_GetTransformMatrixV2 161 */ 162 int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16]); 163 164 /** 165 * @brief Obtains the native image's surface id. 166 * 167 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 168 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 169 * @param surfaceId Indicates the surface id. 170 * @return Returns an error code, 0 is success, otherwise, failed. 171 * @since 11 172 * @version 1.0 173 */ 174 int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId); 175 176 /** 177 * @brief Set the frame available callback. 178 * 179 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 180 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 181 * @param listener Indicates the callback function. 182 * @return Returns an error code, 0 is success, otherwise, failed. 183 * @since 11 184 * @version 1.0 185 */ 186 int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener); 187 188 /** 189 * @brief Unset the frame available callback. 190 * 191 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 192 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 193 * @return Returns an error code, 0 is success, otherwise, failed. 194 * @since 11 195 * @version 1.0 196 */ 197 int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image); 198 199 /** 200 * @brief Destroy the <b>OH_NativeImage</b> created by OH_NativeImage_Create, and the pointer to \n 201 * <b>OH_NativeImage</b> will be null after this operation. 202 * 203 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 204 * @param image Indicates the pointer to a <b>OH_NativeImage</b> pointer. 205 * @since 9 206 * @version 1.0 207 */ 208 void OH_NativeImage_Destroy(OH_NativeImage** image); 209 210 /** 211 * @brief Obtains the transform matrix of the texture image by producer transform type.\n 212 * 213 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 214 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 215 * @param matrix Indicates the retrieved 4*4 transform matrix . 216 * @return 0 - Success. 217 * 40001000 - image is NULL. 218 * @since 12 219 * @version 1.0 220 */ 221 int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16]); 222 223 /** 224 * @brief Acquire an <b>OHNativeWindowBuffer</b> through an <b>OH_NativeImage</b> instance for content consumer.\n 225 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 226 * This method will create an <b>OHNativeWindowBuffer</b>.\n 227 * If there is a situation when <b>OHNativeWindowBuffer</b> is still used after calling 228 * <b>OH_NativeImage_ReleaseNativeWindowBuffer</b>, you must pay attention to the following two points.\n 229 * 1) When using <b>OHNativeWindowBuffer</b>, need to increase its reference count 230 * by <b>OH_NativeWindow_NativeObjectReference</b>.\n 231 * 2) When the <b>OHNativeWindowBuffer</b> is used up, its reference count needs to be decremented 232 * by <b>OH_NativeWindow_NativeObjectUnreference</b>.\n 233 * This interface needs to be used in conjunction with <b>OH_NativeImage_ReleaseNativeWindowBuffer<\b>, 234 * otherwise memory leaks will occur.\n 235 * When the fenceFd is used up, you need to close it.\n 236 * 237 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 238 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 239 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> point. 240 * @param fenceFd Indicates the pointer to a file descriptor handle. 241 * @return {@link NATIVE_ERROR_OK} 0 - Success. 242 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer, fenceFd is NULL. 243 * {@link NATIVE_ERROR_NO_BUFFER} 40601000 - No buffer for consume. 244 * @since 12 245 * @version 1.0 246 */ 247 int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image, 248 OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd); 249 250 /** 251 * @brief Release the <b>OHNativeWindowBuffer</b> to the buffer queue through an 252 * <b>OH_NativeImage</b> instance for reuse.\n 253 * The fenceFd will be close by system.\n 254 * 255 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 256 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 257 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> instance. 258 * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. 259 * @return {@link NATIVE_ERROR_OK} 0 - Success. 260 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer is NULL. 261 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - nativeWindowBuffer state invalid. 262 * {@link NATIVE_ERROR_BUFFER_NOT_IN_CACHE} 41210000 - nativeWindowBuffer not in cache. 263 * @since 12 264 * @version 1.0 265 */ 266 int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image, 267 OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd); 268 269 /** 270 * @brief Create a <b>OH_NativeImage</b> as surface consumer. \n 271 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 272 * This interface needs to be used in conjunction with <b>OH_NativeImage_Destroy<\b>, 273 * otherwise memory leaks will occur.\n 274 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 275 * @return Returns the pointer to the <b>OH_NativeImage</b> instance created if the operation is successful, \n 276 * returns <b>NULL</b> otherwise. 277 * @since 12 278 * @version 1.0 279 */ 280 OH_NativeImage* OH_ConsumerSurface_Create(); 281 282 /** 283 * @brief Set the default usage of the <b>OH_NativeImage</b>.\n 284 * This interface dose not support concurrency.\n 285 * 286 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 287 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 288 * @param usage Indicates the usage of the <b>OH_NativeImage</b>.Refer to the enum <b>OH_NativeBuffer_Usage</b>. 289 * @return {@link NATIVE_ERROR_OK} 0 - Success. 290 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 291 * @since 13 292 * @version 1.0 293 */ 294 int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage); 295 296 /** 297 * @brief Set the default size of the <b>OH_NativeImage</b>.\n 298 * This interface dose not support concurrency.\n 299 * 300 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 301 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 302 * @param width Indicates the width of the <b>OH_NativeImage</b>, and it should be greater than 0. 303 * @param height Indicates the height of the <b>OH_NativeImage</b>, and it should be greater than 0. 304 * @return {@link NATIVE_ERROR_OK} 0 - Success. 305 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL or width, height less than or equal to 0. 306 * @since 13 307 * @version 1.0 308 */ 309 int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height); 310 #ifdef __cplusplus 311 } 312 #endif 313 314 /** @} */ 315 #endif