Surface

Surface

Overview

Provides the capabilities of applying for and releasing shared memory in multimedia and graphics scenarios.

Provides shared memory for multimedia and graphics.

This module is used to apply for and release shared memory and is used by the multimedia and graphics modules across processes.

Since:

1.0

Version:

1.0

Since:

1.0

Version:

1.0

Summary

Files

File Name	Description
ibuffer_consumer_listener.h	Declares the consumer listener used to notify consumers when the surface status is updated.
surface.h	Provides the capabilities of applying for and releasing shared memory in multimedia and graphics scenarios.
surface_buffer.h	Provides functions such as setting the virtual address, size, and additional attributes of shared memory.
surface_type.h	Provides the capabilities of setting shared memory parameters.

Data Structures

Data Structure Name	Description
OHOS::IBufferConsumerListener	Defines the consumer listener used to notify consumers when the surface status is updated.
OHOS::Surface	Defines the consumer listener used to notify consumers when the surface status is updated.
OHOS::SurfaceBuffer	Provides functions such as setting the virtual address, size, and additional attributes of shared memory.

Enumerations

Enumeration Name	Description
OHOS::BufferConsumerUsage { OHOS::BUFFER_CONSUMER_USAGE_SORTWARE = 0, OHOS::BUFFER_CONSUMER_USAGE_HARDWARE, OHOS::BUFFER_CONSUMER_USAGE_HARDWARE_CONSUMER_CACHE, OHOS::BUFFER_CONSUMER_USAGE_HARDWARE_PRODUCER_CACHE, OHOS::BUFFER_CONSUMER_USAGE_MAX }	Enumerates shared memory usage scenarios, including physically contiguous memory and virtual memory.
OHOS::ImagePixelFormat { OHOS::IMAGE_PIXEL_FORMAT_NONE = 0, OHOS::IMAGE_PIXEL_FORMAT_RGB565 = 101, OHOS::IMAGE_PIXEL_FORMAT_ARGB1555, OHOS::IMAGE_PIXEL_FORMAT_RGB888, OHOS::IMAGE_PIXEL_FORMAT_ARGB8888, OHOS::IMAGE_PIXEL_FORMAT_YUYV = 201, OHOS::IMAGE_PIXEL_FORMAT_YVYU, OHOS::IMAGE_PIXEL_FORMAT_UYVY, OHOS::IMAGE_PIXEL_FORMAT_VYUY, OHOS::IMAGE_PIXEL_FORMAT_AYUV, OHOS::IMAGE_PIXEL_FORMAT_YUV410, OHOS::IMAGE_PIXEL_FORMAT_YVU410, OHOS::IMAGE_PIXEL_FORMAT_YUV411, OHOS::IMAGE_PIXEL_FORMAT_YVU411, OHOS::IMAGE_PIXEL_FORMAT_YUV420, OHOS::IMAGE_PIXEL_FORMAT_YVU420, OHOS::IMAGE_PIXEL_FORMAT_YUV422, OHOS::IMAGE_PIXEL_FORMAT_YVU422, OHOS::IMAGE_PIXEL_FORMAT_YUV444, OHOS::IMAGE_PIXEL_FORMAT_YVU444, OHOS::IMAGE_PIXEL_FORMAT_NV12 = 301, OHOS::IMAGE_PIXEL_FORMAT_NV21, OHOS::IMAGE_PIXEL_FORMAT_NV16, OHOS::IMAGE_PIXEL_FORMAT_NV61 }	Enumerates a pixel format.

Enumeration Name

Description

OHOS::BufferConsumerUsage { OHOS::BUFFER_CONSUMER_USAGE_SORTWARE = 0, OHOS::BUFFER_CONSUMER_USAGE_HARDWARE, OHOS::BUFFER_CONSUMER_USAGE_HARDWARE_CONSUMER_CACHE, OHOS::BUFFER_CONSUMER_USAGE_HARDWARE_PRODUCER_CACHE, OHOS::BUFFER_CONSUMER_USAGE_MAX }

Enumerates shared memory usage scenarios, including physically contiguous memory and virtual memory.

Enumerates a pixel format.

Functions

Function Name	Description
OHOS::IBufferConsumerListener::OnBufferAvailable ()=0	virtual void Called to notify a consumer that a buffer is available for consumption.
OHOS::Surface::CreateSurface ()	static Surface A constructor used to create a Surface object for consumers to use.
OHOS::Surface::~Surface ()	virtual A destructor used to delete the Surface instance.
OHOS::Surface::SetQueueSize (uint8_t queueSize)=0	virtual void Sets the number of buffers that can be allocated to the surface. The default value is 1. The value range is [1, 10].
OHOS::Surface::GetQueueSize ()=0	virtual uint8_t Obtains the number of surface buffers that can be allocated to the surface. The default value is 1. The value range is [1, 10].
OHOS::Surface::SetWidthAndHeight (uint32_t width, uint32_t height)=0	virtual void Sets the width and height of the surface for calculating its stride and size. The default value range of width and height is (0,7680].
OHOS::Surface::GetWidth ()=0	virtual uint32_t Obtains the width of the surface.
OHOS::Surface::GetHeight ()=0	virtual uint32_t Obtains the height of the surface.
OHOS::Surface::SetFormat (uint32_t format)=0	virtual void Sets the pixel format of the surface. For details, see ImageFormat. The default pixel format is IMAGE_PIXEL_FORMAT_RGB565.
OHOS::Surface::GetFormat ()=0	virtual uint32_t Obtains the pixel format of the surface. For details, see ImageFormat. The default pixel format is IMAGE_PIXEL_FORMAT_RGB565.
OHOS::Surface::SetStrideAlignment (uint32_t strideAlignment)=0	virtual void Sets the number of bytes for stride alignment.
OHOS::Surface::GetStrideAlignment ()=0	virtual uint32_t Obtains the number of bytes for stride alignment. By default, 4-byte aligned is used.
OHOS::Surface::GetStride ()=0	virtual uint32_t Obtains the stride of the surface.
OHOS::Surface::SetSize (uint32_t size)=0	virtual void Sets the size of the shared memory to allocate.
OHOS::Surface::GetSize ()=0	virtual uint32_t Obtains the size of the shared memory to allocate.
OHOS::Surface::SetUsage (uint32_t usage)=0	virtual void Sets the usage scenario of the buffer. Physically contiguous memory and virtual memory (by default) are supported. By default, virtual memory is allocated.
OHOS::Surface::GetUsage ()=0	virtual uint32_t Obtains the usage scenario of the buffer. Physically contiguous memory and virtual memory are supported.
OHOS::Surface::SetUserData (const std::string &key, const std::string &value)=0	virtual void Sets surface user data, which is stored in the format of <key, value>.
OHOS::Surface::GetUserData (const std::string &key)=0	virtual std::string Obtains surface user data.
OHOS::Surface::RequestBuffer (uint8_t wait=0)=0	virtual SurfaceBuffer Obtains a buffer to write data.
OHOS::Surface::FlushBuffer (SurfaceBuffer buffer)=0	virtual int32_t Flushes a buffer to the dirty queue for consumers to use.
OHOS::Surface::AcquireBuffer ()=0	virtual SurfaceBuffer Obtains a buffer.
OHOS::Surface::ReleaseBuffer (SurfaceBuffer buffer)=0	virtual bool Releases the consumed buffer.
OHOS::Surface::CancelBuffer (SurfaceBuffer buffer)=0	virtual void Releases a buffer to the free queue.
OHOS::Surface::RegisterConsumerListener (IBufferConsumerListener &listener)=0	virtual void Registers a consumer listener.
OHOS::Surface::UnregisterConsumerListener ()=0	virtual void Unregisters the consumer listener.
OHOS::SurfaceBuffer::GetVirAddr () const =0	virtual void * Obtains the virtual address of shared memory for producers and consumers.
OHOS::SurfaceBuffer::GetPhyAddr () const =0	virtual uint64_t Obtains the physical address of shared memory.
OHOS::SurfaceBuffer::GetSize () const =0	virtual uint32_t Obtains the size of shared memory.
OHOS::SurfaceBuffer::SetSize (uint32_t size)=0	virtual void Sets the size of shared memory.
OHOS::SurfaceBuffer::SetInt32 (uint32_t key, int32_t value)=0	virtual int32_t Sets an extra attribute value of the int32 type.
OHOS::SurfaceBuffer::GetInt32 (uint32_t key, int32_t &value)=0	virtual int32_t Obtains an extra attribute value of the int32 type.
OHOS::SurfaceBuffer::SetInt64 (uint32_t key, int64_t value)=0	virtual int32_t Sets an extra attribute value of the int64 type.
OHOS::SurfaceBuffer::GetInt64 (uint32_t key, int64_t &value)=0	virtual int32_t Obtains an extra attribute value of the int64 type.

Details

Enumeration Type Documentation

BufferConsumerUsage

enum [OHOS::BufferConsumerUsage]($api-api-SmartVision-Devices-Surface.md#ga16d4d4f73d748455e45924ffbdd1e891)

Description:

Enumerates shared memory usage scenarios, including physically contiguous memory and virtual memory.

Enumerator	Description
BUFFER_CONSUMER_USAGE_SORTWARE	Virtual memory
BUFFER_CONSUMER_USAGE_HARDWARE	Physically contiguous memory. The cache is not used.
BUFFER_CONSUMER_USAGE_HARDWARE_CONSUMER_CACHE	Physically contiguous memory. Consumers use the cache.
BUFFER_CONSUMER_USAGE_HARDWARE_PRODUCER_CACHE	Physically contiguous memory. Producers use the cache.
BUFFER_CONSUMER_USAGE_MAX	Valid maximum value, used to determine whether the current shared memory usage scenario is within a proper range.

ImagePixelFormat

enum [OHOS::ImagePixelFormat]($api-api-SmartVision-Devices-Surface.md#gaa191d6e3b92a0f527744d43e056ae025)

Description:

Enumerates a pixel format.

Enumerator	Description
IMAGE_PIXEL_FORMAT_NONE	Invalid pixel format
IMAGE_PIXEL_FORMAT_RGB565	RGB565 pixel format
IMAGE_PIXEL_FORMAT_ARGB1555	ARGB555 pixel format
IMAGE_PIXEL_FORMAT_RGB888	RGB888 pixel format
IMAGE_PIXEL_FORMAT_ARGB8888	ARGB8888 pixel format
IMAGE_PIXEL_FORMAT_YUYV	YUYV pixel format
IMAGE_PIXEL_FORMAT_YVYU	YVYU pixel format
IMAGE_PIXEL_FORMAT_UYVY	UYVY pixel format
IMAGE_PIXEL_FORMAT_VYUY	VYUY pixel format
IMAGE_PIXEL_FORMAT_AYUV	AYUV pixel format
IMAGE_PIXEL_FORMAT_YUV410	YUV410 pixel format
IMAGE_PIXEL_FORMAT_YVU410	YVU410 pixel format
IMAGE_PIXEL_FORMAT_YUV411	YUV411 pixel format
IMAGE_PIXEL_FORMAT_YVU411	YVU411 pixel format
IMAGE_PIXEL_FORMAT_YUV420	YUV420 pixel format
IMAGE_PIXEL_FORMAT_YVU420	YVU420 pixel format
IMAGE_PIXEL_FORMAT_YUV422	YUV422 pixel format
IMAGE_PIXEL_FORMAT_YVU422	YVU422 pixel format
IMAGE_PIXEL_FORMAT_YUV444	YUV444 pixel format
IMAGE_PIXEL_FORMAT_YVU444	YVU444 pixel format
IMAGE_PIXEL_FORMAT_NV12	NV12 pixel format
IMAGE_PIXEL_FORMAT_NV21	NV21 pixel format
IMAGE_PIXEL_FORMAT_NV16	NV16 pixel format
IMAGE_PIXEL_FORMAT_NV61	NV61 pixel format

Function Documentation

AcquireBuffer()

virtual [SurfaceBuffer]($api-api-SmartVision-Devices-OHOS-SurfaceBuffer.md)* OHOS::Surface::AcquireBuffer ()

Description:

Obtains a buffer.

Consumers can use this function to obtain the buffer placed in the dirty queue by producers. If there is no buffer in the queue, nullptr is returned.

Returns:

Returns the pointer to the SurfaceBuffer object.

CancelBuffer()

virtual void OHOS::Surface::CancelBuffer ([SurfaceBuffer]($api-api-SmartVision-Devices-OHOS-SurfaceBuffer.md) * buffer)

Description:

Releases a buffer to the free queue.

Parameters:

Name	Description
SurfaceBuffer	Indicates the pointer to the buffer to be released by producers.

CreateSurface()

static [Surface]($api-api-SmartVision-Devices-OHOS-Surface.md)* OHOS::Surface::CreateSurface ()

Description:

A constructor used to create a Surface object for consumers to use.

In multi-process scenarios, this function is provided for consumers to obtain buffers generated by producers for consumption. In single-process scenarios, this function can be used by both consumers and producers.

FlushBuffer()

virtual int32_t OHOS::Surface::FlushBuffer ([SurfaceBuffer]($api-api-SmartVision-Devices-OHOS-SurfaceBuffer.md) * buffer)

Description:

Flushes a buffer to the dirty queue for consumers to use.

Parameters:

Name	Description
SurfaceBuffer	Indicates the pointer to the buffer flushed by producers.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

GetFormat()

virtual uint32_t OHOS::Surface::GetFormat ()

Description:

Obtains the pixel format of the surface. For details, see ImageFormat. The default pixel format is IMAGE_PIXEL_FORMAT_RGB565.

Returns:

Returns the pixel format.

GetHeight()

virtual uint32_t OHOS::Surface::GetHeight ()

Description:

Obtains the height of the surface.

Returns:

Returns the surface height, in pixels.

GetInt32()

virtual int32_t OHOS::SurfaceBuffer::GetInt32 (uint32_t key, int32_t & value )

Description:

Obtains an extra attribute value of the int32 type.

Obtains an extra attribute value of the int32 type, The extra attribute is stored in the format of . Each key corresponds to a value. If the key does not exist or the value is not int32, -1 is returned.

Parameters:

Name	Description
key	Indicates the key of a key-value pair for which the value is to be obtained.
value	Indicates the value of the key-value pair obtained.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

GetInt64()

virtual int32_t OHOS::SurfaceBuffer::GetInt64 (uint32_t key, int64_t & value )

Description:

Obtains an extra attribute value of the int64 type.

Obtains an extra attribute value of the int64 type, The extra attribute is stored in the format of . Each key corresponds to a value. If the key does not exist or the value is not int64, -1 is returned.

Parameters:

Name	Description
key	Indicates the key of a key-value pair for which the value is to be obtained.
value	Indicates the value of the key-value pair obtained.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

GetPhyAddr()

virtual uint64_t OHOS::SurfaceBuffer::GetPhyAddr () const

Description:

Obtains the physical address of shared memory.

Returns:

Returns the physical address of shared memory.

GetQueueSize()

virtual uint8_t OHOS::Surface::GetQueueSize ()

Description:

Obtains the number of surface buffers that can be allocated to the surface. The default value is 1. The value range is [1, 10].

Returns:

Returns the number of buffers.

GetSize() [1/2]

virtual uint32_t OHOS::SurfaceBuffer::GetSize () const

Description:

Obtains the size of shared memory.

Returns:

Returns the size of shared memory.

GetSize() [2/2]

virtual uint32_t OHOS::Surface::GetSize ()

Description:

Obtains the size of the shared memory to allocate.

Returns:

Returns the size of the shared memory.

GetStride()

virtual uint32_t OHOS::Surface::GetStride ()

Description:

Obtains the stride of the surface.

Returns:

Returns the stride.

GetStrideAlignment()

virtual uint32_t OHOS::Surface::GetStrideAlignment ()

Description:

Obtains the number of bytes for stride alignment. By default, 4-byte aligned is used.

Returns:

Returns the number of bytes for stride alignment.

GetUsage()

virtual uint32_t OHOS::Surface::GetUsage ()

Description:

Obtains the usage scenario of the buffer. Physically contiguous memory and virtual memory are supported.

Returns:

Returns the usage scenario of the buffer. For details, see BUFFER_CONSUMER_USAGE.

GetUserData()

virtual std::string OHOS::Surface::GetUserData (const std::string & key)

Description:

Obtains surface user data.

Parameters:

Name	Description
key	Indicates the key of a key-value pair for which the value is to be obtained.

Returns:

Returns the value of the key-value pair obtained.

GetVirAddr()

virtual void* OHOS::SurfaceBuffer::GetVirAddr () const

Description:

Obtains the virtual address of shared memory for producers and consumers.

Returns:

Returns the virtual address of shared memory.

GetWidth()

virtual uint32_t OHOS::Surface::GetWidth ()

Description:

Obtains the width of the surface.

Returns:

Returns the surface width, in pixels.

OnBufferAvailable()

virtual void OHOS::IBufferConsumerListener::OnBufferAvailable ()

Description:

Called to notify a consumer that a buffer is available for consumption.

RegisterConsumerListener()

virtual void OHOS::Surface::RegisterConsumerListener ([IBufferConsumerListener]($api-api-SmartVision-Devices-OHOS-IBufferConsumerListener.md) & listener)

Description:

Registers a consumer listener.

When a buffer is placed in the dirty queue, OnBufferAvailable is called to notify consumers. If the listener is repeatedly registered, only the latest one is retained.

Parameters:

Name	Description
IBufferConsumerListener	Indicates the listener to register.

ReleaseBuffer()

virtual bool OHOS::Surface::ReleaseBuffer ([SurfaceBuffer]($api-api-SmartVision-Devices-OHOS-SurfaceBuffer.md) * buffer)

Description:

Releases the consumed buffer.

After a consumer has used a SurfaceBuffer object, the consumer can release it through ReleaseBuffer. The released object is placed into the free queue so that producers can apply for the object.

Parameters:

Name	Description
SurfaceBuffer	Indicates the pointer to the buffer released.

Returns:

Returns true if the buffer is released; returns false otherwise.

RequestBuffer()

virtual [SurfaceBuffer]($api-api-SmartVision-Devices-OHOS-SurfaceBuffer.md)* OHOS::Surface::RequestBuffer (uint8_t wait = [/topic/body/section/screen/code
     {""}) 0 (code])

Description:

Obtains a buffer to write data.

Parameters:

Name	Description
wait	Specifies whether the function waits for an available buffer. If wait is 1, the function waits until there is an available buffer in the free queue before returning a pointer. If the wait is 0, the function does not wait and returns nullptr if there is no buffer in the free queue. The default value is 0.

Returns:

Returns the pointer to the buffer if the operation is successful; returns nullptr otherwise.

SetFormat()

virtual void OHOS::Surface::SetFormat (uint32_t format)

Description:

Sets the pixel format of the surface. For details, see ImageFormat. The default pixel format is IMAGE_PIXEL_FORMAT_RGB565.

Parameters:

Name	Description
format	Indicates the pixel format to be set.

SetInt32()

virtual int32_t OHOS::SurfaceBuffer::SetInt32 (uint32_t key, int32_t value )

Description:

Sets an extra attribute value of the int32 type.

Sets an extra attribute value of the int32 type, The extra attribute is stored in the format of . Each key corresponds to a value. If the same keys are used in two calls, the value in the second call overwrites that in the first call.

Parameters:

Name	Description
key	Indicates the key of a key-value pair to set.
value	Indicates the value of the key-value pair to set.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

SetInt64()

virtual int32_t OHOS::SurfaceBuffer::SetInt64 (uint32_t key, int64_t value )

Description:

Sets an extra attribute value of the int64 type.

Sets an extra attribute value of the int64 type. The storage mode of the extra attribute is . the value in the second call overwrites that in the first call.

Parameters:

Name	Description
key	Indicates the key of a key-value pair to set.
value	Indicates the value of the key-value pair to set.

Returns:

Returns 0 if the operation is successful; returns -1 otherwise.

SetQueueSize()

virtual void OHOS::Surface::SetQueueSize (uint8_t queueSize)

Description:

Sets the number of buffers that can be allocated to the surface. The default value is 1. The value range is [1, 10].

Parameters:

Name	Description
queueSize	Indicates the number of buffers to set.

SetSize() [1/2]

virtual void OHOS::SurfaceBuffer::SetSize (uint32_t size)

Description:

Sets the size of shared memory.

Parameters:

Name	Description
size	Indicates the size of shared memory to set.

SetSize() [2/2]

virtual void OHOS::Surface::SetSize (uint32_t size)

Description:

Sets the size of the shared memory to allocate.

Parameters:

Name	Description
size	Indicates the size of the shared memory. The value range is (0,58982400].

SetStrideAlignment()

virtual void OHOS::Surface::SetStrideAlignment (uint32_t strideAlignment)

Description:

Sets the number of bytes for stride alignment.

By default, 4-byte aligned is used. The value range is [4,32].

Parameters:

Name	Description
strideAlignment	Indicates the number of bytes for stride alignment.

SetUsage()

virtual void OHOS::Surface::SetUsage (uint32_t usage)

Description:

Sets the usage scenario of the buffer. Physically contiguous memory and virtual memory (by default) are supported. By default, virtual memory is allocated.

Parameters:

Name	Description
usage	Indicates the usage scenario of the buffer. For details, see BUFFER_CONSUMER_USAGE.

SetUserData()

virtual void OHOS::Surface::SetUserData (const std::string & key, const std::string & value )

Description:

Sets surface user data, which is stored in the format of .

Parameters:

Name	Description
key	Indicates the key of a key-value pair to store.
value	Indicates the value of the key-value pair to store.

SetWidthAndHeight()

virtual void OHOS::Surface::SetWidthAndHeight (uint32_t width, uint32_t height )

Description:

Sets the width and height of the surface for calculating its stride and size. The default value range of width and height is (0,7680].

Parameters:

Name	Description
width	Indicates the surface width, in pixels.
height	Indicates the surface height, in pixels.

UnregisterConsumerListener()

virtual void OHOS::Surface::UnregisterConsumerListener ()

Description:

Unregisters the consumer listener.

After the listener is unregistered, no callback is triggered when a buffer is placed in the dirty queue.

~Surface()

virtual OHOS::Surface::~Surface ()

Description:

A destructor used to delete the Surface instance.

This function releases the surface and all buffers applied for the surface.