external_window.h
Overview
This file declares the functions for obtaining and using NativeWindow.
Sample: NDKNativeWindow
File to include: <native_window/external_window.h>
Library: libnative_window.so
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Related module: NativeWindow
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| Region | Region | Describes the rectangle (dirty region) where the content is to be updated in the local OHNativeWindow. |
| Rect | - | If rects is a null pointer, the buffer size is the same as the size of the dirty region by default. |
| OHHDRMetaData | OHHDRMetaData | Describes the HDR metadata. |
| OHExtDataHandle | OHExtDataHandle | Describes the extended data handle. |
| OHIPCParcel | OHIPCParcel | Provides access to OHIPCParcel, which is an IPC parcelable object. |
| NativeWindow | OHNativeWindow | Provides access to OHNativeWindow. |
| NativeWindowBuffer | OHNativeWindowBuffer | Provides access to OHNativeWindowBuffer. |
| OH_NativeBuffer | OH_NativeBuffer | Provides access to OH_NativeBuffer. |
Enums
| Name | typedef Keyword | Description |
|---|---|---|
| NativeWindowOperation | NativeWindowOperation | Defines an enum for the operation codes in the OH_NativeWindow_NativeWindowHandleOpt function. |
| OHScalingMode | OHScalingMode | Enumerates the scaling modes. |
| OHScalingModeV2 | OHScalingModeV2 | Defines an enum for the rendering scaling modes. |
| OHHDRMetadataKey | OHHDRMetadataKey | Enumerates the HDR metadata keys. |
| OHSurfaceSource | OHSurfaceSource | Defines an enum for the sources of content displayed in the local window. |
Functions
| Name | Description |
|---|---|
| OHNativeWindow* OH_NativeWindow_CreateNativeWindow(void* pSurface) | Creates an OHNativeWindow instance. A new OHNativeWindow instance is created each time this function is called. Note: If this API is unavailable, you can use OH_NativeImage_AcquireNativeWindow or XComponent as a substitute. |
| void OH_NativeWindow_DestroyNativeWindow(OHNativeWindow* window) | Decreases the reference count of an OHNativeWindow instance by 1 and when the reference count reaches 0, destroys the instance. This function is not thread-safe. |
| OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer(void* pSurfaceBuffer) | Creates an OHNativeWindowBuffer instance. A new OHNativeWindowBuffer instance is created each time this function is called. Note: If this function is unavailable, you can use OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer as a substitute. |
| OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer(OH_NativeBuffer* nativeBuffer) | Creates an OHNativeWindowBuffer instance. A new OHNativeWindowBuffer instance is created each time this function is called. This function must be used in pair with OH_NativeWindow_DestroyNativeWindowBuffer. Otherwise, memory leak occurs. This function is not thread-safe. |
| void OH_NativeWindow_DestroyNativeWindowBuffer(OHNativeWindowBuffer* buffer) | Decreases the reference count of an OHNativeWindowBuffer instance by 1 and when the reference count reaches 0, destroys the instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeWindowRequestBuffer(OHNativeWindow *window,OHNativeWindowBuffer **buffer, int *fenceFd) | Requests an OHNativeWindowBuffer through an OHNativeWindow instance for content production. Before calling this function, you must call SET_BUFFER_GEOMETRY to set the width and height of OHNativeWindow. This function must be used in pair with OH_NativeWindow_NativeWindowFlushBuffer. Otherwise, memory leak occurs. When fenceFd is used up, you must close it. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeWindowFlushBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer,int fenceFd, Region region) | Flushes the OHNativeWindowBuffer filled with the produced content to the buffer queue through an OHNativeWindow instance for content consumption. The system will close fenceFd. You do not need to close it. This function is not thread-safe. |
| int32_t OH_NativeWindow_GetLastFlushedBuffer(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16]) | Obtains the OHNativeWindowBuffer that was flushed to the buffer queue last time through an OHNativeWindow instance. |
| int32_t OH_NativeWindow_NativeWindowAbortBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer) | Returns the OHNativeWindowBuffer to the buffer queue through an OHNativeWindow instance, without filling in any content. The OHNativeWindowBuffer can be used for a new request. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeWindowHandleOpt(OHNativeWindow *window, int code, ...) | Sets or obtains the attributes of an OHNativeWindow instance, including the width, height, and content format. This function is not thread-safe. |
| BufferHandle *OH_NativeWindow_GetBufferHandleFromNative(OHNativeWindowBuffer *buffer) | Obtains the pointer to a BufferHandle of an OHNativeWindowBuffer instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeObjectReference(void *obj) | Adds the reference count of a native object. This function must be used in pair with OH_NativeWindow_NativeObjectUnreference. Otherwise, memory leak occurs. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeObjectUnreference(void *obj) | Decreases the reference count of a native object by 1 and when the reference count reaches 0, destroys this object. This function is not thread-safe. |
| int32_t OH_NativeWindow_GetNativeObjectMagic(void *obj) | Obtains the magic ID of a native object. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeWindowSetScalingMode(OHNativeWindow *window, uint32_t sequence,OHScalingMode scalingMode) | Sets a scaling mode for an OHNativeWindow. |
| int32_t OH_NativeWindow_NativeWindowSetMetaData(OHNativeWindow *window, uint32_t sequence, int32_t size,const OHHDRMetaData *metaData) | Sets metadata for an OHNativeWindow. |
| int32_t OH_NativeWindow_NativeWindowSetMetaDataSet(OHNativeWindow *window, uint32_t sequence, OHHDRMetadataKey key,int32_t size, const uint8_t *metaData) | Sets a metadata set for an OHNativeWindow. |
| int32_t OH_NativeWindow_NativeWindowSetTunnelHandle(OHNativeWindow *window, const OHExtDataHandle *handle) | Sets a tunnel handle to an OHNativeWindow. |
| int32_t OH_NativeWindow_NativeWindowAttachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer) | Attaches an OHNativeWindowBuffer to an OHNativeWindow instance. This function must be used in pair with OH_NativeWindow_NativeWindowDetachBuffer. Otherwise, memory management disorder may occur. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeWindowDetachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer) | Detaches an OHNativeWindowBuffer from an OHNativeWindow instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_GetSurfaceId(OHNativeWindow *window, uint64_t *surfaceId) | Obtains a surface ID through an OHNativeWindow. This function is not thread-safe. |
| int32_t OH_NativeWindow_CreateNativeWindowFromSurfaceId(uint64_t surfaceId, OHNativeWindow **window) | Creates an OHNativeWindow instance based on a surface ID. This function must be used in pair with OH_NativeWindow_DestroyNativeWindow. Otherwise, memory leak occurs. If OHNativeWindow instances are released concurrently, call OH_NativeWindow_NativeObjectReference and OH_NativeWindow_NativeObjectUnreference to increase and decrease the reference count of OHNativeWindow. The surface obtained by using the surface ID must be created in the current process, but not in a different process. This function is not thread-safe. |
| int32_t OH_NativeWindow_NativeWindowSetScalingModeV2(OHNativeWindow* window, OHScalingModeV2 scalingMode) | Sets a rendering scaling mode for an OHNativeWindow instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_GetLastFlushedBufferV2(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16]) | Obtains the OHNativeWindowBuffer that was flushed to the buffer queue last time through an OHNativeWindow instance. The difference between this function and OH_NativeWindow_GetLastFlushedBuffer lies in the matrix. This function must be used in pair with OH_NativeWindow_NativeObjectUnreference. Otherwise, memory leak occurs. This function is not thread-safe. |
| void OH_NativeWindow_SetBufferHold(OHNativeWindow *window) | Enables the single-frame buffering mechanism, which caches a frame buffer in advance and delays the display of the frame to smooth the frame rate fluctuation. |
| int32_t OH_NativeWindow_WriteToParcel(OHNativeWindow *window, OHIPCParcel *parcel) | Writes an OHNativeWindow instance to an OHIPCParcel instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_ReadFromParcel(OHIPCParcel *parcel, OHNativeWindow **window) | Reads an OHNativeWindow instance from an OHIPCParcel instance. This function creates an OHNativeWindow instance. After it is used, you need to use this function in pair with OH_NativeWindow_DestroyNativeWindow. Otherwise, memory leak occurs. This function is not thread-safe. |
| int32_t OH_NativeWindow_SetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace colorSpace) | Sets the color space for an OHNativeWindow instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_GetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace *colorSpace) | Obtains the color space of an OHNativeWindow instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_SetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t *metadata) | Sets a metadata value for an OHNativeWindow instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_GetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t *size, uint8_t **metadata) | Obtains the metadata value of an OHNativeWindow instance. This function is not thread-safe. |
| int32_t OH_NativeWindow_CleanCache(OHNativeWindow *window) | Clears the OHNativeWindowBuffer cache in OHNativeWindow. Ensure that OHNativeWindowBuffer has been successfully allocated by calling OH_NativeWindow_NativeWindowRequestBuffer. This function is not thread-safe. |
| int32_t OH_NativeWindow_PreAllocBuffers(OHNativeWindow *window, uint32_t allocBufferCnt) | Request multiple OHNativeWindowBuffer blocks in advance through the OHNativeWindow object for content production. Before calling this function, you need to set the width and height of OHNativeWindow through OH_NativeWindow_NativeWindowHandleOpt. This function is not thread-safe. |
| int32_t OH_NativeWindow_LockBuffer(OHNativeWindow* window, Region region, OHNativeWindowBuffer** buffer) | Requests an OHNativeWindowBuffer through an OHNativeWindow instance for content production, and locks the OHNativeWindowBuffer. This API must be used together with OH_NativeWindow_UnlockAndFlushBuffer. After this API locks the OHNativeWindowBuffer, the OHNativeWindowBuffer can be locked again only after the OH_NativeWindow_UnlockAndFlushBuffer API is called to unlock the OHNativeWindowBuffer. If this API is called to lock the OHNativeWindowBuffer repeatedly, an invalid operation error code is returned. This API supports image rendering through memory read and write on the CPU. This function is not thread-safe. |
| int32_t OH_NativeWindow_UnlockAndFlushBuffer(OHNativeWindow* window) | Flushes the OHNativeWindowBuffer filled with the produced content to the buffer queue through an OHNativeWindow instance for content consumption, and locks the OHNativeWindowBuffer. This API must be used together with OH_NativeWindow_LockBuffer. If this API is called to unlock the OHNativeWindowBuffer repeatedly, an invalid operation error code is returned. This function is not thread-safe. |
Enum Description
NativeWindowOperation
enum NativeWindowOperation
Description
Defines an enum for the operation codes in the OH_NativeWindow_NativeWindowHandleOpt function.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
| Enum | Description |
|---|---|
| SET_BUFFER_GEOMETRY | Sets the geometry of the local window buffer. Variable arguments in the function: [Input] int32_t width and [Input] int32_t height. Note: The order of width and height for setting is different from that for obtaining. Exercise caution when using this API. |
| GET_BUFFER_GEOMETRY | Obtains the geometry of the local window buffer. Variable arguments in the function: [Output] int32_t *height and [Output] int32_t *width. Note: The order of width and height for obtaining is different from that for setting. Exercise caution when using this API. |
| GET_FORMAT | Obtains the format of the local window buffer. Variable arguments in the function: [Output] int32_t *format. For details about the available options, see OH_NativeBuffer_Format. |
| SET_FORMAT | Sets the format of the local window buffer. Variable arguments in the function: [Input] int32_t format. For details about the available options, see OH_NativeBuffer_Format. |
| GET_USAGE | Obtains the read/write mode of the local window. Variable arguments in the function: [Output] uint64_t *usage. For details about the available options, see OH_NativeBuffer_Usage. |
| SET_USAGE | Sets the usage mode for the local window buffer. Variable argument in the function: [Input] uint64_t usage. For details about the available options, see OH_NativeBuffer_Usage. |
| SET_STRIDE | Sets the stride of the local window buffer. Variable argument in the function: [Input] int32_t stride. Deprecated from: 16 |
| GET_STRIDE | Obtains the stride of the local window buffer. Variable argument in the function: [Output] int32_t *stride. Deprecated from: 16 Substitute: Use OH_NativeWindow_GetBufferHandleFromNative to obtain a BufferHandle instance, and obtain the stride from this instance. |
| SET_SWAP_INTERVAL | Sets the swap interval of the local window buffer. Variable argument in the function: [Input] int32_t interval. |
| GET_SWAP_INTERVAL | Obtains the swap interval of the local window buffer. Variable argument in the function: [Output] int32_t *interval. |
| SET_TIMEOUT | Sets the timeout duration for requesting the local window buffer, in ms. Default value: 3,000 ms. Variable argument in the function: [Input] int32_t timeout. |
| GET_TIMEOUT | Obtains the timeout duration for requesting the local window buffer, in ms. Default value: 3,000 ms. Variable argument in the function: [Output] int32_t *timeout. |
| SET_COLOR_GAMUT | Sets the color gamut of the local window buffer. Variable argument in the function: [Input] int32_t colorGamut. For details about the available options, see OH_NativeBuffer_ColorGamut. |
| GET_COLOR_GAMUT | Obtains the color gamut of the local window buffer. Variable arguments in the function: [Output] int32_t *colorGamut. For details about the available options, see OH_NativeBuffer_ColorGamut. |
| SET_TRANSFORM | Sets the transform of the local window buffer. Variable argument in the function: [Input] int32_t transform. For details about the available options, see OH_NativeBuffer_TransformType. |
| GET_TRANSFORM | Obtains the transform of the local window buffer. Variable argument in the function: [Output] int32_t *transform. For details about the available options, see OH_NativeBuffer_TransformType. |
| SET_UI_TIMESTAMP | Sets the UI timestamp for the local window buffer. Variable argument in the function: [Input] uint64_t uiTimestamp. |
| GET_BUFFERQUEUE_SIZE | Obtains the memory queue size. Variable argument in the function: [Output] int32_t *size. Since: 12 |
| SET_SOURCE_TYPE | Sets the source of content displayed in the local window. Variable argument in the function: [Input] int32_t sourceType. For details about the available options, see OHSurfaceSource. Since: 12 |
| GET_SOURCE_TYPE | Obtains the source of content displayed in the local window. Variable argument in the function: [Output] int32_t *sourceType. For details about the available options, see OHSurfaceSource. Since: 12 |
| SET_APP_FRAMEWORK_TYPE | Sets the application framework name of the local window. Variable argument in the function: [Input] char* frameworkType. A maximum of 64 bytes are supported. Since: 12 |
| GET_APP_FRAMEWORK_TYPE | Obtains the application framework name of the local window. Variable argument in the function: [Output] char** frameworkType. Since: 12 |
| SET_HDR_WHITE_POINT_BRIGHTNESS | Sets the brightness of HDR white points. Variable arguments in the function: [Input] float brightness. The value range is [0.0f, 1.0f]. Since: 12 |
| SET_SDR_WHITE_POINT_BRIGHTNESS | Sets the brightness of SDR white points. Variable arguments in the function: [Input] float brightness. The value range is [0.0f, 1.0f]. Since: 12 |
| SET_DESIRED_PRESENT_TIMESTAMP = 24 | Sets a timestamp indicating when the local window buffer is expected to show on the screen. The timestamp takes effect only when RenderService is the consumer of the local window and after OH_NativeWindow_NativeWindowFlushBuffer is called. The next buffer added to the queue by the producer is consumed by RenderService and displayed on the screen only after the expected on-screen time arrives. If there are multiple buffers in the queue from various producers, all of them have set desiredPresentTimestamp, and the desired time arrives, the buffer that was enqueued earliest will be pushed back into the queue by the consumer. If the expected on-screen time exceeds the time provided by the consumer by over 1 second, the expected timestamp is ignored. Variable argument in the function: [Input] int64_t desiredPresentTimestamp. The value must be greater than 0 and should be generated by the standard library std::chrono::steady_clock, in nanoseconds. Since: 13 |
OHScalingMode
enum OHScalingMode
Description
Enumerates the scaling modes.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 9
Deprecated from: 10
Substitute API: OHScalingModeV2
| Enum | Description |
|---|---|
| OH_SCALING_MODE_FREEZE = 0 | The window content cannot be updated before the buffer of the window size is received. |
| OH_SCALING_MODE_SCALE_TO_WINDOW | The buffer is scaled in two dimensions to match the window size. |
| OH_SCALING_MODE_SCALE_CROP | The buffer is scaled uniformly so that its smaller size can match the window size. |
| 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. |
OHScalingModeV2
enum OHScalingModeV2
Description
Defines an enum for the rendering scaling modes.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
| Enum | Description |
|---|---|
| OH_SCALING_MODE_FREEZE_V2 = 0 | Freezes the window. The window content is not updated until a buffer with the same size as the window is received. |
| OH_SCALING_MODE_SCALE_TO_WINDOW_V2 | Scales the buffer to match the window size. |
| OH_SCALING_MODE_SCALE_CROP_V2 | Scales the buffer at the original aspect ratio to enable the smaller side of the buffer to match the window, while making the excess part transparent. |
| OH_SCALING_MODE_NO_SCALE_CROP_V2 | Crops the buffer by window size. Pixels outside the cropping rectangle are considered completely transparent. |
| OH_SCALING_MODE_SCALE_FIT_V2 | Scales the buffer at the original aspect ratio to fully display the buffer content, while filling the unfilled area of the window with the background color. This mode is not available for the development board and the Emulator. |
OHHDRMetadataKey
enum OHHDRMetadataKey
Description
Enumerates the HDR metadata keys.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 9
Deprecated from: 10
| Enum | Description |
|---|---|
| OH_METAKEY_RED_PRIMARY_X = 0 | X coordinate of the red primary color. |
| OH_METAKEY_RED_PRIMARY_Y = 1, | Y coordinate of the red primary color. |
| OH_METAKEY_GREEN_PRIMARY_X = 2, | X coordinate of the green primary color. |
| OH_METAKEY_GREEN_PRIMARY_Y = 3, | Y coordinate of the green primary color. |
| OH_METAKEY_BLUE_PRIMARY_X = 4, | X coordinate of the blue primary color. |
| OH_METAKEY_BLUE_PRIMARY_Y = 5, | Y coordinate of the blue primary color. |
| OH_METAKEY_WHITE_PRIMARY_X = 6, | X coordinate of the white point. |
| OH_METAKEY_WHITE_PRIMARY_Y = 7, | Y coordinate of the white point. |
| OH_METAKEY_MAX_LUMINANCE = 8, | Maximum luminance. |
| OH_METAKEY_MIN_LUMINANCE = 9, | Minimum luminance. |
| OH_METAKEY_MAX_CONTENT_LIGHT_LEVEL = 10, | Maximum content light level (MaxCLL). |
| OH_METAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, | Maximum frame average light level. |
| OH_METAKEY_HDR10_PLUS = 12, | HDR10 Plus. |
| OH_METAKEY_HDR_VIVID = 13, | Vivid. |
OHSurfaceSource
enum OHSurfaceSource
Description
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Defines an enum for the sources of content displayed in the local window.
Since: 12
| Enum | Description |
|---|---|
| OH_SURFACE_SOURCE_DEFAULT = 0 | Default source. |
| OH_SURFACE_SOURCE_UI | The window content comes from UIs. |
| OH_SURFACE_SOURCE_GAME | The window content comes from games. |
| OH_SURFACE_SOURCE_CAMERA | The window content comes from cameras. |
| OH_SURFACE_SOURCE_VIDEO | The window content comes from videos. |
Function Description
OH_NativeWindow_CreateNativeWindow()
OHNativeWindow* OH_NativeWindow_CreateNativeWindow(void* pSurface)
Description
Creates an OHNativeWindow instance. A new OHNativeWindow instance is created each time this function is called.
Note: If this API is unavailable, you can use OH_NativeImage_AcquireNativeWindow or XComponent as a substitute.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Deprecated from: 12
Parameters
| Name | Description |
|---|---|
| void* pSurface | Pointer to a ProduceSurface. The type is sptr<OHOS::Surface>. |
Returns
| Type | Description |
|---|---|
| OHNativeWindow* | Returns the pointer to the OHNativeWindow instance created. |
OH_NativeWindow_DestroyNativeWindow()
void OH_NativeWindow_DestroyNativeWindow(OHNativeWindow* window)
Description
Decreases the reference count of an OHNativeWindow instance by 1 and when the reference count reaches 0, destroys the instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindow* window | Pointer to an OHNativeWindow instance. |
OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer()
OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer(void* pSurfaceBuffer)
Description
Creates an OHNativeWindowBuffer instance. A new OHNativeWindowBuffer instance is created each time this function is called.
Note: If this API is unavailable, you can use OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer as a substitute.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Deprecated from: 12
Substitute: OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer
Parameters
| Name | Description |
|---|---|
| void* pSurfaceBuffer | Pointer to a ProduceSurfaceBuffer. The type is sptrOHOS::SurfaceBuffer. |
Returns
| Type | Description |
|---|---|
| OHNativeWindowBuffer* | Returns the pointer to the OHNativeWindowBuffer instance created. |
OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer()
OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer(OH_NativeBuffer* nativeBuffer)
Description
Creates an OHNativeWindowBuffer instance. A new OHNativeWindowBuffer instance is created each time this function is called.
This function must be used in pair with OH_NativeWindow_DestroyNativeWindowBuffer. Otherwise, memory leak occurs.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_NativeBuffer* nativeBuffer | Pointer to an OH_NativeBuffer instance. |
Returns
| Type | Description |
|---|---|
| OHNativeWindowBuffer* | Returns the pointer to the OHNativeWindowBuffer instance created. |
OH_NativeWindow_DestroyNativeWindowBuffer()
void OH_NativeWindow_DestroyNativeWindowBuffer(OHNativeWindowBuffer* buffer)
Description
Decreases the reference count of an OHNativeWindowBuffer instance by 1 and when the reference count reaches 0, destroys the instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindowBuffer* buffer | Pointer to an OHNativeWindowBuffer instance. |
OH_NativeWindow_NativeWindowRequestBuffer()
int32_t OH_NativeWindow_NativeWindowRequestBuffer(OHNativeWindow *window,OHNativeWindowBuffer **buffer, int *fenceFd)
Description
Requests an OHNativeWindowBuffer through an OHNativeWindow instance for content production.
Before calling this function, you must call SET_BUFFER_GEOMETRY to set the width and height of OHNativeWindow.
This function must be used in pair with OH_NativeWindow_NativeWindowFlushBuffer. Otherwise, memory leak occurs.
When fenceFd is used up, you must close it.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer **buffer | Double pointer to an OHNativeWindowBuffer instance. You can obtain the BufferHandle struct by calling OH_NativeWindow_GetBufferHandleFromNative to access the buffer memory. |
| int *fenceFd | File descriptor handle, used for GPU/CPU sync. The returns are as follows: - ≥0: The buffer is being used by the GPU. You need to wait until the file descriptor is ready. - -1: The buffer can be used directly. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_NativeWindowFlushBuffer()
int32_t OH_NativeWindow_NativeWindowFlushBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer,int fenceFd, Region region)
Description
Flushes the OHNativeWindowBuffer filled with the produced content to the buffer queue through an OHNativeWindow instance for content consumption.
The system will close fenceFd. You do not need to close it.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer *buffer | Pointer to an OHNativeWindowBuffer instance. |
| int fenceFd | File descriptor handle, which is used for timing synchronization. The options are as follows: - -1: The CPU rendering is complete, and no timing synchronization is required. - ≥0: The handle is converted from a GPU synchronization object (for example, eglDupNativeFenceFDANDROID of EGL). The peer end needs to synchronize timing through fenceFd. |
| Region region | Region struct, which indicates a dirty region where content is updated. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetLastFlushedBuffer()
int32_t OH_NativeWindow_GetLastFlushedBuffer(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16])
Description
Obtains the OHNativeWindowBuffer that was flushed to the buffer queue last time through an OHNativeWindow instance.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 11
Deprecated from: 12
Substitute: OH_NativeWindow_GetLastFlushedBufferV2
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer **buffer | Double pointer to an OHNativeWindowBuffer instance. |
| int *fenceFd | Pointer to a file descriptor. |
| matrix | Retrieved 4 × 4 transformation matrix. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_NativeWindowAbortBuffer()
int32_t OH_NativeWindow_NativeWindowAbortBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer)
Description
Returns the OHNativeWindowBuffer to the buffer queue through an OHNativeWindow instance, without filling in any content. The OHNativeWindowBuffer can be used for a new request.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer *buffer | Pointer to an OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_NativeWindowHandleOpt()
int32_t OH_NativeWindow_NativeWindowHandleOpt(OHNativeWindow *window, int code, ...)
Description
Sets or obtains the attributes of an OHNativeWindow instance, including the width, height, and content format.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| int code | Operation code. For details, see NativeWindowOperation. |
| ... | Variable argument, which must be the same as the data type corresponding to the operation code. The number of input parameters must be the same as that of the operation code. Otherwise, undefined behavior may occur. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetBufferHandleFromNative()
BufferHandle *OH_NativeWindow_GetBufferHandleFromNative(OHNativeWindowBuffer *buffer)
Description
Obtains the pointer to a BufferHandle of an OHNativeWindowBuffer instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| OHNativeWindowBuffer *buffer | Pointer to an OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| BufferHandle | Returns the pointer to the BufferHandle instance obtained. |
OH_NativeWindow_NativeObjectReference()
int32_t OH_NativeWindow_NativeObjectReference(void *obj)
Description
Adds the reference count of a native object.
This function must be used in pair with OH_NativeWindow_NativeObjectUnreference. Otherwise, memory leak occurs.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| void *obj | Pointer to an OHNativeWindow or OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_NativeObjectUnreference()
int32_t OH_NativeWindow_NativeObjectUnreference(void *obj)
Description
Decreases the reference count of a native object by 1 and when the reference count reaches 0, destroys this object.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| void *obj | Pointer to an OHNativeWindow or OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetNativeObjectMagic()
int32_t OH_NativeWindow_GetNativeObjectMagic(void *obj)
Description
Obtains the magic ID of a native object.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 8
Parameters
| Name | Description |
|---|---|
| void *obj | Pointer to an OHNativeWindow or OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns the magic ID, which is unique for each native object. |
OH_NativeWindow_NativeWindowSetScalingMode()
int32_t OH_NativeWindow_NativeWindowSetScalingMode(OHNativeWindow *window, uint32_t sequence,OHScalingMode scalingMode)
Description
Sets a scaling mode for an OHNativeWindow.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 9
Deprecated from: 10
Substitute: OH_NativeWindow_NativeWindowSetScalingModeV2
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| uint32_t sequence | Sequence of the producer buffer. |
| OHScalingMode scalingMode | Scaling mode to set. For details, see OHScalingMode. |
Returns
| Type | Description |
|---|---|
| int32_t | 0 if the operation is successful. |
OH_NativeWindow_NativeWindowSetMetaData()
int32_t OH_NativeWindow_NativeWindowSetMetaData(OHNativeWindow *window, uint32_t sequence, int32_t size,const OHHDRMetaData *metaData)
Description
Sets metadata for an OHNativeWindow.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 9
Deprecated from: 10
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| uint32_t sequence | Sequence of the producer buffer. |
| int32_t size | Size of the OHHDRMetaData array. |
| metaData | Pointer to the OHHDRMetaData array. |
Returns
| Type | Description |
|---|---|
| int32_t | 0 if the operation is successful. |
OH_NativeWindow_NativeWindowSetMetaDataSet()
int32_t OH_NativeWindow_NativeWindowSetMetaDataSet(OHNativeWindow *window, uint32_t sequence, OHHDRMetadataKey key,int32_t size, const uint8_t *metaData)
Description
Sets a metadata set for an OHNativeWindow.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 9
Deprecated from: 10
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| uint32_t sequence | Sequence of the producer buffer. |
| OHHDRMetadataKey key | Metadata key. For details, see OHHDRMetadataKey. |
| int32_t size | Size of the uint8_t vector. |
| metaDate | Pointer to the uint8_t vector. |
Returns
| Type | Description |
|---|---|
| int32_t | 0 if the operation is successful. |
OH_NativeWindow_NativeWindowSetTunnelHandle()
int32_t OH_NativeWindow_NativeWindowSetTunnelHandle(OHNativeWindow *window, const OHExtDataHandle *handle)
Description
Sets a tunnel handle to an OHNativeWindow.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 9
Deprecated from: 10
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| const OHExtDataHandle *handle | Pointer to an OHExtDataHandle instance. |
Returns
| Type | Description |
|---|---|
| int32_t | 0 if the operation is successful. |
OH_NativeWindow_NativeWindowAttachBuffer()
int32_t OH_NativeWindow_NativeWindowAttachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer)
Description
Attaches an OHNativeWindowBuffer to an OHNativeWindow instance.
This function must be used in pair with OH_NativeWindow_NativeWindowDetachBuffer. Otherwise, memory management disorder may occur.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer *buffer | Pointer to an OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_NativeWindowDetachBuffer()
int32_t OH_NativeWindow_NativeWindowDetachBuffer(OHNativeWindow *window, OHNativeWindowBuffer *buffer)
Description
Detaches an OHNativeWindowBuffer from an OHNativeWindow instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer *buffer | Pointer to an OHNativeWindowBuffer instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetSurfaceId()
int32_t OH_NativeWindow_GetSurfaceId(OHNativeWindow *window, uint64_t *surfaceId)
Description
Obtains a surface ID through an OHNativeWindow.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| uint64_t *surfaceId | Pointer to the surface ID. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_CreateNativeWindowFromSurfaceId()
int32_t OH_NativeWindow_CreateNativeWindowFromSurfaceId(uint64_t surfaceId, OHNativeWindow **window)
Description
Creates an OHNativeWindow instance based on a surface ID.
This function must be used in pair with OH_NativeWindow_DestroyNativeWindow. Otherwise, memory leak occurs.
If OHNativeWindow instances are released concurrently, call OH_NativeWindow_NativeObjectReference and OH_NativeWindow_NativeObjectUnreference to increase and decrease the reference count of OHNativeWindow.
The surface obtained by using the surface ID must be created in the current process, but not in a different process.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| uint64_t surfaceId | Surface ID. |
| OHNativeWindow **window | Double pointer to an OHNativeWindow instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_NativeWindowSetScalingModeV2()
int32_t OH_NativeWindow_NativeWindowSetScalingModeV2(OHNativeWindow* window, OHScalingModeV2 scalingMode)
Description
Sets a rendering scaling mode for an OHNativeWindow instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow* window | Pointer to an OHNativeWindow instance. |
| OHScalingModeV2 scalingMode | Scaling mode. For details about the available options, see OHScalingModeV2. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetLastFlushedBufferV2()
int32_t OH_NativeWindow_GetLastFlushedBufferV2(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16])
Description
Obtains the OHNativeWindowBuffer that was flushed to the buffer queue last time through an OHNativeWindow instance. The difference between this function and OH_NativeWindow_GetLastFlushedBuffer lies in the matrix.
This function must be used in pair with OH_NativeWindow_NativeObjectUnreference. Otherwise, memory leak occurs.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHNativeWindowBuffer **buffer | Double pointer to an OHNativeWindowBuffer instance. |
| int *fenceFd | Pointer to a file descriptor. |
| matrix | Retrieved 4 × 4 transformation matrix. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_SetBufferHold()
void OH_NativeWindow_SetBufferHold(OHNativeWindow *window)
Description
Enables the single-frame buffering mechanism, which caches a frame buffer in advance and delays the display of the frame to smooth the frame rate fluctuation.
After this function is enabled, the system caches a frame buffer, and the frame is displayed one display cycle later. If a long frame or uneven frame interval occurs during subsequent rendering, the cached frame can be used to fill the blank to reduce image freezing.
You are advised to call this function before the rendering peak to establish buffer protection. The buffer takes effect only once. After the buffer is consumed, it automatically becomes invalid. If continuous protection is required, call this function again.
This function is applicable to scenarios that require high frame rate stability, such as games, animations, and complex UI rendering. However, it introduces a frame display delay (for example, 16.6 ms in the 60 Hz refresh rate). Therefore, this function is not recommended in high-interaction real-time scenarios.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
OH_NativeWindow_WriteToParcel()
int32_t OH_NativeWindow_WriteToParcel(OHNativeWindow *window, OHIPCParcel *parcel)
Description
Writes an OHNativeWindow instance to an OHIPCParcel instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OHIPCParcel *parcel | Pointer to an OHIPCParcel instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_ReadFromParcel()
int32_t OH_NativeWindow_ReadFromParcel(OHIPCParcel *parcel, OHNativeWindow **window)
Description
Reads an OHNativeWindow instance from an OHIPCParcel instance.
This function creates an OHNativeWindow instance. After it is used, you need to use this function in pair with OH_NativeWindow_DestroyNativeWindow. Otherwise, memory leak occurs.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHIPCParcel *parcel | Pointer to an OHIPCParcel instance. |
| OHNativeWindow **window | Double pointer to an OHNativeWindow instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_SetColorSpace()
int32_t OH_NativeWindow_SetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace colorSpace)
Description
Sets the color space for an OHNativeWindow instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OH_NativeBuffer_ColorSpace colorSpace | Pointer to the color space. For details about the available options, see OH_NativeBuffer_ColorSpace. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetColorSpace()
int32_t OH_NativeWindow_GetColorSpace(OHNativeWindow *window, OH_NativeBuffer_ColorSpace *colorSpace)
Description
Obtains the color space of an OHNativeWindow instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OH_NativeBuffer_ColorSpace *colorSpace | Pointer to the color space. For details about the available options, see OH_NativeBuffer_ColorSpace. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_SetMetadataValue()
int32_t OH_NativeWindow_SetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t *metadata)
Description
Sets a metadata value for an OHNativeWindow instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OH_NativeBuffer_MetadataKey metadataKey | Metadata type of the window. The value is obtained from OH_NativeBuffer_MetadataKey. |
| int32_t size | Size of the uint8_t vector. For details about the value range, see OH_NativeBuffer_MetadataKey. |
| metaDate | Pointer to the uint8_t vector. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_GetMetadataValue()
int32_t OH_NativeWindow_GetMetadataValue(OHNativeWindow *window, OH_NativeBuffer_MetadataKey metadataKey,int32_t *size, uint8_t **metadata)
Description
Obtains the metadata value of an OHNativeWindow instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 12
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
| OH_NativeBuffer_MetadataKey metadataKey | Metadata type of the window. The value is obtained from OH_NativeBuffer_MetadataKey. |
| int32_t *size | Size of the uint8_t vector. For details about the value range, see OH_NativeBuffer_MetadataKey. |
| metaDate | Double pointer to the uint8_t vector. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_CleanCache()
int32_t OH_NativeWindow_CleanCache(OHNativeWindow *window)
Description
Clears the OHNativeWindowBuffer cache in OHNativeWindow.
Ensure that OHNativeWindowBuffer has been successfully allocated by calling OH_NativeWindow_NativeWindowRequestBuffer.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 19
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to an OHNativeWindow instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_PreAllocBuffers()
int32_t OH_NativeWindow_PreAllocBuffers(OHNativeWindow *window, uint32_t allocBufferCnt)
Description
Request multiple OHNativeWindowBuffer blocks in advance through the OHNativeWindow object for content production.
Before calling this function, you need to set the width and height of OHNativeWindow through OH_NativeWindow_NativeWindowHandleOpt.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 22
Parameters
| Name | Description |
|---|---|
| OHNativeWindow *window | Pointer to the OHNativeWindow struct instance. |
| uint32_t allocBufferCnt | Number of buffers to be requested in advance. If the value of allocBufferCnt is greater than that of bufferQueueSize, only bufferQueueSize buffers can be requested in advance. bufferQueueSize can be obtained by calling OH_NativeWindow_NativeWindowHandleOpt. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeWindow_LockBuffer()
int32_t OH_NativeWindow_LockBuffer(OHNativeWindow* window, Region region, OHNativeWindowBuffer** buffer)
Description
Requests an OHNativeWindowBuffer through an OHNativeWindow instance for content production, and locks the OHNativeWindowBuffer.
This API must be used together with OH_NativeWindow_UnlockAndFlushBuffer.
After this API locks the OHNativeWindowBuffer, the OHNativeWindowBuffer can be locked again only after the OH_NativeWindow_UnlockAndFlushBuffer API is called to unlock the OHNativeWindowBuffer.
If this API is called to lock the OHNativeWindowBuffer repeatedly, an invalid operation error code is returned.
This API supports image rendering through memory read and write on the CPU.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 23
Parameters
| Name | Description |
|---|---|
| OHNativeWindow* window | Pointer to the OHNativeWindow struct instance. |
| Region region | Region struct, which indicates a dirty region where content is updated. |
| OHNativeWindowBuffer** buffer | Double pointer to OHNativeWindowBuffer. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if window or buffer is a null pointer. Returns NATIVE_ERROR_UNKNOWN if the surface member of window is a null pointer. |
OH_NativeWindow_UnlockAndFlushBuffer()
int32_t OH_NativeWindow_UnlockAndFlushBuffer(OHNativeWindow* window)
Description
Flushes the OHNativeWindowBuffer filled with the produced content to the buffer queue through an OHNativeWindow instance for content consumption, and locks the OHNativeWindowBuffer.
This API must be used together with OH_NativeWindow_LockBuffer.
If this API is called to unlock the OHNativeWindowBuffer repeatedly, an invalid operation error code is returned.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeWindow
Since: 23
Parameters
| Name | Description |
|---|---|
| OHNativeWindow* window | Pointer to the OHNativeWindow struct instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if window is a null pointer. Returns NATIVE_ERROR_UNKNOWN if the surface member of window is a null pointer. |