1 /* 2 * Copyright (c) 2021-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_EXTERNAL_NATIVE_WINDOW_H_ 17 #define NDK_INCLUDE_EXTERNAL_NATIVE_WINDOW_H_ 18 19 /** 20 * @addtogroup NativeWindow 21 * @{ 22 * 23 * @brief Provides the native window capability for connection to the EGL. 24 * 25 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 26 * @since 8 27 * @version 1.0 28 */ 29 30 /** 31 * @file external_window.h 32 * 33 * @brief Defines the functions for obtaining and using a native window. 34 * 35 * @library libnative_window.so 36 * @since 8 37 * @version 1.0 38 */ 39 40 #include <stdint.h> 41 #include "buffer_handle.h" 42 43 #ifdef __cplusplus 44 extern "C" { 45 #endif 46 typedef struct OH_NativeBuffer OH_NativeBuffer; 47 48 /** 49 * @brief native window. 50 * @since 8 51 */ 52 struct NativeWindow; 53 54 /** 55 * @brief native window buffer. 56 * @since 8 57 */ 58 struct NativeWindowBuffer; 59 60 /** 61 * @brief define the new type name OHNativeWindow for struct NativeWindow. 62 * @since 8 63 */ 64 typedef struct NativeWindow OHNativeWindow; 65 66 /** 67 * @brief define the new type name OHNativeWindowBuffer for struct NativeWindowBuffer. 68 * @since 8 69 */ 70 typedef struct NativeWindowBuffer OHNativeWindowBuffer; 71 72 /** 73 * @brief indicates a dirty region where content is updated. 74 * @since 8 75 */ 76 typedef struct Region { 77 /** if rects is nullptr, fill the Buffer dirty size by default */ 78 struct Rect { 79 int32_t x; 80 int32_t y; 81 uint32_t w; 82 uint32_t h; 83 } *rects; 84 /** if rectNumber is 0, fill the Buffer dirty size by default */ 85 int32_t rectNumber; 86 }Region; 87 88 89 /** 90 * @brief Indicates the operation code in the function OH_NativeWindow_NativeWindowHandleOpt. 91 * @since 8 92 */ 93 enum NativeWindowOperation { 94 /** 95 * set native window buffer geometry, 96 * variable parameter in function is 97 * [in] int32_t width, [in] int32_t height 98 */ 99 SET_BUFFER_GEOMETRY, 100 /** 101 * get native window buffer geometry, 102 * variable parameter in function is 103 * [out] int32_t *height, [out] int32_t *width 104 */ 105 GET_BUFFER_GEOMETRY, 106 /** 107 * get native window buffer format, 108 * variable parameter in function is 109 * [out] int32_t *format 110 */ 111 GET_FORMAT, 112 /** 113 * set native window buffer format, 114 * variable parameter in function is 115 * [in] int32_t format 116 */ 117 SET_FORMAT, 118 /** 119 * get native window buffer usage, 120 * variable parameter in function is 121 * [out] int32_t *usage. 122 */ 123 GET_USAGE, 124 /** 125 * set native window buffer usage, 126 * variable parameter in function is 127 * [in] int32_t usage. 128 */ 129 SET_USAGE, 130 /** 131 * set native window buffer stride, 132 * variable parameter in function is 133 * [in] int32_t stride. 134 */ 135 SET_STRIDE, 136 /** 137 * get native window buffer stride, 138 * variable parameter in function is 139 * [out] int32_t *stride. 140 */ 141 GET_STRIDE, 142 /** 143 * set native window buffer swap interval, 144 * variable parameter in function is 145 * [in] int32_t interval. 146 */ 147 SET_SWAP_INTERVAL, 148 /** 149 * get native window buffer swap interval, 150 * variable parameter in function is 151 * [out] int32_t *interval. 152 */ 153 GET_SWAP_INTERVAL, 154 /** 155 * set native window buffer timeout, 156 * variable parameter in function is 157 * [in] int32_t timeout. 158 */ 159 SET_TIMEOUT, 160 /** 161 * get native window buffer timeout, 162 * variable parameter in function is 163 * [out] int32_t *timeout. 164 */ 165 GET_TIMEOUT, 166 /** 167 * set native window buffer colorGamut, 168 * variable parameter in function is 169 * [in] int32_t colorGamut. 170 */ 171 SET_COLOR_GAMUT, 172 /** 173 * get native window buffer colorGamut, 174 * variable parameter in function is 175 * [out int32_t *colorGamut]. 176 */ 177 GET_COLOR_GAMUT, 178 /** 179 * set native window buffer transform, 180 * variable parameter in function is 181 * [in] int32_t transform. 182 */ 183 SET_TRANSFORM, 184 /** 185 * get native window buffer transform, 186 * variable parameter in function is 187 * [out] int32_t *transform. 188 */ 189 GET_TRANSFORM, 190 /** 191 * set native window buffer uiTimestamp, 192 * variable parameter in function is 193 * [in] uint64_t uiTimestamp. 194 */ 195 SET_UI_TIMESTAMP, 196 }; 197 198 /** 199 * @brief Indicates Scaling Mode. 200 * @since 9 201 * @deprecated(since = "10") 202 */ 203 typedef enum { 204 /** 205 * the window content is not updated until a buffer of 206 * the window size is received 207 */ 208 OH_SCALING_MODE_FREEZE = 0, 209 /** 210 * the buffer is scaled in two dimensions to match the window size 211 */ 212 OH_SCALING_MODE_SCALE_TO_WINDOW, 213 /** 214 * the buffer is uniformly scaled so that the smaller size of 215 * the buffer matches the window size 216 */ 217 OH_SCALING_MODE_SCALE_CROP, 218 /** 219 * the window is clipped to the size of the buffer's clipping rectangle 220 * pixels outside the clipping rectangle are considered fully transparent. 221 */ 222 OH_SCALING_MODE_NO_SCALE_CROP, 223 } OHScalingMode; 224 225 /** 226 * @brief Enumerates the HDR metadata keys. 227 * @since 9 228 * @deprecated(since = "10") 229 */ 230 typedef enum { 231 OH_METAKEY_RED_PRIMARY_X = 0, 232 OH_METAKEY_RED_PRIMARY_Y = 1, 233 OH_METAKEY_GREEN_PRIMARY_X = 2, 234 OH_METAKEY_GREEN_PRIMARY_Y = 3, 235 OH_METAKEY_BLUE_PRIMARY_X = 4, 236 OH_METAKEY_BLUE_PRIMARY_Y = 5, 237 OH_METAKEY_WHITE_PRIMARY_X = 6, 238 OH_METAKEY_WHITE_PRIMARY_Y = 7, 239 OH_METAKEY_MAX_LUMINANCE = 8, 240 OH_METAKEY_MIN_LUMINANCE = 9, 241 OH_METAKEY_MAX_CONTENT_LIGHT_LEVEL = 10, 242 OH_METAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, 243 OH_METAKEY_HDR10_PLUS = 12, 244 OH_METAKEY_HDR_VIVID = 13, 245 } OHHDRMetadataKey; 246 247 /** 248 * @brief Defines the HDR metadata. 249 * @since 9 250 * @deprecated(since = "10") 251 */ 252 typedef struct { 253 OHHDRMetadataKey key; 254 float value; 255 } OHHDRMetaData; 256 257 /** 258 * @brief Defines the ExtData Handle 259 * @since 9 260 * @deprecated(since = "10") 261 */ 262 typedef struct OHExtDataHandle { 263 /**< Handle fd, -1 if not supported */ 264 int32_t fd; 265 /**< the number of reserved integer value */ 266 uint32_t reserveInts; 267 /**< the reserved data */ 268 int32_t reserve[0]; 269 } OHExtDataHandle; 270 271 /** 272 * @brief Creates a <b>OHNativeWindow</b> instance. A new <b>OHNativeWindow</b> instance is created each time this function is called. 273 * 274 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 275 * @param pSurface Indicates the pointer to a <b>ProduceSurface</b>. The type is a pointer to <b>sptr<OHOS::Surface></b>. 276 * @return Returns the pointer to the <b>OHNativeWindow</b> instance created. 277 * @since 8 278 * @version 1.0 279 */ 280 OHNativeWindow* OH_NativeWindow_CreateNativeWindow(void* pSurface); 281 282 /** 283 * @brief Decreases the reference count of a <b>OHNativeWindow</b> instance by 1, and when the reference count reaches 0, destroys the instance. 284 * 285 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 286 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 287 * @since 8 288 * @version 1.0 289 */ 290 void OH_NativeWindow_DestroyNativeWindow(OHNativeWindow* window); 291 292 /** 293 * @brief Creates a <b>OHNativeWindowBuffer</b> instance. A new <b>OHNativeWindowBuffer</b> instance is created each time this function is called. 294 * 295 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 296 * @param pSurfaceBuffer Indicates the pointer to a produce buffer. The type is <b>sptr<OHOS::SurfaceBuffer></b>. 297 * @return Returns the pointer to the <b>OHNativeWindowBuffer</b> instance created. 298 * @since 8 299 * @version 1.0 300 */ 301 OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer(void* pSurfaceBuffer); 302 303 /** 304 * @brief Creates a <b>OHNativeWindowBuffer</b> instance. 305 A new <b>OHNativeWindowBuffer</b> instance is created each time this function is called. 306 * 307 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 308 * @param nativeBuffer Indicates the pointer to a native buffer. The type is <b>OH_NativeBuffer*</b>. 309 * @return Returns the pointer to the <b>OHNativeWindowBuffer</b> instance created. 310 * @since 11 311 * @version 1.0 312 */ 313 OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer(OH_NativeBuffer* nativeBuffer); 314 315 /** 316 * @brief Decreases the reference count of a <b>OHNativeWindowBuffer</b> instance by 1 and, when the reference count reaches 0, destroys the instance. 317 * 318 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 319 * @param buffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> instance. 320 * @since 8 321 * @version 1.0 322 */ 323 void OH_NativeWindow_DestroyNativeWindowBuffer(OHNativeWindowBuffer* buffer); 324 325 /** 326 * @brief Requests a <b>OHNativeWindowBuffer</b> through a <b>OHNativeWindow</b> instance for content production. 327 * 328 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 329 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 330 * @param buffer Indicates the double pointer to a <b>OHNativeWindowBuffer</b> instance. 331 * @param fenceFd Indicates the pointer to a file descriptor handle. 332 * @return Returns an error code, 0 is success, otherwise, failed. 333 * @since 8 334 * @version 1.0 335 */ 336 int32_t OH_NativeWindow_NativeWindowRequestBuffer(OHNativeWindow *window, 337 OHNativeWindowBuffer **buffer, int *fenceFd); 338 339 /** 340 * @brief Flushes the <b>OHNativeWindowBuffer</b> filled with the content to the buffer queue through a <b>OHNativeWindow</b> instance for content consumption. 341 * 342 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 343 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 344 * @param buffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> instance. 345 * @param fenceFd Indicates a file descriptor handle, which is used for timing synchronization. 346 * @param region Indicates a dirty region where content is updated. 347 * @return Returns an error code, 0 is success, otherwise, failed. 348 * @since 8 349 * @version 1.0 350 */ 351 int32_t OH_NativeWindow_NativeWindowFlushBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer, 352 int fenceFd, Region region); 353 354 /** 355 * @brief Get the last flushed <b>OHNativeWindowBuffer</b> from a <b>OHNativeWindow</b> instance. 356 * 357 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 358 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 359 * @param buffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> pointer. 360 * @param fenceFd Indicates the pointer to a file descriptor handle. 361 * @param matrix Indicates the retrieved 4*4 transform matrix. 362 * @return Returns an error code, 0 is success, otherwise, failed. 363 * @since 11 364 * @version 1.0 365 */ 366 int32_t OH_NativeWindow_GetLastFlushedBuffer(OHNativeWindow *window, OHNativeWindowBuffer **buffer, 367 int *fenceFd, float matrix[16]); 368 369 /** 370 * @brief Returns the <b>OHNativeWindowBuffer</b> to the buffer queue through a <b>OHNativeWindow</b> instance, without filling in any content. The <b>OHNativeWindowBuffer</b> can be used for another request. 371 * 372 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 373 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 374 * @param buffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> instance. 375 * @return Returns an error code, 0 is success, otherwise, failed. 376 * @since 8 377 * @version 1.0 378 */ 379 int32_t OH_NativeWindow_NativeWindowAbortBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer); 380 381 /** 382 * @brief Sets or obtains the attributes of a native window, including the width, height, and content format. 383 * 384 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 385 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 386 * @param code Indicates the operation code, pointer to <b>NativeWindowOperation</b>. 387 * @param ... variable parameter, must correspond to code one-to-one. 388 * @return Returns an error code, 0 is success, otherwise, failed. 389 * @since 8 390 * @version 1.0 391 */ 392 int32_t OH_NativeWindow_NativeWindowHandleOpt(OHNativeWindow *window, int code, ...); 393 394 /** 395 * @brief Obtains the pointer to a <b>BufferHandle</b> of a <b>OHNativeWindowBuffer</b> instance. 396 * 397 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 398 * @param buffer Indicates the pointer to a <b>OHNativeWindowBuffer</b> instance. 399 * @return Returns the pointer to the <b>BufferHandle</b> instance obtained. 400 * @since 8 401 * @version 1.0 402 */ 403 BufferHandle *OH_NativeWindow_GetBufferHandleFromNative(OHNativeWindowBuffer *buffer); 404 405 /** 406 * @brief Adds the reference count of a native object. 407 * 408 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 409 * @param obj Indicates the pointer to a <b>OHNativeWindow</b> or <b>OHNativeWindowBuffer</b> instance. 410 * @return Returns an error code, 0 is success, otherwise, failed. 411 * @since 8 412 * @version 1.0 413 */ 414 int32_t OH_NativeWindow_NativeObjectReference(void *obj); 415 416 /** 417 * @brief Decreases the reference count of a native object and, when the reference count reaches 0, destroys this object. 418 * 419 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 420 * @param obj Indicates the pointer to a <b>OHNativeWindow</b> or <b>OHNativeWindowBuffer</b> instance. 421 * @return Returns an error code, 0 is success, otherwise, failed. 422 * @since 8 423 * @version 1.0 424 */ 425 int32_t OH_NativeWindow_NativeObjectUnreference(void *obj); 426 427 /** 428 * @brief Obtains the magic ID of a native object. 429 * 430 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 431 * @param obj Indicates the pointer to a <b>OHNativeWindow</b> or <b>OHNativeWindowBuffer</b> instance. 432 * @return Returns the magic ID, which is unique for each native object. 433 * @since 8 434 * @version 1.0 435 */ 436 int32_t OH_NativeWindow_GetNativeObjectMagic(void *obj); 437 438 /** 439 * @brief Sets scalingMode of a native window. 440 * 441 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 442 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 443 * @param sequence Indicates the sequence to a produce buffer. 444 * @param scalingMode Indicates the enum value to <b>OHScalingMode</b> 445 * @return Returns an error code, 0 is success, otherwise, failed. 446 * @since 9 447 * @version 1.0 448 * @deprecated(since = "10") 449 */ 450 int32_t OH_NativeWindow_NativeWindowSetScalingMode(OHNativeWindow *window, uint32_t sequence, 451 OHScalingMode scalingMode); 452 453 /** 454 * @brief Sets metaData of a native window. 455 * 456 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 457 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 458 * @param sequence Indicates the sequence to a produce buffer. 459 * @param size Indicates the size of a <b>OHHDRMetaData</b> vector. 460 * @param metaDate Indicates the pointer to a <b>OHHDRMetaData</b> vector. 461 * @return Returns an error code, 0 is success, otherwise, failed. 462 * @since 9 463 * @version 1.0 464 * @deprecated(since = "10") 465 */ 466 int32_t OH_NativeWindow_NativeWindowSetMetaData(OHNativeWindow *window, uint32_t sequence, int32_t size, 467 const OHHDRMetaData *metaData); 468 469 /** 470 * @brief Sets metaDataSet of a native window. 471 * 472 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 473 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 474 * @param sequence Indicates the sequence to a produce buffer. 475 * @param key Indicates the enum value to <b>OHHDRMetadataKey</b> 476 * @param size Indicates the size of a uint8_t vector. 477 * @param metaDate Indicates the pointer to a uint8_t vector. 478 * @return Returns an error code, 0 is success, otherwise, failed. 479 * @since 9 480 * @version 1.0 481 * @deprecated(since = "10") 482 */ 483 int32_t OH_NativeWindow_NativeWindowSetMetaDataSet(OHNativeWindow *window, uint32_t sequence, OHHDRMetadataKey key, 484 int32_t size, const uint8_t *metaData); 485 486 /** 487 * @brief Sets tunnel handle of a native window. 488 * 489 * @syscap SystemCapability.Graphic.Graphic2D.NativeWindow 490 * @param window Indicates the pointer to a <b>OHNativeWindow</b> instance. 491 * @param handle Indicates the pointer to a <b>OHExtDataHandle</b>. 492 * @return Returns an error code, 0 is success, otherwise, failed. 493 * @since 9 494 * @version 1.0 495 * @deprecated(since = "10") 496 */ 497 int32_t OH_NativeWindow_NativeWindowSetTunnelHandle(OHNativeWindow *window, const OHExtDataHandle *handle); 498 499 #ifdef __cplusplus 500 } 501 #endif 502 503 /** @} */ 504 #endif