Chapitre -115 · SDF texte

Signed Distance Field — Text

Du texte dans ta vue Metal, depuis les polices d'écriture que tu aimes.

Distance Field (champ de distances) : Pour chaque pixel d'une image, tu stockes sa distance au bord le plus proche d'une forme.

Signed (signée) : Cette distance est positive à l'extérieur, négative à l'intérieur (ou l'inverse selon la convention).

Forme : un cercle
  extérieur            bord            intérieur
  +3  +2  +1     +0.5 [ 0.0 ] -0.5     -1  -2  -3
Ce n'est pas une invention GPU au départ —
c'est un concept de géométrie computationnelle qui existait bien avant.

Il n'est pas essentiel de tout connaitre, ce sont les étapes recommandé pour afficher du texte à l'écran et c'est une technique très utilisé. Néanmoins, si tu as des débordements, des caractères coupés ou autres, il est bien de savoir modifier le programme à ta gise (et parce que tu veux une super police géniale).

Histoire

80 s': Les SDF sont utilisés en robotique et en planification de trajectoire. Si ton robot sait la distance à l'obstacle le plus proche en chaque point, il peut naviguer proprement.
2007: Chris Green chez Valve publie le paper qui change tout → "Improved Alpha-Tested Magnification for Vector Textures and Special Effects" (SIGGRAPH 2007). Il applique l'idée aux glyphes de texte pour les jeux. Avant ça, Source Engine avait du texte moche qui pixelisait. Après, un seul atlas petit = texte net à toutes les tailles.; C'est littéralement un ingénieur de Valve qui a popularisé la technique pour le rendu temps réel..

Un exemple d'atlas : Syne / IBM

La photo n'est pas représentative exactement, j'ai réduis la qualité volontairement pour le web.

Comparaison avec une image bitmap (ou matricielle)

Bitmap: Tu photographies la forme.; Utilisé par ton OS, ImGUI, ton navigateur web,…; Pour du corps de texte à 13px dans une UI système, le bitmap rasterisé pixel-perfect gagne.; Image numérique composée d'une grille de points colorés, appelés pixels, où chaque pixel possède sa propre couleur. Contrairement aux images vectorielles, les bitmaps sont dépendants de la résolution et peuvent se pixelliser s'ils sont agrandis. Les formats courants incluent .bmp, .jpg, .png, et .gif; Bitmap atlas — chaque glyphe est rasterisé pixel-perfect à une taille fixe. Si tu veux du texte à 12px ET à 48px → deux atlas différents (ou un atlas énorme avec les deux tailles).
SDF: Tu cartographies à quelle distance tu en es depuis chaque pixel.; Utilisé par les moteurs de jeu, les logiciels de graphique vectoriels, Ray marching,…; Introduit un flou inhérent aux petites tailles et perd le hinting subpixel qui rend le texte lisible à 12px sur écran non-Retina. Pour un rendu à 48px+ c'est parfait !; Carte de distances beaucoup plus robuste au zoom qu'une image, parce que les distances interpolent bien. Un champ de distances reste mathématiquement cohérent. Police vectorielle, format .svg,…; SDF atlas — chaque glyphe encode des distances. Un seul atlas couvre toutes les tailles avec le même fichier.

Le ray marching est une technique de rendu 3D entière basée sur des SDF de formes géométriques (sdSphere, sdBox...), popularisée par Inigo Quilez sur https://www.shadertoy.com, c'est la même idée étendue en 3D : au lieu de distances à des bords de glyphes, c'est des distances à des surfaces 3D.

Un programme écrit en C++ uniquement, qui va nous générer un atlas de texture

Tu peux créer ta propre police d'écriture, en télécharger sur https://www.dafont.com et https://fonts.google.com ou utiliser celles que tu possèdes déjà dans ton Font-Book (App Native macOS)

FreeType

Bibliothèque logicielle disponible gratuitement pour rendre les polices.

Écrite en C, conçue pour être petite, efficace, hautement personnalisable et portable tout en produisant une sortie de haute qualité (images glyph) de la plupart des formats de polices vectorielles et bitmap.

# Shell
brew install freetype # update / install

Libpng

Bibliothèque de référence PNG officielle. Il prend en charge presque toutes les fonctionnalités PNG, est extensible et a été largement testé depuis plus de 30 ans.

# Shell
man libpng
brew install libpng # update / install

Génère un atlas SDF à partir d'un fichier TTF

Une fois créé/téléchargé, choisis le grammage qu'il te faut. SemiBold (IBM Plex Mono SemiBold) et Bold (Syne Bold) sont présentés.

Fichier .ttf (TrueType Font)

Format de police numérique standard développé par Apple et adopté par Microsoft, offrant une compatibilité maximale sur Windows et Mac. Il stocke des contours vectoriels, permettant d'afficher et d'imprimer des textes avec une grande netteté à n'importe quelle taille.

Quelques presets d'exemple (à modifier jusqu'à résultat acceptable) :

# Shell
./text_sdf_gen IBMPlexMono-SemiBold.ttf ibmplexmonosemibold4096.png metricsibmplexmonosemibold4096.csv
# Police: IBM Plex Mono SemiBold
# Taille: 640 px, Padding: 8 (default), Rayon SDF: 8 (default)
# Glyphes générés: 111
# Atlas: 4096x4096, utilisé jusqu'à Y=3997 (parfait)

./text_sdf_gen "Syne-ExtraBold.ttf" "syne2048xBold.png" "metrics.csv" "8" "8"
# Police: Syne ExtraBold
# Taille: 224 px, Padding: 8, Rayon SDF: 8
# Glyphes générés: 111 (sans Trucs)
# Atlas: 2048x2048, utilisé jusqu'à Y=1925

# Si tous les caractères n'ont pas pu être inclus, le programme te le dira :
# Attention: Atlas trop petit! Augmenter atlasSize. (ou réduit fontSize)

Si ton écran possède 1898 pixels de hauteur et que tu veux qu'un caractère recouvre 1/10 de ceux-ci (ce qui est énorme). Choisis une fontSize de 192.

Le plus important reste la taille de ton atlas (image) en pixel, là où tu dois optimiser la place pour ne pas avoir trop de perte (zone noire).

Tu peux évidemment travailler avec des polices d'écriture utilisant des charactères d'une autre langue (certains caractères peuvent manquer mais c'est rare) ou que tu aurais inventé.

Il n'y a pas besoin de fichier header, ni de l'inclure au projet Metal, on ne veut que la sortie du programme.

/// C++ — Exemple de programme pour l'atlas — text_SDF.cpp — update:18/05/26
#include </opt/homebrew/Cellar/freetype/2.14.3/include/freetype2/ft2build.h>
#include FT_FREETYPE_H // Inclus les 2 librairies selon leur documentation

#include </opt/homebrew/Cellar/libpng/1.6.58/include/png.h>
#include <cmath>
#include <vector>
#include <string>
#include <fstream>
#include <algorithm>
#include <cstring>

struct Config // Ici tu modifies fontSize & atlasSize. le reste c'est pour les curieux
{
    std::string inputFont;
    std::string outputAtlas;
    std::string outputMetrics;
    int fontSize = 256 - 64; // plus grand = meilleure qualité
    int padding = 8;         // Padding autour de chaque glyphe
    int sdfRadius = 8;       // Rayon de la distance signée
    int atlasSize = 4096;    // Taille de l'atlas (carré)
    
    std::string charset =    // Caractères que tu veux inclure
    // Juste un espace, mais ultra important
    " "
    // Chiffres
    "0123456789"
    // Alphabet minuscule
    "abcdefghijklmnopqrstuvwxyz"
    // Alphabet majuscule
    "ABCDEFGHIJKLMNOPQRSTUVWXYZ"
    // ASCII
    "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
    // Symboles
    "€£¥¢©®™°±×÷≤≥≠≈∞"
    // Trucs
    "ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõöøùúûüýþÿ";
};

Remarque : La structure suivante est quasiment identique à la structure GlyphInfo qui nous permettra de stocker nos données dans notre application.

/// C++ — Exemple de programme pour l'atlas — text_SDF.cpp suite — update:18/05/26
struct GeneratedGlyph // Informations sur un glyphe généré
{
    uint32_t codepoint;
    int atlasX, atlasY;
    int atlasWidth, atlasHeight;
    int width, height;
    int bearingX, bearingY;
    int advance;
    std::vector<uint8_t> sdfData;
};

// Calcul de la distance signée pour un pixel
float const computeSDF(const uint8_t* bitmap, int bmpWidth, int bmpHeight, int px, int py, int radius)
{
    // Déterminer si le pixel est "inside" (dans le glyphe)
    bool inside = false;
    
    if (px >= 0 && px < bmpWidth && py >= 0 && py < bmpHeight)
        inside = bitmap[py * bmpWidth + px] > 127;
    
    float minDist = static_cast<float>(radius);
    
    // Chercher le pixel de bordure le plus proche
    for (int dy = -radius; dy <= radius; dy++)
    {
        for (int dx = -radius; dx <= radius; dx++)
        {
            int nx = px + dx;
            int ny = py + dy;
            
            if (nx < 0 || nx >= bmpWidth || ny < 0 || ny >= bmpHeight)
                continue;
            
            bool neighborInside = bitmap[ny * bmpWidth + nx] > 127;
            
            // Bordure trouvée
            if (neighborInside != inside)
            {
                float dist = std::sqrt(static_cast<float>(dx * dx + dy * dy));
                minDist = std::min(minDist, dist);
            }
        }
    }
    return inside ? minDist : -minDist; // Normaliser: inside = positif, outside = négatif
}

// Génération du SDF pour un glyphe
std::vector<uint8_t> generateGlyphSDF(FT_GlyphSlot glyph, int padding, int radius)
{
    int bmpWidth = glyph->bitmap.width;
    int bmpHeight = glyph->bitmap.rows;
    
    // Taille finale avec padding
    int sdfWidth = bmpWidth + padding * 2;
    int sdfHeight = bmpHeight + padding * 2;
    
    std::vector<uint8_t> sdf(sdfWidth * sdfHeight);
    
    for (int y = 0; y < sdfHeight; y++)
    {
        for (int x = 0; x < sdfWidth; x++)
        {
            // Position dans le bitmap original
            int bx = x - padding;
            int by = y - padding;
            
            float dist = computeSDF(glyph->bitmap.buffer, bmpWidth, bmpHeight, bx, by, radius);
            
            // Normaliser en 0-255 (128 = bord)
            float normalized = (dist / static_cast<float>(radius)) * 0.5f + 0.5f;
            normalized = std::clamp(normalized, 0.0f, 1.0f);
            
            sdf[y * sdfWidth + x] = static_cast<uint8_t>(normalized * 255.0f);
        }
    }
    return sdf;
}

std::vector<uint32_t> decodeUTF8(const std::string& text)
{
    std::vector<uint32_t> result;
    
    for (size_t i = 0; i < text.size();)
    {
        uint32_t cp = 0;
        unsigned char c = text[i];
        
        if ((c & 0x80) == 0)
        {
            cp = c;
            i += 1;
        }
        else if ((c & 0xE0) == 0xC0)
        {
            cp = (c & 0x1F) << 6;
            cp |= (text[i + 1] & 0x3F);
            i += 2;
        }
        else if ((c & 0xF0) == 0xE0)
        {
            cp = (c & 0x0F) << 12;
            cp |= (text[i + 1] & 0x3F) << 6;
            cp |= (text[i + 2] & 0x3F);
            i += 3;
        }
        else if ((c & 0xF8) == 0xF0)
        {
            cp = (c & 0x07) << 18;
            cp |= (text[i + 1] & 0x3F) << 12;
            cp |= (text[i + 2] & 0x3F) << 6;
            cp |= (text[i + 3] & 0x3F);
            i += 4;
        }
        else
            i += 1;

        result.push_back(cp);
    }
    return result;
}

bool savePNG(const std::string& path, const uint8_t* data, int width, int height)
{
    FILE* fp = fopen(path.c_str(), "wb");
    if (!fp)
        return false;

    png_structp png = png_create_write_struct(PNG_LIBPNG_VER_STRING, nullptr, nullptr, nullptr);

    png_infop info = png_create_info_struct(png);
    
    if (setjmp(png_jmpbuf(png)))
    {
        fclose(fp);
        return false;
    }
    
    png_init_io(png, fp);
    
    png_set_IHDR(png, info, width, height, 8, PNG_COLOR_TYPE_GRAY,
                 PNG_INTERLACE_NONE, PNG_COMPRESSION_TYPE_DEFAULT, PNG_FILTER_TYPE_DEFAULT);
    png_write_info(png, info);
    
    std::vector<png_bytep> rows(height);
    
    for (int y = 0; y < height; y++)
        rows[y] = const_cast<uint8_t*>(&data[y * width]);
    
    png_write_image(png, rows.data());
        png_write_end(png, nullptr);
    
    png_destroy_write_struct(&png, &info);
    fclose(fp);
    
    return true;
}

int main(int argc, char* argv[])
{
    Config config;
    
    if (argc < 4)
    {
        printf("Usage: %s <font.ttf> <atlas.png> <metrics.csv> [fontSize] [padding]\n", argv[0]);
        return 1;
    }
    
    config.inputFont = argv[1];
    config.outputAtlas = argv[2];
    config.outputMetrics = argv[3];
    if (argc > 4)
        config.fontSize = std::stoi(argv[4]);
    if (argc > 5)
        config.padding = std::stoi(argv[5]);
    
    // Initialisation FreeType
    FT_Library ft;
    
    if (FT_Init_FreeType(&ft))
    {
        printf("Erreur: Impossible d'initialiser FreeType\n");
        return 1;
    }
    
    FT_Face face;
    
    if (FT_New_Face(ft, config.inputFont.c_str(), 0, &face))
    {
        printf("Erreur: Impossible de charger la police '%s'\n", config.inputFont.c_str());
        return 1;
    }
    
    FT_Set_Pixel_Sizes(face, 0, config.fontSize);
    
    printf("Police: %s %s\n", face->family_name, face->style_name);
    printf("Size: %d px, Pad: %d, RayonSDF: %d\n", config.fontSize, config.padding, config.sdfRadius);
    
    // Génération des glyphes
    std::vector<GeneratedGlyph> glyphs;
    std::vector<uint32_t> codepoints = decodeUTF8(config.charset);
    
    for (uint32_t cp : codepoints)
    {
        FT_UInt glyphIndex = FT_Get_Char_Index(face, cp);
        
        if (glyphIndex == 0 && cp != ' ')
            continue;
        
        if (FT_Load_Glyph(face, glyphIndex, FT_LOAD_RENDER))
            continue;
        
        GeneratedGlyph g;
        g.codepoint = cp;
        g.width = face->glyph->bitmap.width;
        g.height = face->glyph->bitmap.rows;
        g.bearingX = face->glyph->bitmap_left;
        g.bearingY = face->glyph->bitmap_top;
        g.advance = face->glyph->advance.x >> 6;
        
        // Générer le SDF
        g.sdfData = generateGlyphSDF(face->glyph, config.padding, config.sdfRadius);
        g.atlasWidth = g.width + config.padding * 2;
        g.atlasHeight = g.height+ config.padding * 2;
        
        glyphs.push_back(std::move(g));
    }
    
    printf("Glyphes générés: %zu\n", glyphs.size());
    
    // Tri par hauteur décroissante (meilleur packing)
    std::sort(glyphs.begin(), glyphs.end(), [](const auto& a, const auto& b) {
        return a.atlasHeight > b.atlasHeight;
    });
    
    // Packing simple en lignes
    int atlasWidth = config.atlasSize;
    int atlasHeight = config.atlasSize;
    std::vector<uint8_t> atlas(atlasWidth * atlasHeight, 0);
    
    int cursorX = 0;
    int cursorY = 0;
    int rowHeight = 0;
    
    for (auto& g : glyphs)
    {
        // Nouvelle ligne si nécessaire
        if (cursorX + g.atlasWidth > atlasWidth)
        {
            cursorX = 0;
            cursorY += rowHeight + 1;
            rowHeight = 0;
        }
        
        if (cursorY + g.atlasHeight > atlasHeight)
        {
            printf("Attention: Atlas trop petit! Augmenter atlasSize.\n");
            break;
        }
        
        // Copier le SDF dans l'atlas
        g.atlasX = cursorX;
        g.atlasY = cursorY;
        
        for (int y = 0; y < g.atlasHeight; y++)
        {
            memcpy(&atlas[(cursorY + y) * atlasWidth + cursorX,
                   &g.sdfData[y * g.atlasWidth], g.atlasWidth);
        }
        
        cursorX += g.atlasWidth + 1;
        rowHeight = std::max(rowHeight, g.atlasHeight);
    }
    
    printf("Atlas: %dx%d, utilisé jusqu'à Y=%d\n", atlasWidth, atlasHeight, cursorY + rowHeight);
    
    // Sauvegarde de l'atlas PNG
    if (!savePNG(config.outputAtlas, atlas.data(), atlasWidth, atlasHeight))
    {
        printf("Erreur: Impossible de sauvegarder l'atlas\n");
        return 1;
    }
    
    printf("Atlas sauvegardé: %s\n", config.outputAtlas.c_str());
    
    // Sauvegarde des métriques
    std::ofstream metricsFile(config.outputMetrics);
    metricsFile << "baseSize=" << config.fontSize << "\n";
    metricsFile << "# codepoint,atlasX,atlasY,atlasW,atlasH,width,height,bearingX,bearingY,advance\n";
    
    for (const auto& g : glyphs)
    {
        metricsFile << g.codepoint << ","
                    << g.atlasX << "," << g.atlasY << ","
                    << g.atlasWidth << "," << g.atlasHeight << ","
                    << g.width << "," << g.height << ","
                    << g.bearingX << "," << g.bearingY << ","
                    << g.advance << "\n";
    }
    
    printf("Métriques sauvegardées: %s\n", config.outputMetrics.c_str());
    
    FT_Done_Face(face);
    FT_Done_FreeType(ft);
    
    return 0;
}

# Shell
# Compilation (depending of your implementation) :
clang++ -std=c++17 text_SDF.cpp -o text_sdf_gen -I/usr/local/include/freetype2 -lfreetype -lpng
# or
clang++ -std=c++17 text_SDF.cpp -o text_sdf_gen -I/opt/homebrew/include/freetype2 \
    -L/opt/homebrew/lib -lfreetype -lpng
# Usage : [] optionnel, va utiliser celui par défaut dans le C++
./text_sdf_gen font.ttf output_atlas.png output_metrics.csv [size] [padding]

En sortie du programme, tu retrouves deux fichiers pour chaques polices :

metrics.csv

positions UV de chaques caractères sur l'image générée.

atlas.png

Image blanc sur noir avec des reliefs de profondeur. 72 pixels/inch (DPI pour un usage sur un écran), un canal (Grey).

On peut les ajouter à notre dossier assets/ & s'assurer qu'ils soient intégré correctement pour la compilation.

Avec Makefile
Avec Xcode: Dans la configuration Xcode (blue icon) → Build Phases → Copy Bundle Resources → Tu ajoutes si nécessaire l'asset au bundle → + → atlas.png → & → metrics.csv

Signed Distance Field — Text

Du texte dans ta vue Metal, depuis les polices d'écriture que tu aimes.

Histoire

Un exemple d'atlas : Syne / IBM

Comparaison avec une image bitmap (ou matricielle)

Un programme écrit en C++ uniquement, qui va nous générer un atlas de texture

Génère un atlas SDF à partir d'un fichier TTF

Le fichier .csv contient les données de chaque glyphe :

Retour à notre projet, on crée un fichier pour les stuctures de données partagées

État d'échantillonement (MTL::SamplerState)

Le shader

À quoi devrait ressembler la structure de ton projet

Et le C++