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.

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

  1. 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

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. virtual uint32_t OHOS::Surface::GetHeight ()

Description:

Obtains the height of the surface.

Returns:

Returns the surface height, in pixels.

GetInt32()

  1. 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()

  1. 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()

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

Description:

Obtains the physical address of shared memory.

Returns:

Returns the physical address of shared memory.

GetQueueSize()

  1. 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]

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

Description:

Obtains the size of shared memory.

Returns:

Returns the size of shared memory.

GetSize() [2/2]

  1. 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()

  1. virtual uint32_t OHOS::Surface::GetStride ()

Description:

Obtains the stride of the surface.

Returns:

Returns the stride.

GetStrideAlignment()

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. virtual uint32_t OHOS::Surface::GetWidth ()

Description:

Obtains the width of the surface.

Returns:

Returns the surface width, in pixels.

OnBufferAvailable()

  1. virtual void OHOS::IBufferConsumerListener::OnBufferAvailable ()

Description:

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

RegisterConsumerListener()

  1. 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()

  1. 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()

  1. virtual [SurfaceBuffer]($api-api-SmartVision-Devices-OHOS-SurfaceBuffer.md)* OHOS::Surface::RequestBuffer (uint8_t wait = [/topic/body/section/screen/code
  2. {""}) 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()

  1. 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()

  1. 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()

  1. 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()

  1. 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]

  1. 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]

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. 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()

  1. 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.