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 FilesFile 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 StructuresData 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.
EnumerationsEnumeration 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.
FunctionsFunction 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 BufferConsumerUsageenum [OHOS::BufferConsumerUsage](Surface.md#ga16d4d4f73d748455e45924ffbdd1e891)
Description:
Enumerates shared memory usage scenarios, including physically contiguous memory and virtual memory.
Enumerator
Description
BUFFER_CONSUMER_USAGE_SORTWAREVirtual memory
BUFFER_CONSUMER_USAGE_HARDWAREPhysically contiguous memory. The cache is not used.
BUFFER_CONSUMER_USAGE_HARDWARE_CONSUMER_CACHEPhysically contiguous memory. Consumers use the cache.
BUFFER_CONSUMER_USAGE_HARDWARE_PRODUCER_CACHEPhysically contiguous memory. Producers use the cache.
BUFFER_CONSUMER_USAGE_MAXValid maximum value, used to determine whether the current shared memory usage scenario is within a proper range.
ImagePixelFormatenum [OHOS::ImagePixelFormat](Surface.md#gaa191d6e3b92a0f527744d43e056ae025)
Description:
Enumerates a pixel format.
Enumerator
Description
IMAGE_PIXEL_FORMAT_NONEInvalid pixel format
IMAGE_PIXEL_FORMAT_RGB565RGB565 pixel format
IMAGE_PIXEL_FORMAT_ARGB1555ARGB555 pixel format
IMAGE_PIXEL_FORMAT_RGB888RGB888 pixel format
IMAGE_PIXEL_FORMAT_ARGB8888ARGB8888 pixel format
IMAGE_PIXEL_FORMAT_YUYVYUYV pixel format
IMAGE_PIXEL_FORMAT_YVYUYVYU pixel format
IMAGE_PIXEL_FORMAT_UYVYUYVY pixel format
IMAGE_PIXEL_FORMAT_VYUYVYUY pixel format
IMAGE_PIXEL_FORMAT_AYUVAYUV pixel format
IMAGE_PIXEL_FORMAT_YUV410YUV410 pixel format
IMAGE_PIXEL_FORMAT_YVU410YVU410 pixel format
IMAGE_PIXEL_FORMAT_YUV411YUV411 pixel format
IMAGE_PIXEL_FORMAT_YVU411YVU411 pixel format
IMAGE_PIXEL_FORMAT_YUV420YUV420 pixel format
IMAGE_PIXEL_FORMAT_YVU420YVU420 pixel format
IMAGE_PIXEL_FORMAT_YUV422YUV422 pixel format
IMAGE_PIXEL_FORMAT_YVU422YVU422 pixel format
IMAGE_PIXEL_FORMAT_YUV444YUV444 pixel format
IMAGE_PIXEL_FORMAT_YVU444YVU444 pixel format
IMAGE_PIXEL_FORMAT_NV12NV12 pixel format
IMAGE_PIXEL_FORMAT_NV21NV21 pixel format
IMAGE_PIXEL_FORMAT_NV16NV16 pixel format
IMAGE_PIXEL_FORMAT_NV61NV61 pixel format
Function Documentation AcquireBuffer()virtual [SurfaceBuffer](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](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](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](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 key, value . 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 key, value . 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](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](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](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 key, value . 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 key, value . 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 key, value .
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.
本文链接: http://thesurfacemaster.immuno-online.com/view-724942.html