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 * @kit ArkGraphics2D 33 * @library libnative_image.so 34 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 35 * @since 9 36 * @version 1.0 37 */ 38 39 #ifndef NDK_INCLUDE_NATIVE_IMAGE_H_ 40 #define NDK_INCLUDE_NATIVE_IMAGE_H_ 41 42 #include <stdint.h> 43 44 #ifdef __cplusplus 45 extern "C" { 46 #endif 47 48 struct OH_NativeImage; 49 typedef struct OH_NativeImage OH_NativeImage; 50 typedef struct NativeWindow OHNativeWindow; 51 /** 52 * @brief define the new type name OHNativeWindowBuffer for struct NativeWindowBuffer. 53 * @since 12 54 */ 55 typedef struct NativeWindowBuffer OHNativeWindowBuffer; 56 /** 57 * @brief The callback function of frame available. 58 * 59 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 60 * @param context User defined context, returned to the user in the callback function 61 * @since 11 62 * @version 1.0 63 */ 64 typedef void (*OH_OnFrameAvailable)(void *context); 65 66 /** 67 * @brief A listener for native image, use <b>OH_NativeImage_SetOnFrameAvailableListener</b> to register \n 68 * the listener object to <b>OH_NativeImage</b>, the callback will be triggered when there is available frame 69 * 70 * @since 11 71 * @version 1.0 72 */ 73 typedef struct OH_OnFrameAvailableListener { 74 /** User defined context, returned to the user in the callback function*/ 75 void *context; 76 /** The callback function of frame available.*/ 77 OH_OnFrameAvailable onFrameAvailable; 78 } OH_OnFrameAvailableListener; 79 80 /** 81 * @brief Create a <b>OH_NativeImage</b> related to an Opengl ES texture and target. \n 82 * This interface needs to be used in conjunction with <b>OH_NativeImage_Destroy</b>, 83 * otherwise memory leaks will occur.\n 84 * This interface is a non-thread-safe type interface.\n 85 * 86 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 87 * @param textureId Indicates the id of the Opengl ES texture which the native image attached to. 88 * @param textureTarget Indicates the Opengl ES target. 89 * @return Returns the pointer to the <b>OH_NativeImage</b> instance created if the operation is successful, \n 90 * returns <b>NULL</b> otherwise. 91 * @since 9 92 * @version 1.0 93 */ 94 OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget); 95 96 /** 97 * @brief Acquire the OHNativeWindow for the OH_NativeImage.\n 98 * This interface is a non-thread-safe type interface.\n 99 * 100 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 101 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 102 * @return Returns the pointer to the OHNativeWindow if the operation is successful, returns <b>NULL</b> otherwise. 103 * @since 9 104 * @version 1.0 105 */ 106 OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image); 107 108 /** 109 * @brief Attach the OH_NativeImage to Opengl ES context, and the Opengl ES texture is bound to the \n 110 * GL_TEXTURE_EXTERNAL_OES, which will update by the OH_NativeImage.\n 111 * This interface is a non-thread-safe type interface.\n 112 * 113 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 114 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 115 * @param textureId Indicates the id of the Opengl ES texture which the native image attached to. 116 * @return Returns an error code, 0 is success, otherwise, failed. 117 * @since 9 118 * @version 1.0 119 */ 120 int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId); 121 122 /** 123 * @brief Detach the OH_NativeImage from the Opengl ES context.\n 124 * This interface is a non-thread-safe type interface.\n 125 * 126 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 127 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 128 * @return Returns an error code, 0 is success, otherwise, failed. 129 * @since 9 130 * @version 1.0 131 */ 132 133 int32_t OH_NativeImage_DetachContext(OH_NativeImage* image); 134 135 /** 136 * @brief Update the related Opengl ES texture with the OH_NativeImage acquired buffer.\n 137 * This interface needs to be called in the Opengl ES context thread.\n 138 * This interface needs to be called after receiving the <b>OH_OnFrameAvailableListener</b> callback.\n 139 * This interface is a non-thread-safe type interface.\n 140 * 141 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 142 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 143 * @return Returns an error code, 0 is success, otherwise, failed. 144 * @since 9 145 * @version 1.0 146 */ 147 int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image); 148 149 /** 150 * @brief Get the timestamp of the texture image set by the most recent call to OH_NativeImage_UpdateSurfaceImage.\n 151 * This interface is a non-thread-safe type interface.\n 152 * 153 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 154 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 155 * @return Returns the timestamp associated to the texture image. 156 * @since 9 157 * @version 1.0 158 */ 159 int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image); 160 161 /** 162 * @brief Return the transform matrix of the texture image set by the most recent call to \n 163 * OH_NativeImage_UpdateSurfaceImage. 164 * 165 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 166 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 167 * @param matrix Indicates the retrieved 4*4 transform matrix . 168 * @return Returns an error code, 0 is success, otherwise, failed. 169 * @since 9 170 * @version 1.0 171 * @deprecated since 12 172 * @useinstead OH_NativeImage_GetTransformMatrixV2 173 */ 174 int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16]); 175 176 /** 177 * @brief Return the native image's surface id.\n 178 * This interface is a non-thread-safe type interface.\n 179 * 180 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 181 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 182 * @param surfaceId Indicates the surface id. 183 * @return Returns an error code, 0 is success, otherwise, failed. 184 * @since 11 185 * @version 1.0 186 */ 187 int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId); 188 189 /** 190 * @brief Set the frame available callback.\n 191 * Not allow calling other interfaces in the callback function.\n 192 * This interface is a non-thread-safe type interface.\n 193 * 194 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 195 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 196 * @param listener Indicates the callback function. 197 * @return Returns an error code, 0 is success, otherwise, failed. 198 * @since 11 199 * @version 1.0 200 */ 201 int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener); 202 203 /** 204 * @brief Unset the frame available callback.\n 205 * This interface is a non-thread-safe type interface.\n 206 * 207 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 208 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 209 * @return Returns an error code, 0 is success, otherwise, failed. 210 * @since 11 211 * @version 1.0 212 */ 213 int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image); 214 215 /** 216 * @brief Destroy the <b>OH_NativeImage</b> created by OH_NativeImage_Create, and the pointer to 217 * <b>OH_NativeImage</b> will be null after this operation.\n 218 * This interface is a non-thread-safe type interface.\n 219 * 220 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 221 * @param image Indicates the pointer to a <b>OH_NativeImage</b> pointer. 222 * @since 9 223 * @version 1.0 224 */ 225 void OH_NativeImage_Destroy(OH_NativeImage** image); 226 227 /** 228 * @brief Obtains the transform matrix of the texture image by producer transform type.\n 229 * The matrix will not be update until <b>OH_NativeImage_UpdateSurfaceImage</b> is called.\n 230 * This interface is a non-thread-safe type interface.\n 231 * 232 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 233 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 234 * @param matrix Indicates the retrieved 4*4 transform matrix . 235 * @return 0 - Success. 236 * 40001000 - image is NULL. 237 * @since 12 238 * @version 1.0 239 */ 240 int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16]); 241 242 /** 243 * @brief Obtains the transform matrix that combines with crop rect. 244 * 245 * This API returns a transform matrix that combines the crop rect. 246 * Note that the matrix will not be updated until <b>OH_NativeImage_UpdateSurfaceImage</b> is called.\n 247 * This interface is a non-thread-safe type interface.\n 248 * 249 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 250 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 251 * @param matrix Indicates the retrieved 4*4 transform matrix . 252 * @return {@link NATIVE_ERROR_OK} 0 - Success. 253 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 254 * {@link NATIVE_ERROR_MEM_OPERATION_ERROR} 30001000 - Memory operation error, failed to get transform matrix. 255 * @since 15 256 * @version 1.0 257 */ 258 int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16]); 259 260 /** 261 * @brief Acquire an <b>OHNativeWindowBuffer</b> through an <b>OH_NativeImage</b> instance for content consumer.\n 262 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 263 * This method will create an <b>OHNativeWindowBuffer</b>.\n 264 * When using <b>OHNativeWindowBuffer</b>, need to increase its reference count 265 * by <b>OH_NativeWindow_NativeObjectReference</b>.\n 266 * When the <b>OHNativeWindowBuffer</b> is used up, its reference count needs to be decremented 267 * by <b>OH_NativeWindow_NativeObjectUnreference</b>.\n 268 * This interface needs to be used in conjunction with <b>OH_NativeImage_ReleaseNativeWindowBuffer</b>, 269 * otherwise memory leaks will occur.\n 270 * When the fenceFd is used up, you need to close it.\n 271 * This interface is a non-thread-safe type interface.\n 272 * 273 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 274 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 275 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> point. 276 * @param fenceFd Indicates the pointer to a file descriptor handle. 277 * @return {@link NATIVE_ERROR_OK} 0 - Success. 278 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer, fenceFd is NULL. 279 * {@link NATIVE_ERROR_NO_BUFFER} 40601000 - No buffer for consume. 280 * @since 12 281 * @version 1.0 282 */ 283 int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image, 284 OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd); 285 286 /** 287 * @brief Release the <b>OHNativeWindowBuffer</b> to the buffer queue through an 288 * <b>OH_NativeImage</b> instance for reuse.\n 289 * The fenceFd will be closed by system.\n 290 * This interface is a non-thread-safe type interface.\n 291 * 292 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 293 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 294 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> instance. 295 * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. 296 * @return {@link NATIVE_ERROR_OK} 0 - Success. 297 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer is NULL. 298 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - nativeWindowBuffer state invalid. 299 * {@link NATIVE_ERROR_BUFFER_NOT_IN_CACHE} 41210000 - nativeWindowBuffer not in cache. 300 * @since 12 301 * @version 1.0 302 */ 303 int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image, 304 OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd); 305 306 /** 307 * @brief Create a <b>OH_NativeImage</b> as a consumerSurface. \n 308 * This interface is only used for memory rotation on the surface consumer, 309 * the <b>OH_NativeImage</b> will not actively perform memory rendering processing.\n 310 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 311 * This interface is used in conjunction with <b>OH_NativeImage_AcquireNativeWindowBuffer</b> and 312 * <b>OH_NativeImage_ReleaseNativeWindowBuffer</b>.\n 313 * This interface needs to be used in conjunction with <b>OH_NativeImage_Destroy</b>, 314 * otherwise memory leaks will occur.\n 315 * This interface is a non-thread-safe type interface.\n 316 * 317 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 318 * @return Returns the pointer to the <b>OH_NativeImage</b> instance created if the operation is successful, \n 319 * returns <b>NULL</b> otherwise. 320 * @since 12 321 * @version 1.0 322 */ 323 OH_NativeImage* OH_ConsumerSurface_Create(void); 324 325 /** 326 * @brief Set the default usage of the <b>OH_NativeImage</b>.\n 327 * This interface is a non-thread-safe type interface.\n 328 * 329 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 330 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 331 * @param usage Indicates the usage of the <b>OH_NativeImage</b>.Refer to the enum <b>OH_NativeBuffer_Usage</b>. 332 * @return {@link NATIVE_ERROR_OK} 0 - Success. 333 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 334 * @since 13 335 * @version 1.0 336 */ 337 int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage); 338 339 /** 340 * @brief Set the default size of the <b>OH_NativeImage</b>.\n 341 * This interface is a non-thread-safe type interface.\n 342 * 343 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 344 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 345 * @param width Indicates the width of the <b>OH_NativeImage</b>, and it should be greater than 0. 346 * @param height Indicates the height of the <b>OH_NativeImage</b>, and it should be greater than 0. 347 * @return {@link NATIVE_ERROR_OK} 0 - Success. 348 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL or width, height less than or equal to 0. 349 * @since 13 350 * @version 1.0 351 */ 352 int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height); 353 354 /** 355 * @brief Set the rendering in drop buffer mode of the <b>OH_NativeImage</b>.\n 356 * In this mode, most of the buffers produced by the producer will be discarded, 357 * and the latest buffer will be selected for rending.\n 358 * This mode can not simultaneously guarantee high frame rate requirements.\n 359 * This interface suggest be called after the <b>OH_NativeImage_Create</b> call immediately.\n 360 * This interface will only take effect when used together with the <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 361 * This interface is a non-thread-safe type interface.\n 362 * 363 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 364 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 365 * @param isOpen Indicates the switch of drop buffer mode. 366 * @return {@link NATIVE_ERROR_OK} 0 - Success. 367 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 368 * @since 17 369 * @version 1.0 370 */ 371 int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen); 372 #ifdef __cplusplus 373 } 374 #endif 375 376 /** @} */ 377 #endif