dfx_frame_trace

dfx_frame_trace 模块提供帧追踪功能，用于调试时记录和统计帧渲染性能数据。

Class Summary

OHOS::DfxFrameTrace

帧绘制追踪单例类，用于记录和展示图形渲染管线的帧级绘制耗时与事件追踪信息

构造：无

成员函数：

接口名称	功能简述
GetInstance	获取 DfxFrameTrace 单例引用
EnableFrameTrace	设置帧追踪使能计数
BeginTrace	开始一次帧追踪采集
SetDrawRect	设置当前帧的绘制区域
SetFlushMemType	设置刷新内存类型
EndTrace	结束一次帧追踪采集
SetPathType	设置路径绘制类型与属性
FrameTraceStart	记录一个绘制命令的起始时间
FrameTraceEnd	记录一个绘制命令的结束时间与区域
ShowFrameTrace	将当前帧追踪记录写入事件任务链
EventTraceStart	开始一次事件追踪
EventTraceEnd	结束一次事件追踪
TaskTraceStart	开始一次任务追踪
TaskTraceEnd	结束一次任务追踪

使用包含头文件：#include "dfx/dfx_frame_trace.h"
声明头文件：middleware/services/gui/uikit/proprietary/include/dfx/dfx_frame_trace.h
公有运算符：无
继承关系：HeapBase
嵌套类型：无
模板形参：无

Functions

OHOS::DfxFrameTrace

GetInstance

static DfxFrameTrace& GetInstance()

功能说明

核心用途：获取 DfxFrameTrace 全局单例引用
设计目的：通过静态局部变量实现线程安全的懒加载单例模式
使用场景：所有帧追踪接口均需通过此单例调用

EnableFrameTrace

void EnableFrameTrace(int enable)

功能说明

核心用途：设置帧追踪的使能计数，控制追踪采集的启停
设计目的：通过计数器机制控制采集次数，计数归零后自动停止追踪
使用场景：需要采集指定帧数的绘制性能数据时调用

入参

名称	参数类型	详细说明	约束取值范围
enable	int	追踪使能计数，决定可采集的帧数	正整数

BeginTrace

void BeginTrace()

功能说明

核心用途：标记一帧追踪采集的开始，初始化采集状态
设计目的：在追踪计数大于 0 时激活采集，同步获取系统运行状态与频率信息
使用场景：每帧渲染开始前调用，与 EndTrace 配对使用

SetDrawRect

void SetDrawRect(const Rect &rect)

功能说明

核心用途：设置当前帧的绘制脏区域矩形
设计目的：记录帧级绘制区域信息，用于性能分析时定位绘制范围
使用场景：在 BeginTrace 之后、EndTrace 之前设置绘制区域

入参

名称	参数类型	详细说明	约束取值范围
rect	const Rect &	入参只读引用，绘制区域矩形	Rect 有效坐标范围

SetFlushMemType

void SetFlushMemType(bool isSram)

功能说明

核心用途：设置刷新操作的内存类型标识
设计目的：区分 SRAM 与 PSRAM 刷新类型，用于性能分析时标记刷新来源
使用场景：在刷新操作前设置内存类型

入参

名称	参数类型	详细说明	约束取值范围
isSram	bool	入参，内存类型标识	true: SRAM; false: PSRAM

EndTrace

void EndTrace()

功能说明

核心用途：标记一帧追踪采集的结束，递减追踪计数
设计目的：在存在绘制记录时递减计数，并清除当前帧采集状态
使用场景：每帧渲染结束后调用，与 BeginTrace 配对使用

SetPathType

void SetPathType(FrameTraceType type, FrameTracePathAttr attr)

功能说明

核心用途：设置路径绘制操作的追踪类型与路径属性
设计目的：将 HW_DRAW_PATH 类型的通用路径绘制细化为具体的绘制类型与属性，用于更精确的性能分析
使用场景：在调用 FrameTraceStart 前设置路径绘制的具体类型和属性

入参

名称	参数类型	详细说明	约束取值范围
type	FrameTraceType	路径绘制的具体类型	FrameTraceType 枚举值
attr	FrameTracePathAttr	路径属性标识	FrameTracePathAttr 枚举值

FrameTraceStart

void FrameTraceStart(FrameTraceType type)

功能说明

核心用途：记录一个绘制命令的起始时间点
设计目的：通过栈式管理支持嵌套绘制命令的追踪，最外层命令记录实际采集数据
使用场景：每个绘制操作开始时调用，与 FrameTraceEnd 配对使用

入参

名称	参数类型	详细说明	约束取值范围
type	FrameTraceType	绘制命令类型	FrameTraceType 枚举值

FrameTraceEnd

void FrameTraceEnd(FrameTraceType type, const Rect *rect = nullptr)

功能说明

核心用途：记录一个绘制命令的结束时间点与关联绘制区域
设计目的：在最外层绘制命令退出时记录耗时与区域信息，支持 HW_DRAW_PATH 类型的自动替换
使用场景：每个绘制操作结束时调用，与 FrameTraceStart 配对使用

入参

名称	参数类型	详细说明	约束取值范围
type	FrameTraceType	绘制命令类型	FrameTraceType 枚举值
rect	const Rect *	入参只读指针，绘制区域矩形，可为 nullptr	nullptr 或指向有效 Rect 对象

ShowFrameTrace

void ShowFrameTrace()

功能说明

核心用途：将当前帧的追踪记录写入事件任务链中的 FrameRecord
设计目的：在事件和任务追踪均处于记录状态时，将帧绘制数据持久化到 TaskRecord 中
使用场景：一帧绘制完成后、EndTrace 之前调用

EventTraceStart

void EventTraceStart()

功能说明

核心用途：开始一次事件追踪，创建 EventRecord 并记录起始时间
设计目的：在追踪计数大于 0 时创建事件记录节点，追加到事件链表尾部
使用场景：事件处理开始时调用，与 EventTraceEnd 配对使用

EventTraceEnd

void EventTraceEnd()

功能说明

核心用途：结束一次事件追踪，记录结束时间
设计目的：在追踪计数归零时触发事件记录的展示与清理
使用场景：事件处理结束时调用，与 EventTraceStart 配对使用

TaskTraceStart

void TaskTraceStart()

功能说明

核心用途：在当前事件下开始一次任务追踪，创建 TaskRecord 并记录起始时间
设计目的：在事件追踪处于记录状态时创建任务记录节点，追加到当前事件的任务链表尾部
使用场景：任务执行开始时调用，与 TaskTraceEnd 配对使用

前置条件

事件追踪已通过 EventTraceStart 启动且处于记录状态（eventRecording_ == true）
事件链表非空（events_ != nullptr）

TaskTraceEnd

void TaskTraceEnd()

功能说明

核心用途：结束当前任务追踪，记录任务结束时间
设计目的：在事件和任务追踪均处于记录状态时，记录任务耗时
使用场景：任务执行结束时调用，与 TaskTraceStart 配对使用

前置条件

事件追踪已启动且处于记录状态（eventRecording_ == true）
任务追踪已启动且处于记录状态（taskRecording_ == true）
事件链表非空（events_ != nullptr）
当前事件的任务链表非空（curEvt.tasks != nullptr）

Enumerations

FrameTraceType

enum class FrameTraceType {
    SW_DRAW_TRANSFORM = 0,
    SW_DRAW_IMGBLIT,
    HW_DRAW_IMGBLIT,
    HW_DRAW_PATH,
    HW_CLIP_IMGBYPATH,
    SW_DRAW_CUBICBEZIER,
    SW_DRAW_RECT,
    HW_DRAW_RECT,
    HW_DRAW_BLUR,
    SW_DRAW_LETTER,
    SW_DRAW_ARC,
    SW_DRAW_LINE,
    HW_DRAW_SUBMIT,
    HW_DRAW_FLUSH,
    HW_DRAW_WAIT,
    HW_DRAW_ARC_RECT,
    HW_DRAW_LINE,
    HW_DRAW_ARC,
    HW_DRAW_CUBICBEZIER,
    HW_DRAW_ELLIPSE,
    HW_DRAW_LIGHT,
    HW_DRAW_3D_CYLINDER,
    HW_DRAW_3D_MESH,
    HW_DRAW_3D_SPHERE,
    HW_DRAW_RAIN,
    DRAW_MAX
};

枚举成员	取值	描述
SW_DRAW_TRANSFORM	0	软件绘制变换
SW_DRAW_IMGBLIT	1	软件图像位块传送
HW_DRAW_IMGBLIT	2	硬件图像位块传送
HW_DRAW_PATH	3	硬件路径绘制
HW_CLIP_IMGBYPATH	4	硬件路径裁剪图像
SW_DRAW_CUBICBEZIER	5	软件三次贝塞尔曲线绘制
SW_DRAW_RECT	6	软件矩形绘制
HW_DRAW_RECT	7	硬件矩形绘制
HW_DRAW_BLUR	8	硬件模糊绘制
SW_DRAW_LETTER	9	软件文字绘制
SW_DRAW_ARC	10	软件圆弧绘制
SW_DRAW_LINE	11	软件线段绘制
HW_DRAW_SUBMIT	12	硬件提交
HW_DRAW_FLUSH	13	硬件刷新
HW_DRAW_WAIT	14	硬件等待
HW_DRAW_ARC_RECT	15	硬件圆角矩形绘制
HW_DRAW_LINE	16	硬件线段绘制
HW_DRAW_ARC	17	硬件圆弧绘制
HW_DRAW_CUBICBEZIER	18	硬件三次贝塞尔曲线绘制
HW_DRAW_ELLIPSE	19	硬件椭圆绘制
HW_DRAW_LIGHT	20	硬件光照绘制
HW_DRAW_3D_CYLINDER	21	硬件3D圆柱体绘制
HW_DRAW_3D_MESH	22	硬件3D网格绘制
HW_DRAW_3D_SPHERE	23	硬件3D球体绘制
HW_DRAW_RAIN	24	硬件雨滴效果绘制
DRAW_MAX	25	枚举边界值

FrameTracePathAttr

enum class FrameTracePathAttr : uint8_t {
    NONE = 0,
    FILL = 1,
    STROKE = 1 << 1,
    BOTH = (1 << 1) | 1,
};

枚举成员	取值	描述
NONE	0	无属性
FILL	1	填充属性
STROKE	2	描边属性
BOTH	3	填充与描边属性