1# NativeWindow 2 3 4## Overview 5 6Provides the native window capability for connection to the EGL. 7 8\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 9 10**Since:** 118 12 13 14## Summary 15 16 17### Files 18 19| Name | Description | 20| -------- | -------- | 21| [external_window.h](external__window_8h.md) | Defines the functions for obtaining and using a native window. <br>File to Include: <native_window/external_window.h> | 22 23 24### Structs 25 26| Name | Description | 27| -------- | -------- | 28| [Region](_region.md) | Defines the rectangle (dirty region) where the content is to be updated in the local native window. | 29| [OHHDRMetaData](_o_h_h_d_r_meta_data.md) | Defines the HDR metadata. | 30| [OHExtDataHandle](_o_h_ext_data_handle.md) | Defines the extended data handle. | 31 32 33### Types 34 35| Name | Description | 36| -------- | -------- | 37| OHNativeWindow | Provides the function of accessing the **NativeWindow**. | 38| OHNativeWindowBuffer | Provides the function of accessing the **NativeWindowBuffer**. | 39| Region | Defines the rectangle (dirty region) where the content is to be updated in the local native window. | 40 41 42### Enums 43 44| Name | Description | 45| -------- | -------- | 46| [NativeWindowOperation](#nativewindowoperation) {<br/>SET_BUFFER_GEOMETRY, GET_BUFFER_GEOMETRY, GET_FORMAT, SET_FORMAT,<br/>GET_USAGE, SET_USAGE, SET_STRIDE, GET_STRIDE,<br/>SET_SWAP_INTERVAL, GET_SWAP_INTERVAL, SET_TIMEOUT, GET_TIMEOUT,<br/>SET_COLOR_GAMUT, GET_COLOR_GAMUT, SET_TRANSFORM, GET_TRANSFORM,<br/>SET_UI_TIMESTAMP<br/>} | Enumerates the operation codes in the **OH_NativeWindow_NativeWindowHandleOpt** function. | 47| [OHScalingMode](#ohscalingmode) { OH_SCALING_MODE_FREEZE = 0, OH_SCALING_MODE_SCALE_TO_WINDOW, OH_SCALING_MODE_SCALE_CROP, OH_SCALING_MODE_NO_SCALE_CROP } | Enumerates the scaling modes. | 48| [OHHDRMetadataKey](#ohhdrmetadatakey) {<br/>OH_METAKEY_RED_PRIMARY_X = 0, OH_METAKEY_RED_PRIMARY_Y = 1, OH_METAKEY_GREEN_PRIMARY_X = 2, OH_METAKEY_GREEN_PRIMARY_Y = 3,<br/>OH_METAKEY_BLUE_PRIMARY_X = 4, OH_METAKEY_BLUE_PRIMARY_Y = 5, OH_METAKEY_WHITE_PRIMARY_X = 6, OH_METAKEY_WHITE_PRIMARY_Y = 7,<br/>OH_METAKEY_MAX_LUMINANCE = 8, OH_METAKEY_MIN_LUMINANCE = 9, OH_METAKEY_MAX_CONTENT_LIGHT_LEVEL = 10, OH_METAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11,<br/>OH_METAKEY_HDR10_PLUS = 12, OH_METAKEY_HDR_VIVID = 13<br/>} | Enumerates the HDR metadata keys. | 49 50 51### Functions 52 53| Name | Description | 54| -------- | -------- | 55| [OH_NativeWindow_CreateNativeWindow](#oh_nativewindow_createnativewindow) (void \*pSurface) | Creates a **NativeWindow** instance. A new **NativeWindow** instance is created each time this function is called. | 56| [OH_NativeWindow_DestroyNativeWindow](#oh_nativewindow_destroynativewindow) (OHNativeWindow \*window) | Decreases the reference count of a **NativeWindow** instance by 1 and when the reference count reaches 0, destroys the instance. | 57| [OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer](#oh_nativewindow_createnativewindowbufferfromsurfacebuffer) (void \*pSurfaceBuffer) | Creates a **NativeWindowBuffer** instance. A new **NativeWindowBuffer** instance is created each time this function is called. | 58| [OH_NativeWindow_DestroyNativeWindowBuffer](#oh_nativewindow_destroynativewindowbuffer) (OHNativeWindowBuffer \*buffer) | Decreases the reference count of a **NativeWindowBuffer** instance by 1 and when the reference count reaches 0, destroys the instance. | 59| [OH_NativeWindow_NativeWindowRequestBuffer](#oh_nativewindow_nativewindowrequestbuffer) (OHNativeWindow \*window, OHNativeWindowBuffer \*\*buffer, int \*fenceFd) | Requests a **NativeWindowBuffer** through a **NativeWindow** instance for content production. | 60| [OH_NativeWindow_NativeWindowFlushBuffer](#oh_nativewindow_nativewindowflushbuffer) (OHNativeWindow \*window, OHNativeWindowBuffer \*buffer, int fenceFd, [Region](_region.md) region) | Flushes the **NativeWindowBuffer** filled with the content to the buffer queue through a **NativeWindow** instance for content consumption. | 61| [OH_NativeWindow_NativeWindowAbortBuffer](#oh_nativewindow_nativewindowabortbuffer) (OHNativeWindow \*window, OHNativeWindowBuffer \*buffer) | Returns the **NativeWindowBuffer** to the buffer queue through a **NativeWindow** instance, without filling in any content. The **NativeWindowBuffer** can be used for another request. | 62| [OH_NativeWindow_NativeWindowHandleOpt](#oh_nativewindow_nativewindowhandleopt) (OHNativeWindow \*window, int code,...) | Sets or obtains the attributes of a native window, including the width, height, and content format. | 63| [OH_NativeWindow_GetBufferHandleFromNative](#oh_nativewindow_getbufferhandlefromnative) (OHNativeWindowBuffer \*buffer) | Obtains the pointer to a **BufferHandle** of a **NativeWindowBuffer** instance. | 64| [OH_NativeWindow_NativeObjectReference](#oh_nativewindow_nativeobjectreference) (void \*obj) | Adds the reference count of a native object. | 65| [OH_NativeWindow_NativeObjectUnreference](#oh_nativewindow_nativeobjectunreference) (void \*obj) | Decreases the reference count of a native object and when the reference count reaches 0, destroys this object. | 66| [OH_NativeWindow_GetNativeObjectMagic](#oh_nativewindow_getnativeobjectmagic) (void \*obj) | Obtains the magic ID of a native object. | 67| [OH_NativeWindow_NativeWindowSetScalingMode](#oh_nativewindow_nativewindowsetscalingmode) (OHNativeWindow \*window, uint32_t sequence, [OHScalingMode](#ohscalingmode) scalingMode) | Sets the scaling mode for a native window. | 68| [OH_NativeWindow_NativeWindowSetMetaData](#oh_nativewindow_nativewindowsetmetadata) (OHNativeWindow \*window, uint32_t sequence, int32_t size, const [OHHDRMetaData](_o_h_h_d_r_meta_data.md) \*metaData) | Sets the metadata for a native window. | 69| [OH_NativeWindow_NativeWindowSetMetaDataSet](#oh_nativewindow_nativewindowsetmetadataset) (OHNativeWindow \*window, uint32_t sequence, [OHHDRMetadataKey](#ohhdrmetadatakey) key, int32_t size, const uint8_t \*metaData) | Sets the metadata set for a native window. | 70| [OH_NativeWindow_NativeWindowSetTunnelHandle](#oh_nativewindow_nativewindowsettunnelhandle) (OHNativeWindow \*window, const [OHExtDataHandle](_o_h_ext_data_handle.md) \*handle) | Sets a tunnel handle for a native window. | 71 72 73## Enum Description 74 75 76### NativeWindowOperation 77 78 79``` 80enum NativeWindowOperation 81``` 82**Description**<br> 83Enumerates the operation codes in the **OH_NativeWindow_NativeWindowHandleOpt** function. 84 85| Name | Description | 86| -------- | -------- | 87| SET_BUFFER_GEOMETRY | Setting the geometry for the local window buffer. Variable arguments in the function: [Input] int32_t height and [Input] int32_t width. | 88| GET_BUFFER_GEOMETRY | Obtaining the geometry of the local window buffer. Variable arguments in the function: [Output] int32_t \*height and [Output] int32_t \*width. | 89| GET_FORMAT | Obtaining the format of the local window buffer. Variable argument in the function: [Output] int32_t \*format. | 90| SET_FORMAT | Setting the format for the local window buffer. Variable argument in the function: [Input] int32_t format. | 91| GET_USAGE | Obtaining the usage mode of the local window buffer. Variable argument in the function: [Output] int32_t \*usage. | 92| SET_USAGE | Setting the usage mode for the local window buffer. Variable argument in the function: [Input] int32_t usage. | 93| SET_STRIDE | Setting the stride for the local window buffer. Variable argument in the function: [Input] int32_t stride. | 94| GET_STRIDE | Obtaining the stride of the local window buffer. Variable argument in the function: [Output] int32_t \*stride. | 95| SET_SWAP_INTERVAL | Setting the swap interval for the local window buffer. Variable argument in the function: [Input] int32_t interval. | 96| GET_SWAP_INTERVAL | Obtaining the swap interval of the local window buffer. Variable argument in the function: [Output] int32_t \*interval. | 97| SET_TIMEOUT | Setting the timeout duration for requesting the local window buffer. Variable argument in the function: [Input] int32_t timeout. | 98| GET_TIMEOUT | Obtaining the timeout duration for requesting the local window buffer. Variable argument in the function: [Output] int32_t \*timeout. | 99| SET_COLOR_GAMUT | Setting the color gamut for the local window buffer. Variable argument in the function: [Input] int32_t colorGamut. | 100| GET_COLOR_GAMUT | Obtaining the color gamut of the local window buffer. Variable argument in the function: [out int32_t \*colorGamut]. | 101| SET_TRANSFORM | Setting the transform for the local window buffer. Variable argument in the function: [Input] int32_t transform. | 102| GET_TRANSFORM | Obtaining the transform of the local window buffer. Variable argument in the function: [Output] int32_t \*transform. | 103| SET_UI_TIMESTAMP | Setting the UI timestamp for the local window buffer. Variable argument in the function: [Input] uint64_t uiTimestamp. | 104 105 106### OHHDRMetadataKey 107 108 109``` 110enum OHHDRMetadataKey 111``` 112**Description**<br> 113Enumerates the HDR metadata keys. 114 115| Name | Description | 116| -------- | -------- | 117| OH_METAKEY_RED_PRIMARY_X | X coordinate of the red primary color. | 118| OH_METAKEY_RED_PRIMARY_Y | Y coordinate of the red primary color. | 119| OH_METAKEY_GREEN_PRIMARY_X | X coordinate of the green primary color. | 120| OH_METAKEY_GREEN_PRIMARY_Y | Y coordinate of the green primary color. | 121| OH_METAKEY_BLUE_PRIMARY_X | X coordinate of the blue primary color. | 122| OH_METAKEY_BLUE_PRIMARY_Y | Y coordinate of the blue primary color. | 123| OH_METAKEY_WHITE_PRIMARY_X | X coordinate of the white point. | 124| OH_METAKEY_WHITE_PRIMARY_Y | Y coordinate of the white point. | 125| OH_METAKEY_MAX_LUMINANCE | Maximum luminance. | 126| OH_METAKEY_MIN_LUMINANCE | Minimum luminance. | 127| OH_METAKEY_MAX_CONTENT_LIGHT_LEVEL | Maximum content light level (MaxCLL). | 128| OH_METAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL | Maximum frame average light level (MaxFALLL). | 129| OH_METAKEY_HDR10_PLUS | HDR10+. | 130| OH_METAKEY_HDR_VIVID | Vivid. | 131 132 133### OHScalingMode 134 135 136``` 137enum OHScalingMode 138``` 139**Description**<br> 140Enumerates the scaling modes. 141 142| Name | Description | 143| -------- | -------- | 144| OH_SCALING_MODE_FREEZE | The window content cannot be updated before the buffer of the window size is received. | 145| OH_SCALING_MODE_SCALE_TO_WINDOW | The buffer is scaled in two dimensions to match the window size. | 146| OH_SCALING_MODE_SCALE_CROP | The buffer is scaled uniformly so that its smaller size can match the window size. | 147| OH_SCALING_MODE_NO_SCALE_CROP | The window is cropped to the size of the buffer's cropping rectangle. Pixels outside the cropping rectangle are considered completely transparent. | 148 149 150## Function Description 151 152 153### OH_NativeWindow_CreateNativeWindow() 154 155 156``` 157OHNativeWindow* OH_NativeWindow_CreateNativeWindow (void * pSurface) 158``` 159**Description**<br> 160Creates a **NativeWindow** instance. A new **NativeWindow** instance is created each time this function is called. 161 162\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 163 164 **Parameters** 165 166| Name | Description | 167| -------- | -------- | 168| pSurface | Indicates the pointer to a **ProduceSurface**. The type is **sptr<OHOS::Surface>**. | 169 170**Returns** 171 172Returns the pointer to the **NativeWindow** instance created. 173 174 175### OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer() 176 177 178``` 179OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer (void * pSurfaceBuffer) 180``` 181**Description**<br> 182Creates a **NativeWindowBuffer** instance. A new **NativeWindowBuffer** instance is created each time this function is called. 183 184\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 185 186 **Parameters** 187 188| Name | Description | 189| -------- | -------- | 190| pSurfaceBuffer | Indicates the pointer to a produce buffer. The type is **sptr<OHOS::SurfaceBuffer>**. | 191 192**Returns** 193 194Returns the pointer to the **NativeWindowBuffer** instance created. 195 196 197### OH_NativeWindow_DestroyNativeWindow() 198 199 200``` 201void OH_NativeWindow_DestroyNativeWindow (OHNativeWindow * window) 202``` 203**Description**<br> 204Decreases the reference count of a **NativeWindow** instance by 1 and when the reference count reaches 0, destroys the instance. 205 206\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 207 208 **Parameters** 209 210| Name | Description | 211| -------- | -------- | 212| window | Indicates the pointer to a **NativeWindow** instance. | 213 214 215### OH_NativeWindow_DestroyNativeWindowBuffer() 216 217 218``` 219void OH_NativeWindow_DestroyNativeWindowBuffer (OHNativeWindowBuffer * buffer) 220``` 221**Description**<br> 222Decreases the reference count of a **NativeWindowBuffer** instance by 1 and when the reference count reaches 0, destroys the instance. 223 224\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 225 226 **Parameters** 227 228| Name | Description | 229| -------- | -------- | 230| buffer | Indicates the pointer to a **NativeWindowBuffer** instance. | 231 232 233### OH_NativeWindow_GetBufferHandleFromNative() 234 235 236``` 237BufferHandle* OH_NativeWindow_GetBufferHandleFromNative (OHNativeWindowBuffer * buffer) 238``` 239**Description**<br> 240Obtains the pointer to a **BufferHandle** of a **NativeWindowBuffer** instance. 241 242\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 243 244 **Parameters** 245 246| Name | Description | 247| -------- | -------- | 248| buffer | Indicates the pointer to a **NativeWindowBuffer** instance. | 249 250**Returns** 251 252Returns the pointer to the **BufferHandle** instance obtained. 253 254 255### OH_NativeWindow_GetNativeObjectMagic() 256 257 258``` 259int32_t OH_NativeWindow_GetNativeObjectMagic (void * obj) 260``` 261**Description**<br> 262Obtains the magic ID of a native object. 263 264\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 265 266 **Parameters** 267 268| Name | Description | 269| -------- | -------- | 270| obj | Indicates the pointer to a **NativeWindow** or **NativeWindowBuffer** instance. | 271 272**Returns** 273 274Returns the magic ID, which is unique for each native object. 275 276 277### OH_NativeWindow_NativeObjectReference() 278 279 280``` 281int32_t OH_NativeWindow_NativeObjectReference (void * obj) 282``` 283**Description**<br> 284Adds the reference count of a native object. 285 286\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 287 288 **Parameters** 289 290| Name | Description | 291| -------- | -------- | 292| obj | Indicates the pointer to a **NativeWindow** or **NativeWindowBuffer** instance. | 293 294**Returns** 295 296Returns an error code defined in **GSError**. 297 298 299### OH_NativeWindow_NativeObjectUnreference() 300 301 302``` 303int32_t OH_NativeWindow_NativeObjectUnreference (void * obj) 304``` 305**Description**<br> 306Decreases the reference count of a native object and when the reference count reaches 0, destroys this object. 307 308\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 309 310 **Parameters** 311 312| Name | Description | 313| -------- | -------- | 314| obj | Indicates the pointer to a **NativeWindow** or **NativeWindowBuffer** instance. | 315 316**Returns** 317 318Returns an error code defined in **GSError**. 319 320 321### OH_NativeWindow_NativeWindowAbortBuffer() 322 323 324``` 325int32_t OH_NativeWindow_NativeWindowAbortBuffer (OHNativeWindow * window, OHNativeWindowBuffer * buffer ) 326``` 327**Description**<br> 328Returns the **NativeWindowBuffer** to the buffer queue through a **NativeWindow** instance, without filling in any content. The **NativeWindowBuffer** can be used for another request. 329 330\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 331 332 **Parameters** 333 334| Name | Description | 335| -------- | -------- | 336| window | Indicates the pointer to a **NativeWindow** instance. | 337| buffer | Indicates the pointer to a **NativeWindowBuffer** instance. | 338 339**Returns** 340 341Returns an error code defined in **GSError**. 342 343 344### OH_NativeWindow_NativeWindowFlushBuffer() 345 346 347``` 348int32_t OH_NativeWindow_NativeWindowFlushBuffer (OHNativeWindow * window, OHNativeWindowBuffer * buffer, int fenceFd, Region region ) 349``` 350**Description**<br> 351Flushes the **NativeWindowBuffer** filled with the content to the buffer queue through a **NativeWindow** instance for content consumption. 352 353\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 354 355 **Parameters** 356 357| Name | Description | 358| -------- | -------- | 359| window | Indicates the pointer to a **NativeWindow** instance. | 360| buffer | Indicates the pointer to a **NativeWindowBuffer** instance. | 361| fenceFd | Indicates a file descriptor handle, which is used for timing synchronization. | 362| region | Indicates a dirty region where content is updated. | 363 364**Returns** 365 366Returns an error code defined in **GSError**. 367 368 369### OH_NativeWindow_NativeWindowHandleOpt() 370 371 372``` 373int32_t OH_NativeWindow_NativeWindowHandleOpt (OHNativeWindow * window, int code, ... ) 374``` 375**Description**<br> 376Sets or obtains the attributes of a native window, including the width, height, and content format. 377 378\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 379 380 **Parameters** 381 382| Name | Description | 383| -------- | -------- | 384| window | Indicates the pointer to a **NativeWindow** instance. | 385| code | Indicates the operation code. For details, see [NativeWindowOperation](#nativewindowoperation). | 386| ... | Indicates the variable argument, which must correspond to the operation code. | 387 388**Returns** 389 390Returns an error code defined in **GSError**. 391 392 393### OH_NativeWindow_NativeWindowRequestBuffer() 394 395 396``` 397int32_t OH_NativeWindow_NativeWindowRequestBuffer (OHNativeWindow * window, OHNativeWindowBuffer ** buffer, int * fenceFd ) 398``` 399**Description**<br> 400Requests a **NativeWindowBuffer** through a **NativeWindow** instance for content production. 401 402\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 403 404 **Parameters** 405 406| Name | Description | 407| -------- | -------- | 408| window | Indicates the pointer to a **NativeWindow** instance. | 409| buffer | Indicates the double pointer to a **NativeWindowBuffer** instance. | 410| fenceFd | Indicates the pointer to a file descriptor handle. | 411 412**Returns** 413 414Returns an error code defined in **GSError**. 415 416 417### OH_NativeWindow_NativeWindowSetMetaData() 418 419 420``` 421int32_t OH_NativeWindow_NativeWindowSetMetaData (OHNativeWindow * window, uint32_t sequence, int32_t size, const OHHDRMetaData * metaData ) 422``` 423**Description**<br> 424Sets the metadata for a native window. 425 426\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 427 428 **Parameters** 429 430| Name | Description | 431| -------- | -------- | 432| window | Indicates the pointer to a **NativeWindow** instance. | 433| sequence | Indicates the sequence of the producer buffer. | 434| size | Indicates the size of the **[OHHDRMetaData](_o_h_h_d_r_meta_data.md)** array. | 435| metaData | Indicates the pointer to the **[OHHDRMetaData](_o_h_h_d_r_meta_data.md)** array. | 436 437**Returns** 438 439Returns an error code defined in **GSError**. 440 441 442### OH_NativeWindow_NativeWindowSetMetaDataSet() 443 444 445``` 446int32_t OH_NativeWindow_NativeWindowSetMetaDataSet (OHNativeWindow * window, uint32_t sequence, OHHDRMetadataKey key, int32_t size, const uint8_t * metaData ) 447``` 448**Description**<br> 449Sets the metadata set for a native window. 450 451\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 452 453 **Parameters** 454 455| Name | Description | 456| -------- | -------- | 457| window | Indicates the pointer to a **NativeWindow** instance. | 458| sequence | Indicates the sequence of the producer buffer. | 459| key | Indicates a metadata key. For details, see **OHHDRMetadataKey**. | 460| size | Indicates the size of the uint8_t vector. | 461| metaData | Indicates the pointer to the uint8_t vector. | 462 463**Returns** 464 465Returns an error code defined in **GSError**. 466 467 468### OH_NativeWindow_NativeWindowSetScalingMode() 469 470 471``` 472int32_t OH_NativeWindow_NativeWindowSetScalingMode (OHNativeWindow * window, uint32_t sequence, OHScalingMode scalingMode ) 473``` 474**Description**<br> 475Sets the scaling mode for a native window. 476 477\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 478 479 **Parameters** 480 481| Name | Description | 482| -------- | -------- | 483| window | Indicates the pointer to a **NativeWindow** instance. | 484| sequence | Indicates the sequence of the producer buffer. | 485| scalingMode | Indicates the scaling mode to set. For details, see **OHScalingMode**. | 486 487**Returns** 488 489Returns an error code defined in **GSError**. 490 491 492### OH_NativeWindow_NativeWindowSetTunnelHandle() 493 494 495``` 496int32_t OH_NativeWindow_NativeWindowSetTunnelHandle (OHNativeWindow * window, const OHExtDataHandle * handle ) 497``` 498**Description**<br> 499Sets a tunnel handle for a native window. 500 501\@syscap SystemCapability.Graphic.Graphic2D.NativeWindow 502 503 **Parameters** 504 505| Name | Description | 506| -------- | -------- | 507| window | Indicates the pointer to a **NativeWindow** instance. | 508| handle | Indicates the pointer to an **[OHExtDataHandle](_o_h_ext_data_handle.md)**. | 509 510**Returns** 511 512Returns an error code defined in **GSError**. 513