nvg-resolution-mode
【必读】NanoVG 项目分辨率模式选择指南。在调用 nvgBeginFrame 前必须先确定分辨率模式,否则高 DPI 屏幕会出现 UI 过小/模糊问题。 SKIP when: 项目没有任何 raw NanoVG 调用(纯 urhox-libs/UI 组件项目、纯 3D 游戏 + UI HUD)。 MUST trigger when: 项目包含 raw NanoVG 调用(nvgCreate/n
SKILL.md.installer/skills/nvg-resolution-mode/SKILL.md
GitHubNanoVG 分辨率模式编写范式
本指南面向 AI 辅助编程优化,默认选择优先保证鲁棒性和首次成功率。
三种模式是递进叠加关系:C(无缩放)→ B(+DPR)→ A(+设计缩放)
核心变量
local physW, physH = graphics:GetWidth(), graphics:GetHeight() -- 物理分辨率
local dpr = graphics:GetDPR() -- 设备像素比(1.0/2.0/3.0)
local logicalW, logicalH = physW / dpr, physH / dpr -- 系统逻辑分辨率
关系:系统逻辑分辨率 = 物理分辨率 / DPR
模式选择
默认规则:除非明确提供了设计分辨率,否则始终选择模式 B,以迎合AI习惯。
| 条件 | 模式 | 基于 | 布局推荐 |
|---|---|---|---|
| 明确了设计分辨率 | A(设计分辨率) | B + 设计缩放 | 绝对布局 / 响应式 |
| 未明确设计分辨率(默认) | B(系统逻辑分辨率) | C + DPR 修正 | 响应式 |
| 不建议,仅当用户明确要求 | C(物理像素) | 基础 | 响应式 |
识别设计分辨率:
- "按 1080P 做"、"720P 适配"、"1920×1080"、"设计尺寸是..." → 模式 A
决策场景:
- 应用/工具向(模拟器、仪表盘、编辑器)→ B
- 游戏向 → 视需求而定:
- 默认/顺 AI(成功率优先、快速出原型)→ B
- 进阶需求(UI 密集、逻辑依赖 2D 坐标)→ A
模式 C:物理像素(基础)
基础代码,无任何缩放。仅当用户明确要求时使用,高 DPI 屏幕上内容显小。不建议直接使用。
nvgBeginFrame(vg, physW, physH, 1.0)
-- 坐标 1 单位 = 1 物理像素
-- 坐标范围:(0,0) 到 (physW, physH)
nvgEndFrame(vg)
输入坐标:引擎返回物理像素,无需转换。
模式 B:系统逻辑分辨率(默认)
在 C 基础上加 DPR 修正,高 DPI 屏幕清晰。未明确设计分辨率时的默认选择,必须用响应式布局。
nvgBeginFrame(vg, logicalW, logicalH, dpr) -- 改用逻辑分辨率 + pixelRatio=dpr
-- 坐标 1 单位 = 1 逻辑像素 = dpr 个物理像素
-- 坐标范围:(0,0) 到 (logicalW, logicalH)
nvgEndFrame(vg)
输入坐标:logicalX = inputX / dpr
完整示例
local physW, physH = graphics:GetWidth(), graphics:GetHeight()
local dpr = graphics:GetDPR()
local logicalW, logicalH = physW / dpr, physH / dpr
function HandleNanoVGRender()
nvgBeginFrame(vg, logicalW, logicalH, dpr)
-- 响应式布局:百分比/锚点定位
local padding = 20
local btnW, btnH = 120, 40
-- 右上角按钮
nvgBeginPath(vg)
nvgRect(vg, logicalW - btnW - padding, padding, btnW, btnH)
nvgFillColor(vg, nvgRGBA(100, 150, 200, 255))
nvgFill(vg)
nvgEndFrame(vg)
end
-- 窗口变化
SubscribeToEvent("ScreenMode", function()
physW, physH = graphics:GetWidth(), graphics:GetHeight()
dpr = graphics:GetDPR()
logicalW, logicalH = physW / dpr, physH / dpr
end)
模式 A:设计分辨率(进阶)
使用前提(至少满足一项):
- 用户提供了设计尺寸(如:1920x1080、1080P、720P等)
- UI 大量使用固定坐标布局
- 不同屏幕下核心内容必须视觉比例一致
- 给定的参考项目满足以上几点
否则,留在模式 B。
在 B 基础上加 设计缩放。
设计尺寸定义
| 写法 | 示例 | 说明 |
|---|---|---|
| 单分量(简化) | designSize = 1080 |
等价于 designW = designH = 1080 |
| 双分量(完整) | designW, designH = 1920, 1080 |
完整设计尺寸 |
核心公式
-- 输入(二选一)
local designSize = 1080 -- 单分量
local designW, designH = designSize, designSize
-- 或
local designW, designH = 1920, 1080 -- 双分量
-- 缩放因子(CONTAIN:设计区域完整显示,设计区域外需要响应式布局)
local scale = math.min(logicalW / designW, logicalH / designH)
-- 缩放因子(COVER:设计区域填满屏幕,边缘裁剪,不常用)
-- local scale = math.max(logicalW / designW, logicalH / designH)
-- 设计空间下的屏幕尺寸和居中偏移
local screenDesignW = logicalW / scale
local screenDesignH = logicalH / scale
local designOffsetX = (screenDesignW - designW) / 2
local designOffsetY = (screenDesignH - designH) / 2
布局方式
可自由选择或混合,常用 “纯响应式” 或 “绝对布局” + “部分响应式”。
| 布局 | 代码 | 坐标范围 |
|---|---|---|
| 响应式(屏幕空间) | 只用 nvgScale |
(0,0) 到 (screenDesignW, screenDesignH) |
| 绝对布局(设计空间) | nvgScale + nvgTranslate |
(0,0) 到 (designW, designH) |
混合布局说明 在设计区域内绝对布局时,设计区域外的内容仍需响应式处理(背景填充去黑边、全屏遮罩、屏幕边缘停靠等)。
核心代码:
nvgBeginFrame(vg, logicalW, logicalH, dpr)
nvgScale(vg, scale, scale)
-- 坐标范围:(0,0) 到 (screenDesignW, screenDesignH)
-- [响应式] 屏幕空间,用 screenDesignW/H 定位
DrawRectWrap(vg, screenDesignW - 220, 20, 200, 60) -- 右上角
-- 进入设计空间
nvgTranslate(vg, designOffsetX, designOffsetY)
-- [绝对布局] 设计空间内,边界 (0,0)-(designW, designH)
DrawRectWrap(vg, 100, 50, 200, 80) -- 设计稿坐标
-- [响应式] 临时切回屏幕空间,右上角停靠
nvgTranslate(vg, -designOffsetX, -designOffsetY)
DrawRectWrap(vg, screenDesignW - 200, 20, 180, 60)
nvgTranslate(vg, designOffsetX, designOffsetY)
nvgEndFrame(vg)
输入坐标转换
| 布局 | 转换公式 |
|---|---|
| 响应式(屏幕空间) | designX = inputX / dpr / scale |
| 绝对布局(设计空间) | designX = inputX / dpr / scale - designOffsetX |
完整示例
local physW, physH = graphics:GetWidth(), graphics:GetHeight()
local dpr = graphics:GetDPR()
local logicalW, logicalH = physW / dpr, physH / dpr
-- 输入(二选一)
local designW, designH = 1920, 1080 -- 双分量
-- local designSize = 1080; designW, designH = designSize, designSize -- 单分量
local scale, screenDesignW, screenDesignH, designOffsetX, designOffsetY
local function RecalcLayout()
scale = math.min(logicalW / designW, logicalH / designH)
screenDesignW = logicalW / scale
screenDesignH = logicalH / scale
designOffsetX = (screenDesignW - designW) / 2
designOffsetY = (screenDesignH - designH) / 2
end
RecalcLayout()
function HandleNanoVGRender()
nvgBeginFrame(vg, logicalW, logicalH, dpr)
nvgScale(vg, scale, scale)
-- [响应式] 背景填满屏幕(用 screenDesignW/H)
nvgBeginPath(vg)
nvgRect(vg, 0, 0, screenDesignW, screenDesignH)
nvgFillColor(vg, nvgRGBA(30, 30, 40, 255))
nvgFill(vg)
-- 进入设计空间
nvgTranslate(vg, designOffsetX, designOffsetY)
-- [绝对布局] 设计空间内,边界 (0,0)-(designW, designH)
nvgBeginPath(vg)
nvgRect(vg, 50, 50, 300, 30)
nvgFillColor(vg, nvgRGBA(255, 0, 0, 200))
nvgFill(vg)
-- [响应式] 临时切回屏幕空间,右上角停靠
nvgTranslate(vg, -designOffsetX, -designOffsetY)
nvgBeginPath(vg)
nvgRect(vg, screenDesignW - 200, 20, 180, 60)
nvgFillColor(vg, nvgRGBA(100, 150, 200, 255))
nvgFill(vg)
nvgTranslate(vg, designOffsetX, designOffsetY)
nvgEndFrame(vg)
end
SubscribeToEvent("ScreenMode", function()
physW, physH = graphics:GetWidth(), graphics:GetHeight()
dpr = graphics:GetDPR()
logicalW, logicalH = physW / dpr, physH / dpr
RecalcLayout()
end)
可轻松从 B 升级到 A(DPR 巧妙抵消)
模式 A 基于 B 实现,只需加 nvgScale(响应式)或 nvgScale + nvgTranslate(绝对布局)。DPR 在计算中被约掉(scale × dpr = physW / designSize),本质是设计坐标到物理像素的直接映射。
输入坐标转换汇总
引擎输入 API 返回物理像素:
-- 桌面端
local mousePos = input:GetMousePosition()
local inputX, inputY = mousePos.x, mousePos.y
-- 移动端(触摸事件中)
local inputX = eventData:GetInt("X")
local inputY = eventData:GetInt("Y")
| 模式 | 转换公式 |
|---|---|
| C(物理像素) | 无需转换 |
| B(系统逻辑分辨率) | logicalX = inputX / dpr |
| A 响应式(屏幕空间) | designX = inputX / dpr / scale |
| A 绝对布局(设计空间) | designX = inputX / dpr / scale - designOffsetX |
问题诊断
| 症状 | 可能原因 | 解决方案 |
|---|---|---|
| 高 DPI 屏幕 UI 过小 | 使用了模式 C(无 DPR 修正) | 改用模式 B 或 A |
| UI 模糊/不清晰 | pixelRatio 设置错误 | 确保 nvgBeginFrame 的 pixelRatio = dpr |
| 点击/触摸位置不准 | 输入坐标未转换 | 检查输入坐标转换公式 |
| 窗口缩放后 UI 错位 | 未监听 ScreenMode 事件 | 添加 ScreenMode 事件重算变量 |
| 设计稿内容被裁剪 | 使用了 COVER 模式 | 改用 CONTAIN(math.min) |
备注
本文档适用于包含 raw NanoVG 调用的项目。引擎渲染顺序为 raw NanoVG → UI Widget 树 → 虚拟摇杆,urhox-libs/UI 在 Widget 层渲染,内部已自动处理分辨率缩放,不需要本 Skill。但如果项目同时使用 raw NanoVG(如 2D 游戏图形)+ UI 组件(如 HUD),仍需本 Skill 配置 NanoVG 部分的分辨率。
最后更新: 2026-02-09