native_buffer.h

Overview

This file declares the functions for obtaining and using NativeBuffer.

File to include: <native_buffer/native_buffer.h>

Library: libnative_buffer.so

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Related module: OH_NativeBuffer

Summary

Structs

Name	typedef Keyword	Description
OH_NativeBuffer_Config	OH_NativeBuffer_Config	Describes the OH_NativeBuffer property configuration, which is used when you apply for a new OH_NativeBuffer instance or query the properties of an existing instance.
OH_NativeBuffer_Plane	OH_NativeBuffer_Plane	Describes the plane information of an image.
OH_NativeBuffer_Planes	OH_NativeBuffer_Planes	Describes the plane information of images in an OH_NativeBuffer instance.
OH_NativeBuffer	OH_NativeBuffer	Provides the declaration of an OH_NativeBuffer struct.
OHIPCParcel	OHIPCParcel	Provides the OHIPCParcel struct declaration for inter-process communication.

Enums

Name	typedef Keyword	Description
OH_NativeBuffer_Usage	OH_NativeBuffer_Usage	Defines an enum for the OH_NativeBuffer usages.
OH_NativeBuffer_ColorGamut	OH_NativeBuffer_ColorGamut	Defines an enum for the color gamuts of an OH_NativeBuffer instance.

Functions

Name	Description
OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config)	Creates an OH_NativeBuffer instance based on an OH_NativeBuffer_Config struct. A new OH_NativeBuffer instance is created each time this function is called. This API must be used in pair with OH_NativeBuffer_Unreference. Otherwise, memory leak occurs. This function is not thread-safe.
int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer)	Increases the reference count of an OH_NativeBuffer instance by 1. This API must be used in pair with OH_NativeBuffer_Unreference. Otherwise, memory leak occurs. This function is not thread-safe.
int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer)	Decreases the reference count of an OH_NativeBuffer instance by 1 and, when the reference count reaches 0, destroys the instance. This function is not thread-safe.
void OH_NativeBuffer_GetConfig(OH_NativeBuffer buffer, OH_NativeBuffer_Config config)	Obtains the properties of an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_Map(OH_NativeBuffer buffer, void *virAddr)	Maps the ION memory allocated to an OH_NativeBuffer instance to the process address space. This API must be used in pair with OH_NativeBuffer_Unmap. This function is not thread-safe.
int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer)	Unmaps the ION memory allocated to an OH_NativeBuffer instance from the process address space. This function is not thread-safe.
uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer)	Obtains the sequence number of an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_SetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace colorSpace)	Sets the color space for an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_MapPlanes(OH_NativeBuffer buffer, void virAddr, OH_NativeBuffer_Planes outPlanes)	Maps the multi-channel ION memory corresponding to an OH_NativeBuffer instance to the process address space. This function is not thread-safe.
int32_t OH_NativeBuffer_FromNativeWindowBuffer(OHNativeWindowBuffer nativeWindowBuffer, OH_NativeBuffer *buffer)	Converts an OHNativeWindowBuffer instance to an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_GetColorSpace(OH_NativeBuffer buffer, OH_NativeBuffer_ColorSpace colorSpace)	Obtains the color space of an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_SetMetadataValue(OH_NativeBuffer buffer, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t metadata)	Sets a metadata value for an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_GetMetadataValue(OH_NativeBuffer buffer, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t **metadata)	Obtains the metadata value of an OH_NativeBuffer instance. This function is not thread-safe.
int32_t OH_NativeBuffer_MapWaitFence(OH_NativeBuffer buffer, int32_t fenceFd, void *virAddr)	Maps the ION memory corresponding to OH_NativeBuffer to the process space, and permanently blocks the input fenceFd. If OK is returned, the system closes fenceFd. For other return values, you need to close fenceFd by yourself. This API must be used in pair with OH_NativeBuffer_Unmap. This function is not thread-safe.
int32_t OH_NativeBuffer_WriteToParcel(OH_NativeBuffer* buffer, OHIPCParcel* parcel)	Writes an OH_NativeBuffer object to an IPC serialization object. This function is not thread-safe.
int32_t OH_NativeBuffer_ReadFromParcel(OHIPCParcel* parcel, OH_NativeBuffer** buffer)	Reads an OH_NativeBuffer object from an IPC serialization object. Creates an OH_NativeBuffer object. When it is no longer used, you need to use this API together with OH_NativeBuffer_Unreference. Otherwise, a memory leak may occur. This function is not thread-safe.
int32_t OH_NativeBuffer_IsSupported(OH_NativeBuffer_Config config, bool* isSupported)	Checks whether the system supports the input OH_NativeBuffer_Config configuration information. This function is not thread-safe.
int32_t OH_NativeBuffer_MapAndGetConfig(OH_NativeBuffer* buffer, void** virAddr, OH_NativeBuffer_Config* config)	Maps the multi-channel ION memory corresponding to the OH_NativeBuffer to the process space and obtains the OH_NativeBuffer_Config corresponding to OH_NativeBuffer. This function is not thread-safe.

Enum Description

OH_NativeBuffer_Usage

enum OH_NativeBuffer_Usage

Description

Defines an enum for the OH_NativeBuffer usages.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 10

Enum	Description
NATIVEBUFFER_USAGE_CPU_READ = (1ULL << 0)	CPU readable.
NATIVEBUFFER_USAGE_CPU_WRITE = (1ULL << 1)	CPU writable.
NATIVEBUFFER_USAGE_MEM_DMA = (1ULL << 3)	Direct memory access to the buffer.
NATIVEBUFFER_USAGE_MEM_MMZ_CACHE = (1ULL << 5)	Buffer of the media memory area. Since: 20
NATIVEBUFFER_USAGE_HW_RENDER = (1ULL << 8)	GPU writable. Since: 12
NATIVEBUFFER_USAGE_HW_TEXTURE = (1ULL << 9)	GPU readable. Since: 12
NATIVEBUFFER_USAGE_CPU_READ_OFTEN = (1ULL << 16)	Direct mapping of CPU. Since: 12
NATIVEBUFFER_USAGE_ALIGNMENT_512 = (1ULL << 18)	512-byte alignment. Since: 12

OH_NativeBuffer_ColorGamut

enum OH_NativeBuffer_ColorGamut

Description

Defines an enum for the color gamuts of an OH_NativeBuffer instance.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 12

Enum	Description
NATIVEBUFFER_COLOR_GAMUT_NATIVE = 0	Default gamut.
NATIVEBUFFER_COLOR_GAMUT_STANDARD_BT601 = 1	Standard BT.601 color gamut.
NATIVEBUFFER_COLOR_GAMUT_STANDARD_BT709 = 2	Standard BT.709 color gamut.
NATIVEBUFFER_COLOR_GAMUT_DCI_P3 = 3	DCI P3 color gamut.
NATIVEBUFFER_COLOR_GAMUT_SRGB = 4	SRGB color gamut.
NATIVEBUFFER_COLOR_GAMUT_ADOBE_RGB = 5	Adobe RGB color gamut.
NATIVEBUFFER_COLOR_GAMUT_DISPLAY_P3 = 6	Display P3 color gamut.
NATIVEBUFFER_COLOR_GAMUT_BT2020 = 7	BT.2020 color gamut.
NATIVEBUFFER_COLOR_GAMUT_BT2100_PQ = 8	BT.2100 PQ color gamut.
NATIVEBUFFER_COLOR_GAMUT_BT2100_HLG = 9	BT.2100 HLG color gamut format
NATIVEBUFFER_COLOR_GAMUT_DISPLAY_BT2020 = 10	Display BT.2020 color gamut.

Function Description

OH_NativeBuffer_Alloc()

OH_NativeBuffer* OH_NativeBuffer_Alloc(const OH_NativeBuffer_Config* config)

Description

Creates an OH_NativeBuffer instance based on an OH_NativeBuffer_Config struct. A new OH_NativeBuffer instance is created each time this function is called.
This API must be used in pair with OH_NativeBuffer_Unreference. Otherwise, memory leak occurs.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
const OH_NativeBuffer_Config* config	Pointer to an OH_NativeBuffer_Config instance.

Returns

Type	Description
OH_NativeBuffer*	Returns the pointer to the OH_NativeBuffer instance created if the operation is successful; returns NULL otherwise.

OH_NativeBuffer_Reference()

int32_t OH_NativeBuffer_Reference(OH_NativeBuffer *buffer)

Description

Increases the reference count of an OH_NativeBuffer instance by 1.
This API must be used in pair with OH_NativeBuffer_Unreference. Otherwise, memory leak occurs.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.

Returns

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

OH_NativeBuffer_Unreference()

int32_t OH_NativeBuffer_Unreference(OH_NativeBuffer *buffer)

Description

Decreases the reference count of an OH_NativeBuffer instance by 1 and, when the reference count reaches 0, destroys the instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.

Returns

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

OH_NativeBuffer_GetConfig()

void OH_NativeBuffer_GetConfig(OH_NativeBuffer *buffer, OH_NativeBuffer_Config* config)

Description

Obtains the properties of an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.
OH_NativeBuffer_Config* config	Pointer to an OH_NativeBuffer_Config instance, which is used to receive the properties of OH_NativeBuffer.

OH_NativeBuffer_Map()

int32_t OH_NativeBuffer_Map(OH_NativeBuffer *buffer, void **virAddr)

Description

Maps the ION memory allocated to an OH_NativeBuffer instance to the process address space.
This API must be used in pair with OH_NativeBuffer_Unmap.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.
void **virAddr	Double pointer to the address of the virtual memory.

Returns

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

OH_NativeBuffer_Unmap()

int32_t OH_NativeBuffer_Unmap(OH_NativeBuffer *buffer)

Description

Unmaps the ION memory allocated to an OH_NativeBuffer instance from the process address space.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.

Returns

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

OH_NativeBuffer_GetSeqNum()

uint32_t OH_NativeBuffer_GetSeqNum(OH_NativeBuffer *buffer)

Description

Obtains the sequence number of an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 9

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.

Returns

Type	Description
uint32_t	Returns the unique sequence number of the OH_NativeBuffer instance.

OH_NativeBuffer_SetColorSpace()

int32_t OH_NativeBuffer_SetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace colorSpace)

Description

Sets the color space for an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 11

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer 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.

OH_NativeBuffer_MapPlanes()

int32_t OH_NativeBuffer_MapPlanes(OH_NativeBuffer *buffer, void **virAddr, OH_NativeBuffer_Planes *outPlanes)

Description

Maps the multi-channel ION memory corresponding to an OH_NativeBuffer instance to the process address space.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 12

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.
void **virAddr	Double pointer to the address of the virtual memory.
OH_NativeBuffer_Planes *outPlanes	Pointer to the plane information of all images.

Returns

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

OH_NativeBuffer_FromNativeWindowBuffer()

int32_t OH_NativeBuffer_FromNativeWindowBuffer(OHNativeWindowBuffer *nativeWindowBuffer, OH_NativeBuffer **buffer)

Description

Converts an OHNativeWindowBuffer instance to an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 12

Parameters

Name	Description
OHNativeWindowBuffer *nativeWindowBuffer	Pointer to an OHNativeWindowBuffer instance.
OH_NativeBuffer **buffer	Pointer to an OH_NativeBuffer instance.

Returns

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

OH_NativeBuffer_GetColorSpace()

int32_t OH_NativeBuffer_GetColorSpace(OH_NativeBuffer *buffer, OH_NativeBuffer_ColorSpace *colorSpace)

Description

Obtains the color space of an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 12

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer 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.

OH_NativeBuffer_SetMetadataValue()

int32_t OH_NativeBuffer_SetMetadataValue(OH_NativeBuffer *buffer, OH_NativeBuffer_MetadataKey metadataKey,int32_t size, uint8_t *metadata)

Description

Sets a metadata value for an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 12

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.
OH_NativeBuffer_MetadataKey metadataKey	Metadata type of OH_NativeBuffer. For details about the available options, see OH_NativeBuffer_MetadataKey.
int32_t size	Size of the uint8_t vector. For details about the value range, see OH_NativeBuffer_MetadataKey.
uint8_t *metadata	Pointer to the uint8_t vector.

Returns

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

OH_NativeBuffer_GetMetadataValue()

int32_t OH_NativeBuffer_GetMetadataValue(OH_NativeBuffer *buffer, OH_NativeBuffer_MetadataKey metadataKey,int32_t *size, uint8_t **metadata)

Description

Obtains the metadata value of an OH_NativeBuffer instance.
This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 12

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.
OH_NativeBuffer_MetadataKey metadataKey	Metadata type of OH_NativeBuffer. For details about the available options, see OH_NativeBuffer_MetadataKey.
int32_t *size	Size of the uint8_t vector. For details about the value range, see OH_NativeBuffer_MetadataKey.
uint8_t **metadata	Double pointer to the uint8_t vector.

Returns

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

OH_NativeBuffer_MapWaitFence()

int32_t OH_NativeBuffer_MapWaitFence(OH_NativeBuffer *buffer, int32_t fenceFd, void **virAddr)

Description

Maps the ION memory corresponding to OH_NativeBuffer to the process space, and permanently blocks the input fenceFd.

If OK is returned, the system closes fenceFd. For other return values, you need to close fenceFd by yourself.

This API must be used in pair with OH_NativeBuffer_Unmap.

This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 23

Parameters

Name	Description
OH_NativeBuffer *buffer	Pointer to an OH_NativeBuffer instance.
int32_t fenceFd	File descriptor handle, which is used for concurrent synchronization control.
void **virAddr	Double pointer to the address of the virtual memory.

Returns

Type	Description
int32_t	Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if buffer or virAddr is a null pointer, or fenceFd is less than 0. Returns NATIVE_ERROR_UNKNOWN if the mapping fails.

OH_NativeBuffer_WriteToParcel()

int32_t OH_NativeBuffer_WriteToParcel(OH_NativeBuffer* buffer, OHIPCParcel* parcel)

Description

Writes an OH_NativeBuffer object to an IPC serialization object.

This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 23

Parameters

Name	Description
OH_NativeBuffer* buffer	Pointer to an OH_NativeBuffer instance.
OHIPCParcel* parcel	Pointer to an OHIPCParcel struct instance, which is used as the output parameter.

Returns

Type	Description
int32_t	Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if buffer or parcel is a null pointer. Returns NATIVE_ERROR_BINDER_ERROR if IPC sending fails.

OH_NativeBuffer_ReadFromParcel()

int32_t OH_NativeBuffer_ReadFromParcel(OHIPCParcel* parcel, OH_NativeBuffer** buffer)

Description

Reads an OH_NativeBuffer object from an IPC serialization object.

Creates an OH_NativeBuffer object. When it is no longer used, you need to use this API together with OH_NativeBuffer_Unreference. Otherwise, a memory leak may occur.

This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 23

Parameters

Name	Description
OHIPCParcel* parcel	Pointer to an OHIPCParcel struct instance.
OH_NativeBuffer** buffer	Level-2 pointer to an OH_NativeBuffer struct instance, which is used as the output parameter.

Returns

Type	Description
int32_t	Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if parcel or buffer is a null pointer. Returns NATIVE_ERROR_UNKNOWN if the parcel fails to be deserialized.

OH_NativeBuffer_IsSupported()

int32_t OH_NativeBuffer_IsSupported(OH_NativeBuffer_Config config, bool* isSupported)

Description

Checks whether the system supports the input OH_NativeBuffer_Config configuration information.

This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 23

Parameters

Name	Description
OH_NativeBuffer_Config config	OH_NativeBuffer_Config struct instance.
bool* isSupported	If the value is true, the system supports the input OH_NativeBuffer_Config configuration information. If the value is false, the system does not support the input OH_NativeBuffer_Config configuration information. 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 isSupported is a null pointer.

OH_NativeBuffer_MapAndGetConfig()

int32_t OH_NativeBuffer_MapAndGetConfig(OH_NativeBuffer* buffer, void** virAddr, OH_NativeBuffer_Config* config)

Description

Maps the multi-channel ION memory corresponding to the OH_NativeBuffer to the process space and obtains the OH_NativeBuffer_Config corresponding to OH_NativeBuffer.

This function is not thread-safe.

System capability: SystemCapability.Graphic.Graphic2D.NativeBuffer

Since: 23

Parameters

Name	Description
OH_NativeBuffer* buffer	Level-2 pointer to an OH_NativeBuffer struct instance.
void** virAddr	Level-2 pointer to the address of the virtual memory mapped to the current process, which is used as the output parameter.
OH_NativeBuffer_Config* config	Pointer to an OH_NativeBuffer_Config struct instance, which is used as the output parameter.

Returns

Type	Description
int32_t	Returns NATIVE_ERROR_OK if the operation is successful. Returns NATIVE_ERROR_INVALID_ARGUMENTS if buffer, virAddr, or config is a null pointer. Returns NATIVE_ERROR_UNKNOWN if the mapping fails.