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