《OGRE 3D 渲染引擎原理与架构》2.2 自定义可渲染对象

Renderable 是渲染队列里真正可画的单元:派生类必须实现 getMaterial/getRenderOperation/getWorldTransforms 三个纯虚方法,preRender/postRender 提供临渲染钩子,DEFAULT_PRIORITY=100 参与队列排序。lab 复现一个最小 Renderable 子类与把 Renderable 塞进队列的过程。

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 对象工厂与类型注册 。

继续阅读

探索更多技术文章

浏览归档,发现更多关于系统设计、工具链和工程实践的内容。

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析·向量数据库与 AI 检索内核》 · 目录与学习路径(45 篇)
  2. 《大规模分布式计算深入解析》15.3 自研向量引擎:可执行骨架与工程缺口
  3. 《大规模分布式计算深入解析》14.1 Milvus:组件架构、段管理与检索链路