多通道有符号距离场生成器

这是一个用于从矢量形状和字体字形生成有符号距离场的工具，可作为纹理表示用于实时图形中高效复现这些形状。虽然它也可以用来生成最著名的传统有符号距离场（如Valve的这篇论文所述）和垂直距离场，但其主要目的是使用我开发的方法生成多通道距离场。与单色距离场不同，它们能够通过利用所有三个颜色通道几乎完美地复现锐角。

下面的比较展示了图像质量的提升。

• 要了解更多关于这种方法的信息，您可以阅读我的硕士论文。
• 如果您想为文本渲染生成完整的字体图集，请查看我的MSDF-Atlas-Gen。
• 查看更新日志了解最新变化。

入门

该项目可以作为库或控制台程序使用。它分为两部分，core和extensions。核心模块没有依赖项，只使用纯C++。它包含所有关键的数据结构和算法，可以通过msdfgen.h头文件访问。扩展包含用于加载字体和SVG文件以及保存PNG图像的实用工具。这些由msdfgen-ext.h头文件暴露。该模块使用FreeType、TinyXML2、libpng和（可选的）Skia。

此外，还有main.cpp，它将功能封装成一个综合的独立控制台程序。要立即开始使用该程序，可以在"Releases"部分下载Windows二进制文件。要将项目作为库使用，您可以通过vcpkg包管理器安装：

vcpkg install msdfgen

或者，要从源代码构建项目，您可以使用包含的CMake脚本。在默认配置中，它需要vcpkg作为第三方库依赖项的提供者。如果您将环境变量VCPKG_ROOT设置为vcpkg目录，CMake配置将自动从vcpkg获取所有必需的包。

控制台命令

独立程序的执行方式为：

msdfgen.exe <模式> <输入> <选项>

其中只有输入规范是必需的。

模式可以是以下之一：

• sdf – 生成常规单色（真）有符号距离场。
• psdf – 生成单色有符号垂直距离场。
• msdf（默认）– 使用我的新方法生成多通道有符号距离场。
• mtsdf – 生成在alpha通道中结合多通道和真有符号距离场。

输入可以指定为以下之一：

• -font <filename.ttf> <字符代码> – 从字体文件加载字形。字符代码可以表示为十进制（63）或十六进制（0x3F）Unicode值，或单引号中的ASCII字符（'?'）。
• -svg <filename.svg> – 加载SVG文件。注意，只会使用文件中的最后一个矢量路径。
• -shapedesc <filename.txt>、-defineshape <定义>、-stdin – 分别从文件、下一个参数或标准输入加载形状的文本描述。其语法在下文中有详细说明。

可以使用**-help**打印完整的可用选项列表。 一些重要的选项包括：

• -o <filename> – 指定输出文件名。所需格式将从扩展名推断（png、bmp、tiff、rgba、fl32、txt、bin）。否则，使用-format。
• -dimensions <宽度> <高度> – 指定输出距离场的尺寸（以像素为单位）。
• -range <范围>、-pxrange <范围> – 分别以形状单位或距离场像素指定形状周围可表示的最小和最大有符号距离之间的范围宽度。
• -scale <比例> – 设置用于将形状单位转换为距离场像素的比例。
• -translate <x> <y> – 以形状单位设置形状的平移。否则，原点（0, 0）位于左下角。
• -autoframe – 自动调整形状大小以适应距离场。如果输出必须精确对齐，您应该使用-translate和-scale手动定位。
• -angle <角度> – 指定被视为角的最大角度。可以用弧度（3.0）或度数（末尾加D，如171.9D）表示。
• -testrender <filename.png> <宽度> <高度> - 通过使用生成的距离场将原始形状渲染到具有指定尺寸的PNG文件中来测试它。或者，-testrendermulti在不组合颜色通道的情况下渲染图像，可能让您了解多通道距离场的工作原理。
• -exportshape <filename.txt> - 将带有边缘着色的形状文本描述保存到指定文件。这可以稍后通过-shapedesc编辑和用作输入。
• -printmetrics – 打印有关形状布局的一些有用信息。

例如，

msdfgen.exe msdf -font C:\Windows\Fonts\arialbd.ttf 'M' -o msdf.png -dimensions 32 32 -pxrange 4 -autoframe -testrender render.png 1024 1024

将从Arial Bold字体中获取大写字母M，生成32×32的多通道距离场，距离范围为4像素宽，将其存储到msdf.png中，并创建字形的测试渲染为render.png。

注意： 不要使用-autoframe来生成字符映射！它仅用于快速预览。

库API

如果您选择在自己的程序中使用这个工具，需要执行一些简单的步骤来生成距离场。请注意，所有类和函数都在msdfgen命名空间中。

• 获取一个 Shape 对象。你可以通过 loadGlyph 或 loadSvgShape 加载它，或者手动构造它。它由闭合轮廓组成，而轮廓又由边组成。边由 LinearEdge、QuadraticEdge 或 CubicEdge 表示。你可以用两个端点和 0 到 2 个贝塞尔控制点构造它们。

• 使用 normalize 方法规范化形状，如果需要多通道 SDF，则为边分配颜色。这可以使用 edgeColoringSimple（或其他）启发式方法自动完成，或通过手动设置每条边的 color 成员来完成。请记住，每条边至少要开启两个颜色通道。

• 调用 generateSDF、generatePSDF、generateMSDF 或 generateMTSDF 来生成一个浮点型 Bitmap 对象的距离场。然后可以进一步处理或使用 saveBmp、savePng、saveTiff 等保存到文件。

• 你还可以使用 renderSDF 从距离场渲染图像。考虑在此之前对距离场调用 simulate8bit 来模拟标准的 8 位/通道图像格式。

示例：

#include <msdfgen.h>
#include <msdfgen-ext.h>

using namespace msdfgen;

int main() {
    if (FreetypeHandle *ft = initializeFreetype()) {
        if (FontHandle *font = loadFont(ft, "C:\\Windows\\Fonts\\arialbd.ttf")) {
            Shape shape;
            if (loadGlyph(shape, font, 'A', FONT_SCALING_EM_NORMALIZED)) {
                shape.normalize();
                //                      最大角度
                edgeColoringSimple(shape, 3.0);
                //          输出宽度, 高度
                Bitmap<float, 3> msdf(32, 32);
                //                            缩放, 平移（以 em 为单位）
                SDFTransformation t(Projection(32.0, Vector2(0.125, 0.125)), Range(0.125));
                generateMSDF(msdf, shape, t);
                savePng(msdf, "output.png");
            }
            destroyFont(font);
        }
        deinitializeFreetype(ft);
    }
    return 0;
}

使用多通道距离场

使用由此程序生成的多通道距离场与使用单色距离场类似。唯一的额外操作是在片段着色器内部计算三个通道的中值，就在采样距离场之后。然后可以像往常一样使用这个有符号距离值。

以下是一个带有抗锯齿的 GLSL 片段着色器示例：

in vec2 texCoord;
out vec4 color;
uniform sampler2D msdf;
uniform vec4 bgColor;
uniform vec4 fgColor;

float median(float r, float g, float b) {
    return max(min(r, g), min(max(r, g), b));
}

void main() {
    vec3 msd = texture(msdf, texCoord).rgb;
    float sd = median(msd.r, msd.g, msd.b);
    float screenPxDistance = screenPxRange()*(sd - 0.5);
    float opacity = clamp(screenPxDistance + 0.5, 0.0, 1.0);
    color = mix(bgColor, fgColor, opacity);
}

这里，screenPxRange() 表示输出屏幕像素中的距离场范围。例如，如果在生成 32x32 距离场时像素范围设置为 2，并且用它来绘制屏幕上 72x72 像素的四边形，它应该返回 4.5（因为 72/32 * 2 = 4.5）。 对于 2D 渲染，这通常可以替换为预先计算的统一值。

仅对于3D 透视渲染，其中纹理比例在屏幕上变化，你可能想要用以下方式实现这个函数，使用片段导数。我建议预先计算 unitRange 作为统一变量，而不是 pxRange，以获得更好的性能。

uniform float pxRange; // 设置为距离场的像素范围

float screenPxRange() {
    vec2 unitRange = vec2(pxRange)/vec2(textureSize(msdf, 0));
    vec2 screenTexSize = vec2(1.0)/fwidth(texCoord);
    return max(0.5*dot(unitRange, screenTexSize), 1.0);
}

screenPxRange() 绝不能低于 1。如果低于 2，抗锯齿很可能会失败，你可能需要用更宽的范围重新生成距离场。

形状描述语法

文本形状描述具有以下语法。

• 每个闭合轮廓用大括号括起来：{ <轮廓 1> } { <轮廓 2> }
• 每个点（和控制点）写作两个用逗号分隔的实数。
• 轮廓中的点用分号分隔。
• 每个轮廓的最后一个点必须等于第一个点，或者可以使用符号 #，它表示第一个点。
• 任意两点之间可以有边段规格，也用分号分隔。这可以包括边的颜色（c、m、y 或 w）和/或括号内的一个或两个贝塞尔曲线控制点。

例如，

{ -1, -1; m; -1, +1; y; +1, +1; m; +1, -1; y; # }

表示一个带有品红色和黄色边的正方形，

{ 0, 1; (+1.6, -0.8; -1.6, -0.8); # }

是由单个三次贝塞尔曲线形成的泪滴形状。