Irrlicht 引擎實戰：集成 FreeType 實現中文顯示

環境準備

• IDE: Visual Studio 2008
• Irrlicht SDK: 1.3 版 (官網下載)
• FreeType: 2.2.1 版 (SourceForge)

需將 freetype221MT.lib 加入鏈接器輸入依賴。

核心實現代碼

#include <irrlicht.h>
#include "TTFontManager.h"  // 封裝 FreeType 的字體管理器
#include "CGUITTFont.h"     // Irrlicht GUI 字體介面實現

using namespace irr;
using namespace irr::core;
using namespace irr::video;
using namespace irr::scene;
using namespace irr::gui;

#pragma comment(lib, "irrlicht.lib")
#pragma comment(lib, "freetype221MT.lib")

int main() {
    // 1. 創建設備 (Direct3D 9, 640x480, 16位色)
    IrrlichtDevice *device = createDevice(EDT_DIRECT3D9, 
        dimension2d<s32>(640, 480), 16, false, false, false, 0);
    if (!device) return 1;

    device->setWindowCaption(L"你好 世界!"); // 窗口標題支援 Unicode

    // 2. 獲取核心子系統
    IVideoDriver *driver = device->getVideoDriver();
    ISceneManager *smgr = device->getSceneManager();
    IGUIEnvironment *guienv = device->getGUIEnvironment();

    // 3. 內建字體測試 (僅支援 ASCII)
    guienv->addStaticText(L"Hello World.", rect<s32>(10,10,200,20), true);

    // 4. 初始化 TrueType 字體管理器 (單例模式)
    new TTFontManager(driver);
    TTFontManager *ttmgr = TTFontManager::GetSingletonPtr();

    // 5. 載入系統字體 (宋體 simsun.ttc, 24 像素)
    IGUIFont *font = ttmgr->getFont("simsun.ttc", 24);
    if (!font) {
        device->drop();
        return 1;
    }

    // 6. 建立簡單場景：貼圖立方體 + 相機
    ISceneNode *cubeNode = smgr->addCubeSceneNode(100.0f);
    ITexture *tex = driver->getTexture("texture.jpg");
    cubeNode->setMaterialTexture(0, tex);
    cubeNode->setMaterialFlag(EMF_LIGHTING, false); // 無光照，純貼圖
    smgr->addCameraSceneNode(0, vector3df(100,100,-100), vector3df(0,0,0));

    // 7. 主渲染循環
    while (device->run()) {
        driver->beginScene(true, true, SColor(255,200,200,255)); // 清屏+深度
        smgr->drawAll();       // 繪製 3D 場景
        guienv->drawAll();     // 繪製 GUI 元素 (內建字體)

        // 使用 FreeType 字體繪製中文 (座標矩形, 顏色紅色)
        font->draw(L"這是一段中文,字體為宋體!", 
                   rect<s32>(0,200,200,30), 
                   SColor(255,255,0,0));

        driver->endScene();
    }

    // 8. 資源釋放 (逆序)
    font->drop();
    delete ttmgr;
    device->drop();

    return 0;
}

關鍵技術點解析

1. TTFontManager / CGUITTFont 封裝層

Irrlicht 內建字體 (IGUIFont) 僅支援位圖字體，無法直接渲染 TTF/TTC。TTFontManager 封裝 FreeType 完成：

• 字體文件加載 (FT_New_Face)
• 字形光柵化 (FT_Load_Glyph, FT_Render_Glyph)
• 生成 Irrlicht 紋理圖集
• 實現 IGUIFont::draw() 繪製介面

（完整封裝代碼較長，見附件 TTFontManager.h/.cpp, CGUITTFont.h/.cpp）

2. Unicode 支援

• 源文件保存為 UTF-8 / UTF-16 (Visual Studio 2008 預設支持)
• 字面量加 L"" 前綴 → wchar_t* 寬字符串
• Irrlicht 核心 API 統一使用寬字符 (wchar_t / irr::core::stringw)

3. 字體文件路徑

simsun.ttc 為 Windows 系統字體，通常位於 C:\Windows\Fonts\。實際部署時建議：

• 將所需字體文件複製到項目資源目錄
• 使用相對路徑 "./fonts/simsun.ttc"
• 避免依賴系統目錄，提升可移植性

運行效果

程序啟動後顯示：

• 3D 場景：旋轉的貼圖立方體
• GUI 層：頂部 "Hello World." (內建字體)
• GUI 層：中部 "這是一段中文,字體為宋體!" (FreeType 渲染，清晰無鋸齒)

常見問題與避坑指南

擴展建議

• 封裝字體大小/顏色/描邊/陰影等樣式屬性
• 支援從內存緩衝區加載字體 (打包進資源文件)
• 集成 HarfBuzz 實現複雜文本佈局 (阿拉伯語連字、印地語重排等)
• 升級 Irrlicht 1.8+ / 1.9 版本，內建 CGUITTFont 已較完善