使用FreeType与SDL2渲染文本时出现白方块而非字符

嘿，我之前在做SDL2+FreeType文本渲染的时候也踩过这个白方块的坑，太懂那种调试半天没进展的感觉了！咱们从几个核心点来排查和解决：

FreeType用FT_LOAD_RENDER加载字形后，生成的是8位灰度位图——每个字节存储的是字符的Alpha通道值（0=透明背景，255=完全不透明的字符），而不是RGB颜色值。如果你的SDL_Surface参数没对应上，就会把这些灰度值错误解析成RGB，导致全白方块。

1. 确认FreeType的字形加载方式 #

首先要保证你用了正确的加载标记，让FreeType生成位图：

// 加载'A'字符的字形，必须加FT_LOAD_RENDER
FT_UInt glyph_index = FT_Get_Char_Index(face, 'A');
if (FT_Load_Glyph(face, glyph_index, FT_LOAD_RENDER) != 0) {
    fprintf(stderr, "加载字形失败！\n");
    return;
}
// 转换成位图字形
FT_BitmapGlyph bitmap_glyph = (FT_BitmapGlyph)glyph;
FT_Bitmap* bitmap = &bitmap_glyph->bitmap;

如果没加FT_LOAD_RENDER，FreeType只会生成矢量数据，不会生成像素buffer，这时候用空buffer创建SDL_Surface就会显示白块。

2. 正确创建SDL_Surface #

针对FreeType的8位Alpha位图，你需要创建A8格式的SDL_Surface，掩码要只启用Alpha通道：

SDL_Surface* glyph_surface = SDL_CreateRGBSurfaceFrom(
    bitmap->buffer,          // FreeType的像素buffer
    bitmap->width,           // 字形宽度
    bitmap->rows,            // 字形高度
    8,                       // 8位像素深度（对应Alpha通道）
    bitmap->pitch,           // 每行字节数（FreeType已提供）
    0, 0, 0, 0xFF            // A8格式掩码：只Alpha通道有效
);

如果之前用了RGB的掩码（比如0xFF0000, 0x00FF00, 0x0000FF, 0），SDL会把8位的Alpha值当成红色通道，其他通道为0，最终显示白色（因为红色满值+无透明）。

3. 开启混合模式让Alpha生效 #

创建完Surface后，一定要设置正确的混合模式，不然SDL会忽略Alpha通道，把整个Surface当成不透明的白色块：

if (SDL_SetSurfaceBlendMode(glyph_surface, SDL_BLENDMODE_BLEND) != 0) {
    fprintf(stderr, "设置混合模式失败：%s\n", SDL_GetError());
}

4. 可选：转成RGBA格式适配32位渲染目标 #

如果你的目标渲染表面是32位RGBA格式，也可以手动把FreeType的8位Alpha转成RGBA像素（字符用白色，Alpha用FreeType的值）：

// 创建32位RGBA Surface
SDL_Surface* glyph_surface = SDL_CreateRGBSurface(0, bitmap->width, bitmap->rows, 32,
    0xFF000000,  // R掩码
    0x00FF0000,  // G掩码
    0x0000FF00,  // B掩码
    0x000000FF   // A掩码
);
uint32_t* dst_pixels = (uint32_t*)glyph_surface->pixels;

// 逐像素填充RGBA数据
for (int y = 0; y < bitmap->rows; y++) {
    for (int x = 0; x < bitmap->width; x++) {
        uint8_t alpha = bitmap->buffer[y * bitmap->pitch + x];
        // 白色字符 + FreeType的Alpha值
        dst_pixels[y * glyph_surface->w + x] = (0xFF << 24) | (0xFF << 16) | (0xFF << 8) | alpha;
    }
}

• 检查字形是否正确加载：可以打印bitmap->width和bitmap->rows，如果是0说明字形加载有问题
• 确认SDL渲染目标的格式：如果目标Surface没有Alpha通道，可能会导致透明部分显示白色背景，这时候需要先填充目标Surface的背景色再渲染

按照上面的步骤调整后，应该就能正常显示字符而不是白方块了！

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