《OGRE 3D 渲染引擎原理与架构》3.3 自动参数绑定

世界矩阵、光源、时间这类常量不想每帧手动填,OGRE 提供 setAutoConstant:AutoConstantType 枚举描述「要什么」,AutoConstantEntry 记录目标物理索引与 extraInfo,_updateAutoParams 每帧从 AutoParamDataSource 取值写回。lab 复现字典查询、条目追加/更新与四类自动常量回写。

3.3 自动参数绑定

手写 setNamedConstant 每帧都要算世界矩阵、找光源、读时钟——又慢又容易漏。OGRE 的答案是自动参数:你只声明「逻辑索引 0 绑定世界矩阵」,剩下的交给引擎。这一节看 AutoConstantType 怎么描述「要什么」,AutoConstantEntry 怎么记「写哪里」,以及 _updateAutoParams 每帧怎么把值填进去。

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

3.2 讲的是「手动」写入的缓冲;helio 四卷渲染器里 uniform 靠每帧手动赋值。这里看 OGRE 的声明式方案:一组预定义的 AutoConstantType 枚举 + 一个每帧执行的自动回写循环,让常见矩阵/光照/时间常量零成本自动更新。

要什么:AutoConstantType 枚举

自动常量类型是一张巨大的枚举,从矩阵到光照到时间应有尽有:

// OgreMain/include/OgreGpuProgramParams.h:AutoConstantType(v14.6.3 源码摘录,已删减)
        enum AutoConstantType
        {
            /// The current world matrix
            ACT_WORLD_MATRIX,
            /// The current world matrix, inverted
            ACT_INVERSE_WORLD_MATRIX,
            /** Provides transpose of world matrix.
            */
            ACT_TRANSPOSE_WORLD_MATRIX,
            /// The current world matrix, inverted & transposed
            ACT_INVERSE_TRANSPOSE_WORLD_MATRIX,

继续读能看到视图矩阵族、投影矩阵族、WVP 族、灯光族、时间族(ACT_TIME、ACT_TIME_0_X…)、视口尺寸族等上百个值。材料脚本里 param_named_auto world_matrix world_matrix 的 world_matrix 字符串就是这些枚举的名字——两者靠 AutoConstantDictionary 互相翻译:

// OgreMain/src/OgreGpuProgramParams.cpp:AutoConstantDictionary(v14.6.3 源码摘录,已删减)
    GpuProgramParameters::AutoConstantDefinition GpuProgramParameters::AutoConstantDictionary[] = {
        AutoConstantDefinition(ACT_WORLD_MATRIX,                  "world_matrix",                16, ET_REAL, ACDT_NONE),
        AutoConstantDefinition(ACT_INVERSE_WORLD_MATRIX,          "inverse_world_matrix",        16, ET_REAL, ACDT_NONE),
        AutoConstantDefinition(ACT_TRANSPOSE_WORLD_MATRIX,             "transpose_world_matrix",            16, ET_REAL, ACDT_NONE),
        AutoConstantDefinition(ACT_INVERSE_TRANSPOSE_WORLD_MATRIX, "inverse_transpose_world_matrix", 16, ET_REAL, ACDT_NONE),

elementCount 告诉引擎这个常量占多少 float:矩阵 16,camera_position 3,time 1。dataType 决定 extra 参数是整数索引(第几盏灯)还是浮点因子(时间周期)。

记哪里:AutoConstantEntry

每次 setAutoConstant 会生成一条 AutoConstantEntry,记录目标位置、类型和附加数据:

// OgreMain/include/OgreGpuProgramParams.h:AutoConstantEntry(v14.6.3 源码摘录,已删减)
        class AutoConstantEntry
        {
        public:
            /// The target (physical) constant index
            size_t physicalIndex;
            /// The type of parameter
            AutoConstantType paramType;
            /// Additional information to go with the parameter
            union{
                uint32 data;
                float fData;
            };
            /// The variability of this parameter (see GpuParamVariability)
            uint16 variability;

关键的 union { uint32 data; float fData; }:同一个 4 字节,当作整数时存「第几盏灯/数组多大」,当作浮点时存「时间周期因子」。条目的集合就是 mAutoConstants:

// OgreMain/include/OgreGpuProgramParams.h:AutoConstantList(v14.6.3 源码摘录,已删减)
        // Auto parameter storage
        typedef std::vector<AutoConstantEntry> AutoConstantList;

怎么绑:setAutoConstant 与 _setRawAutoConstant

绑定分两步。setAutoConstant(index, acType, extraInfo) 先查字典拿尺寸、向上取整到 float4,再解析逻辑索引的物理偏移:

// OgreMain/src/OgreGpuProgramParams.cpp:setAutoConstant(v14.6.3 源码摘录,已删减)
    void GpuProgramParameters::setAutoConstant(size_t index, AutoConstantType acType, uint32 extraInfo)
    {
        // Get auto constant definition for sizing
        const AutoConstantDefinition* autoDef = getAutoConstantDefinition(acType);

        if(!autoDef)
            OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND, "No constant definition found for type " +
                        StringConverter::toString(acType),
                        "GpuProgramParameters::setAutoConstant");

        // round up to nearest multiple of 4
        size_t sz = autoDef->elementCount;
        if (sz % 4 > 0)
        {
            sz += 4 - (sz % 4);
        }

        GpuLogicalIndexUse* indexUse = getConstantLogicalIndexUse(index, sz, deriveVariability(acType), BCT_FLOAT);

        if(indexUse)
            _setRawAutoConstant(indexUse->physicalIndex, acType, extraInfo, indexUse->variability, sz);
    }

注意 sz 的取整逻辑:elementCount=3(相机位置)被抬到 4——因为低层汇编常量的基本单位是 float4。_setRawAutoConstant 负责写条目:

// OgreMain/src/OgreGpuProgramParams.cpp:_setRawAutoConstant(v14.6.3 源码摘录,已删减)
    void GpuProgramParameters::_setRawAutoConstant(size_t physicalIndex,
                                                   AutoConstantType acType, uint32 extraInfo, uint16 variability, uint8 elementSize)
    {
        // update existing index if it exists
        bool found = false;
        for (auto& ac : mAutoConstants)
        {
            if (ac.physicalIndex == physicalIndex)
            {
                ac.paramType = acType;
                ac.data = extraInfo;
                ac.elementCount = elementSize;
                ac.variability = variability;
                found = true;
                break;
            }
        }
        if (!found)
            mAutoConstants.push_back(AutoConstantEntry(acType, physicalIndex, extraInfo, variability, elementSize));

        mCombinedVariability |= variability;


    }

两个设计点:

  • 幂等更新:同一物理索引重复绑定,是更新已有条目而不是追加——避免重复条目造成每帧重复回写。
  • 可变性累积:mCombinedVariability |= variability。GPV_PER_OBJECT/GPV_LIGHTS 等可变性掩码决定哪些渲染阶段需要重算自动参数(逐对象 vs 每盏灯)。

何时填:_updateAutoParams

条目是「声明」,真正取值发生在 _updateAutoParams:

// OgreMain/include/OgreGpuProgramParams.h:_updateAutoParams 声明(v14.6.3 源码摘录,已删减)
        /** Update automatic parameters.
            @param source The source of the parameters
            @param variabilityMask A mask of GpuParamVariability which identifies which autos will need updating
        */
        void _updateAutoParams(const AutoParamDataSource* source, uint16 variabilityMask);

它遍历 mAutoConstants,按 paramType 从 AutoParamDataSource(SceneManager 每帧填充的「当前渲染状态快照」)取值,memcpy 进常量缓冲。渲染循环里的调用链是:

  1. SceneManager 更新 mAutoParamDataSource(世界矩阵、相机、光源列表、雾、时间)。
  2. 提交 Renderable 前,_updateAutoParams(&dataSource, mCombinedVariability)。
  3. 各 RenderSystem 绑定缓冲,着色器读到最新值。

variabilityMask 是优化闸门:如果这一帧只变了世界矩阵(GPV_PER_OBJECT),就只重写标记为 per-object 的条目,全局常量(投影矩阵)跳过。lab 用四类常量验证了这条链路。

参数更新粒度取决于数据来源

GPU 程序定义和参数对象分别处理程序代码及输入。相机、视口和时间参数随帧或目标变化,世界矩阵和实例参数会随 Renderable 变化。自动常量的有效值要看当前 AutoParamDataSource。

定位 SceneManager::_issueRenderOp 与参数绑定的先后。以同一相机的两个实体为例,观察共享程序仍收到各自的世界变换。

帧级与对象级参数的来源

flowchart LR
  F["帧与视口"] --> A["AutoParamDataSource"]
  C["相机、灯光"] --> A
  O["当前 Renderable 与世界矩阵"] --> A
  P["Pass 的自动常量声明"] --> U["更新参数对象"]
  A --> U
  U --> B["后端绑定程序参数"]
  B --> D["提交该对象的 RenderOperation"]

源码定位

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

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

下面复现字典查询、条目追加/更新与四类自动常量回写。它与 src/03-3-auto-params.cpp 逐字节一致:

// file: src/03-3-auto-params.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/03-3-auto-params.cpp -o bin/03-3-auto-params && ./bin/03-3-auto-params
//
// 复现自动参数绑定(对应 OgreGpuProgramParams.h 1050-1081、OgreGpuProgramParams.cpp 1388-1434):
//   AutoConstantEntry 记录 physicalIndex + paramType + union(data/fData) + variability;
//   setAutoConstant 查 AutoConstantDictionary 得到 elementCount,向上取整到 float4 后落到物理索引;
//   _setRawAutoConstant 更新已有条目或追加,mCombinedVariability 累积可变性;
//   _updateAutoParams 遍历 mAutoConstants,按 paramType 从 AutoParamDataSource 取当前值写回缓冲。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cstdint>
#include <cstring>
#include <map>
#include <string>
#include <vector>

namespace ogre_repro {

enum AutoConstantType {
  ACT_WORLD_MATRIX = 0,
  ACT_VIEW_MATRIX,
  ACT_VIEWPROJ_MATRIX,
  ACT_TIME,
  ACT_CAMERA_POSITION
};

enum ACDataType { ACDT_NONE = 0, ACDT_INT, ACDT_REAL };

struct AutoConstantDefinition {
  AutoConstantType acType;
  const char* name;
  size_t elementCount;
  ACDataType dataType;
};

// 对应 AutoConstantDictionary 的前几项(真实表在 OgreGpuProgramParams.cpp 36-)
static const AutoConstantDefinition AutoConstantDictionary[] = {
    {ACT_WORLD_MATRIX, "world_matrix", 16, ACDT_NONE},
    {ACT_VIEW_MATRIX, "view_matrix", 16, ACDT_NONE},
    {ACT_VIEWPROJ_MATRIX, "viewproj_matrix", 16, ACDT_NONE},
    {ACT_TIME, "time", 1, ACDT_REAL},
    {ACT_CAMERA_POSITION, "camera_position", 3, ACDT_NONE},
};

// 对应 AutoConstantEntry:union 让同一 4 字节既当 int 索引又当 float 因子
struct AutoConstantEntry {
  size_t physicalIndex;
  AutoConstantType paramType;
  union {
    uint32_t data;
    float fData;
  };
  uint16_t variability;
  uint8_t elementCount;

  AutoConstantEntry(AutoConstantType t, size_t idx, uint32_t d, uint16_t v, uint8_t e)
      : physicalIndex(idx), paramType(t), data(d), variability(v), elementCount(e) {}
  AutoConstantEntry(AutoConstantType t, size_t idx, float f, uint16_t v, uint8_t e)
      : physicalIndex(idx), paramType(t), fData(f), variability(v), elementCount(e) {}
};

using AutoConstantList = std::vector<AutoConstantEntry>;

// 对应 AutoParamDataSource 的简化:只提供本 lab 需要的取值
struct AutoParamDataSource {
  float world[16];
  float viewproj[16];
  float time;
  float camPos[3];

  void getWorldMatrix(float out[16]) const { std::memcpy(out, world, sizeof(world)); }
  void getViewProjMatrix(float out[16]) const { std::memcpy(out, viewproj, sizeof(viewproj)); }
  float getTime() const { return time; }
  void getCameraPosition(float out[3]) const { std::memcpy(out, camPos, sizeof(camPos)); }
};

class GpuProgramParameters {
 public:
  void _setLogicalIndexes(const std::map<size_t, size_t>& logicalToPhysical, size_t byteSize) {
    mLogicalToPhysical = logicalToPhysical;
    mConstants.assign(byteSize, 0);
  }

  static const AutoConstantDefinition* getAutoConstantDefinition(AutoConstantType t) {
    for (const auto& d : AutoConstantDictionary) {
      if (d.acType == t) return &d;
    }
    return nullptr;
  }

  // 对应 setAutoConstant:查字典取尺寸,向上取整到 float4,解析物理索引后落条目
  void setAutoConstant(size_t index, AutoConstantType acType, uint32_t extraInfo) {
    const AutoConstantDefinition* def = getAutoConstantDefinition(acType);
    size_t sz = def ? def->elementCount : 0;
    if (sz % 4 > 0) sz += 4 - (sz % 4);  // round up to nearest multiple of 4
    size_t physicalIndex = _getConstantPhysicalIndex(index);
    _setRawAutoConstant(physicalIndex, acType, extraInfo, /*variability=*/1, sz);
  }

  // 对应 _setRawAutoConstant 的 float 变体(union.fData 存周期因子)
  void setAutoConstantReal(size_t index, AutoConstantType acType, float rData) {
    size_t physicalIndex = _getConstantPhysicalIndex(index);
    _setRawAutoConstantReal(physicalIndex, acType, rData, /*variability=*/1, 4);
  }

  size_t getAutoConstantCount() const { return mAutoConstants.size(); }
  const AutoConstantList& getAutoConstants() const { return mAutoConstants; }

  // 对应 _updateAutoParams:按 paramType 从数据源取值写回物理缓冲
  void _updateAutoParams(const AutoParamDataSource& source) {
    for (const auto& ac : mAutoConstants) {
      switch (ac.paramType) {
        case ACT_WORLD_MATRIX:
          source.getWorldMatrix(reinterpret_cast<float*>(&mConstants[ac.physicalIndex]));
          break;
        case ACT_VIEWPROJ_MATRIX:
          source.getViewProjMatrix(reinterpret_cast<float*>(&mConstants[ac.physicalIndex]));
          break;
        case ACT_TIME: {
          float t = source.getTime() * ac.fData;  // fData = 周期缩放因子
          std::memcpy(&mConstants[ac.physicalIndex], &t, sizeof(float));
          break;
        }
        case ACT_CAMERA_POSITION:
          source.getCameraPosition(reinterpret_cast<float*>(&mConstants[ac.physicalIndex]));
          break;
        default:
          break;
      }
    }
  }

  float readFloat(size_t byteOffset) const {
    float f = 0.0f;
    std::memcpy(&f, &mConstants[byteOffset], sizeof(float));
    return f;
  }

 private:
  size_t _getConstantPhysicalIndex(size_t logicalIndex) const {
    auto it = mLogicalToPhysical.find(logicalIndex);
    return it == mLogicalToPhysical.end() ? 0 : it->second;
  }

  void _setRawAutoConstant(size_t physicalIndex, AutoConstantType acType, uint32_t extraInfo,
                           uint16_t variability, uint8_t elementSize) {
    // 更新已有条目,否则追加;mCombinedVariability |= variability(简化为成员累加)
    bool found = false;
    for (auto& ac : mAutoConstants) {
      if (ac.physicalIndex == physicalIndex) {
        ac.paramType = acType;
        ac.data = extraInfo;
        ac.elementCount = elementSize;
        ac.variability = variability;
        found = true;
        break;
      }
    }
    if (!found)
      mAutoConstants.push_back(AutoConstantEntry(acType, physicalIndex, extraInfo, variability, elementSize));
    mCombinedVariability |= variability;
  }

  void _setRawAutoConstantReal(size_t physicalIndex, AutoConstantType acType, float rData,
                               uint16_t variability, uint8_t elementSize) {
    bool found = false;
    for (auto& ac : mAutoConstants) {
      if (ac.physicalIndex == physicalIndex) {
        ac.paramType = acType;
        ac.fData = rData;
        ac.elementCount = elementSize;
        ac.variability = variability;
        found = true;
        break;
      }
    }
    if (!found)
      mAutoConstants.push_back(AutoConstantEntry(acType, physicalIndex, rData, variability, elementSize));
    mCombinedVariability |= variability;
  }

  std::vector<uint8_t> mConstants;
  std::map<size_t, size_t> mLogicalToPhysical;
  AutoConstantList mAutoConstants;
  uint16_t mCombinedVariability = 0;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 字典查询:类型与名字双向可查
  const AutoConstantDefinition* wm = GpuProgramParameters::getAutoConstantDefinition(ACT_WORLD_MATRIX);
  CHECK(wm != nullptr);
  CHECK(wm->elementCount == 16);
  CHECK_EQ(std::string(wm->name), std::string("world_matrix"));
  CHECK_EQ(std::string(GpuProgramParameters::getAutoConstantDefinition(ACT_TIME)->name),
           std::string("time"));
  CHECK(GpuProgramParameters::getAutoConstantDefinition(ACT_CAMERA_POSITION)->elementCount == 3);

  // 逻辑索引 -> 物理偏移;每个 16-float 矩阵占 64 字节,区域互不重叠
  GpuProgramParameters params;
  std::map<size_t, size_t> l2p;
  l2p[0] = 0;    // world: 字节 0-63
  l2p[4] = 64;   // viewproj: 字节 64-127
  l2p[8] = 128;  // time: 字节 128-131
  l2p[9] = 144;  // camera: 字节 144-155
  params._setLogicalIndexes(l2p, 160);

  params.setAutoConstant(0, ACT_WORLD_MATRIX, 0);        // elementCount 16 -> 4 个 float4
  params.setAutoConstant(4, ACT_VIEWPROJ_MATRIX, 0);     // 16 -> 4 个 float4
  params.setAutoConstantReal(8, ACT_TIME, 2.0f);         // 1 -> 取整 4,union.fData 存 2.0
  params.setAutoConstant(9, ACT_CAMERA_POSITION, 0);     // 3 -> 取整 4
  CHECK(params.getAutoConstantCount() == 4);

  const auto& list = params.getAutoConstants();
  CHECK(list[0].physicalIndex == 0);
  CHECK(list[0].paramType == ACT_WORLD_MATRIX);
  CHECK(list[1].physicalIndex == 64);
  CHECK(list[2].paramType == ACT_TIME);
  CHECK(list[2].fData == 2.0f);      // union 的 float 通道
  CHECK(list[3].elementCount == 4);  // camera_position 向上取整到 4

  // 重复 setAutoConstant(0):更新已有条目,不追加
  params.setAutoConstant(0, ACT_WORLD_MATRIX, 1);
  CHECK(params.getAutoConstantCount() == 4);
  CHECK(list[0].data == 1);  // extraInfo 被更新

  // _updateAutoParams:从数据源拉当前值写回缓冲
  AutoParamDataSource src = {};
  for (int i = 0; i < 16; ++i) src.world[i] = static_cast<float>(i + 1);
  for (int i = 0; i < 16; ++i) src.viewproj[i] = static_cast<float>(101 + i);
  src.time = 0.5f;
  src.camPos[0] = 7.0f;
  src.camPos[1] = 8.0f;
  src.camPos[2] = 9.0f;
  params._updateAutoParams(src);

  CHECK(params.readFloat(0) == 1.0f);
  CHECK(params.readFloat(12) == 4.0f);
  CHECK(params.readFloat(60) == 16.0f);     // world_matrix 16 个 float
  CHECK(params.readFloat(64) == 101.0f);
  CHECK(params.readFloat(124) == 116.0f);   // viewproj_matrix 16 个 float
  CHECK(params.readFloat(128) == 1.0f);     // time * fData = 0.5 * 2
  CHECK(params.readFloat(144) == 7.0f);
  CHECK(params.readFloat(152) == 9.0f);     // camera_position 3 个 float

  return lab::report("03-3 自动参数绑定");
}

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

小结

  • AutoConstantType 枚举声明「要什么」;AutoConstantDictionary 在枚举与字符串名之间互译并携带尺寸。
  • AutoConstantEntry 记录物理索引、类型与 union(data/fData),存于 mAutoConstants。
  • setAutoConstant 查字典取尺寸、向上取整到 float4,经逻辑→物理映射落到物理偏移。
  • _setRawAutoConstant 同物理索引幂等更新;mCombinedVariability 累积可变性掩码。
  • _updateAutoParams 按 paramType 从 AutoParamDataSource 取值写回,variabilityMask 控制哪些条目需要重算。

阅读导航:上一节:3.2 参数缓冲 GpuProgramParameters · 下一节:4.1 Pass 的渲染状态 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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