《OGRE 3D 渲染引擎原理与架构》1.3 创建渲染目标

渲染目标用双表登记:mRenderTargets 按名、mPrioritisedRenderTargets 按优先级。attachRenderTarget 同时进两表,getRenderTarget 按名查,detach 同步移除并重置 active。_createRenderWindow 默认实现先查重名再登记。lab 复现双表登记与销毁链。

1.3 创建渲染目标

一个窗口、一张渲染到纹理的贴图、一个多渲染目标——它们都是一种 RenderTarget。这一节看渲染目标在 RenderSystem 里怎么登记、怎么按名取回、怎么销毁。OGRE 用「双表 + 名字即身份」管理它们,模式与卷一 6.2 的 ArchiveManager 如出一辙。

本章与站内既有内容的分工

卷一 1.3 讲过 CMake 构建,这里是渲染目标的登记与生命周期;与卷一 11.3 相机的 mCameras map 登记同一范式,但多了「优先级分组」。

attachRenderTarget:双表登记

// OgreMain/src/OgreRenderSystem.cpp:RenderSystem::attachRenderTarget(v14.6.3 源码摘录,已删减)
    void RenderSystem::attachRenderTarget( RenderTarget &target )
    {
        assert( target.getPriority() < OGRE_NUM_RENDERTARGET_GROUPS );

        mRenderTargets.emplace(target.getName(), &target);
        mPrioritisedRenderTargets.emplace(target.getPriority(), &target);
    }

一张目标同时进入两张表:

表键用途
mRenderTargets名字getRenderTarget(name) 按名快速查找
mPrioritisedRenderTargets优先级渲染顺序:一帧里按优先级依次更新所有目标

assert(target.getPriority() < OGRE_NUM_RENDERTARGET_GROUPS) 是哨兵——优先级被限制在固定分组数内(窗口、RTT 等分属不同组),保证排序语义稳定。

按名取回与摘除

// OgreMain/src/OgreRenderSystem.cpp:RenderSystem::getRenderTarget/detachRenderTarget(v14.6.3 源码摘录,已删减)
    RenderTarget * RenderSystem::getRenderTarget( const String &name )
    {
        RenderTargetMap::iterator it = mRenderTargets.find( name );
        RenderTarget *ret = NULL;

        if( it != mRenderTargets.end() )
        {
            ret = it->second;
        }

        return ret;
    }
    //---------------------------------------------------------------------------------------------
    RenderTarget * RenderSystem::detachRenderTarget( const String &name )
    {
        RenderTargetMap::iterator it = mRenderTargets.find( name );
        RenderTarget *ret = NULL;

        if( it != mRenderTargets.end() )
        {
            ret = it->second;

            /* Remove the render target from the priority groups. */
            RenderTargetPriorityMap::iterator itarg, itargend;
            itargend = mPrioritisedRenderTargets.end();
            for( itarg = mPrioritisedRenderTargets.begin(); itarg != itargend; ++itarg )
            {
                if( itarg->second == ret ) {
                    mPrioritisedRenderTargets.erase( itarg );
                    break;
                }
            }

            mRenderTargets.erase( it );
        }
        /// If detached render target is the active render target, reset active render target
        if(ret == mActiveRenderTarget)
            mActiveRenderTarget = 0;

        return ret;
    }

注意 detachRenderTarget 的细节:名字表删除只需一次 erase,但优先级表是多重表(RenderTargetPriorityMap),同名键可能有多项,所以按指针逐个匹配删。还有一行容易忽略的收尾:若摘除的正是当前活跃目标,mActiveRenderTarget 置空——状态一致性在每次操作里维护。

销毁链与默认创建

// OgreMain/src/OgreRenderSystem.cpp:RenderSystem::_createRenderWindow(v14.6.3 源码摘录,已删减)
    RenderWindow* RenderSystem::_createRenderWindow(const String& name, unsigned int width,
                                                    unsigned int height, bool fullScreen,
                                                    const NameValuePairList* miscParams)
    {
        if (mRenderTargets.find(name) != mRenderTargets.end())
        {
            OGRE_EXCEPT(Exception::ERR_INVALIDPARAMS, "Window with name '" + name + "' already exists");
        }

        // Log a message
        StringStream ss;
        ss << "RenderSystem::_createRenderWindow \"" << name << "\", " <<
            width << "x" << height << " ";
        if (fullScreen)
            ss << "fullscreen ";
        else
            ss << "windowed ";
        ...
        return NULL;
    }
    //---------------------------------------------------------------------------------------------
    void RenderSystem::destroyRenderTarget(const String& name)
    {
        RenderTarget* rt = detachRenderTarget(name);
        OGRE_DELETE rt;
    }

基类的 _createRenderWindow 默认实现只做两件事:重名抛 ERR_INVALIDPARAMS、打日志,然后 return NULL——真正的窗口创建留给各后端 override(GL/Vulkan/Metal 各自建原生窗口对象)。这个默认实现的角色是「公共前置 + 校验」,暴露了 OGRE 惯用的基类兜底 + 子类实现模式。销毁则统一走 destroyRenderTarget = detach(摘除) + delete(释放)。

窗口与离屏目标共用调度接口

RenderTarget 抽象提供视口、更新和帧统计。后端负责创建窗口或纹理目标,并按名字和优先级登记到 RenderSystem。按名取得对象并不等于其会参与本帧的自动更新。

逐项检查 active、autoUpdated、优先级和关联视口。目标 detach 之后,与目标关联的资源和引用应按具体创建者的销毁契约处理。

源码定位

  • OgreMain/src/OgreRenderSystem.cpp :attachRenderTarget(366-372)、getRenderTarget(375-386)、detachRenderTarget(389-416)、_createRenderWindow 默认实现(318-348)、destroyRenderTarget(360-364)
  • OgreMain/include/OgreRenderSystem.h :RenderTargetMap mRenderTargets(1140)、RenderTargetPriorityMap mPrioritisedRenderTargets(1142)、RenderTarget * mActiveRenderTarget(1144)
  • OgreMain/src/OgreRoot.cpp :Root::createRenderWindow → mActiveRenderer->_createRenderWindow(...)(962-970)

上游引用固定到 OGRE v14.6.3 源码 。

可运行产物:C++ 最小验证

下面复现双表登记、按名取回、摘除与销毁链。它与 src/01-3-render-target-creation.cpp 逐字节一致:

// file: src/01-3-render-target-creation.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/01-3-render-target-creation.cpp -o bin/01-3-render-target-creation && ./bin/01-3-render-target-creation
//
// 复现渲染目标登记表(对应 OgreRenderSystem.cpp 366-416 与 OgreRenderSystem.h 1136-1144):
//   mRenderTargets 按名登记、mPrioritisedRenderTargets 按优先级登记;
//   attachRenderTarget 同时进入两表(getPriority 分组);
//   getRenderTarget 按名查找;detachRenderTarget 从两表移除并重置 active;
//   destroyRenderTarget = detach + 删除;_createRenderWindow 默认实现做重名检查。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <map>
#include <string>

namespace ogre_repro {

class RenderTarget {
 public:
  RenderTarget(const std::string& name, unsigned int priority) : mName(name), mPriority(priority) {}
  virtual ~RenderTarget() = default;
  const std::string& getName() const { return mName; }
  unsigned int getPriority() const { return mPriority; }
  int mUpdates = 0;

 private:
  std::string mName;
  unsigned int mPriority;
};

class RenderSystem {
 public:
  // 对应 attachRenderTarget:双表登记
  void attachRenderTarget(RenderTarget& target) {
    mRenderTargets.emplace(target.getName(), &target);
    mPrioritisedRenderTargets.emplace(target.getPriority(), &target);
  }
  // 对应 getRenderTarget:按名查找
  RenderTarget* getRenderTarget(const std::string& name) const {
    auto it = mRenderTargets.find(name);
    return it == mRenderTargets.end() ? nullptr : it->second;
  }
  // 对应 detachRenderTarget:从两表移除;若为 active 则重置
  RenderTarget* detachRenderTarget(const std::string& name) {
    auto it = mRenderTargets.find(name);
    RenderTarget* ret = nullptr;
    if (it != mRenderTargets.end()) {
      ret = it->second;
      for (auto pit = mPrioritisedRenderTargets.begin(); pit != mPrioritisedRenderTargets.end(); ++pit) {
        if (pit->second == ret) {
          mPrioritisedRenderTargets.erase(pit);
          break;
        }
      }
      mRenderTargets.erase(it);
    }
    if (ret == mActiveRenderTarget) mActiveRenderTarget = nullptr;
    return ret;
  }
  // 对应 destroyRenderTarget:detach + delete
  void destroyRenderTarget(const std::string& name) {
    RenderTarget* rt = detachRenderTarget(name);
    delete rt;
  }
  // 对应 _createRenderWindow 默认实现:重名即抛
  RenderTarget* _createRenderWindow(const std::string& name, unsigned int w, unsigned int h) {
    if (mRenderTargets.find(name) != mRenderTargets.end())
      throw std::runtime_error("Window with name '" + name + "' already exists");
    RenderTarget* rt = new RenderTarget(name, 0);
    attachRenderTarget(*rt);
    return rt;
  }
  size_t targetCount() const { return mRenderTargets.size(); }
  size_t priorityGroupCount() const { return mPrioritisedRenderTargets.size(); }
  void setActive(RenderTarget* rt) { mActiveRenderTarget = rt; }

 private:
  std::map<std::string, RenderTarget*> mRenderTargets;          // 按名
  std::multimap<unsigned int, RenderTarget*> mPrioritisedRenderTargets;  // 按优先级
  RenderTarget* mActiveRenderTarget = nullptr;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  RenderSystem rs;

  // 创建主窗口:登记进两表
  rs._createRenderWindow("MainWindow", 1920, 1080);
  CHECK(rs.targetCount() == 1);
  CHECK(rs.priorityGroupCount() == 1);

  // 第二张:不同优先级(渲染目标组)
  RenderTarget* hdr = new RenderTarget("HDRTarget", 1);
  rs.attachRenderTarget(*hdr);
  CHECK(rs.targetCount() == 2);
  CHECK(rs.priorityGroupCount() == 2);

  // getRenderTarget 按名取回
  CHECK(rs.getRenderTarget("MainWindow") != nullptr);
  CHECK(rs.getRenderTarget("Missing") == nullptr);

  // 重名创建抛异常
  bool threw = false;
  try { rs._createRenderWindow("MainWindow", 800, 600); } catch (const std::runtime_error&) { threw = true; }
  CHECK(threw);

  // 设 active,detach 后 active 被重置
  RenderTarget* mainWin = rs.getRenderTarget("MainWindow");
  rs.setActive(mainWin);
  RenderTarget* detached = rs.detachRenderTarget("MainWindow");
  CHECK(detached == mainWin);
  CHECK(rs.getRenderTarget("MainWindow") == nullptr);
  CHECK(rs.priorityGroupCount() == 1);  // 优先级表同步移除

  // destroy = detach + delete
  rs.destroyRenderTarget("HDRTarget");
  CHECK(rs.targetCount() == 0);
  CHECK(rs.priorityGroupCount() == 0);

  delete detached;

  return lab::report("01-3 创建渲染目标");
}

本机实测(Apple clang 16,clang++ -std=c++20):编译通过(-Wall 零警告),断言 12/12 通过。

小结

  • 渲染目标双表登记:mRenderTargets 按名、mPrioritisedRenderTargets 按优先级,一帧按优先级顺序更新。
  • detachRenderTarget 从两表移除,且摘除的是 active 目标时置空 mActiveRenderTarget。
  • 基类 _createRenderWindow 默认实现做重名检查 + 日志,真正创建由后端 override。
  • destroyRenderTarget = detach(摘除) + delete(释放),生命周期单一入口。

阅读导航:上一节:1.2 渲染状态管理 · 下一节:2.1 硬件缓冲抽象 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

  1. 《大规模分布式计算深入解析》15.3 落地:从 Neo4j 到自研图引擎
  2. 《大规模分布式计算深入解析·图计算与图数据库内核》 · 目录与学习路径(45 篇)
  3. 《大规模分布式计算深入解析》15.2 十一卷主线:从切分到图