《OGRE 3D 渲染引擎原理与架构》12.2 布告板类型

布告板有两个类型维度:BillboardOrigin 九种基准点决定板相对位置哪个点对齐,BillboardType 五种类型决定板如何朝向相机(点板、公共方向、自身方向、垂直公共、垂直自身)。lab 复现 origin 参数偏移、轴向生成与四角顶点合成。

12.2 布告板类型

一块板的「位置」到底指板的哪个点?它又该怎么朝向相机?两个问题由 BillboardOrigin 与 BillboardType 回答。前者是九种基准点(中心、上边中点、左下角……),后者是五种朝向模型(始终正对、绕公共轴转、绕自身轴转、垂直于公共/自身方向)。这一节解析两套枚举与把类型翻译成「四角顶点」的生成函数。

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

helio 四卷的精灵只做「正对相机」一种;cg 三卷讲过屏幕对齐的数学。这里解析真实 OGRE 的 BillboardOrigin/BillboardType(OgreBillboardSet.h)与 getParametricOffsets/genBillboardAxes/genVertOffsets(OgreBillboardSet.cpp):基准点怎么变成参数偏移、五种类型怎么决定板的局部轴、四个角点怎么由轴和尺寸合成。

BillboardOrigin:板的位置指哪个点

BillboardOrigin 枚举定义板的基准点,9 个值对应 3×3 网格:

// OgreMain/include/OgreBillboardSet.h:BillboardOrigin(v14.6.3 源码摘录,已删减)
    enum BillboardOrigin
    {
        BBO_TOP_LEFT,
        BBO_TOP_CENTER,
        BBO_TOP_RIGHT,
        BBO_CENTER_LEFT,
        BBO_CENTER,
        BBO_CENTER_RIGHT,
        BBO_BOTTOM_LEFT,
        BBO_BOTTOM_CENTER,
        BBO_BOTTOM_RIGHT
    };

树以底部中点为基准(树根踩地),火球以中心为基准,光标以左上角为基准——选哪个 origin 决定了板相对其位置点怎么摆。基准点被翻译成参数偏移 (left, right, top, bottom),表示四边相对板中心的参数化位置。getParametricOffsets 按 origin 填这四个值:

// OgreMain/src/OgreBillboardSet.cpp:BillboardSet::getParametricOffsets(v14.6.3 源码摘录,已删减)
    void BillboardSet::getParametricOffsets(
        Real& left, Real& right, Real& top, Real& bottom )
    {
        switch( mOriginType )
        {
        case BBO_TOP_LEFT:
            left = 0.0f;
            right = 1.0f;
            top = 0.0f;
            bottom = -1.0f;
            break;
        ...
        case BBO_CENTER:
            left = -0.5f;
            right = 0.5f;
            top = 0.5f;
            bottom = -0.5f;
            break;
        ...
        case BBO_BOTTOM_CENTER:
            left = -0.5f;
            right = 0.5f;
            top = 1.0f;
            bottom = 0.0f;
            break;
Originleftrighttopbottom含义
BBO_CENTER−0.50.50.5−0.5位置是板中心
BBO_BOTTOM_CENTER−0.50.51.00.0位置是底边中点
BBO_TOP_LEFT0.01.00.0−1.0位置是左上角

BillboardType:板如何朝向

BillboardType 枚举定义五种朝向模型。默认的 BBT_POINT 始终正对相机且保持竖直;ORIENTED 系列让板只绕一个轴旋转着面对相机(适合雨滴、叶子);PERPENDICULAR 系列让板平面垂直于某个方向(用于不面向相机的地面贴花):

// OgreMain/include/OgreBillboardSet.h:BillboardType(v14.6.3 源码摘录,已删减)
    /** The type of billboard to use. */
    enum BillboardType
    {
        /// Standard point billboard (default), always faces the camera completely and is always upright
        BBT_POINT,
        /// Billboards are oriented around a shared direction vector (used as Y axis) and only rotate around this to face the camera
        BBT_ORIENTED_COMMON,
        /// Billboards are oriented around their own direction vector (their own Y axis) and only rotate around this to face the camera
        BBT_ORIENTED_SELF,
        /// Billboards are perpendicular to a shared direction vector (used as Z axis, the facing direction) and X, Y axis are determined by a shared up-vertor
        BBT_PERPENDICULAR_COMMON,
        /// Billboards are perpendicular to their own direction vector (their own Z axis, the facing direction) and X, Y axis are determined by a shared up-vertor
        BBT_PERPENDICULAR_SELF
    };

类型与方向的设置入口成对出现:

// OgreMain/include/OgreBillboardSet.h:setBillboardType/setCommonDirection(v14.6.3 源码摘录,已删减)
        void setBillboardType(BillboardType bbt) { mBillboardType = bbt; }
        ...
        void setCommonDirection(const Vector3& vec) { mCommonDirection = vec; }

BBT_ORIENTED_COMMON 时所有板共用 mCommonDirection 作 Y 轴(例如无风的雨);BBT_ORIENTED_SELF 时每块板用自己的 mDirection 作 Y 轴(例如被风吹散的叶)。PERPENDICULAR 系列还需要 setCommonUpVector 提供公共上向量来确定 X/Y 轴。

从类型到四角顶点

每帧生成板几何分三步。genBillboardAxes 按类型算出板的局部 X/Y 轴:

// OgreMain/src/OgreBillboardSet.cpp:BillboardSet::genBillboardAxes(v14.6.3 源码摘录,已删减)
    void BillboardSet::genBillboardAxes(Vector3* pX, Vector3 *pY, const Billboard* bb)
    {
        ...
        switch (mBillboardType)
        {
        case BBT_POINT:
            ...
            // Get camera axes for X and Y (depth is irrelevant)
            *pX = mCamQ * Vector3::UNIT_X;
            *pY = mCamQ * Vector3::UNIT_Y;
            break;

        case BBT_ORIENTED_COMMON:
            // Y-axis is common direction
            // X-axis is cross with camera direction
            *pY = mCommonDirection;
            *pX = mCamDir.crossProduct(*pY);
            pX->normalise();
            break;

        case BBT_ORIENTED_SELF:
            // Y-axis is direction
            // X-axis is cross with camera direction
            *pY = bb->mDirection;
            *pX = mCamDir.crossProduct(*pY);
            pX->normalise();
            break;
        ...
        }
    }

POINT 直接取相机右/上轴;ORIENTED_* 用 Y 轴与相机方向叉积出 X 轴。得到轴后,genVertOffsets 用参数偏移 × 尺寸 × 轴合成四个角点偏移:

// OgreMain/src/OgreBillboardSet.cpp:BillboardSet::genVertOffsets(v14.6.3 源码摘录,已删减)
    void BillboardSet::genVertOffsets(Real inleft, Real inright, Real intop, Real inbottom,
        Real width, Real height, const Vector3& x, const Vector3& y, Vector3* pDestVec)
    {
        Vector3 vLeftOff, vRightOff, vTopOff, vBottomOff;
        /* Calculate default offsets. Scale the axes by
           parametric offset and dimensions, ready to be added to
           positions.
        */

        vLeftOff   = x * ( inleft   * width );
        vRightOff  = x * ( inright  * width );
        vTopOff    = y * ( intop   * height );
        vBottomOff = y * ( inbottom * height );

        // Make final offsets to vertex positions
        pDestVec[0] = vLeftOff  + vTopOff;
        pDestVec[1] = vRightOff + vTopOff;
        pDestVec[2] = vLeftOff  + vBottomOff;
        pDestVec[3] = vRightOff + vBottomOff;
    }

四个角点 = 左/右偏移与上/下偏移的组合,最后再加到板的 mPosition 上,得到最终世界位置。整个流程:origin → 参数偏移 → 类型 → 局部轴 → 角点偏移 → 位置。

源码定位

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

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

下面用纯 C++ 复现 origin 参数偏移、类型轴向生成与四角顶点合成。它与 src/12-2-billboard-type.cpp 逐字节一致:

// file: src/12-2-billboard-type.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/12-2-billboard-type.cpp -o bin/12-2-billboard-type && ./bin/12-2-billboard-type
//
// 复现布告板类型与 4 角生成(对应 OgreBillboardSet.h 56/83/450/590/609、OgreBillboardSet.cpp 653/762/918):
//   BillboardOrigin 是 9 个 origin;BillboardType 有 POINT/ORIENTED_COMMON/ORIENTED_SELF/
//   PERPENDICULAR_COMMON/PERPENDICULAR_SELF;
//   getParametricOffsets 按 origin 给左右上下参数;
//   genBillboardAxes 按类型生成 X/Y 轴(POINT 用相机轴、ORIENTED_COMMON 固定方向、ORIENTED_SELF 各自方向);
//   genVertOffsets 用轴与尺寸合成 4 个角点偏移。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cmath>
#include <cstdint>

namespace ogre_repro {

// 对应 OgreBillboardSet.h 56:BillboardOrigin
enum BillboardOrigin {
  BBO_TOP_LEFT,
  BBO_TOP_CENTER,
  BBO_TOP_RIGHT,
  BBO_CENTER_LEFT,
  BBO_CENTER,
  BBO_CENTER_RIGHT,
  BBO_BOTTOM_LEFT,
  BBO_BOTTOM_CENTER,
  BBO_BOTTOM_RIGHT
};

// 对应 OgreBillboardSet.h 83:BillboardType
enum BillboardType {
  BBT_POINT,               // OgreBillboardSet.h 85
  BBT_ORIENTED_COMMON,     // OgreBillboardSet.h 87
  BBT_ORIENTED_SELF,       // OgreBillboardSet.h 89
  BBT_PERPENDICULAR_COMMON,// OgreBillboardSet.h 91
  BBT_PERPENDICULAR_SELF   // OgreBillboardSet.h 93
};

struct Vec3 {
  float x = 0.f;
  float y = 0.f;
  float z = 0.f;
  Vec3() = default;
  Vec3(float px, float py, float pz) : x(px), y(py), z(pz) {}
};

Vec3 operator+(const Vec3& a, const Vec3& b) { return Vec3(a.x + b.x, a.y + b.y, a.z + b.z); }
Vec3 operator*(const Vec3& a, float s) { return Vec3(a.x * s, a.y * s, a.z * s); }

Vec3 cross(const Vec3& a, const Vec3& b) {
  return Vec3(a.y * b.z - a.z * b.y, a.z * b.x - a.x * b.z, a.x * b.y - a.y * b.x);
}

Vec3 normalize(const Vec3& a) {
  float len = std::sqrt(a.x * a.x + a.y * a.y + a.z * a.z);
  float inv = len > 0.f ? 1.f / len : 1.f;
  return Vec3(a.x * inv, a.y * inv, a.z * inv);
}

// 对应 OgreBillboardSet.cpp 653:getParametricOffsets
void getParametricOffsets(BillboardOrigin origin, float& left, float& right, float& top,
                          float& bottom) {
  switch (origin) {
    case BBO_TOP_LEFT:
      left = 0.f;
      right = 1.f;
      top = 0.f;
      bottom = -1.f;
      break;
    case BBO_CENTER:
      left = -0.5f;
      right = 0.5f;
      top = 0.5f;
      bottom = -0.5f;
      break;
    case BBO_BOTTOM_CENTER:
      left = -0.5f;
      right = 0.5f;
      top = 1.f;
      bottom = 0.f;
      break;
    default:  // 其余 origin 省略,默认中心
      left = -0.5f;
      right = 0.5f;
      top = 0.5f;
      bottom = -0.5f;
      break;
  }
}

// 对应 OgreBillboardSet.cpp 762:genBillboardAxes(节选)
void genBillboardAxes(BillboardType type, const Vec3& camDir, const Vec3& commonDir,
                      const Vec3& bbDir, Vec3& pX, Vec3& pY) {
  switch (type) {
    case BBT_POINT:
      // 相机轴:X=右,Y=上
      pX = Vec3(1.f, 0.f, 0.f);
      pY = Vec3(0.f, 1.f, 0.f);
      break;
    case BBT_ORIENTED_COMMON:
      // Y 轴是公共方向,X 轴与相机方向叉积
      pY = commonDir;
      pX = normalize(cross(camDir, pY));
      break;
    case BBT_ORIENTED_SELF:
      // Y 轴是各自方向,X 轴与相机方向叉积
      pY = bbDir;
      pX = normalize(cross(camDir, pY));
      break;
    default:
      pY = Vec3(0.f, 1.f, 0.f);
      pX = Vec3(1.f, 0.f, 0.f);
      break;
  }
}

// 4 个角点偏移:left-top / right-top / left-bottom / right-bottom
struct Corners {
  Vec3 lt;
  Vec3 rt;
  Vec3 lb;
  Vec3 rb;
};

// 对应 OgreBillboardSet.cpp 918:genVertOffsets
Corners genVertOffsets(float left, float right, float top, float bottom, float width,
                       float height, const Vec3& x, const Vec3& y) {
  Corners c;
  c.lt = x * (left * width) + y * (top * height);
  c.rt = x * (right * width) + y * (top * height);
  c.lb = x * (left * width) + y * (bottom * height);
  c.rb = x * (right * width) + y * (bottom * height);
  return c;
}

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // BillboardType 枚举顺序
  CHECK_EQ(BBT_POINT, 0);
  CHECK_EQ(BBT_ORIENTED_COMMON, 1);
  CHECK_EQ(BBT_ORIENTED_SELF, 2);
  CHECK_EQ(BBT_PERPENDICULAR_COMMON, 3);
  CHECK_EQ(BBT_PERPENDICULAR_SELF, 4);

  // getParametricOffsets:origin 决定参数
  float l, r, t, b;
  getParametricOffsets(BBO_CENTER, l, r, t, b);
  CHECK_EQ(l, -0.5f);
  CHECK_EQ(r, 0.5f);
  CHECK_EQ(t, 0.5f);
  CHECK_EQ(b, -0.5f);
  getParametricOffsets(BBO_BOTTOM_CENTER, l, r, t, b);
  CHECK_EQ(t, 1.f);
  CHECK_EQ(b, 0.f);

  // POINT:X/Y 为相机轴,4 角以中心对称
  Vec3 x, y;
  genBillboardAxes(BBT_POINT, Vec3(0.f, 0.f, -1.f), Vec3(0.f, 1.f, 0.f), Vec3(0.f, 1.f, 0.f), x, y);
  CHECK_EQ(x.x, 1.f);
  CHECK_EQ(y.y, 1.f);
  Corners c = genVertOffsets(-0.5f, 0.5f, 0.5f, -0.5f, 2.f, 2.f, x, y);
  CHECK_EQ(c.lt.x, -1.f);
  CHECK_EQ(c.lt.y, 1.f);
  CHECK_EQ(c.rb.x, 1.f);
  CHECK_EQ(c.rb.y, -1.f);

  // ORIENTED_COMMON:Y 固定为公共方向
  genBillboardAxes(BBT_ORIENTED_COMMON, Vec3(0.f, 0.f, -1.f), Vec3(0.f, 1.f, 0.f),
                   Vec3(0.f, 1.f, 0.f), x, y);
  CHECK_EQ(y.y, 1.f);

  // ORIENTED_SELF:Y 为各自方向
  genBillboardAxes(BBT_ORIENTED_SELF, Vec3(0.f, 0.f, -1.f), Vec3(0.f, 1.f, 0.f),
                   Vec3(0.f, 0.f, 1.f), x, y);
  CHECK_EQ(y.z, 1.f);

  return lab::report("12-2 布告板类型");
}

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

小结

  • BillboardOrigin 9 值描述「板位置指板的哪个点」,被 getParametricOffsets 翻译成左右上下参数。
  • BillboardType 5 值描述朝向模型:POINT 正对相机、ORIENTED 绕公共/自身方向转、PERPENDICULAR 垂直于公共/自身方向。
  • genBillboardAxes 按类型算出局部 X/Y 轴:POINT 取相机轴,ORIENTED 用方向与相机方向叉积。
  • genVertOffsets 用参数偏移 × 尺寸 × 轴合成四角偏移,再加到板位置得世界位置。
  • 流程:origin → 参数偏移 → 类型 → 局部轴 → 角点偏移 → 位置。

阅读导航:上一节:12.1 布告板集合 · 下一节:12.3 布告板渲染 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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