目录

external_window.h

Overview

This file declares the functions for obtaining and using NativeWindow.

File to include: <native_window/external_window.h>

Library: libnative_window.so

System capability: SystemCapability.Graphic.Graphic2D.NativeWindow

Since: 8

Related module: NativeWindow

Summary

[h2]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.

[h2]Enums

Name typedef Keyword Description
NativeWindowOperation NativeWindowOperation Defines an enum for the operation codes in the OH_NativeWindow_NativeWindowHandleOpt function.
OHScalingMode OHScalingMode Scaling mode.
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.

[h2]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. Each call produces a new OHNativeWindowBuffer instance.

This interface requires coordination with OH_NativeWindow_DestroyNativeWindowBuffer; otherwise, a memory leak will occur.

This interface is non-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)

Increments the reference count of a NativeObject.

This interface requires coordination with OH_NativeWindow_NativeObjectUnreference; otherwise, a memory leak will occur.

This interface is non-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 the corresponding OHNativeWindow by surfaceId.

This interface requires coordination with OH_NativeWindow_DestroyNativeWindow; otherwise, a memory leak will occur.

If OHNativeWindow is released concurrently, use OH_NativeWindow_NativeObjectReference and OH_NativeWindow_NativeObjectUnreference to increment and decrement the reference count of OHNativeWindow.

The surface obtained by surfaceId must be created in the current process; it cannot be obtained across processes.

This interface is non-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 from OHNativeWindow the OHNativeWindowBuffer last returned to the buffer queue. The difference from OH_NativeWindow_GetLastFlushedBuffer lies in the matrix.

This interface requires coordination with OH_NativeWindow_NativeObjectUnreference; otherwise, a memory leak will occur.

This interface is non-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 unlocks 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.
int32_t OH_NativeWindow_Set3DMetadataValue(OHNativeWindow *window, OH_NativeBuffer_3D_MetadataKey metadataKey, int32_t size, uint8_t *metadata)

Sets the 3D metadata property value for OHNativeWindow.

This interface is non-thread-safe.
int32_t OH_NativeWindow_Get3DMetadataValue(OHNativeWindow *window, OH_NativeBuffer_3D_MetadataKey metadataKey, int32_t *size, uint8_t **metadata)

Obtains the 3D metadata property value of OHNativeWindow.

This interface is non-thread-safe.

Enum Description

[h2]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 Set the timeout waiting time for the local window to request buffers. The default value is 3000 milliseconds when not manually set. The variable parameter in the function is [input] int32_t timeout, in milliseconds.
GET_TIMEOUT Get the timeout waiting time for the local window to request buffers. The default value is 3000 milliseconds when not manually set. The variable parameter in the function is [output] int32_t *timeout, in milliseconds.
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

Get the buffer queue size. The variable parameter in the function is [output] int32_t *size.

Since Version: 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

[h2]OHScalingMode

enum OHScalingMode

Description

Scaling mode.

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.

[h2]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 the Emulator.

[h2]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.

[h2]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

[h2]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 A pointer to the producer ProducerSurface, of type sptr<OHOS::Surface>.

Returns

Type Description
OHNativeWindow* Returns the pointer to the OHNativeWindow instance created.

[h2]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.

[h2]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 A pointer to the producer buffer, of type sptr<OHOS::SurfaceBuffer>.

Returns

Type Description
OHNativeWindowBuffer* Returns the pointer to the OHNativeWindowBuffer instance created.

[h2]OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer()

OHNativeWindowBuffer* OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer(OH_NativeBuffer* nativeBuffer)

Description

Creates an OHNativeWindowBuffer instance. Each call produces a new OHNativeWindowBuffer instance.

This interface requires coordination with OH_NativeWindow_DestroyNativeWindowBuffer; otherwise, a memory leak will occur.

This interface is non-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.

[h2]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.

[h2]OH_NativeWindow_NativeWindowRequestBuffer()

int32_t OH_NativeWindow_NativeWindowRequestBuffer(OHNativeWindow *window,OHNativeWindowBuffer **buffer, int *fenceFd)

Description

Applies for an OHNativeWindowBuffer through the OHNativeWindow object, used for content production.

When calling this interface, you need to set the width and height of the OHNativeWindow through SET_BUFFER_GEOMETRY.

If the width and height are not set, the default width and height set by the consumer will be used.

This interface requires coordination with OH_NativeWindow_NativeWindowFlushBuffer; otherwise, memory will be exhausted.

When fenceFd is no longer used, the user needs to close it.

This interface is non-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.

[h2]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

A Region struct that represents a dirty region whose content has been updated.

The maximum number of Region.rectNumber is 1000. When rectNumber ≤ 0 or rectNumber > 1000, the entire buffer is used as the dirty region.

The coordinate origin of Region.rect is the lower-left corner of the buffer.

Returns

Type Description
int32_t Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise.

[h2]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 Indicates the 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.

[h2]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.

[h2]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.

[h2]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 a pointer to the BufferHandle structure instance.

[h2]OH_NativeWindow_NativeObjectReference()

int32_t OH_NativeWindow_NativeObjectReference(void *obj)

Description

Increments the reference count of a NativeObject.

This interface requires coordination with OH_NativeWindow_NativeObjectUnreference; otherwise there will be a memory leak.

This interface is a non-thread-safe type interface.

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.

[h2]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.

[h2]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.

[h2]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 Returns 0 if the operation is successful; for other return values, see OHNativeErrorCode.

[h2]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. The maximum supported value is 3000. If the value exceeds this limit, NATIVE_ERROR_INVALID_ARGUMENTS is returned.
metaData Pointer to the OHHDRMetaData array.

Returns

Type Description
int32_t Returns 0 if the operation is successful; for other return values, see OHNativeErrorCode.

[h2]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. The maximum supported value is 3000. If it exceeds this value, NATIVE_ERROR_INVALID_ARGUMENTS is returned.
metaData Pointer to the uint8_t vector.

Returns

Type Description
int32_t Returns 0 if the operation is successful; for other return values, see OHNativeErrorCode.

[h2]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 The return value 0 indicates that the execution succeeds. For other return values, see OHNativeErrorCode.

[h2]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.

[h2]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.

[h2]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.

[h2]OH_NativeWindow_CreateNativeWindowFromSurfaceId()

int32_t OH_NativeWindow_CreateNativeWindowFromSurfaceId(uint64_t surfaceId, OHNativeWindow **window)

Description

Creates the corresponding OHNativeWindow by surfaceId.

This interface requires coordination with OH_NativeWindow_DestroyNativeWindow; otherwise, a memory leak will occur.

If OHNativeWindow is released concurrently, you need to increment and decrement the reference count of OHNativeWindow through OH_NativeWindow_NativeObjectReference and OH_NativeWindow_NativeObjectUnreference.

The surface obtained by surfaceId must be created in the current process and cannot be obtained across processes.

This interface is non-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.

[h2]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.

[h2]OH_NativeWindow_GetLastFlushedBufferV2()

int32_t OH_NativeWindow_GetLastFlushedBufferV2(OHNativeWindow *window, OHNativeWindowBuffer **buffer,int *fenceFd, float matrix[16])

Description

Obtains the OHNativeWindowBuffer last returned to the buffer queue from OHNativeWindow. The difference from OH_NativeWindow_GetLastFlushedBuffer lies in the matrix.

This interface requires coordination with the OH_NativeWindow_NativeObjectUnreference interface; otherwise there will be a memory leak.

This interface is a non-thread-safe type interface.

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 Represents the 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.

[h2]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.

[h2]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.

[h2]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.

[h2]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.

[h2]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.

[h2]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 OHNativeWindow. Its 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.
metadata Pointer to a uint8_t vector.

Returns

Type Description
int32_t Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise.

[h2]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.
metadata Double pointer to a uint8_t vector.

Returns

Type Description
int32_t Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise.

[h2]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.

[h2]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.

[h2]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

A Region struct that represents a dirty region whose content has been updated.

The maximum number of Region.rectNumber is 1000. When rectNumber is less than or equal to 0 or greater than 1000, the entire buffer is used as the dirty region.

Region.rect uses the lower-left corner of the buffer as the coordinate origin.
OHNativeWindowBuffer** buffer Double pointer to OHNativeWindowBuffer.

Returns

Type Description
int32_t

Returns NATIVE_ERROR_OK when execution succeeds.

Returns NATIVE_ERROR_INVALID_ARGUMENTS when window or buffer is a null pointer.

Returns NATIVE_ERROR_UNKNOWN when the surface member of window is a null pointer.

For other return values, see OHNativeErrorCode.

[h2]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 unlocks 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 when the execution is successful.

Returns NATIVE_ERROR_INVALID_ARGUMENTS when window is a null pointer.

Returns NATIVE_ERROR_UNKNOWN when the surface member of window is a null pointer.

For other return values, see OHNativeErrorCode.

[h2]OH_NativeWindow_Set3DMetadataValue()

int32_t OH_NativeWindow_Set3DMetadataValue(OHNativeWindow *window, OH_NativeBuffer_3D_MetadataKey metadataKey, int32_t size, uint8_t *metadata)

Description

Sets the 3D metadata property value for OHNativeWindow.

This interface is a non-thread-safe type interface.

System capability: SystemCapability.Graphic.Graphic2D.NativeWindow

Since: 26.0.0

Parameters

Name Description
OHNativeWindow *window A pointer to a structure instance of OHNativeWindow.
OH_NativeBuffer_3D_MetadataKey metadataKey The 3D metadata type of OHNativeWindow.
int32_t size The size of the uint8_t vector.
uint8_t *metadata A pointer to the uint8_t vector.

Return value

Type Description
int32_t

Returns NATIVE_ERROR_OK if the operation is successful.

Returns NATIVE_ERROR_INVALID_ARGUMENTS if window or metadata is a null pointer.

Returns NATIVE_ERROR_UNKNOWN if setting the 3D metadata fails.

Returns NATIVE_ERROR_UNSUPPORTED if an unsupported metadataKey is passed in.

For other return values, see OHNativeErrorCode.

[h2]OH_NativeWindow_Get3DMetadataValue()

int32_t OH_NativeWindow_Get3DMetadataValue(OHNativeWindow *window, OH_NativeBuffer_3D_MetadataKey metadataKey, int32_t *size, uint8_t **metadata)

Description

Obtains the 3D metadata property value of an OHNativeWindow.

This interface is a non-thread-safe type interface.

System capability: SystemCapability.Graphic.Graphic2D.NativeWindow

Since: 26.0.0

Parameters

Name Description
OHNativeWindow *window A pointer to a struct instance of OHNativeWindow.
OH_NativeBuffer_3D_MetadataKey metadataKey The 3D metadata type of the OHNativeWindow.
int32_t *size The size of the uint8_t vector.
uint8_t **metadata A secondary pointer to the uint8_t vector, used as an output parameter.

Return value

Type Description
int32_t

Returns NATIVE_ERROR_OK when the execution is successful.

Returns NATIVE_ERROR_INVALID_ARGUMENTS when window, metadata, or size is a null pointer.

Returns NATIVE_ERROR_UNKNOWN when copying or allocating memory fails, or obtaining the 3D metadata fails.

Returns NATIVE_ERROR_UNSUPPORTED when an unsupported metadataKey is passed in.

For other return values, see OHNativeErrorCode.