《OGRE 3D 渲染引擎原理与架构》15.2 相机视口装配

相机视口装配把 RenderTarget、Camera、Viewport 连成三元组:Viewport 构造时把相对矩形缩放成实际像素矩形,_updateDimensions 在 autoAspectRatio 为真时同步相机 aspect;aspect 进入视锥投影,固定垂直 FOV 按 aspect 缩放水平视场。源码在 OgreMain/ 的 OgreViewport.cpp 与 OgreFrustum.cpp。lab 复现尺寸换算、aspect 同步与投影缩放。

15.2 相机视口装配

15.1 造出了场景管理器,它手里有一个相机。但相机要真正成像,得挂到一块渲染目标上、占一个视口。这一节讲 RenderTarget、Camera、Viewport 三元组怎么装配:相对矩形怎么变成像素矩形、相机长宽比怎么跟视口同步、长宽比怎么进入投影。

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

本卷 2.1 节讲过 Frustum 的投影矩阵、2.2 节讲过 Viewport 的裁剪。这一节把两者接到一起:视口是「相机 → 渲染目标」之间的接线员。RTSS 的 scheme 切换、覆盖层的尺寸也依赖视口的实际尺寸——它在 _updateDimensions 里完成像素换算。

三元组:RenderTarget / Camera / Viewport

Viewport 的构造参数直接就是三元组的成员:一个相机、一块渲染目标、一个相对矩形、一个 Z 序:

// OgreMain/src/OgreViewport.cpp:Viewport::Viewport(v14.6.3 源码摘录,已删减)
    Viewport::Viewport(Camera* cam, RenderTarget* target, FloatRect relRect, int ZOrder)
        : mCamera(cam)
        , mTarget(target)
        , mRelRect(relRect)
        // Actual dimensions will update later
        , mZOrder(ZOrder)
        , mBackColour(ColourValue::Black)
        , mDepthClearValue(1)
        , mClearEveryFrame(true)
        , mClearBuffers(FBT_COLOUR | FBT_DEPTH)
        , mUpdated(false)
        , mShowOverlays(true)
        , mShowSkies(true)
        , mShowShadows(true)
        , mVisibilityMask(0xFFFFFFFF)
        , mMaterialSchemeName(MaterialManager::DEFAULT_SCHEME_NAME)
        , mIsAutoUpdated(true)
		, mColourBuffer(CBT_BACK)
    {           
        // Calculate actual dimensions
        _updateDimensions();

        // notify camera
        if(cam) cam->_notifyViewport(this);
    }

构造完立即 _updateDimensions() 算出实际像素矩形,并通知相机「你被挂到了一个视口」。Z 序决定同目标上多个视口谁先画。

_updateDimensions:相对矩形 → 像素矩形

相对矩形(0..1)乘上目标的宽高就得到实际像素矩形:

// OgreMain/src/OgreViewport.cpp:Viewport::_updateDimensions(v14.6.3 源码摘录,已删减)
    void Viewport::_updateDimensions(void)
    {
        Real height = (Real) mTarget->getHeight();
        Real width = (Real) mTarget->getWidth();

        mActRect = Rect(mRelRect.left * width, mRelRect.top * height, mRelRect.right * width, mRelRect.bottom * height);

        // This will check if the cameras getAutoAspectRatio() property is set.
        // If it's true its aspect ratio is fit to the current viewport
        // If it's false the camera remains unchanged.
        // This allows cameras to be used to render to many viewports,
        // which can have their own dimensions and aspect ratios.

        if (mCamera) 
        {
            if (mCamera->getAutoAspectRatio())
                mCamera->setAspectRatio((float)mActRect.width() / (float)mActRect.height());
        }

        mUpdated = true;

        for (auto *l : mListeners)
        {
            l->viewportDimensionsChanged(this);
        }
    }

两个值得注意的点:

  • 宽高比同步是有条件的:只有 getAutoAspectRatio() 为真时,视口才改写相机的 mAspect。一个相机可以挂多个视口(分屏、阴影贴图相机),各视口尺寸不同——关闭 autoAspectRatio 的相机保持自己的比例,不受某个视口影响。
  • 监听器通知:尺寸变化后 viewportDimensionsChanged 通知所有监听器,覆盖层的像素模式元素正是靠它重算。

setAspectRatio:进入视锥与投影

Frustum::setAspectRatio 写入比例并让视锥失效(下次取投影时重算):

// OgreMain/src/OgreFrustum.cpp:Frustum::setAspectRatio(v14.6.3 源码摘录,已删减)
    void Frustum::setAspectRatio(Real r)
    {
        mAspect = r;
        invalidateFrustum();
    }

invalidateFrustum() 置位 mFrustumInvalidated——投影矩阵、视锥面、包围盒等所有派生数据全部延迟重算。长宽比在投影里的作用很直接:固定垂直 FOV(mFovY),水平视场的半角正切等于 tan(fovY/2) * aspect。宽屏(aspect > 1)看到更宽的水平范围,垂直范围不变——这就是「FOV 是垂直的」这个约定的来源。

装配顺序与运行回路

完整装配:

  1. 创建相机,setAutoAspectRatio(true)(默认)。
  2. 构造 Viewport(cam, target, relRect, zOrder):_updateDimensions 算出像素矩形并同步相机 aspect。
  3. 相机 aspect 使视锥失效,渲染器取投影时重算。
  4. 目标尺寸变化(窗口 resize)→ _updateDimensions 再次执行 → aspect 重新同步 → 覆盖层等监听器重算。

源码定位

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

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

下面用纯 C++ 复现三元组装配:相对矩形 → 像素矩形换算、autoAspectRatio 同步与关闭时保持、setAspectRatio 的视锥失效、以及 aspect 进入投影的水平视场缩放。它与 src/15-2-camera-viewport-assembly.cpp 逐字节一致:

// file: src/15-2-camera-viewport-assembly.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/15-2-camera-viewport-assembly.cpp -o bin/15-2-camera-viewport-assembly && ./bin/15-2-camera-viewport-assembly
//
// 复现相机 + 视口 + 渲染目标三元组装配(对应 OgreMain/src/OgreRoot.cpp
// 962-981 的 Root::createRenderWindow、OgreMain/src/OgreViewport.cpp 33-69、97-126
// 的 Viewport 构造与 _updateDimensions,以及 OgreFrustum.cpp 713-717 的
// setAspectRatio):
//   RenderTarget 提供宽高;Viewport 以相对矩形缩放为实际像素矩形;
//   camera 的 autoAspectRatio 为真时按实际宽高比同步 aspect;
//   aspect 进入视锥(投影):固定垂直 FOV,水平范围按 aspect 缩放。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

#include <cmath>
#include <cstdint>
#include <string>

namespace ogre_repro {

using Real = float;

// 对应 Frustum(OgreFrustum.h 240-244):只保留 aspect 与投影。
class Frustum {
 public:
  Real getAspectRatio() const { return mAspect; }
  // 对应 Frustum::setAspectRatio(OgreFrustum.cpp 713-717)。
  void setAspectRatio(Real r) {
    mAspect = r;
    mFrustumInvalidated = true;
  }
  void setFovY(Real fovY) { mFovY = fovY; }
  Real getFovY() const { return mFovY; }

  // 简化投影:以 aspect 缩放水平视场,返回水平半角(tan 值)。
  Real getHorizontalTanHalf() const { return std::tan(mFovY * 0.5f) * mAspect; }
  bool isInvalidated() const { return mFrustumInvalidated; }
  void clearInvalidated() { mFrustumInvalidated = false; }

 protected:
  Real mAspect = 1.0f;
  Real mFovY = 0.785398f;  // 45 度
  bool mFrustumInvalidated = false;
};

// 对应 Camera(OgreCamera.cpp 853-861):继承 Frustum + autoAspectRatio。
class Camera : public Frustum {
 public:
  explicit Camera(const std::string& name) : mName(name), mAutoAspectRatio(true) {}
  bool getAutoAspectRatio() const { return mAutoAspectRatio; }
  void setAutoAspectRatio(bool b) { mAutoAspectRatio = b; }
  const std::string& getName() const { return mName; }

 private:
  std::string mName;
  bool mAutoAspectRatio;
};

// 对应 RenderTarget:只记录宽高。
class RenderTarget {
 public:
  RenderTarget(unsigned int w, unsigned int h) : mWidth(w), mHeight(h) {}
  unsigned int getWidth() const { return mWidth; }
  unsigned int getHeight() const { return mHeight; }

 private:
  unsigned int mWidth, mHeight;
};

// 对应 FloatRect / Rect。
struct FloatRect {
  Real left, top, right, bottom;
};
struct Rect {
  Real left, top, right, bottom;
  Real width() const { return right - left; }
  Real height() const { return bottom - top; }
};

// 对应 Viewport(OgreViewport.cpp 33-126)。
class Viewport {
 public:
  Viewport(Camera* cam, RenderTarget* target, FloatRect relRect, int zOrder)
      : mCamera(cam), mTarget(target), mRelRect(relRect), mZOrder(zOrder) {
    (void)mZOrder;  // 对应 Viewport 的 Z 序(本复现不涉及多视口先后渲染)
    updateDimensions();
  }

  // 对应 Viewport::_updateDimensions(OgreViewport.cpp 97-126)。
  void updateDimensions() {
    Real width = static_cast<Real>(mTarget->getWidth());
    Real height = static_cast<Real>(mTarget->getHeight());
    mActRect = Rect{mRelRect.left * width, mRelRect.top * height,
                    mRelRect.right * width, mRelRect.bottom * height};
    if (mCamera) {
      if (mCamera->getAutoAspectRatio())
        mCamera->setAspectRatio(mActRect.width() / mActRect.height());
    }
    mUpdated = true;
  }

  // 对应 Viewport::setDimensions(OgreViewport.cpp 128-132)。
  void setDimensions(float left, float top, float width, float height) {
    mRelRect = FloatRect{left, top, left + width, top + height};
    updateDimensions();
  }

  Rect getActRect() const { return mActRect; }
  bool isUpdated() const { return mUpdated; }

 private:
  Camera* mCamera;
  RenderTarget* mTarget;
  FloatRect mRelRect;
  int mZOrder;
  Rect mActRect{0, 0, 0, 0};
  bool mUpdated = false;
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  // 渲染目标 + 相机三元组
  RenderTarget target(800, 600);
  Camera cam("MainCamera");
  CHECK(cam.getAutoAspectRatio());

  // 全屏视口:相对 (0,0,1,1) -> 实际 (0,0,800,600)
  Viewport vp(&cam, &target, FloatRect{0, 0, 1, 1}, 0);
  CHECK(vp.isUpdated());
  Rect act = vp.getActRect();
  CHECK_EQ(act.width(), 800.0f);
  CHECK_EQ(act.height(), 600.0f);
  // autoAspectRatio 为真:aspect = 800/600 = 4/3
  CHECK(std::fabs(cam.getAspectRatio() - 4.0f / 3.0f) < 1e-5f);

  // 半屏视口(左半):实际宽 400
  Viewport vp2(&cam, &target, FloatRect{0, 0, 0.5f, 1}, 1);
  Rect act2 = vp2.getActRect();
  CHECK_EQ(act2.width(), 400.0f);
  CHECK(std::fabs(cam.getAspectRatio() - 400.0f / 600.0f) < 1e-5f);

  // setDimensions:改变相对矩形并重算
  vp2.setDimensions(0.25f, 0.25f, 0.5f, 0.5f);
  Rect act3 = vp2.getActRect();
  CHECK_EQ(act3.left, 200.0f);  // 0.25 * 800
  CHECK_EQ(act3.top, 150.0f);   // 0.25 * 600
  CHECK_EQ(act3.width(), 400.0f);
  CHECK_EQ(act3.height(), 300.0f);
  CHECK(std::fabs(cam.getAspectRatio() - 400.0f / 300.0f) < 1e-5f);

  // autoAspectRatio 为假:相机 aspect 不被视口改写
  cam.setAutoAspectRatio(false);
  cam.clearInvalidated();
  cam.setAspectRatio(1.6f);
  CHECK(cam.isInvalidated());  // setAspectRatio 触发视锥失效
  cam.clearInvalidated();
  Viewport vp3(&cam, &target, FloatRect{0, 0, 1, 1}, 2);
  CHECK_EQ(cam.getAspectRatio(), 1.6f);
  CHECK(!cam.isInvalidated());  // 视口未改写相机 aspect

  // aspect 进入投影:固定垂直 FOV,水平半角 = tan(fovY/2) * aspect
  cam.setAutoAspectRatio(true);
  cam.setAspectRatio(2.0f);
  cam.setFovY(0.785398f);  // 45 度
  Real horizontalTan = cam.getHorizontalTanHalf();
  // tan(22.5°) ≈ 0.41421356,×2 = 0.82842712
  CHECK(std::fabs(horizontalTan - 0.82842712f) < 1e-4f);

  return lab::report("15-2 相机视口装配");
}

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

小结

  • Viewport 把相机、渲染目标、相对矩形、Z 序组成三元组,构造时立即算实际尺寸。
  • _updateDimensions 用目标宽高把相对矩形放大成像素矩形,尺寸变化时通知监听器。
  • autoAspectRatio 为真时视口同步相机 aspect;为假时相机比例不受视口影响(多视口复用相机)。
  • setAspectRatio 写入比例并令视锥失效,投影矩阵延迟重算。
  • 固定垂直 FOV 时,水平半角正切 = tan(fovY/2) * aspect,宽屏看更宽的水平范围。

阅读导航:上一节:15.1 场景装配 · 下一节:15.3 完整一帧渲染 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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