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 脚本编译器 。
继续阅读
探索更多技术文章
浏览归档,发现更多关于系统设计、工具链和工程实践的内容。