harmony 鸿蒙external_window.h

2025-06-12
浏览 (3)

external_window.h

Overview

The external_window.h file declares the functions for obtaining and using NativeWindow.

File to include: <native_window/external_window.h>

Library: libnative_window.so

Since: 8

Related module: NativeWindow

Summary

Structs

Name	Description
struct Region	Describes the rectangle (dirty region) where the content is to be updated in the local OHNativeWindow.
struct Region::Rect	Describes a rectangle.
struct OHHDRMetaData	Describes the HDR metadata.
struct OHExtDataHandle	Describes the extended data handle.

Types

Name	Description
typedef struct OHIPCParcel OHIPCParcel	Provides access to OHIPCParcel, which is an IPC parcelable object.
typedef struct NativeWindow OHNativeWindow	Provides the capability of accessing the OHNativeWindow.
typedef struct NativeWindowBuffer OHNativeWindowBuffer	Provides the capability of accessing the OHNativeWindowBuffer.
typedef struct Region Region	Defines a struct for the rectangle (dirty region) where the content is to be updated in the local OHNativeWindow.
typedef enum OHNativeErrorCode OHNativeErrorCode	Describes an enum for the error codes.
typedef enum NativeWindowOperation NativeWindowOperation	Describes an enum for the operation codes in the OH_NativeWindow_NativeWindowHandleOpt function.
typedef enum OHScalingModeV2 OHScalingModeV2	Defines an enum for the rendering scaling modes.
typedef enum OHSurfaceSource OHSurfaceSource	Defines an enum for the sources of content displayed in the local window.

Enums

Name	Description
OHNativeErrorCode { NATIVE_ERROR_OK = 0, NATIVE_ERROR_MEM_OPERATION_ERROR = 30001000, NATIVE_ERROR_INVALID_ARGUMENTS = 40001000, NATIVE_ERROR_NO_PERMISSION = 40301000, NATIVE_ERROR_NO_BUFFER = 40601000, NATIVE_ERROR_NO_CONSUMER = 41202000, NATIVE_ERROR_NOT_INIT = 41203000, NATIVE_ERROR_CONSUMER_CONNECTED = 41206000, NATIVE_ERROR_BUFFER_STATE_INVALID = 41207000, NATIVE_ERROR_BUFFER_IN_CACHE = 41208000, NATIVE_ERROR_BUFFER_QUEUE_FULL = 41209000, NATIVE_ERROR_BUFFER_NOT_IN_CACHE = 41210000,NATIVE_ERROR_CONSUMER_DISCONNECTED = 41211000,NATIVE_ERROR_CONSUMER_NO_LISTENER_REGISTERED = 41212000, NATIVE_ERROR_UNSUPPORTED = 50102000, NATIVE_ERROR_UNKNOWN = 50002000, NATIVE_ERROR_HDI_ERROR = 50007000,NATIVE_ERROR_BINDER_ERROR = 50401000,NATIVE_ERROR_EGL_STATE_UNKNOWN = 60001000, NATIVE_ERROR_EGL_API_FAILED = 60002000 }	Enumerates the error codes.
NativeWindowOperation { SET_BUFFER_GEOMETRY, GET_BUFFER_GEOMETRY, GET_FORMAT, SET_FORMAT], GET_USAGE, SET_USAGE, SET_STRIDE, GET_STRIDE, SET_SWAP_INTERVAL, GET_SWAP_INTERVAL, SET_TIMEOUT, GET_TIMEOUT, SET_COLOR_GAMUT, GET_COLOR_GAMUT, SET_TRANSFORM, GET_TRANSFORM, SET_UI_TIMESTAMP, GET_BUFFERQUEUE_SIZE, SET_SOURCE_TYPE, GET_SOURCE_TYPE, SET_APP_FRAMEWORK_TYPE, GET_APP_FRAMEWORK_TYPE, SET_HDR_WHITE_POINT_BRIGHTNESS, SET_SDR_WHITE_POINT_BRIGHTNESS, SET_DESIRED_PRESENT_TIMESTAMP = 24 }	Enumerates the operation codes in the OH_NativeWindow_NativeWindowHandleOpt function.
OHScalingMode { OH_SCALING_MODE_FREEZE = 0, OH_SCALING_MODE_SCALE_TO_WINDOW, OH_SCALING_MODE_SCALE_CROP, OH_SCALING_MODE_NO_SCALE_CROP }	Enumerates the scaling modes.
OHScalingModeV2 { OH_SCALING_MODE_FREEZE_V2 = 0, OH_SCALING_MODE_SCALE_TO_WINDOW_V2, OH_SCALING_MODE_SCALE_CROP_V2, OH_SCALING_MODE_NO_SCALE_CROP_V2, OH_SCALING_MODE_SCALE_FIT_V2 }	Enumerates the rendering scaling modes.
OHHDRMetadataKey { OH_METAKEY_RED_PRIMARY_X = 0, OH_METAKEY_RED_PRIMARY_Y = 1, OH_METAKEY_GREEN_PRIMARY_X = 2, OH_METAKEY_GREEN_PRIMARY_Y = 3, OH_METAKEY_BLUE_PRIMARY_X = 4, OH_METAKEY_BLUE_PRIMARY_Y = 5, OH_METAKEY_WHITE_PRIMARY_X = 6, OH_METAKEY_WHITE_PRIMARY_Y = 7, OH_METAKEY_MAX_LUMINANCE = 8, OH_METAKEY_MIN_LUMINANCE = 9, OH_METAKEY_MAX_CONTENT_LIGHT_LEVEL = 10, OH_METAKEY_MAX_FRAME_AVERAGE_LIGHT_LEVEL = 11, OH_METAKEY_HDR10_PLUS = 12, OH_METAKEY_HDR_VIVID = 13 }	Enumerates the HDR metadata keys.
OHSurfaceSource { OH_SURFACE_SOURCE_DEFAULT = 0, OH_SURFACE_SOURCE_UI, OH_SURFACE_SOURCE_GAME, OH_SURFACE_SOURCE_CAMERA,OH_SURFACE_SOURCE_VIDEO }	Enumerates 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. If this function is unavailable, you can create an OHNativeWindow instance by calling OH_NativeImage_AcquireNativeWindow or through the XComponent.
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.
OHNativeWindowBuffer * OH_NativeWindow_CreateNativeWindowBufferFromSurfaceBuffer (void *pSurfaceBuffer)	Creates an OHNativeWindowBuffer instance. A new OHNativeWindowBuffer instance is created each time this function is called. This API is deprecated since API version 12 and replaced by OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer.
OHNativeWindowBuffer * OH_NativeWindow_CreateNativeWindowBufferFromNativeBuffer (OH_NativeBuffer *nativeBuffer)	Creates an OHNativeWindowBuffer instance. A new OHNativeWindowBuffer instance is created each time this function is called.
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.
int32_t OH_NativeWindow_NativeWindowRequestBuffer (OHNativeWindow window, OHNativeWindowBuffer buffer, int fenceFd)	Requests an OHNativeWindowBuffer through an OHNativeWindow instance for content production.
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.
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.
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.
BufferHandle * OH_NativeWindow_GetBufferHandleFromNative (OHNativeWindowBuffer *buffer)	Obtains the pointer to a BufferHandle of an OHNativeWindowBuffer instance.
int32_t OH_NativeWindow_NativeObjectReference (void *obj)	Adds the reference count of a native object.
int32_t OH_NativeWindow_NativeObjectUnreference (void *obj)	Decreases the reference count of a native object and when the reference count reaches 0, destroys this object.
int32_t OH_NativeWindow_GetNativeObjectMagic (void *obj)	Obtains the magic ID of a native object.
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.
int32_t OH_NativeWindow_NativeWindowDetachBuffer (OHNativeWindow window, OHNativeWindowBuffer buffer)	Detaches an OHNativeWindowBuffer from an OHNativeWindow instance.
int32_t OH_NativeWindow_GetSurfaceId (OHNativeWindow window, uint64_t surfaceId)	Obtains a surface ID through an OHNativeWindow.
int32_t OH_NativeWindow_CreateNativeWindowFromSurfaceId (uint64_t surfaceId, OHNativeWindow **window)	Creates an OHNativeWindow instance based on a surface ID.
int32_t OH_NativeWindow_NativeWindowSetScalingModeV2 (OHNativeWindow *window, OHScalingModeV2 scalingMode)	Sets a rendering scaling mode for an OHNativeWindow instance.
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.
void OH_NativeWindow_SetBufferHold (OHNativeWindow *window)	Buffers a frame in advance and holds it for the interval of a frame to offset the possible loss of subsequent oversized frames.
int32_t OH_NativeWindow_WriteToParcel (OHNativeWindow window, OHIPCParcel parcel)	Writes an OHNativeWindow instance to an OHIPCParcel instance.
int32_t OH_NativeWindow_ReadFromParcel (OHIPCParcel parcel, OHNativeWindow *window)	Reads an OHNativeWindow instance from an OHIPCParcel instance.
int32_t OH_NativeWindow_SetColorSpace (OHNativeWindow *window, OH_NativeBuffer_ColorSpace colorSpace)	Sets the color space for an OHNativeWindow instance.
int32_t OH_NativeWindow_GetColorSpace (OHNativeWindow window, OH_NativeBuffer_ColorSpace colorSpace)	Obtains the color space of an OHNativeWindow instance.
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.
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.