native_image.h
Overview
This file declares the functions for obtaining and using NativeImage.
Sample: NDKNativeImage
File to include: <native_image/native_image.h>
Library: libnative_image.so
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Related module: OH_NativeImage
Summary
Structs
| Name | typedef Keyword | Description |
|---|---|---|
| OH_OnFrameAvailableListener | OH_OnFrameAvailableListener | Defines an OH_NativeImage listener, which is registered through OH_NativeImage_SetOnFrameAvailableListener. The listener triggers a callback when a frame is available. |
| OH_NativeImage | OH_NativeImage | Provides the declaration of an OH_NativeImage struct. |
| NativeWindow | OHNativeWindow | Provides the capability of accessing the NativeWindow. |
| NativeWindowBuffer | OHNativeWindowBuffer | Provides the declaration of a NativeWindowBuffer struct. |
Functions
| Name | typedef Keyword | Description |
|---|---|---|
| typedef void (*OH_OnFrameAvailable)(void *context) | OH_OnFrameAvailable | Callback function triggered when a frame is available. |
| OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget) | - | Creates an OH_NativeImage instance to be associated with the specified 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 received. 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. This function returns a transformation matrix that is determined by the buffer's rotation angle and actual valid content area during the consumption of the buffer by OH_NativeImage, specifically when calling OH_NativeImage_UpdateSurfaceImage or OH_NativeImage_AcquireNativeWindowBuffer. This function is not thread-safe. |
| int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd) | - | Obtain an OHNativeWindowBuffer instance through the OH_NativeImage instance on the consumer side. This function cannot be used in 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) | - | Release the OHNativeWindowBuffer instance through the 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(void) | - | 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 in together with OH_NativeImage_UpdateSurfaceImage. This function must be used in together 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. |
| 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_CreateWithSingleBufferMode(uint32_t textureId, uint32_t textureTarget, bool singleBufferMode) | - | Creates an OH_NativeImage instance with the texture ID. The instance is associated with the texture ID and texture target of OpenGL ES, and determines whether to set the single-buffer mode. This function must be used in pair with OH_NativeImage_Destroy. Otherwise, memory leak occurs. This function is not thread-safe. |
| OH_NativeImage* OH_ConsumerSurface_CreateWithSingleBufferMode(bool singleBufferMode) | - | Creates an OH_NativeImage instance as the consumer of the surface and determines whether to set the single-buffer mode. This function is used only for memory rotation of the surface consumer. The created OH_NativeImage does not perform memory rendering. This function cannot be used in together with OH_NativeImage_UpdateSurfaceImage. This function must be used in pair with OH_NativeImage_Destroy. Otherwise, memory leak occurs. This function is not thread-safe. |
| int32_t OH_NativeImage_ReleaseTextImage(OH_NativeImage* image) | - | Unbinds SurfaceBuffer from the texture and restores the texture to the unused state. In single-buffer mode, this function is called to release the texture. Otherwise, the producer cannot request a buffer next time. This function is not thread-safe. |
| int32_t OH_NativeImage_GetColorSpace(OH_NativeImage* image, OH_NativeBuffer_ColorSpace* colorSpace) | - | Obtains the color space of the texture image that is most recently passed to OH_NativeImage_UpdateSurfaceImage. This function is not thread-safe. |
| int32_t OH_NativeImage_AcquireLatestNativeWindowBuffer(OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd) | - | Obtains the OHNativeWindowBuffer recently produced by the producer through the OH_NativeImage of the consumer, and discards other buffers. The consumer can receive the callback of all available buffers (including discarded buffers) through the callback registered by OH_OnFrameAvailableListener. This function cannot be used in together with OH_NativeImage_UpdateSurfaceImage. This function is not thread-safe. |
| int32_t OH_NativeImage_IsReleased(OH_NativeImage* image, bool* isReleased) | - | Queries whether the texture associated with OH_NativeImage has been released. This function is not thread-safe. |
| int32_t OH_NativeImage_Release(OH_NativeImage* image) | - | Clears OHNativeWindowBuffer of all OHNativeWindow and detaches OH_NativeImage from the OpenGL ES context. This function is not thread-safe. |
Function Description
OH_OnFrameAvailable()
typedef void (*OH_OnFrameAvailable)(void *context)
Description
Callback function triggered when a frame is available.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 11
Parameters
| Name | Description |
|---|---|
| void *context | User-defined context information, which is returned when the callback is triggered. |
OH_NativeImage_Create()
OH_NativeImage* OH_NativeImage_Create(uint32_t textureId, uint32_t textureTarget)
Description
Creates an OH_NativeImage instance to be associated with the specified 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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| uint32_t textureId | OpenGL ES texture ID. |
| uint32_t textureTarget | OpenGL ES texture target. The value can be GL_TEXTURE_2D or GL_TEXTURE_EXTERNAL_OES. For details, see How do I choose between the texture types GL_TEXTURE_2D and GL_TEXTURE_EXTERNAL_OES?. |
Returns
| Type | Description |
|---|---|
| OH_NativeImage* | Returns a pointer to the OH_NativeImage instance if the creation is successful; returns NULL otherwise. |
OH_NativeImage_AcquireNativeWindow()
OHNativeWindow* OH_NativeImage_AcquireNativeWindow(OH_NativeImage* image)
Description
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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| OHNativeWindow* | Returns a pointer to the OHNativeWindow instance if the operation is successful; returns NULL otherwise. |
OH_NativeImage_AttachContext()
int32_t OH_NativeImage_AttachContext(OH_NativeImage* image, uint32_t textureId)
Description
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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| uint32_t textureId | ID of the OpenGL ES texture to which the OH_NativeImage instance is to be attached. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeImage_DetachContext()
int32_t OH_NativeImage_DetachContext(OH_NativeImage* image)
Description
Detaches an OH_NativeImage instance from the current OpenGL ES context.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeImage_UpdateSurfaceImage()
int32_t OH_NativeImage_UpdateSurfaceImage(OH_NativeImage* image)
Description
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 received.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeImage_GetTimestamp()
int64_t OH_NativeImage_GetTimestamp(OH_NativeImage* image)
Description
Obtains the timestamp of the texture image that recently called the OH_NativeImage_UpdateSurfaceImage function.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| int64_t | Returns the timestamp of the texture image. |
OH_NativeImage_GetTransformMatrix()
int32_t OH_NativeImage_GetTransformMatrix(OH_NativeImage* image, float matrix[16])
Description
Obtains the transformation matrix of the texture image that recently called the OH_NativeImage_UpdateSurfaceImage function.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Deprecated from: 12
Substitute: OH_NativeImage_GetTransformMatrixV2
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| matrix | Buffer used to store the 4 × 4 transformation matrix obtained. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeImage_GetSurfaceId()
int32_t OH_NativeImage_GetSurfaceId(OH_NativeImage* image, uint64_t* surfaceId)
Description
Obtains the surface ID of an OH_NativeImage instance.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage 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_NativeImage_SetOnFrameAvailableListener()
int32_t OH_NativeImage_SetOnFrameAvailableListener(OH_NativeImage* image, OH_OnFrameAvailableListener listener)
Description
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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| OH_OnFrameAvailableListener listener | Listener to register. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeImage_UnsetOnFrameAvailableListener()
int32_t OH_NativeImage_UnsetOnFrameAvailableListener(OH_NativeImage* image)
Description
Deregisters the listener used to listen for frame availability events.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 11
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns 0 if the operation is successful; returns an error code defined in OHNativeErrorCode otherwise. |
OH_NativeImage_Destroy()
void OH_NativeImage_Destroy(OH_NativeImage** image)
Description
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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 9
Parameters
| Name | Description |
|---|---|
| OH_NativeImage** image | Pointer to an OH_NativeImage instance. |
OH_NativeImage_GetTransformMatrixV2()
int32_t OH_NativeImage_GetTransformMatrixV2(OH_NativeImage* image, float matrix[16])
Description
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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 12
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| matrix | Buffer used to store the 4 × 4 transformation matrix obtained. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS (error code: 40001000) if image is a null pointer. Returns NATIVE_ERROR_UNKNOWN (error code: 50002000), indicating an unknown error. In this case, check the logs. |
OH_NativeImage_GetBufferMatrix()
int32_t OH_NativeImage_GetBufferMatrix(OH_NativeImage* image, float matrix[16])
Description
Obtains the transformation matrix calculated based on the rotation angle set by the producer and the actual valid content area of the buffer.
This function returns a transformation matrix that is determined by the buffer's rotation angle and actual valid content area during the consumption of the buffer by OH_NativeImage, specifically when calling OH_NativeImage_UpdateSurfaceImage or OH_NativeImage_AcquireNativeWindowBuffer.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 15
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| matrix | Buffer used to store the 4 × 4 transformation matrix obtained. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS (error code: 40001000) if image is a null pointer. Returns NATIVE_ERROR_MEM_OPERATION_ERROR (error code: 30001000) if the transformation matrix fails to be obtained due to a memory manipulation error. |
OH_NativeImage_AcquireNativeWindowBuffer()
int32_t OH_NativeImage_AcquireNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd)
Description
Obtain an OHNativeWindowBuffer instance through the OH_NativeImage instance on the consumer side. This function cannot be used in 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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 12
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| OHNativeWindowBuffer** nativeWindowBuffer | Double pointer to the OHNativeWindowBuffer instance obtained. |
| int* fenceFd | Pointer to the file descriptor handle. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image, nativeWindowBuffer, or fenceFd is a null pointer. Returns NATIVE_ERROR_NO_BUFFER if no buffer is available for consumption. |
OH_NativeImage_ReleaseNativeWindowBuffer()
int32_t OH_NativeImage_ReleaseNativeWindowBuffer(OH_NativeImage* image,OHNativeWindowBuffer* nativeWindowBuffer, int fenceFd)
Description
Release the OHNativeWindowBuffer instance through the OH_NativeImage instance.
The system will close fenceFd. You do not need to close it.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 12
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| OHNativeWindowBuffer* nativeWindowBuffer | Pointer to an OHNativeWindowBuffer instance. |
| int fenceFd | File descriptor handle, which is used for concurrent synchronization control. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image or nativeWindowBuffer is a null pointer. Returns NATIVE_ERROR_BUFFER_STATE_INVALID if the status of nativeWindowBuffer is invalid. Returns NATIVE_ERROR_BUFFER_NOT_IN_CACHE if nativeWindowBuffer is not in the cache. |
OH_ConsumerSurface_Create()
OH_NativeImage* OH_ConsumerSurface_Create(void)
Description
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 in together with OH_NativeImage_UpdateSurfaceImage.
This function must be used in together 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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 12
Returns
| Type | Description |
|---|---|
| OH_NativeImage* | Returns a pointer to the OH_NativeImage instance if the operation is successful; returns NULL otherwise. |
OH_ConsumerSurface_SetDefaultUsage()
int32_t OH_ConsumerSurface_SetDefaultUsage(OH_NativeImage* image, uint64_t usage)
Description
Sets the default read/write mode.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 13
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| uint64_t usage | Read/write mode. For details about the enumerated values, see OH_NativeBuffer_Usage. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image is a null pointer. |
OH_ConsumerSurface_SetDefaultSize()
int32_t OH_ConsumerSurface_SetDefaultSize(OH_NativeImage* image, int32_t width, int32_t height)
Description
Sets the default size of a geometric shape.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 13
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| int32_t width | Width of the geometric shape. The value is greater than 0, in pixels. |
| int32_t height | Height of the geometric shape. The value is greater than 0, in pixels. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image is a null pointer or width or height is less than 0. |
OH_NativeImage_SetDropBufferMode()
int32_t OH_NativeImage_SetDropBufferMode(OH_NativeImage* image, bool isOpen)
Description
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.
The number of listener callbacks set by OH_NativeImage_SetOnFrameAvailableListener does not decrease because the frame loss mode is set.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 17
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| bool isOpen | Whether to set the frame-dropping mode. The value true means to set the frame-dropping mode, and false means the opposite. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image is a null pointer. |
OH_NativeImage_CreateWithSingleBufferMode()
OH_NativeImage* OH_NativeImage_CreateWithSingleBufferMode(uint32_t textureId, uint32_t textureTarget, bool singleBufferMode)
Description
Creates an OH_NativeImage instance with the texture ID. The instance is associated with the texture ID and texture target of OpenGL ES, and determines whether to set the single-buffer mode.
This function must be used in pair with OH_NativeImage_Destroy. Otherwise, memory leak occurs.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 22
Parameters
| Name | Description |
|---|---|
| uint32_t textureId | OpenGL ES texture ID. |
| uint32_t textureTarget | OpenGL ES texture target. For details, see How do I choose between the texture types GL_TEXTURE_2D and GL_TEXTURE_EXTERNAL_OES?. |
| bool singleBufferMode | Whether to set the single-buffer mode. true: yes; false: no. |
Returns
| Type | Description |
|---|---|
| OH_NativeImage* | Returns a pointer to the OH_NativeImage instance if the creation is successful; returns NULL otherwise. |
OH_ConsumerSurface_CreateWithSingleBufferMode()
OH_NativeImage* OH_ConsumerSurface_CreateWithSingleBufferMode(bool singleBufferMode)
Description
Creates an OH_NativeImage instance as the consumer of the surface and determines whether to set the single-buffer mode.
This function is used only for memory rotation of the surface consumer. The created OH_NativeImage does not perform memory rendering.
This function cannot be used in together with OH_NativeImage_UpdateSurfaceImage.
This function must be used in pair with OH_NativeImage_Destroy. Otherwise, memory leak occurs.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 22
Parameters
| Name | Description |
|---|---|
| bool singleBufferMode | Whether to set the single-buffer mode. true: yes; false: no. |
Returns
| Type | Description |
|---|---|
| OH_NativeImage* | Returns the pointer to the OH_NativeImage instance if the operation is successful; returns NULL otherwise. |
OH_NativeImage_ReleaseTextImage()
int32_t OH_NativeImage_ReleaseTextImage(OH_NativeImage* image)
Description
Unbinds SurfaceBuffer from the texture and restores the texture to the unused state.
In single-buffer mode, this function is called to release the texture. Otherwise, the producer cannot request a buffer next time.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 22
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image is a null pointer. |
OH_NativeImage_GetColorSpace()
int32_t OH_NativeImage_GetColorSpace(OH_NativeImage* image, OH_NativeBuffer_ColorSpace* colorSpace)
Description
Obtains the color space of the texture image that is most recently passed to OH_NativeImage_UpdateSurfaceImage.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 22
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| OH_NativeBuffer_ColorSpace* colorSpace | Pointer to the color space set in OH_NativeImage. For details about the available options, see OH_NativeBuffer_ColorSpace. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image or colorSpace is a null pointer. |
OH_NativeImage_AcquireLatestNativeWindowBuffer()
int32_t OH_NativeImage_AcquireLatestNativeWindowBuffer(OH_NativeImage* image, OHNativeWindowBuffer** nativeWindowBuffer, int* fenceFd)
Description
Obtains the OHNativeWindowBuffer recently produced by the producer through the OH_NativeImage of the consumer, and discards other buffers.
The consumer can receive the callback of all available buffers (including discarded buffers) through the callback registered by OH_OnFrameAvailableListener.
This function cannot be used in 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.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 22
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| OHNativeWindowBuffer** nativeWindowBuffer | Pointer to the second-level OHNativeWindowBuffer. |
| int* fenceFd | Pointer to the file descriptor handle. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image, nativeWindowBuffer, or fenceFd is a null pointer. Returns NATIVE_ERROR_NO_BUFFER if no buffer is available for consumption. |
OH_NativeImage_IsReleased()
int32_t OH_NativeImage_IsReleased(OH_NativeImage* image, bool* isReleased)
Description
Queries whether the texture associated with OH_NativeImage has been released.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 23
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
| bool* isReleased | Whether the texture has been released. true if the texture has been released; false otherwise. This parameter is used as an output parameter. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image or isReleased is a null pointer. |
OH_NativeImage_Release()
int32_t OH_NativeImage_Release(OH_NativeImage* image)
Description
Clears OHNativeWindowBuffer of all OHNativeWindow and detaches OH_NativeImage from the OpenGL ES context.
This function is not thread-safe.
System capability: SystemCapability.Graphic.Graphic2D.NativeImage
Since: 23
Parameters
| Name | Description |
|---|---|
| OH_NativeImage* image | Pointer to an OH_NativeImage instance. |
Returns
| Type | Description |
|---|---|
| int32_t | Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if image is a null pointer. |