目录

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

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

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

[h2]Enums

Name Description

OHNativeErrorCode {

NATIVE_ERROR_OK = 0, 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.

[h2]Functions

Name Description
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_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 fenFd. 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.