lite_surface

lite_surface 模块提供轻量级绘图表面抽象，支持基本图形绘制与像素缓冲区管理。

Class Summary

OHOS::LiteSurface

图形模块的 LiteSurface 类，提供媒体显示相关的缓冲区管理功能

• 构造：无

• 成员函数：

  接口名称	功能简述
  SetQueueSize	设置可分配给 LiteSurface 的缓冲区数量
  GetQueueSize	获取 LiteSurface 可分配的缓冲区数量
  SetWidthAndHeight	设置 LiteSurface 的宽度和高度
  GetWidth	获取 LiteSurface 的宽度
  GetHeight	获取 LiteSurface 的高度
  SetFormat	设置 LiteSurface 的像素格式
  GetFormat	获取 LiteSurface 的像素格式
  SetUsage	设置缓冲区的使用场景
  GetUsage	获取缓冲区的使用场景
  SetUserData	以键值对格式设置 LiteSurface 用户数据
  GetUserData	获取 LiteSurface 用户数据
  RegisterConsumerListener	注册消费者监听器
  UnregisterConsumerListener	注销消费者监听器
  SetStrideAlignment	设置步幅对齐字节数
  GetStrideAlignment	获取步幅对齐字节数
  GetStride	获取 LiteSurface 的步幅
  SetSize	设置共享内存分配大小
  GetSize	获取共享内存分配大小
  RequestBuffer	从空闲队列请求缓冲区用于写入数据
  FlushBuffer	将缓冲区刷新到脏队列供消费者使用
  AcquireBuffer	从脏队列获取缓冲区供消费者消费
  ReleaseBuffer	释放消费者已使用的缓冲区到空闲队列
  CancelBuffer	生产者取消缓冲区并归还空闲队列
  PrepareBuffers	准备视频缓冲区，在播放视频前调用
  ClearBuffers	清除所有缓冲区并释放资源
  GetBackBuf	获取脏队列末尾的缓冲区
  SetUVOffset	设置 UV 分量的地址偏移
  GetUVOffset	获取 UV 分量的地址偏移

• 使用包含头文件：#include "common/lite_surface.h"

• 声明头文件：middleware/services/gui/uikit/proprietary/include/common/lite_surface.h
• 公有运算符：无
• 继承关系：Surface
• 嵌套类型：无
• 模板形参：无

Functions

OHOS::LiteSurface

SetQueueSize

void SetQueueSize(uint8_t queueSize) override

功能说明

• 核心用途：设置可分配给 LiteSurface 的缓冲区数量
• 设计目的：控制生产者-消费者模式下可同时持有的缓冲区数量上限
• 使用场景：在播放视频前配置缓冲区队列大小，仅在缓冲区未分配时调用有效

入参

名称	参数类型	详细说明	约束取值范围
queueSize	uint8_t	待设置的缓冲区数量	1 ~ maxQueueSize_(4)；超过 maxQueueSize_ 时被截断为 maxQueueSize_

GetQueueSize

uint8_t GetQueueSize() override

功能说明

• 核心用途：获取 LiteSurface 可分配的缓冲区数量
• 设计目的：供调用者查询当前配置的队列大小
• 使用场景：配置确认、缓冲区状态查询

返回值

• 返回类型：uint8_t

返回当前配置的缓冲区队列大小

返回值	触发场景
0	未设置队列大小
1~4	已设置的队列大小值

SetWidthAndHeight

void SetWidthAndHeight(uint32_t width, uint32_t height) override

功能说明

• 核心用途：设置 LiteSurface 的宽度和高度，用于计算步幅和缓冲区大小
• 设计目的：在分配缓冲区前配置显示分辨率参数
• 使用场景：仅在缓冲区未分配时调用，缓冲区已分配后调用无效

入参

名称	参数类型	详细说明	约束取值范围
width	uint32_t	LiteSurface 宽度，单位为像素	(0, 7680]
height	uint32_t	LiteSurface 高度，单位为像素	(0, 7680]

GetWidth

uint32_t GetWidth() override

功能说明

• 核心用途：获取 LiteSurface 的宽度
• 设计目的：供调用者查询当前配置的宽度值
• 使用场景：缓冲区参数确认、显示布局计算

返回值

• 返回类型：uint32_t

返回 LiteSurface 宽度，单位为像素

返回值	触发场景
0	未设置宽度
>0	已设置的宽度值

GetHeight

uint32_t GetHeight() override

功能说明

• 核心用途：获取 LiteSurface 的高度
• 设计目的：供调用者查询当前配置的高度值
• 使用场景：缓冲区参数确认、显示布局计算

返回值

• 返回类型：uint32_t

返回 LiteSurface 高度，单位为像素

返回值	触发场景
0	未设置高度
>0	已设置的高度值

SetFormat

void SetFormat(uint32_t format) override

功能说明

• 核心用途：设置 LiteSurface 的像素格式
• 设计目的：指定缓冲区的像素编码格式，用于视频渲染时的格式匹配
• 使用场景：仅在缓冲区未分配时调用，缓冲区已分配后调用无效

入参

名称	参数类型	详细说明	约束取值范围
format	uint32_t	待设置的像素格式	参考 PixelFormat 枚举值

GetFormat

uint32_t GetFormat() override

功能说明

• 核心用途：获取 LiteSurface 的像素格式
• 设计目的：供调用者查询当前配置的像素格式
• 使用场景：格式确认、渲染管线参数匹配

返回值

• 返回类型：uint32_t

返回当前像素格式

返回值	触发场景
PIXEL_FMT_BUTT	未设置格式（默认值）
其他	已设置的像素格式值

SetUsage

void SetUsage(uint32_t usage) override

功能说明

• 核心用途：设置缓冲区的使用场景（本实现为空操作）
• 设计目的：保持与 Surface 基类接口的一致性，LiteSurface 中未实现 usage 逻辑
• 使用场景：调用后无实际效果，仅满足接口契约

入参

名称	参数类型	详细说明	约束取值范围
usage	uint32_t	缓冲区使用场景标识	参考 BUFFER_CONSUMER_USAGE 枚举值

GetUsage

uint32_t GetUsage() override

功能说明

• 核心用途：获取缓冲区的使用场景（本实现固定返回 0）
• 设计目的：保持与 Surface 基类接口的一致性，LiteSurface 中未实现 usage 逻辑
• 使用场景：调用后始终返回 0

返回值

• 返回类型：uint32_t

返回使用场景标识，固定返回 0

返回值	触发场景
0	始终返回 0

SetUserData

void SetUserData(const std::string& key, const std::string& value) override

功能说明

• 核心用途：以键值对格式设置 LiteSurface 用户数据
• 设计目的：支持扩展属性的存储，如视频旋转信息等
• 使用场景：存储 Surface 级别的自定义元数据；用户数据条数上限为 100

入参

名称	参数类型	详细说明	约束取值范围
key	const std::string&	键值对的键名，入参只读引用	非空字符串
value	const std::string&	键值对的值，入参只读引用	非空字符串

GetUserData

std::string GetUserData(const std::string& key) override

功能说明

• 核心用途：根据键名获取 LiteSurface 用户数据
• 设计目的：查询之前通过 SetUserData 存储的扩展属性
• 使用场景：读取 Surface 级别的自定义元数据

入参

名称	参数类型	详细说明	约束取值范围
key	const std::string&	待查询的键名，入参只读引用	非空字符串

返回值

• 返回类型：std::string

返回键名对应的值

返回值	触发场景
空字符串	键名不存在
非空字符串	键名对应的值

RegisterConsumerListener

void RegisterConsumerListener(IBufferConsumerListener& listener) override

功能说明

• 核心用途：注册消费者监听器，当缓冲区放入脏队列时通知消费者
• 设计目的：实现生产者-消费者模式下的异步通知机制
• 使用场景：消费者端注册回调，接收缓冲区就绪通知；重复注册仅保留最新监听器

入参

名称	参数类型	详细说明	约束取值范围
listener	IBufferConsumerListener&	消费者监听器引用	入参引用，不可为空引用

UnregisterConsumerListener

void UnregisterConsumerListener() override

功能说明

• 核心用途：注销消费者监听器
• 设计目的：停止脏队列缓冲区就绪的通知
• 使用场景：消费者不再需要接收缓冲区通知时调用；注销后缓冲区放入脏队列不再触发回调

SetStrideAlignment

void SetStrideAlignment(uint32_t strideAlignment) override

功能说明

• 核心用途：设置步幅对齐字节数
• 设计目的：控制缓冲区行跨度的内存对齐方式
• 使用场景：仅在缓冲区未分配时调用，缓冲区已分配后调用无效

入参

名称	参数类型	详细说明	约束取值范围
strideAlignment	uint32_t	步幅对齐字节数	[4, 32]；默认 4 字节对齐

GetStrideAlignment

uint32_t GetStrideAlignment() override

功能说明

• 核心用途：获取步幅对齐字节数
• 设计目的：供调用者查询当前配置的对齐参数
• 使用场景：默认 4 字节对齐，用于步幅计算

返回值

• 返回类型：uint32_t

返回步幅对齐字节数

返回值	触发场景
0	未设置对齐参数
4	默认 4 字节对齐
其他	已设置的对齐字节数

GetStride

uint32_t GetStride() override

功能说明

• 核心用途：获取 LiteSurface 的步幅
• 设计目的：根据宽度和步幅对齐参数计算实际行跨度
• 使用场景：缓冲区内存布局计算；宽度未设置时返回 0，对齐参数未设置时返回宽度值

返回值

• 返回类型：uint32_t

返回步幅值

返回值	触发场景
0	宽度未设置
width	步幅对齐参数未设置时返回宽度值
对齐后的值	按步幅对齐参数计算后的值

SetSize

void SetSize(uint32_t size) override

功能说明

• 核心用途：设置共享内存分配大小
• 设计目的：指定单个缓冲区的内存分配大小
• 使用场景：仅在缓冲区未分配时调用，缓冲区已分配后调用无效

入参

名称	参数类型	详细说明	约束取值范围
size	uint32_t	共享内存大小	(0, 58982400]

GetSize

uint32_t GetSize() override

功能说明

• 核心用途：获取共享内存分配大小
• 设计目的：供调用者查询当前配置的缓冲区内存大小
• 使用场景：缓冲区参数确认、内存预算评估

返回值

• 返回类型：uint32_t

返回共享内存大小

返回值	触发场景
0	未设置大小
>0	已设置的内存大小值

RequestBuffer

SurfaceBuffer* RequestBuffer(uint8_t wait = 0) override

功能说明

• 核心用途：从空闲队列请求缓冲区用于写入数据
• 设计目的：为生产者提供获取可用缓冲区的入口
• 使用场景：生产者写入数据前调用；wait=0 时不等待立即返回，wait=1 时等待空闲缓冲区可用

前置条件

• 缓冲区队列大小（queueSize）、内存大小（size）、宽度（width）、高度（height）、像素格式（format）均已设置且有效
• 调用前 LiteSurface 对象已构造完成且未进入析构状态

入参

名称	参数类型	详细说明	约束取值范围
wait	uint8_t	是否等待可用缓冲区	0：不等待（默认）；1：等待

返回值

• 返回类型：SurfaceBuffer*

返回缓冲区指针

返回值	触发场景
nullptr	无可用缓冲区或参数未配置
非空指针	成功获取的缓冲区指针

FlushBuffer

int32_t FlushBuffer(SurfaceBuffer* buffer) override

功能说明

• 核心用途：将缓冲区刷新到脏队列供消费者使用
• 设计目的：生产者完成数据写入后将缓冲区提交给消费者
• 使用场景：生产者写完数据后调用，缓冲区状态变为 BUFFER_STATE_FLUSH 并通知消费者监听器

入参

名称	参数类型	详细说明	约束取值范围
buffer	SurfaceBuffer*	待刷新的缓冲区指针	入参指针，不可为 nullptr；须为 RequestBuffer 返回的有效缓冲区

返回值

• 返回类型：int32_t

返回操作结果

返回值	触发场景
0	刷新成功
-1	缓冲区无效或刷新失败

AcquireBuffer

SurfaceBuffer* AcquireBuffer() override

功能说明

• 核心用途：从脏队列获取缓冲区供消费者消费
• 设计目的：为消费者提供获取已就绪缓冲区的入口
• 使用场景：消费者获取生产者刷新的缓冲区；缓冲区状态变为 BUFFER_STATE_ACQUIRE

返回值

• 返回类型：SurfaceBuffer*

返回缓冲区指针

返回值	触发场景
nullptr	脏队列为空
非空指针	成功获取的缓冲区指针

ReleaseBuffer

bool ReleaseBuffer(SurfaceBuffer* buffer) override

功能说明

• 核心用途：释放消费者已使用的缓冲区到空闲队列
• 设计目的：消费者消费完毕后将缓冲区归还给生产者复用
• 使用场景：消费者使用完缓冲区后调用；缓冲区状态变为 BUFFER_STATE_RELEASE 并归还空闲队列

入参

名称	参数类型	详细说明	约束取值范围
buffer	SurfaceBuffer*	待释放的缓冲区指针	入参指针，不可为 nullptr；须为 AcquireBuffer 返回的有效缓冲区

返回值

• 返回类型：bool

返回释放结果

返回值	触发场景
true	缓冲区释放成功
false	缓冲区无效或释放失败

CancelBuffer

void CancelBuffer(SurfaceBuffer* buffer) override

功能说明

• 核心用途：生产者取消缓冲区并归还空闲队列
• 设计目的：生产者放弃已请求的缓冲区时调用，内部调用 ReleaseBuffer 实现
• 使用场景：生产者获取缓冲区后决定不再使用时调用

入参

名称	参数类型	详细说明	约束取值范围
buffer	SurfaceBuffer*	待取消的缓冲区指针	入参指针，不可为 nullptr；须为 RequestBuffer 返回的有效缓冲区

PrepareBuffers

void PrepareBuffers()

功能说明

• 核心用途：准备视频缓冲区，在播放视频前调用
• 设计目的：按队列大小预分配所有缓冲区
• 使用场景：视频播放前预分配缓冲区；已分配过时再次调用无效

ClearBuffers

void ClearBuffers()

功能说明

• 核心用途：清除所有缓冲区并释放资源
• 设计目的：释放空闲队列、脏队列和缓冲区列表中的所有缓冲区内存
• 使用场景：停止播放或析构时调用，释放所有已分配的缓冲区资源

GetBackBuf

SurfaceBuffer* GetBackBuf()

功能说明

• 核心用途：获取脏队列末尾的缓冲区
• 设计目的：提供对最近刷新缓冲区的快速访问
• 使用场景：需要获取最新刷新的缓冲区但不从队列中移除时调用

返回值

• 返回类型：SurfaceBuffer*

返回脏队列末尾缓冲区指针

返回值	触发场景
nullptr	脏队列为空
非空指针	脏队列末尾的缓冲区指针

SetUVOffset

void SetUVOffset(uint32_t uvOffset)

功能说明

• 核心用途：设置 UV 分量的地址偏移
• 设计目的：指定 YUV 格式缓冲区中 UV 分量相对于 Y 分量的偏移量
• 使用场景：YUV 格式视频渲染时配置 UV 分量寻址偏移

入参

名称	参数类型	详细说明	约束取值范围
uvOffset	uint32_t	UV 分量的地址偏移	0 ~ 缓冲区大小

GetUVOffset

uint32_t GetUVOffset()

功能说明

• 核心用途：获取 UV 分量的地址偏移
• 设计目的：供调用者查询当前 UV 偏移配置
• 使用场景：YUV 格式渲染时确认 UV 分量偏移参数

返回值

• 返回类型：uint32_t

返回 UV 分量地址偏移

返回值	触发场景
0	未设置 UV 偏移
>0	已设置的 UV 偏移值

Enumerations

BufferState

enum class BufferState {
    BUFFER_STATE_NONE = 0,
    BUFFER_STATE_REQUEST = 1,
    BUFFER_STATE_FLUSH = 2,
    BUFFER_STATE_ACQUIRE = 3,
    BUFFER_STATE_RELEASE = 4
};

枚举成员	取值	描述
BUFFER_STATE_NONE	0	缓冲区初始状态
BUFFER_STATE_REQUEST	1	缓冲区已被生产者请求
BUFFER_STATE_FLUSH	2	缓冲区已被生产者刷新到脏队列
BUFFER_STATE_ACQUIRE	3	缓冲区已被消费者获取
BUFFER_STATE_RELEASE	4	缓冲区已被消费者释放

Structures

BufferItem

struct BufferItem {
    SurfaceBuffer* buffer;
    BufferState state;
};

成员说明

成员名称	数据类型	描述
buffer	SurfaceBuffer*	指向 SurfaceBuffer 对象的指针
state	BufferState	缓冲区当前状态