《OGRE 3D 渲染引擎原理与架构》3.3 编解码器

编解码器用静态注册表管理:Codec 抽象定义 encode/decode 与 magicNumberToFileExt,registerCodec 按类型挂进 msMapCodecs,getCodec 先小写化扩展名再查,getCodec(magic) 遍历注册表用魔数反查文件扩展名。lab 复现 Png/Jpeg 两个解码器的注册、大小写查找与魔数识别。

3.3 编解码器

3.2 节的 Archive 帮你从容器里取到文件字节流,但字节流离「可用的资源」还差一步——PNG 的像素、WAV 的采样、DDS 的压缩块,都需要一个专门的解码器来翻译。OGRE 管这个叫 Codec:一类把「编码数据」转成「引擎可用数据」的双向过滤器。这一节看它的注册表机制和两种查询路径。

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

第 3.2 节结束于 Archive 提供的 DataStream,本节从 DataStream 继续往下走。卷一讲纹理加载时提过 FreeImage 插件,但没展开编解码器的注册机制;这里把 Codec 的静态注册表、扩展名查询、魔数反查三条路径讲透,并解释为什么 OGRE 没有独立的「编解码管理器」类——注册表直接挂在 Codec 基类上。

Codec 抽象:双向过滤器

Codec 的类文档把设计意图讲得很直白——「a codec class works like a two-way filter for data」:

// OgreMain/include/OgreCodec.h:Codec 抽象(v14.6.3 源码摘录,已删减)
    /** Abstract class that defines a 'codec'.

        A codec class works like a two-way filter for data - data entered on
        one end (the decode end) gets processed and transformed into easily
        usable data while data passed the other way around codes it back.
        @par
            The codec concept is a pretty generic one - you can easily understand
            how it can be used for images, sounds, archives, even compressed data.
    */
    class _OgreExport Codec : public CodecAlloc
    {
    private:
        typedef std::map< String, Codec* > CodecList; 
        /** A map that contains all the registered codecs.
        */
        static CodecList msMapCodecs;

    public:
        virtual ~Codec();

        /** Registers a new codec in the database.
        */
        static void registerCodec( Codec *pCodec );

        /** Return whether a codec is registered already. 
        */
        static bool isCodecRegistered( const String& codecType )
        {
            return msMapCodecs.find(codecType) != msMapCodecs.end();
        }

        /** Unregisters a codec from the database.
        */
        static void unregisterCodec( Codec *pCodec )
        {
            msMapCodecs.erase(pCodec->getType());
        }

        /** Gets the file extension list for the registered codecs. */
        static StringVector getExtensions(void);

        /** Gets the codec registered for the passed in file extension. */
        static Codec* getCodec(const String& extension);

        /** Gets the codec that can handle the given 'magic' identifier. 
        @param magicNumberPtr Pointer to a stream of bytes which should identify the file.
            Note that this may be more than needed - each codec may be looking for 
            a different size magic number.
        @param maxbytes The number of bytes passed
        */
        static Codec* getCodec(char *magicNumberPtr, size_t maxbytes);

关键设计点是那句 static CodecList msMapCodecs——注册表是 Codec 基类的静态成员,不是独立的管理器类。registerCodec/unregisterCodec/isCodecRegistered/getCodec 全是静态方法,任何代码都能直接 Codec::getCodec(...) 查询,不必先拿某个管理器单例。一个解码器类可以注册多个实例(每个实例一个扩展名),这正是 FreeImage 插件的做法:一个 FreeImageCodec 类,构造出 png、jpg、tga 等多个实例分别注册。

解码器实例之间靠 getType() 区分——这个纯虚方法返回它的类型字符串(通常就是扩展名)。unregisterCodec 用 pCodec->getType() 作为 key 从 map 中擦除。

注册与查询:小写化是关键

registerCodec 与 getCodec 的实现展示了两端的小心翼翼:

// OgreMain/src/OgreCodec.cpp:registerCodec / getCodec(v14.6.3 源码摘录,已删减)
    void Codec::registerCodec(Codec* pCodec)
    {
        auto ret = msMapCodecs.emplace(pCodec->getType(), pCodec);
        if (!ret.second)
            OGRE_EXCEPT(Exception::ERR_DUPLICATE_ITEM, pCodec->getType() + " already has a registered codec");
    }

    Codec* Codec::getCodec(const String& extension)
    {
        String lwrcase = extension;
        StringUtil::toLowerCase(lwrcase);
        CodecList::const_iterator i = msMapCodecs.find(lwrcase);
        if (i == msMapCodecs.end())
        {
            String formats_str;
            if(msMapCodecs.empty())
                formats_str = "There are no formats supported (no codecs registered).";
            else
                formats_str = "Supported formats are: " + StringConverter::toString(getExtensions()) + ".";

            OGRE_EXCEPT(Exception::ERR_ITEM_NOT_FOUND,
                        "Can not find codec for '" + extension + "' format.\n" + formats_str);
        }

        return i->second;
    }

registerCodec 用 emplace 检测重复:如果 getType() 已经注册过,ret.second 为 false,直接抛 ERR_DUPLICATE_ITEM。getCodec 的关键动作是 StringUtil::toLowerCase(lwrcase)——查询前把扩展名小写化。这意味着调用方传 "PNG" 还是 "png" 都能命中同一个实例;但反过来要求注册端必须用小写类型名,否则查询小写化后永远找不到。

getCodec 查不到时抛 ERR_ITEM_NOT_FOUND,异常消息会列出当前支持的所有格式(Supported formats are: ...)——这是报错信息里最有用的调试线索:一看到格式列表就知道自己的扩展名是不是漏了注册。

魔数反查:不用扩展名也能认文件

有些场景没有文件名可用(比如从内存字节流加载纹理),这时得靠文件的魔数头识别格式。getCodec(char* magicNumberPtr, size_t maxbytes) 遍历整个注册表,问每个解码器「这个字节头你认不认」:

// OgreMain/src/OgreCodec.cpp:getCodec(magic)(v14.6.3 源码摘录,已删减)
    Codec* Codec::getCodec(char *magicNumberPtr, size_t maxbytes)
    {
        for (auto& c : msMapCodecs)
        {
            String ext = c.second->magicNumberToFileExt(magicNumberPtr, maxbytes);
            if (!ext.empty())
            {
                // check codec type matches
                // if we have a single codec class that can handle many types, 
                // and register many instances of it against different types, we
                // can end up matching the wrong one here, so grab the right one
                if (ext == c.second->getType())
                    return c.second;
                else
                    return getCodec(ext);
            }
        }

        return 0;
    }

每个解码器通过 magicNumberToFileExt 检查字节头——认得出就返回它对应的扩展名,认不出返回空串。遍历到第一个「认得出」的解码器后有个细节分支:如果返回的 ext 与当前实例的 getType() 相同,直接返回当前实例;否则调用 getCodec(ext) 按扩展名反查正确的那个实例。注释解释了原因:同一个类注册多个实例时(如 FreeImageCodec 的 png/jpg 实例),魔数识别可能先碰到一个「兄弟实例」,必须回落到扩展名查询拿真正匹配的实例。

magicNumberToFileExt 是虚方法,基类默认返回空串:

// OgreMain/include/OgreCodec.h:magicNumberToFileExt(v14.6.3 源码摘录,已删减)
        /** Maps a magic number header to a file extension, if this codec recognises it.
        @param magicNumberPtr Pointer to a stream of bytes which should identify the file.
            Note that this may be more than needed - each codec may be looking for 
            a different size magic number.
        @param maxbytes The number of bytes passed
        @return A blank string if the magic number was unknown, or a file extension.
        */
        virtual String magicNumberToFileExt(const char* magicNumberPtr, size_t maxbytes) const;

PNG 的魔数是 89 50 4E 47,JPEG 是 FF D8——每个解码器在自己的实现里检查这些字节,认得出就返回 "png"/"jpg" 这样的扩展名。

扩展名和内容识别的分界

Archive 负责取得文件流,Codec 负责解释流,Resource 或组件把结果接入运行时。某些加载路径按扩展名取得 Codec,另一些路径可用内容标记辅助识别。

从 Mesh::loadImpl 跟踪按扩展名查询 Codec 的路径,分别测试文件缺失和缺少 Codec。两者在日志中属于不同层。

源码定位

  • OgreMain/include/OgreCodec.h :Codec 类(46-134)、msMapCodecs(58-61)、registerCodec(68)、isCodecRegistered(72)、unregisterCodec(79)、getCodec(extension)(88)、getCodec(magic)(96)、magicNumberToFileExt(131)
  • OgreMain/src/OgreCodec.cpp :msMapCodecs 定义(32)、registerCodec(61-66)、getCodec(extension)(68-86)、getCodec(magic)(88-107)

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

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

下面用纯 C++ 复现编解码器机制:Codec 静态注册表、小写化扩展名查询、魔数反查,以及 PngCodec/JpegCodec 两个实例的注册与注销。它与 src/ogre-ext-03-3-codec-manager.cpp 逐字节一致:

// file: src/ogre-ext-03-3-codec-manager.cpp
// tier: L1
// verify: clang++ -std=c++20 -I. src/ogre-ext-03-3-codec-manager.cpp -o bin/ogre-ext-03-3-codec-manager && ./bin/ogre-ext-03-3-codec-manager
//
// 复现编解码器机制(对应 OgreMain/include/OgreCodec.h 46-134 的 Codec 抽象、
//   OgreMain/src/OgreCodec.cpp 32/61-107 的 msMapCodecs/registerCodec/getCodec/
//   getCodec(magic),以及 PlugIns/FreeImageCodec 的多实例批量注册):静态注册表
//   按小写扩展名查找,getCodec(magic) 用 magicNumberToFileExt 反查;
//   一个解码器类可注册多个扩展名(PngCodec/JpegCodec 两实例)。
// 独立最小验证,非 OGRE 源码。
#include "verify.h"

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

namespace ogre_repro {

using String = std::string;

// 对应 OgreCodec.h 46-:编解码器抽象
class Codec {
 public:
  virtual ~Codec() {}
  virtual String getType() const = 0;
  // 对应 OgreCodec.h 122-131:魔数 → 扩展名,基类返回空串
  virtual String magicNumberToFileExt(const char* magic, std::size_t maxbytes) const {
    (void)magic;
    (void)maxbytes;
    return "";
  }
  // 解码:输入字节流 → 输出大小(简化契约)
  virtual std::size_t decode(const uint8_t* data, std::size_t size) const = 0;

  // 对应 OgreCodec.cpp 32:静态注册表
  static std::map<String, Codec*>& registry() {
    static std::map<String, Codec*> msMapCodecs;
    return msMapCodecs;
  }
  static void registerCodec(Codec* pCodec) {
    registry().emplace(pCodec->getType(), pCodec);
  }
  static void unregisterCodec(Codec* pCodec) { registry().erase(pCodec->getType()); }
  static bool isCodecRegistered(const String& type) {
    return registry().count(type) != 0;
  }
  // 对应 OgreCodec.cpp 68-86:先小写化再按扩展名查找
  static Codec* getCodec(const String& extension) {
    String lower = extension;
    for (auto& c : lower) c = static_cast<char>(std::tolower(static_cast<unsigned char>(c)));
    auto it = registry().find(lower);
    return it == registry().end() ? nullptr : it->second;
  }
  // 对应 OgreCodec.cpp 88-107:遍历注册表用魔数反查
  static Codec* getCodecByMagic(const char* magic, std::size_t maxbytes) {
    for (const auto& c : registry()) {
      String ext = c.second->magicNumberToFileExt(magic, maxbytes);
      if (!ext.empty()) return getCodec(ext);
    }
    return nullptr;
  }
};

// 仿 FreeImageCodec:PNG 实例识别 89 50 4E 47
class PngCodec : public Codec {
 public:
  String getType() const override { return "png"; }
  String magicNumberToFileExt(const char* magic, std::size_t maxbytes) const override {
    const uint8_t expected[4] = {0x89, 0x50, 0x4E, 0x47};
    if (maxbytes < 4) return "";
    const uint8_t* b = reinterpret_cast<const uint8_t*>(magic);
    if (b[0] == expected[0] && b[1] == expected[1] &&
        b[2] == expected[2] && b[3] == expected[3])
      return "png";
    return "";
  }
  std::size_t decode(const uint8_t* data, std::size_t size) const override {
    (void)data;
    return size;
  }
};

// JPEG 实例识别 FF D8
class JpegCodec : public Codec {
 public:
  String getType() const override { return "jpg"; }
  String magicNumberToFileExt(const char* magic, std::size_t maxbytes) const override {
    const uint8_t expected[2] = {0xFF, 0xD8};
    if (maxbytes < 2) return "";
    const uint8_t* b = reinterpret_cast<const uint8_t*>(magic);
    if (b[0] == expected[0] && b[1] == expected[1]) return "jpg";
    return "";
  }
  std::size_t decode(const uint8_t* data, std::size_t size) const override {
    (void)data;
    return size;
  }
};

}  // namespace ogre_repro

int main() {
  using namespace ogre_repro;

  PngCodec png;
  JpegCodec jpg;
  CHECK(!Codec::isCodecRegistered("png"));

  // 注册两个编解码器(对应 FreeImageCodec::startup 的批量注册)
  Codec::registerCodec(&png);
  Codec::registerCodec(&jpg);
  CHECK(Codec::isCodecRegistered("png"));
  CHECK(Codec::isCodecRegistered("jpg"));

  // 按扩展名查找:大小写不敏感
  Codec* byExt = Codec::getCodec("PNG");
  CHECK(byExt == &png);
  CHECK(Codec::getCodec("bmp") == nullptr);

  // 按魔数反查:PNG 头 89 50 4E 47
  const char pngMagic[4] = {static_cast<char>(0x89), 'P', 'N', 'G'};
  Codec* byMagic = Codec::getCodecByMagic(pngMagic, 4);
  CHECK(byMagic == &png);

  // JPEG 头 FF D8
  const char jpgMagic[2] = {static_cast<char>(0xFF), static_cast<char>(0xD8)};
  Codec* byMagic2 = Codec::getCodecByMagic(jpgMagic, 2);
  CHECK(byMagic2 == &jpg);

  // 未知魔数:遍历全部注册表仍找不到
  const char unknown[2] = {'X', 'Y'};
  CHECK(Codec::getCodecByMagic(unknown, 2) == nullptr);

  // 解码契约:输出大小等于输入
  const uint8_t bytes[8] = {1, 2, 3, 4, 5, 6, 7, 8};
  CHECK_EQ(png.decode(bytes, 8), size_t(8));
  CHECK_EQ(jpg.decode(bytes, 8), size_t(8));

  // 注销后 isCodecRegistered 变 false
  Codec::unregisterCodec(&png);
  CHECK(!Codec::isCodecRegistered("png"));
  CHECK(Codec::isCodecRegistered("jpg"));

  return lab::report("3.3 编解码器");
}

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

小结

  • Codec 是双向过滤器,msMapCodecs 静态注册表直接挂在基类上,没有独立管理器。
  • registerCodec 用 emplace 防重复;getCodec 查询前把扩展名小写化。
  • 一个解码器类可注册多个实例(如 FreeImageCodec 的 png/jpg),靠 getType() 区分。
  • getCodec(magic) 遍历注册表用 magicNumberToFileExt 反查,兄弟实例回落 getCodec(ext)。
  • 查不到扩展名时抛 ERR_ITEM_NOT_FOUND,异常信息列出全部已注册格式。

阅读导航:上一节:3.2 自定义存档 · 下一节:4.1 脚本编译器 。

继续阅读

探索更多技术文章

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

全部文章 返回首页

「books」更多文章

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