如何将FreeType位图拷贝至指定偏移位置的Magick::Image中

DevOps 小满

2026-8-30

问题背景

自研游戏引擎内置了封装OpenGL、DirectX等底层图形库的纹理加载API，该API基于Magick++实现，属于跨平台便捷方案，可快速生成程序化纹理。
当前正在基于FreeType开发文本渲染系统，需要调用这套纹理API动态生成字形水平排列的字体纹理图集。
此前已实现直接将位图缓冲写入OpenGL的版本，本次需要基于Magick++完成平台无关的实现。
核心需求：已获取FreeType生成的字形位图，需要将其像素缓冲区拷贝到Magick::Image对象的指定偏移位置。

现有代码框架

auto texture = e6::textures->create(e6::texture::specification{}, [name, totalWidth, maxHeight](){

      // 初始化FreeType
      FT_Face face;
      FT_Library ft;

      if (FT_Init_FreeType(&ft)) {
        std::cout << "ERROR::FREETYPE: Could not init FreeType Library" << std::endl;
      }

      if (int error = FT_New_Face(ft, path(name.c_str()).c_str(), 0, &face)) {
        std::cout << "Failed to initialise fonts: " << name << std::endl;
        throw std::exception();
      }

      // 设置字体字号
      FT_Set_Pixel_Sizes(face, 0, 100);

      unsigned int cursor = 0; // 记录水平偏移位置

      // 预分配图像缓冲区
      // totalWidth和maxHeight为整个纹理图集的尺寸
      Magick::Image image(Magick::Geometry(totalWidth, maxHeight), "BLACK");
      image.type(Magick::GrayscaleType);
      image.magick("BMP");
      image.depth(8);
      image.modifyImage();
      Magick::Pixels view(image);

      // 遍历ASCII可打印字符集
      for (uint8_t c = 32; c < 128; c++) {
        if (FT_Load_Char(face, c, FT_LOAD_RENDER)) {
          std::cout << "Failed to load glyph: " << c << std::endl;
          continue;
        }

        // 字形参数定义
        unsigned int width = face->glyph->bitmap.width;
        unsigned int height = face->glyph->bitmap.rows;
        unsigned char* image_data = face->glyph->bitmap.buffer;

        // 待实现部分：将image_data拷贝到image的cursor偏移位置

        cursor += width; // 移动水平光标
      }

      image.write(std::string(TEXTURES) + "font-test.bmp"); // 写入文件测试

      // 清理FreeType资源
      FT_Done_Face(face);
      FT_Done_FreeType(ft);

      return image;
    }, "font-" + name);

已尝试方案与故障现象

参照官方像素缓存接口编写的实现代码如下：

Magick::Quantum *pixels = view.get(cursor, 0, width, height);
*pixels = *image_data;
view.sync();

运行后生成完全黑色的图像，最初推测是image_data离开作用域导致拷贝失败。

故障原因

之前的实现存在两个核心错误，和image_data作用域无关：

仅拷贝了单个像素：*pixels = *image_data; 只把字形缓冲区的第一个字节写入了像素数组的第一个位置，区域内其余像素仍为初始黑色值。
未做像素值范围转换：Magick::Quantum的取值范围和ImageMagick编译时的量子深度绑定，默认Q16版本取值范围为0_{65535，直接传入8位灰度值（0}255）时，最大亮度255仅为满亮度的0.3%，视觉上接近纯黑。
额外需要注意坐标方向差异：FreeType生成的位图原点在左下角，Magick::Image坐标原点在左上角，直接按顺序拷贝会出现字形上下颠倒的问题。

正确实现

替换待实现部分的代码如下，兼容所有量子深度的ImageMagick版本，同时处理了字形翻转问题：

const size_t glyphW = face->glyph->bitmap.width;
const size_t glyphH = face->glyph->bitmap.rows;
const unsigned char* glyphBuf = face->glyph->bitmap.buffer;
// 8位灰度值到Magick::Quantum的缩放系数
const Magick::Quantum scale = Magick::MaxRGB / 255;

// 获取目标区域可写像素指针
Magick::Quantum* writePtr = view.get(cursor, 0, glyphW, glyphH);

// 倒序遍历源位图行，适配FreeType和Magick的坐标原点差异
for (int srcRow = glyphH - 1; srcRow >= 0; --srcRow) {
    const unsigned char* rowStart = glyphBuf + srcRow * glyphW;
    for (size_t col = 0; col < glyphW; ++col) {
        // 灰度值转换后写入像素数组
        *writePtr++ = rowStart[col] * scale;
    }
}

cursor += glyphW;

注意：view.sync()调用移到所有字形遍历完成后执行一次即可，循环内频繁调用会带来不必要的性能开销。如果后续渲染阶段会通过纹理坐标处理字形翻转，可去掉源行倒序遍历的逻辑。

内容的提问来源于stack exchange，提问作者user6811107