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 #ifndef NDK_INCLUDE_NATIVE_IMAGE_H_ 17 #define NDK_INCLUDE_NATIVE_IMAGE_H_ 18 19 /** 20 * @addtogroup OH_NativeImage 21 * @{ 22 * 23 * @brief Provides the native image capability. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 26 * @since 9 27 * @version 1.0 28 */ 29 30 /** 31 * @file native_image.h 32 * 33 * @brief Defines the functions for obtaining and using a native image. 34 * 35 * @kit ArkGraphics2D 36 * @library libnative_image.so 37 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 38 * @since 9 39 * @version 1.0 40 */ 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 Acquire an <b>OHNativeWindowBuffer</b> through an <b>OH_NativeImage</b> instance for content consumer.\n 244 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 245 * This method will create an <b>OHNativeWindowBuffer</b>.\n 246 * When using <b>OHNativeWindowBuffer</b>, need to increase its reference count 247 * by <b>OH_NativeWindow_NativeObjectReference</b>.\n 248 * 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 * This interface is a non-thread-safe type interface.\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> point. 258 * @param fenceFd Indicates the pointer to a file descriptor handle. 259 * @return {@link NATIVE_ERROR_OK} 0 - Success. 260 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer, fenceFd is NULL. 261 * {@link NATIVE_ERROR_NO_BUFFER} 40601000 - No buffer for consume. 262 * @since 12 263 * @version 1.0 264 */ 265 int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image, 266 OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd); 267 268 /** 269 * @brief Release the <b>OHNativeWindowBuffer</b> to the buffer queue through an 270 * <b>OH_NativeImage</b> instance for reuse.\n 271 * The fenceFd will be close by system.\n 272 * This interface is a non-thread-safe type interface.\n 273 * 274 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 275 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 276 * @param nativeWindowBuffer Indicates the pointer to an <b>OHNativeWindowBuffer</b> instance. 277 * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. 278 * @return {@link NATIVE_ERROR_OK} 0 - Success. 279 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image, nativeWindowBuffer is NULL. 280 * {@link NATIVE_ERROR_BUFFER_STATE_INVALID} 41207000 - nativeWindowBuffer state invalid. 281 * {@link NATIVE_ERROR_BUFFER_NOT_IN_CACHE} 41210000 - nativeWindowBuffer not in cache. 282 * @since 12 283 * @version 1.0 284 */ 285 int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image, 286 OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd); 287 288 /** 289 * @brief Create a <b>OH_NativeImage</b> as a consumerSurface. \n 290 * This interface is only used for memory rotation on the surface consumer, 291 * the <b>OH_NativeImage</b> will not actively perform memory rendering processing.\n 292 * This method can not be used at the same time with <b>OH_NativeImage_UpdateSurfaceImage</b>.\n 293 * This interface is used in conjunction with <b>OH_NativeImage_AcquireNativeWindowBuffer<\b> and 294 * <b>OH_NativeImage_ReleaseNativeWindowBuffer<\b>.\n 295 * This interface needs to be used in conjunction with <b>OH_NativeImage_Destroy<\b>, 296 * otherwise memory leaks will occur.\n 297 * This interface is a non-thread-safe type interface.\n 298 * 299 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 300 * @return Returns the pointer to the <b>OH_NativeImage</b> instance created if the operation is successful, \n 301 * returns <b>NULL</b> otherwise. 302 * @since 12 303 * @version 1.0 304 */ 305 OH_NativeImage* OH_ConsumerSurface_Create(void); 306 307 /** 308 * @brief Set the default usage of the <b>OH_NativeImage</b>.\n 309 * This interface is a non-thread-safe type interface.\n 310 * 311 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 312 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 313 * @param usage Indicates the usage of the <b>OH_NativeImage</b>.Refer to the enum <b>OH_NativeBuffer_Usage</b>. 314 * @return {@link NATIVE_ERROR_OK} 0 - Success. 315 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL. 316 * @since 13 317 * @version 1.0 318 */ 319 int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage); 320 321 /** 322 * @brief Set the default size of the <b>OH_NativeImage</b>.\n 323 * This interface is a non-thread-safe type interface.\n 324 * 325 * @syscap SystemCapability.Graphic.Graphic2D.NativeImage 326 * @param image Indicates the pointer to a <b>OH_NativeImage</b> instance. 327 * @param width Indicates the width of the <b>OH_NativeImage</b>, and it should be greater than 0. 328 * @param height Indicates the height of the <b>OH_NativeImage</b>, and it should be greater than 0. 329 * @return {@link NATIVE_ERROR_OK} 0 - Success. 330 * {@link NATIVE_ERROR_INVALID_ARGUMENTS} 40001000 - image is NULL or width, height less than or equal to 0. 331 * @since 13 332 * @version 1.0 333 */ 334 int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height); 335 #ifdef __cplusplus 336 } 337 #endif 338 339 /** @} */ 340 #endif