harmony 鸿蒙native_image.h

2025-06-12
浏览 (4)

native_image.h

Overview

The native_image.h file declares the functions for obtaining and using NativeImage.

Library: libnative_image.so

Since: 9

Related module: OH_NativeImage

Summary

Structs

Name	Description
OH_OnFrameAvailableListener	Describes an OH_NativeImage listener, which is registered through OH_NativeImage_SetOnFrameAvailableListener. The listener triggers a callback when a frame is available.

Types

Name	Description
typedef struct OH_NativeImage OH_NativeImage	Provides the declaration of an OH_NativeImage struct.
typedef struct NativeWindow OHNativeWindow	Provides the capability of accessing the NativeWindow.
typedef struct NativeWindowBuffer OHNativeWindowBuffer	Provides the declaration of a NativeWindowBuffer struct.
typedef void(* OH_OnFrameAvailable) (void *context)	Defines the callback function triggered when a frame is available.
typedef struct OH_OnFrameAvailableListener OH_OnFrameAvailableListener	Defines an OH_NativeImage listener, which is registered through {\@link OH_NativeImage_SetOnFrameAvailableListener}. The listener triggers a callback when a frame is available.
typedef enum OHNativeErrorCode OHNativeErrorCode	Defines an enum for the error codes.

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.

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.

Functions

Name	Description
int32_t OH_NativeImage_SetDropBufferMode (OH_NativeImage *image, bool isOpen)	Sets the frame-dropping mode for rendering of an OH_NativeImage instance. In frame-dropping mode, most buffers produced by the producer are discarded, and only the latest buffer is rendered promptly. This mode does not guarantee high frame rates. It is recommended that you can call this function immediately after OH_NativeImage_Create. This function takes effect only when it is used together with OH_NativeImage_UpdateSurfaceImage. This function is not thread-safe.
OH_NativeImage * OH_NativeImage_Create (uint32_t textureId, uint32_t textureTarget)	Creates an OH_NativeImage instance to be associated with the OpenGL ES texture ID and target. This function must be used in pair with OH_NativeImage_Destroy. Otherwise, memory leak occurs. This function is not thread-safe.
OHNativeWindow * OH_NativeImage_AcquireNativeWindow (OH_NativeImage *image)	Obtains an OHNativeWindow instance associated with an OH_NativeImage instance. This function is not thread-safe. When OH_NativeImage is being destructed, the corresponding OHNativeWindow instance is released. If the OHNativeWindow pointer is obtained by using this function, set the pointer to null when releasing the OH_NativeImage instance, so as to prevent subsequent wild pointers.
int32_t OH_NativeImage_AttachContext (OH_NativeImage *image, uint32_t textureId)	Attaches an OH_NativeImage instance to the current OpenGL ES context. The OpenGL ES texture will be bound to an GL_TEXTURE_EXTERNAL_OES instance and updated through the OH_NativeImage instance. This function is not thread-safe.
int32_t OH_NativeImage_DetachContext (OH_NativeImage *image)	Detaches an OH_NativeImage instance from the current OpenGL ES context. This function is not thread-safe.
int32_t OH_NativeImage_UpdateSurfaceImage (OH_NativeImage *image)	Updates the OpenGL ES texture associated with the latest frame through an OH_NativeImage instance. This function must be called in a thread of the OpenGL ES context. This function must be called after the OH_OnFrameAvailableListener callback is triggered. This function is not thread-safe.
int64_t OH_NativeImage_GetTimestamp (OH_NativeImage *image)	Obtains the timestamp of the texture image that recently called the OH_NativeImage_UpdateSurfaceImage function. This function is not thread-safe.
int32_t OH_NativeImage_GetTransformMatrix (OH_NativeImage *image, float matrix[16])	Obtains the transformation matrix of the texture image that recently called the OH_NativeImage_UpdateSurfaceImage function.
int32_t OH_NativeImage_GetSurfaceId (OH_NativeImage image, uint64_t surfaceId)	Obtains the surface ID of an OH_NativeImage instance. This function is not thread-safe.
int32_t OH_NativeImage_SetOnFrameAvailableListener (OH_NativeImage *image, OH_OnFrameAvailableListener listener)	Registers a listener to listen for frame availability events. Do not call other functions of this module in the callback. This function is not thread-safe.
int32_t OH_NativeImage_UnsetOnFrameAvailableListener (OH_NativeImage *image)	Deregisters the listener used to listen for frame availability events. This function is not thread-safe.
void OH_NativeImage_Destroy (OH_NativeImage **image)	Destroys an OH_NativeImage instance created by calling OH_NativeImage_Create. After the instance is destroyed, the pointer to the OH_NativeImage instance is assigned NULL. This function is not thread-safe.
int32_t OH_NativeImage_GetTransformMatrixV2 (OH_NativeImage *image, float matrix[16])	Obtains, based on the rotation angle set by the producer, the transform matrix of the texture image that recently called the OH_NativeImage_UpdateSurfaceImage function. The matrix is updated only after OH_NativeImage_UpdateSurfaceImage is called. This function is not thread-safe.
int32_t OH_NativeImage_GetBufferMatrix (OH_NativeImage *image, float matrix[16])	Obtains the transformation matrix calculated based on the rotation angle set by the producer and the actual valid content area of the buffer.
int32_t OH_NativeImage_AcquireNativeWindowBuffer (OH_NativeImage image, OHNativeWindowBuffer nativeWindowBuffer, int fenceFd)	Obtains an OHNativeWindowBuffer instance through an OH_NativeImage instance on the consumer side. This function cannot be used together with OH_NativeImage_UpdateSurfaceImage. This function creates an OHNativeWindowBuffer. When using the OHNativeWindowBuffer, call OH_NativeWindow_NativeObjectReference to increase its reference count by one. When finishing using the OHNativeWindowBuffer, call OH_NativeWindow_NativeObjectUnreference to decrease the reference count by one. This function must be used in pair with OH_NativeImage_ReleaseNativeWindowBuffer. Otherwise, memory leak occurs. When fenceFd is used up, you must close it. This function is not thread-safe.
int32_t OH_NativeImage_ReleaseNativeWindowBuffer (OH_NativeImage image, OHNativeWindowBuffer nativeWindowBuffer, int fenceFd)	Releases an OHNativeWindowBuffer instance through an OH_NativeImage instance. The system will close fenceFd. You do not need to close it. This function is not thread-safe.
OH_NativeImage * OH_ConsumerSurface_Create ()	Creates an OH_NativeImage instance as the consumer of the surface. This function is used only for memory cycling of the surface consumer. Memory rendering is not proactively performed in the created OH_NativeImage instance. This function cannot be used together with OH_NativeImage_UpdateSurfaceImage. This function must be used in pair with OH_NativeImage_AcquireNativeWindowBuffer and OH_NativeImage_ReleaseNativeWindowBuffer. This function must be used in pair with OH_NativeImage_Destroy. Otherwise, memory leak occurs. This function is not thread-safe.
int32_t OH_ConsumerSurface_SetDefaultUsage (OH_NativeImage *image, uint64_t usage)	Sets the default read/write mode. This function is not thread-safe.
int32_t OH_ConsumerSurface_SetDefaultSize (OH_NativeImage *image, int32_t width, int32_t height)	Sets the default size of a geometric shape. This function is not thread-safe.