鸿蒙开发-想控制帧率和HDR显示？DisplaySync和hdrCapability怎么用-平芜编程栈

想控制帧率和 HDR 显示？DisplaySync 和 hdrCapability 怎么用

做游戏或者图形应用时，有两个常见的需求：

控制帧率：游戏在不同场景下需要不同的帧率——菜单界面 30fps 就够了，战斗场景需要 60fps 甚至更高。
HDR 显示：让画面有更高的亮度范围和色彩表现，暗处更暗，亮处更亮。

HarmonyOS 提供了两个 Kit 来处理这些需求：DisplaySync（可变帧率）和hdrCapability（HDR 能力）。

下面是 DisplaySync 帧率控制的整体流程：

DisplaySync：控制帧率

DisplaySync让你可以指定 UI 自绘制内容的帧率。一般用于自绘制 UI（比如 Canvas 渲染的游戏画面），而不是普通的 ArkUI 组件。

创建 DisplaySync

import{displaySync}from'@kit.ArkGraphics2D';letdisplaySync:displaySync.DisplaySync=displaySync.create();

设置帧率范围

letrange:displaySync.ExpectedFrameRateRange={expected:60,// 期望帧率min:30,// 最低帧率max:120// 最高帧率};displaySync.setExpectedFrameRateRange(range);

三个参数：

expected：期望帧率（fps）
min：最低帧率（系统会尽量不低于这个值）
max：最高帧率（系统不会超过这个值）

为什么要设范围而不是精确值？因为系统需要根据设备性能、温度、电量等因素动态调整。你告诉系统"我期望 60fps，但最低能接受 30"，系统就会在这个范围内尽量满足你。

订阅帧回调

displaySync.on('frame',(frameInfo:displaySync.IntervalInfo)=>{// frameInfo.timestamp：当前帧到达的时间（纳秒）// frameInfo.targetTimestamp：下一帧预期到达的时间（纳秒）// 在这里更新游戏状态、渲染画面this.updateGameLogic();this.renderFrame();});// 启动回调displaySync.on('frame',callback);

IntervalInfo提供了两个时间戳：

timestamp：当前帧的时间
targetTimestamp：下一帧的预期时间

你可以用这两个时间戳来计算帧间隔（deltaTime），实现平滑的动画和物理模拟：

letdeltaTime=(frameInfo.targetTimestamp-frameInfo.timestamp)/1e9;// 转成秒this.moveCharacter(deltaTime);

停止帧回调

displaySync.off('frame');

实际应用场景

游戏主循环：

// 战斗场景：高帧率displaySync.setExpectedFrameRateRange({expected:120,min:60,max:120});// 菜单界面：低帧率省电displaySync.setExpectedFrameRateRange({expected:30,min:30,max:60});// 过场动画：固定帧率displaySync.setExpectedFrameRateRange({expected:24,min:24,max:24});

动态调整：

// 根据设备温度动态调整if(deviceTemperature>40){displaySync.setExpectedFrameRateRange({expected:30,min:30,max:60});}else{displaySync.setExpectedFrameRateRange({expected:60,min:60,max:120});}

hdrCapability：HDR 能力查询

选择 HDR 格式时，可以参考下面的优先级决策流程：

HDR（High Dynamic Range，高动态范围）让画面有更广的亮度和色彩范围。普通 SDR 画面的亮度范围是 0-100 nit，HDR 可以达到 1000 nit 甚至更高——阳光更刺眼，阴影更深邃。

hdrCapability模块不提供 HDR 渲染能力，而是提供查询设备支持哪些 HDR 格式的能力。你可以根据设备支持的格式来决定用哪种 HDR 方案。

HDR 格式枚举

import{hdrCapability}from'@kit.ArkGraphics2D';

格式	值	说明
NONE	0	不支持 HDR
VIDEO_HLG	1	视频 HLG 格式
VIDEO_HDR10	2	视频 HDR10 格式
VIDEO_HDR_VIVID	3	视频 HDR Vivid 格式（华为自研）
IMAGE_HDR_VIVID_DUAL	4	图片 HDR Vivid，双 JPEG 存储
IMAGE_HDR_VIVID_SINGLE	5	图片 HDR Vivid，单 HEIF 存储
IMAGE_HDR_ISO_DUAL	6	图片 HDR ISO，双 JPEG 存储
IMAGE_HDR_ISO_SINGLE	7	图片 HDR ISO，单 HEIF 存储
VIDEO_AIHDR	8	视频 AI HDR 格式（API 24+）

常见的 HDR 格式

HLG（Hybrid Log-Gamma）：BBC 和 NHK 联合开发的 HDR 标准，兼容 SDR 设备。适合广播电视。

HDR10：最普及的 HDR 标准，使用静态元数据。大部分 HDR 电视和显示器都支持。

HDR Vivid：华为自研的 HDR 标准，支持动态元数据，效果比 HDR10 更好。在华为设备上优先使用。

AIHDR：AI 增强的 HDR，通过 AI 算法把 SDR 内容转换成 HDR 效果。

如何使用

你一般不会直接调用hdrCapability的 API，而是在播放视频或显示图片时，根据设备支持的格式来选择内容：

// 伪代码：选择最佳 HDR 格式if(deviceSupports(VIDEO_HDR_VIVID)){playHDRVividVideo();}elseif(deviceSupports(VIDEO_HDR10)){playHDR10Video();}elseif(deviceSupports(VIDEO_HLG)){playHLGVideo();}else{playSDRVideo();}