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 Obtains the transform matrix that combines with crop rect. 225 * 226 * This API returns a transform matrix that combines the crop rect. 227 * Note that the matrix will not be updated until <b>OH_NativeImage_UpdateSurfaceImage</b> is called.\n 228 * This interface is a non-thread-safe type interface.\n 229 * 230 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 231 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 232 * @param matrix Indicates the retrieved 4*4 transform matrix . 233 * @return {@link NATIVE_ERROR_OK} 0 - Success. 234 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 235 * {@link NATIVE_ERROR_MEM_OPERATION_ERROR} 30001000 - Memory operation error, failed to get transform matrix. 236 * @since 14 237 * @version 1.0 238 */ 239 int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16]); 240 /** 241 * @brief Acquire an <b>OHNativeWindowBuffer</b> through an <b>OH_NativeImage</b> instance for content consumer.\n 242 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 243 * This method will create an <b>OHNativeWindowBuffer</b>.\n 244 * If there is a situation when <b>OHNativeWindowBuffer</b> is still used after calling 245 * <b>OH_NativeImage_ReleaseNativeWindowBuffer</b>, you must pay attention to the following two points.\n 246 * 1) When using <b>OHNativeWindowBuffer</b>, need to increase its reference count 247 * by <b>OH_NativeWindow_NativeObjectReference</b>.\n 248 * 2) When the <b>OHNativeWindowBuffer</b> is used up, its reference count needs to be decremented 249 * by <b>OH_NativeWindow_NativeObjectUnreference</b>.\n 250 * This interface needs to be used in conjunction with <b>OH_NativeImage_ReleaseNativeWindowBuffer</b>, 251 * otherwise memory leaks will occur.\n 252 * When the fenceFd is used up, you need to close it.\n 253 * 254 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 255 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 256 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> point. 257 * @param fenceFd Indicates the pointer to a file descriptor handle. 258 * @return {@link NATIVE_ERROR_OK} 0 - Success. 259 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer, fenceFd is NULL. 260 * {@link NATIVE_ERROR_NO_BUFFER} 40601000 - No buffer for consume. 261 * @since 12 262 * @version 1.0 263 */ 264 int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image, 265 OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd); 266 267 /** 268 * @brief Release the <b>OHNativeWindowBuffer</b> to the buffer queue through an 269 * <b>OH_NativeImage</b> instance for reuse.\n 270 * The fenceFd will be closed by system.\n 271 * 272 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 273 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 274 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> instance. 275 * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. 276 * @return {@link NATIVE_ERROR_OK} 0 - Success. 277 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer is NULL. 278 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - nativeWindowBuffer state invalid. 279 * {@link NATIVE_ERROR_BUFFER_NOT_IN_CACHE} 41210000 - nativeWindowBuffer not in cache. 280 * @since 12 281 * @version 1.0 282 */ 283 int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image, 284 OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd); 285 286 /** 287 * @brief Create a <b>OH_NativeImage</b> as surface consumer. \n 288 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 289 * This interface needs to be used in conjunction with <b>OH_NativeImage_Destroy</b>, 290 * otherwise memory leaks will occur.\n 291 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 292 * @return Returns the pointer to the <b>OH_NativeImage</b> instance created if the operation is successful, \n 293 * returns <b>NULL</b> otherwise. 294 * @since 12 295 * @version 1.0 296 */ 297 OH_NativeImage* OH_ConsumerSurface_Create(); 298 299 /** 300 * @brief Set the default usage of the <b>OH_NativeImage</b>.\n 301 * This interface dose not support concurrency.\n 302 * 303 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 304 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 305 * @param usage Indicates the usage of the <b>OH_NativeImage</b>.Refer to the enum <b>OH_NativeBuffer_Usage</b>. 306 * @return {@link NATIVE_ERROR_OK} 0 - Success. 307 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 308 * @since 13 309 * @version 1.0 310 */ 311 int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage); 312 313 /** 314 * @brief Set the default size of the <b>OH_NativeImage</b>.\n 315 * This interface dose not support concurrency.\n 316 * 317 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 318 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 319 * @param width Indicates the width of the <b>OH_NativeImage</b>, and it should be greater than 0. 320 * @param height Indicates the height of the <b>OH_NativeImage</b>, and it should be greater than 0. 321 * @return {@link NATIVE_ERROR_OK} 0 - Success. 322 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL or width, height less than or equal to 0. 323 * @since 13 324 * @version 1.0 325 */ 326 int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height); 327 328 /** 329 * @brief Set the rendering in drop buffer mode of the <b>OH_NativeImage</b>.\n 330 * In this mode, most of the buffers produced by the producer will be discarded, 331 * and the latest buffer will be selected for rending.\n 332 * This mode can not simultaneously guarantee high frame rate requirements.\n 333 * This interface suggest be called after the <b>OH_NativeImage_Create</b> call immediately.\n 334 * This interface is a non-thread-safe type interface.\n 335 * 336 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 337 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 338 * @param isOpen Indicates the switch of drop buffer mode. 339 * @return {@link NATIVE_ERROR_OK} 0 - Success. 340 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 341 * @since 17 342 * @version 1.0 343 */ 344 int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen); 345 #ifdef __cplusplus 346 } 347 #endif 348 349 /** @} */ 350 #endif