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