14.2 渲染一致性测试
单元测试只能证明「函数算对了」,证明不了「渲染出来对不对」。OGRE 的渲染一致性测试(Tests/VisualTests/)走的是另一条路:真的创建一个窗口、真的构建场景、真的把画面截成图片,让人或后续工具去比对。这类测试的价值在于捕捉跨后端、跨版本的行为漂移——同一个 ogrehead.mesh 配同一套天空盒,在 GL3Plus 与 Vulkan 下应该渲染出可比较的结果。
本章与站内既有内容的分工
helio 四卷的 L1/L2/L3 门禁验证「代码能编译、机制能跑」;这里解析 OGRE 面向「画面」的测试基建:VisualTest 基类怎么把「每个测试 = 一个可运行场景」抽象出来,子类只写 setupContent,基类统一管相机、视口、截图与资源清理。
VisualTest:测试即场景
VisualTest.h 把测试类直接继承自 OgreBites::Sample——渲染一致性测试复用 Samples 的运行骨架(窗口、输入、主循环),只需在几个虚函数里填空:
// Tests/VisualTests/Common/include/VisualTest.h:VisualTest 基类(v14.6.3 源码摘录,已删减)
// resource group that will be automatically unloaded after the close of the sample
#define TRANSIENT_RESOURCE_GROUP "VisualTestTransient"
#define ASSETS_RESOURCE_GROUP "General"
/** The base class for a visual test scene */
class VisualTest : public OgreBites::Sample
{
public:
VisualTest()
{
mInfo["Category"] = "Tests";
mInfo["Thumbnail"] = "thumb_visual_tests.png";
Ogre::ResourceGroupManager& rgm = Ogre::ResourceGroupManager::getSingleton();
if (!rgm.resourceGroupExists(TRANSIENT_RESOURCE_GROUP))
rgm.createResourceGroup(TRANSIENT_RESOURCE_GROUP, true);
}
/** set up the camera and viewport */
void setupView() override
{
mCamera = mSceneMgr->createCamera("MainCamera");
mCameraNode = mSceneMgr->getRootSceneNode()->createChildSceneNode();
mCameraNode->attachObject(mCamera);
mCameraNode->setFixedYawAxis(true); // fix lookAt calls
mViewport = mWindow->addViewport(mCamera);
mCamera->setAspectRatio((Ogre::Real)mViewport->getActualWidth() / (Ogre::Real)mViewport->getActualHeight());
mCamera->setNearClipDistance(0.5f);
mCamera->setFarClipDistance(10000.f);
}
...
bool keyPressed(const OgreBites::KeyboardEvent& evt) override
{
if (evt.keysym.sym == OgreBites::SDLK_F6)
mCamera->getViewport()->getTarget()->writeContentsToTimestampedFile("screenshot", ".png");
return true;
}
protected:
// a list of animation states to automatically update
std::vector<Ogre::AnimationState*> mAnimStateList;
};
基类替每个测试做好的事:
- 瞬态资源组:构造时若
TRANSIENT_RESOURCE_GROUP不存在就创建,测试关闭时整组清理(unloadResources里clearResourceGroup)——测试之间不互相污染资源。 - 标准相机:
setupView统一建相机、挂到相机节点、固定偏航轴、设近远裁剪面——每个测试从同一套视角参数出发,截图才可比。 - F6 手动截图:任意时刻按 F6 把当前帧写入带时间戳的 PNG,
writeContentsToTimestampedFile("screenshot", ".png")是引擎级 API,跨后端一致。 - 动画推进:
frameStarted里统一把mAnimStateList里的动画状态addTime(evt.timeSinceLastFrame)——需要动画的测试只管把状态塞进列表。
一个真实的渲染测试
子类的工作量被压缩到极致。CubeMappingTest.cpp 是 VTests 里最短的测试之一:
// Tests/VisualTests/VTests/src/CubeMappingTest.cpp:setupContent(v14.6.3 源码摘录,已删减)
CubeMappingTest::CubeMappingTest()
{
mInfo["Title"] = "VTests_CubeMapping";
mInfo["Description"] = "Tests basic fixed-function cube mapping.";
addScreenshotFrame(10);
}
//---------------------------------------------------------------------------
void CubeMappingTest::setupContent()
{
mSceneMgr->setSkyBox(true, "Examples/MorningSkyBox");
Ogre::SceneNode* node = mSceneMgr->getRootSceneNode()->createChildSceneNode();
Ogre::Entity* head = mSceneMgr->createEntity("ogrehead.mesh");
node->attachObject(head);
head->setMaterialName("Examples/MorningCubeMap");
mCameraNode->setPosition(0,0,100);
}
两个钩子完成了整个测试:
| 钩子 | 做什么 | 对应源码 |
|---|---|---|
| 构造函数 | 填 mInfo 元数据(标题/描述),addScreenshotFrame(10) 声明「第 10 帧截图」 | CubeMappingTest.cpp:31-36 |
setupContent() | 摆场景:开天空盒、建节点、建实体、挂材质、挪相机 | CubeMappingTest.cpp:39-47 |
addScreenshotFrame(10) 很关键:它把「第几帧画面应该稳定可测」显式化。场景初始化、资源加载、材质解析都在头几帧完成,等到第 10 帧才截图,避免「截到半初始化画面」。这就是渲染一致性测试与普通 demo 的分水岭——每个测试声明自己的「可断言时刻」。
一致性从哪来
渲染一致性测试的名字里有「一致性」,它指两件事:
- 跨后端一致:同一测试在 GL3Plus、Vulkan、Metal 上跑,截图应视觉一致(允许数值级差异)。后端差异若导致画面结构不同,测试即失败。
- 跨版本一致:OGRE 自己迭代时,同一测试的旧截图是新版本的回归基准——画面变了,说明渲染行为变了,需要人确认是 bug 还是有意变更。
VisualTest 的 mInfo["Category"] = "Tests" 与统一 setupView 视角,就是为了让这套比对尽量「只差渲染器、不差视角」。
视觉测试的基线比较
flowchart TD
A["固定样例、后端、分辨率"] --> B["推进到指定帧"]
B --> C["读取渲染结果"]
C --> D{"有对应基线?"}
D -->|"有"| E["比较画面并记录差异"]
D -->|"无"| F["生成候选基线,人工审核"]
E --> G["按测试条件判断回归"]
视觉基线和跨后端契约
同一后端的视觉测试固定场景、输出尺寸、时间和资产后,可按一致的像素差异规则比较。跨后端先确认对象可见性、目标写入与输出形状,再按后端记录独立基线。
保存运行命令、设备信息、能力、输入资产和结果。Tiny 读回断言证明本样例的几何可见性,其他目标格式和 shader 路径需要额外实测。
按证据判断一条渲染回归
flowchart TD
A["固定资产、时间、分辨率与相机"] --> B["记录后端、平台及能力"]
B --> C["采集对象、提交、读写和像素"]
C --> D{"与基线同平台同后端?"}
D -->|"是"| E["检查像素差异和运行语义"]
D -->|"否"| F["先检查可见性和提交等语义契约"]
F --> G["为该后端单独记录图像基线"]
E --> R["保留日志、画面与复现命令"]
G --> R
源码定位
Tests/VisualTests/Common/include/VisualTest.h:#define TRANSIENT_RESOURCE_GROUP "VisualTestTransient"(38)、class VisualTest : public OgreBites::Sample(42)、VisualTest()构造(46-53)、setupView() override(56-66)、keyPressedF6 截图(84-90)、std::vector<Ogre::AnimationState*> mAnimStateList(94)Tests/VisualTests/VTests/src/CubeMappingTest.cpp:CubeMappingTest::CubeMappingTest()(31-36)、addScreenshotFrame(10)(35)、void CubeMappingTest::setupContent()(39-47)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现 VisualTest 的骨架:元数据、截图帧调度、内容注册、F6 手动截图、瞬态资源组幂等。它与 src/ogre-ext-14-2-render-test.cpp 逐字节一致:
// file: src/ogre-ext-14-2-render-test.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-14-2-render-test.cpp -o bin/ogre-ext-14-2-render-test && ./bin/ogre-ext-14-2-render-test
//
// 复现 VisualTest 渲染一致性测试骨架(对应 Tests/VisualTests 的
// Common/include/VisualTest.h 与 VTests/src/CubeMappingTest.cpp):
// mInfo 元数据 + addScreenshotFrame(n) 指定截图帧;
// setupContent 注册场景内容(天空盒/网格/材质);
// 帧回调在第 n 帧触发截图,F6 键手动截图;
// TRANSIENT_RESOURCE_GROUP 只在首次构造时创建一次。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 TRANSIENT_RESOURCE_GROUP(VisualTest.h 38)
const char* kTransientGroup = "VisualTestTransient";
// 对应 Ogre::ResourceGroupManager 的最小子集
struct ResourceGroupManager {
std::vector<std::string> groups;
bool resourceGroupExists(const std::string& g) const {
for (const auto& x : groups)
if (x == g) return true;
return false;
}
void createResourceGroup(const std::string& g, bool /*autoload*/) {
if (!resourceGroupExists(g)) groups.push_back(g);
}
};
static ResourceGroupManager g_rgm;
// 对应 keyPressed 的 SDLK_F6
constexpr int kSDLK_F6 = 0x66;
struct KeyEvent {
int sym;
};
// 对应 VisualTest 基类(VisualTest.h 42-95)
class VisualTest {
public:
VisualTest() {
if (!g_rgm.resourceGroupExists(kTransientGroup))
g_rgm.createResourceGroup(kTransientGroup, true);
}
// 对应 mInfo["Title"] / mInfo["Description"]
std::string title;
std::string description;
// 对应 addScreenshotFrame(10)
int screenshotFrame = -1;
void addScreenshotFrame(int f) { screenshotFrame = f; }
// 帧回调(对应 frameStarted):到达截图帧时标记
uint32_t frame = 0;
bool screenshotTaken = false;
void frameRendered() {
++frame;
screenshotTaken = (static_cast<int>(frame) == screenshotFrame);
}
// 对应 setupContent:子类覆盖注册场景内容
virtual void setupContent() {}
};
// 对应 CubeMappingTest(CubeMappingTest.cpp 31-47)
struct CubeMappingTest : VisualTest {
bool skyBox = false;
std::string meshName;
std::string materialName;
CubeMappingTest() {
title = "VTests_CubeMapping";
description = "Tests basic fixed-function cube mapping.";
addScreenshotFrame(10);
}
void setupContent() override {
skyBox = true;
meshName = "ogrehead.mesh";
materialName = "Examples/MorningCubeMap";
}
};
// 对应 VisualTest::keyPressed:F6 手动截图
bool handleKey(const VisualTest& /*vt*/, const KeyEvent& ev, bool& manualShot) {
if (ev.sym == kSDLK_F6) {
manualShot = true;
return true;
}
return false;
}
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 构造:注册瞬态资源组 + 元数据
CubeMappingTest test;
CHECK(g_rgm.resourceGroupExists(kTransientGroup));
CHECK(test.title == "VTests_CubeMapping");
CHECK(test.description == "Tests basic fixed-function cube mapping.");
CHECK(test.screenshotFrame == 10);
// setupContent:注册场景内容
test.setupContent();
CHECK(test.skyBox);
CHECK(test.meshName == "ogrehead.mesh");
CHECK(test.materialName == "Examples/MorningCubeMap");
// 帧推进:前 9 帧不截图,第 10 帧触发
for (uint32_t i = 0; i < 9; ++i) test.frameRendered();
CHECK(!test.screenshotTaken);
test.frameRendered();
CHECK(test.screenshotTaken);
CHECK_EQ(test.frame, static_cast<uint32_t>(10));
// 第 11 帧不再触发
test.frameRendered();
CHECK(!test.screenshotTaken);
// F6 手动截图
bool manual = false;
KeyEvent f6{kSDLK_F6};
CHECK(handleKey(test, f6, manual));
CHECK(manual);
// 其他键不触发
manual = false;
KeyEvent other{0x65};
CHECK(!handleKey(test, other, manual));
CHECK(!manual);
// 资源组幂等:再次构造不重复创建
CubeMappingTest second;
CHECK(g_rgm.resourceGroupExists(kTransientGroup));
CHECK_EQ(static_cast<int>(g_rgm.groups.size()), 1);
return lab::report("14.2 渲染一致性测试");
}
本机实测(Apple clang,clang++ -std=c++20 -Wall):编译零警告,断言 17/17 通过。
小结
- 渲染一致性测试的类继承自
OgreBites::Sample,复用窗口/输入/主循环,子类只填空。 - 基类统一:瞬态资源组隔离、标准相机视角、动画状态推进、F6 手动截图。
addScreenshotFrame(n)把「第几帧可截图」显式化,避开半初始化画面。setupContent()用引擎 API 摆场景(天空盒、实体、材质),截图结果跨后端/跨版本可比。- 一致性 = 跨后端一致 + 跨版本回归基准,画面漂移由人确认是 bug 还是有意变更。
阅读导航:上一节:14.1 测试体系 · 下一节:14.3 回归与验证 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。