2.2 自定义可渲染对象
2.1 讲了 MovableObject 是场景内容的容器,但它不是渲染的直接参与者。真正被渲染队列执行的是 Renderable:MovableObject::_updateRenderQueue 的职责就是造出零个或多个 Renderable 塞进队列。这一节看 OgreRenderable.h 的契约——一个自定义可渲染对象要实现什么、能覆写什么。
本章与站内既有内容的分工
卷二 5.x 从渲染队列内部讲了排序与合批;这里讲 Renderable 这个接口本身——队列里每个元素都必须满足的契约。卷三 1.x 的 Entity 内部就是「一个 MovableObject 带若干个 SubEntity(都是 Renderable)」,本节把它拆开。
Renderable 契约
类本身很小,重要的东西都在公开接口里。Renderable 不是纯虚类——getTechnique/preRender/postRender/getNumWorldTransforms 都有默认实现,只有三个方法必须由派生类给出:
// OgreMain/include/OgreRenderable.h:Renderable 类声明(v14.6.3 源码摘录,已删减)
class _OgreExport Renderable
{
public:
enum
{
DEFAULT_PRIORITY = 100
};
...
/** Retrieves a weak reference to the material this renderable object uses.
Note that the Renderable also has the option to override the getTechnique method
to specify a particular Technique to use instead of the best one available.
*/
virtual const MaterialPtr& getMaterial(void) const = 0;
...
/** Gets the render operation required to send this object to the frame buffer.
*/
virtual void getRenderOperation(RenderOperation& op) = 0;
...
/** Called just prior to the Renderable being rendered.
...
*/
virtual bool preRender(SceneManager* sm, RenderSystem* rsys)
{ (void)sm; (void)rsys; return true; }
/** Called immediately after the Renderable has been rendered.
*/
virtual void postRender(SceneManager* sm, RenderSystem* rsys)
{ (void)sm; (void)rsys; }
...
virtual void getWorldTransforms(Matrix4* xform) const = 0;
...
virtual uint16 getNumWorldTransforms(void) const { return 1; }
...
void setUseIdentityProjection(bool useIdentityProjection)
{
mUseIdentityProjection = useIdentityProjection;
}
...
};
三个纯虚方法与两个常用默认实现:
| 方法 | 类型 | 职责 |
|---|---|---|
getMaterial() | 纯虚 | 返回材质弱引用,队列据此确定 pass 状态与合批键 |
getRenderOperation(RenderOperation&) | 纯虚 | 把顶点/索引缓冲、操作类型、图元写进 RenderOperation,这是 RenderSystem::_render 的输入 |
getWorldTransforms(Matrix4*) | 纯虚 | 填充 1 个(或 GPU 顶点混合时多个)世界变换矩阵 |
getNumWorldTransforms() | 默认返回 1 | 用 GPU 顶点混合时覆写为矩阵个数(骨骼时返回 numBones + 1) |
preRender(sm, rsys) | 默认返回 true | 实际渲染前钩子;返回 false 可抑制自动渲染、自己渲染 |
postRender(sm, rsys) | 空实现 | 实际渲染后钩子,恢复 preRender 里改动的状态 |
getMaterial 的注释透露了分层:Renderable 默认走 getMaterial()->getBestTechnique(...),但派生类可以覆写 getTechnique 指定用某个具体 Technique——材质脚本系统(卷四 4 章)生成的多个技术就是这样被选中的。
DEFAULT_PRIORITY = 100 是队列排序的默认优先级。preRender 的长注释解释了 OGRE 的「延迟渲染器」本质:可见性发现与真正执行渲染是分开的,preRender 才是 Renderable 拿到「此刻就要画」的信号的时机——所有材质状态已设置好,只剩绑定缓冲、执行渲染;而 setUseIdentityProjection 是为 2D 覆盖层准备的(用 {-1, 1} 视图空间,跳过相机投影),普通 3D 对象不必动它。
Renderable 与渲染队列
MovableObject::_updateRenderQueue(RenderQueue* q) 里最常见的实现是调用 q->addRenderable(this)——Entity 的 SubEntity 就是这么进的队列。队列收到一个 Renderable 后并不立即画,而是等帧内所有对象提交完,再按优先级/材质/距离统一排序执行。这就是 2.1 小结那句「_updateRenderQueue 是场景对象与渲染之间的桥」的完整含义。
源码定位
OgreMain/include/OgreRenderable.h:Renderable类声明(63)、DEFAULT_PRIORITY(66-69)、构造函数(72-78)、getMaterial(83)、getTechnique(87-89)、getRenderOperation(92)、_getMaterialLodIndex(96)、preRender(120-126)、postRender(131-134)、getWorldTransforms(144)、getNumWorldTransforms(156-158)、setUseIdentityProjection(167-170)、setUseIdentityView(173-176)
上游引用固定到 OGRE v14.6.3 源码 。
可运行产物:C++ 最小验证
下面用纯 C++ 复现 Renderable 契约:三个纯虚方法、默认优先级、preRender/postRender 钩子、identity 投影开关,以及把 Renderable 塞进渲染队列。它与 src/02-2-custom-renderable.cpp 逐字节一致:
// file: src/02-2-custom-renderable.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/02-2-custom-renderable.cpp -o bin/02-2-custom-renderable && ./bin/02-2-custom-renderable
//
// 复现 Renderable 契约(对应 OgreMain/include/OgreRenderable.h 63- 的类声明、
// 66-69 的 DEFAULT_PRIORITY、83/92/144 的 getMaterial/getRenderOperation/getWorldTransforms、
// 120-134 的 preRender/postRender、156 的 getNumWorldTransforms、167-176 的 identity 开关):
// 派生类必须实现三个纯虚方法;preRender 返回 false 可抑制自动渲染;
// Renderable 被塞进渲染队列等待统一执行。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"
#include <cstdint>
#include <string>
#include <vector>
namespace ogre_repro {
// 对应 Matrix4:极简 4x4(行主序)
struct Matrix4 {
float data[16] = {1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1};
};
// 对应 Material:极简
class Material {
public:
explicit Material(std::string n) : name(std::move(n)) {}
std::string name;
};
// 对应 RenderOperation:极简(真实类含顶点/索引缓冲与图元类型)
struct RenderOperation {
int vertexCount = 0;
};
// 对应 OgreRenderable.h 63-:抽象可渲染对象
class RenderableBase {
public:
static constexpr int DEFAULT_PRIORITY = 100; // 对应 66-69 的 enum
virtual ~RenderableBase() {}
virtual const Material* getMaterial() const = 0; // 83
virtual void getRenderOperation(RenderOperation& op) = 0; // 92
virtual void getWorldTransforms(Matrix4* xform) const = 0; // 144
virtual uint16_t getNumWorldTransforms() const { return 1; } // 156 默认
virtual bool preRender() { return true; } // 120 默认放行
virtual void postRender() {} // 126
void setUseIdentityProjection(bool v) { mUseIdentityProjection = v; } // 167
bool getUseIdentityProjection() const { return mUseIdentityProjection; }
protected:
bool mUseIdentityProjection = false;
};
// 自定义可渲染对象:实现纯虚契约
class SimpleRenderable : public RenderableBase {
public:
const Material* getMaterial() const override { return mMaterial; }
void getRenderOperation(RenderOperation& op) override { op = mOp; }
void getWorldTransforms(Matrix4* xform) const override {
xform->data[0] = mScale; // 简化:只反映一个缩放
}
bool preRender() override {
mPreRenderCalls++;
return mAllowAutoRender;
}
void postRender() override { mPostRenderCalls++; }
Material* mMaterial = nullptr;
RenderOperation mOp;
float mScale = 1.f;
bool mAllowAutoRender = true;
int mPreRenderCalls = 0;
int mPostRenderCalls = 0;
};
// 极简渲染队列:收集 Renderable,不立即执行(对应 OgreRenderQueue)
class RenderQueue {
public:
void addRenderable(RenderableBase* r) { mItems.push_back(r); }
size_t size() const { return mItems.size(); }
std::vector<RenderableBase*> mItems;
};
} // namespace ogre_repro
int main() {
using namespace ogre_repro;
// 默认优先级
CHECK_EQ(RenderableBase::DEFAULT_PRIORITY, 100);
// 契约:三个纯虚方法
SimpleRenderable sr;
Material mat("SimpleMat");
sr.mMaterial = &mat;
sr.mOp.vertexCount = 36;
CHECK(sr.getMaterial() == &mat);
RenderOperation out;
sr.getRenderOperation(out);
CHECK_EQ(out.vertexCount, 36);
// getNumWorldTransforms 不覆写时默认 1
CHECK_EQ(sr.getNumWorldTransforms(), uint16_t(1));
// 世界变换:填充缩放
Matrix4 xf;
sr.mScale = 2.f;
sr.getWorldTransforms(&xf);
CHECK_EQ(xf.data[0], 2.f);
// identity projection 开关
CHECK(!sr.getUseIdentityProjection());
sr.setUseIdentityProjection(true);
CHECK(sr.getUseIdentityProjection());
// preRender/postRender 钩子
CHECK(sr.preRender()); // 默认放行自动渲染
CHECK_EQ(sr.mPreRenderCalls, 1);
sr.postRender();
CHECK_EQ(sr.mPostRenderCalls, 1);
sr.mAllowAutoRender = false;
CHECK(!sr.preRender()); // 返回 false 抑制自动渲染
CHECK_EQ(sr.mPreRenderCalls, 2);
// 塞进渲染队列
RenderQueue q;
q.addRenderable(&sr);
q.addRenderable(&sr);
CHECK_EQ(q.size(), size_t(2));
return lab::report("2.2 自定义可渲染对象");
}
本机实测(Apple clang 16,clang++ -std=c++20 -Wall):编译通过(零警告),断言 13/13 通过。
小结
Renderable是渲染队列真正执行的单元,三个纯虚方法:getMaterial/getRenderOperation/getWorldTransforms。getNumWorldTransforms默认返回 1,GPU 顶点混合/骨骼时覆写为numBones + 1。DEFAULT_PRIORITY = 100参与队列排序;preRender返回false可抑制自动渲染。setUseIdentityProjection/setUseIdentityView为 2D 覆盖层准备,普通 3D 对象不用动。MovableObject::_updateRenderQueue把Renderable塞进RenderQueue,队列统一排序后再执行。
阅读导航:上一节:2.1 自定义可移动对象 · 下一节:2.3 对象工厂与类型注册 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。