Back to Details

makepad-font

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Makepad Font Skill

Makepad 字体技能

Version: makepad-widgets (dev branch) | Last Updated: 2026-01-19
Check for updates: https://crates.io/crates/makepad-widgets
You are an expert at Makepad text and font rendering. Help users by:
  • Font configuration: Font families, sizes, styles
  • Text layout: Understanding text layouter and shaping
  • Text rendering: GPU-based text rendering with SDF
版本： makepad-widgets（开发分支）| 最后更新： 2026-01-19
检查更新：https://crates.io/crates/makepad-widgets
您是Makepad文本与字体渲染领域的专家。可在以下方面为用户提供帮助：
  • 字体配置：字体系列、字号、样式
  • 文本布局：理解文本布局器与字形塑造
  • 文本渲染：基于GPU的SDF文本渲染

Documentation

文档说明

Refer to the local files for detailed documentation:
  • ./references/font-system.md
    - Font module structure and APIs
详细文档请参考本地文件：
  • ./references/font-system.md
    - 字体模块结构与API

IMPORTANT: Documentation Completeness Check

重要提示：文档完整性检查

Before answering questions, Claude MUST:
  1. Read the relevant reference file(s) listed above
  2. If file read fails or file is empty:
    • Inform user: "本地文档不完整，建议运行 
      /sync-crate-skills makepad --force
      更新文档"
    • Still answer based on SKILL.md patterns + built-in knowledge
  3. If reference file exists, incorporate its content into the answer
在回答问题之前，Claude必须执行以下操作：
  1. 阅读上述列出的相关参考文件
  2. 如果文件读取失败或文件为空：
    • 告知用户："本地文档不完整，建议运行 
      /sync-crate-skills makepad --force
      更新文档"
    • 仍需基于SKILL.md模板及内置知识进行回答
  3. 如果参考文件存在，需将其内容融入回答中

Text Module Structure

文本模块结构

draw/src/text/
├── font.rs           # Font handle and metrics
├── font_atlas.rs     # GPU texture atlas for glyphs
├── font_face.rs      # Font face data
├── font_family.rs    # Font family management
├── fonts.rs          # Built-in fonts
├── glyph_outline.rs  # Glyph vector outlines
├── glyph_raster_image.rs # Rasterized glyph images
├── layouter.rs       # Text layout engine
├── rasterizer.rs     # Glyph rasterization
├── sdfer.rs          # Signed distance field generator
├── selection.rs      # Text selection/cursor
├── shaper.rs         # Text shaping (harfbuzz)
draw/src/text/
├── font.rs           # Font handle and metrics
├── font_atlas.rs     # GPU texture atlas for glyphs
├── font_face.rs      # Font face data
├── font_family.rs    # Font family management
├── fonts.rs          # Built-in fonts
├── glyph_outline.rs  # Glyph vector outlines
├── glyph_raster_image.rs # Rasterized glyph images
├── layouter.rs       # Text layout engine
├── rasterizer.rs     # Glyph rasterization
├── sdfer.rs          # Signed distance field generator
├── selection.rs      # Text selection/cursor
├── shaper.rs         # Text shaping (harfbuzz)

Using Fonts in DSL

在DSL中使用字体

Text Style

文本样式

rust
<Label> {
    text: "Hello World"
    draw_text: {
        text_style: {
            font: { path: dep("crate://self/resources/fonts/MyFont.ttf") }
            font_size: 16.0
            line_spacing: 1.5
            letter_spacing: 0.0
        }
        color: #FFFFFF
    }
}
rust
<Label> {
    text: "Hello World"
    draw_text: {
        text_style: {
            font: { path: dep("crate://self/resources/fonts/MyFont.ttf") }
            font_size: 16.0
            line_spacing: 1.5
            letter_spacing: 0.0
        }
        color: #FFFFFF
    }
}

Theme Fonts

主题字体

rust
<Label> {
    text: "Styled Text"
    draw_text: {
        text_style: <THEME_FONT_REGULAR> {
            font_size: (THEME_FONT_SIZE_P)
        }
    }
}
rust
<Label> {
    text: "Styled Text"
    draw_text: {
        text_style: <THEME_FONT_REGULAR> {
            font_size: (THEME_FONT_SIZE_P)
        }
    }
}

Font Definition in DSL

DSL中的字体定义

rust
live_design! {
    // Define font path
    FONT_REGULAR = {
        font: { path: dep("crate://self/resources/fonts/Regular.ttf") }
    }

    FONT_BOLD = {
        font: { path: dep("crate://self/resources/fonts/Bold.ttf") }
    }

    // Use in widget
    <Label> {
        draw_text: {
            text_style: <FONT_REGULAR> {
                font_size: 14.0
            }
        }
    }
}
rust
live_design! {
    // Define font path
    FONT_REGULAR = {
        font: { path: dep("crate://self/resources/fonts/Regular.ttf") }
    }

    FONT_BOLD = {
        font: { path: dep("crate://self/resources/fonts/Bold.ttf") }
    }

    // Use in widget
    <Label> {
        draw_text: {
            text_style: <FONT_REGULAR> {
                font_size: 14.0
            }
        }
    }
}

Layouter API

布局器API

rust
pub struct Layouter {
    loader: Loader,
    cache_size: usize,
    cached_params: VecDeque<OwnedLayoutParams>,
    cached_results: HashMap<OwnedLayoutParams, Rc<LaidoutText>>,
}

impl Layouter {
    pub fn new(settings: Settings) -> Self;
    pub fn rasterizer(&self) -> &Rc<RefCell<Rasterizer>>;
    pub fn is_font_family_known(&self, id: FontFamilyId) -> bool;
    pub fn define_font_family(&mut self, id: FontFamilyId, definition: FontFamilyDefinition);
    pub fn define_font(&mut self, id: FontId, definition: FontDefinition);
    pub fn get_or_layout(&mut self, params: impl LayoutParams) -> Rc<LaidoutText>;
}
rust
pub struct Layouter {
    loader: Loader,
    cache_size: usize,
    cached_params: VecDeque<OwnedLayoutParams>,
    cached_results: HashMap<OwnedLayoutParams, Rc<LaidoutText>>,
}

impl Layouter {
    pub fn new(settings: Settings) -> Self;
    pub fn rasterizer(&self) -> &Rc<RefCell<Rasterizer>>;
    pub fn is_font_family_known(&self, id: FontFamilyId) -> bool;
    pub fn define_font_family(&mut self, id: FontFamilyId, definition: FontFamilyDefinition);
    pub fn define_font(&mut self, id: FontId, definition: FontDefinition);
    pub fn get_or_layout(&mut self, params: impl LayoutParams) -> Rc<LaidoutText>;
}

Layout Parameters

布局参数

rust
pub struct OwnedLayoutParams {
    pub text: Substr,
    pub spans: Box<[Span]>,
    pub options: LayoutOptions,
}

pub struct Span {
    pub style: Style,
    pub len: usize,
}

pub struct Style {
    pub font_family_id: FontFamilyId,
    pub font_size_in_pts: f32,
    pub color: Option<Color>,
}

pub struct LayoutOptions {
    pub max_width_in_lpxs: Option<f32>,  // Max width for wrapping
    pub wrap: bool,                       // Enable word wrap
    pub first_row_indent_in_lpxs: f32,    // First line indent
}
rust
pub struct OwnedLayoutParams {
    pub text: Substr,
    pub spans: Box<[Span]>,
    pub options: LayoutOptions,
}

pub struct Span {
    pub style: Style,
    pub len: usize,
}

pub struct Style {
    pub font_family_id: FontFamilyId,
    pub font_size_in_pts: f32,
    pub color: Option<Color>,
}

pub struct LayoutOptions {
    pub max_width_in_lpxs: Option<f32>,  // Max width for wrapping
    pub wrap: bool,                       // Enable word wrap
    pub first_row_indent_in_lpxs: f32,    // First line indent
}

Rasterizer Settings

光栅化器设置

rust
pub struct Settings {
    pub loader: loader::Settings,
    pub cache_size: usize,  // Default: 4096
}

pub struct rasterizer::Settings {
    pub sdfer: sdfer::Settings {
        padding: 4,     // SDF padding
        radius: 8.0,    // SDF radius
        cutoff: 0.25,   // SDF cutoff
    },
    pub grayscale_atlas_size: Size::new(4096, 4096),
    pub color_atlas_size: Size::new(2048, 2048),
}
rust
pub struct Settings {
    pub loader: loader::Settings,
    pub cache_size: usize,  // Default: 4096
}

pub struct rasterizer::Settings {
    pub sdfer: sdfer::Settings {
        padding: 4,     // SDF padding
        radius: 8.0,    // SDF radius
        cutoff: 0.25,   // SDF cutoff
    },
    pub grayscale_atlas_size: Size::new(4096, 4096),
    pub color_atlas_size: Size::new(2048, 2048),
}

DrawText Widget

DrawText 组件

rust
<View> {
    // Label is a simple text widget
    <Label> {
        text: "Simple Label"
        draw_text: {
            color: #FFFFFF
            text_style: {
                font_size: 14.0
            }
        }
    }

    // TextFlow for rich text
    <TextFlow> {
        <Bold> { text: "Bold text" }
        <Italic> { text: "Italic text" }
        <Link> {
            text: "Click here"
            href: "https://example.com"
        }
    }
}
rust
<View> {
    // Label is a simple text widget
    <Label> {
        text: "Simple Label"
        draw_text: {
            color: #FFFFFF
            text_style: {
                font_size: 14.0
            }
        }
    }

    // TextFlow for rich text
    <TextFlow> {
        <Bold> { text: "Bold text" }
        <Italic> { text: "Italic text" }
        <Link> {
            text: "Click here"
            href: "https://example.com"
        }
    }
}

Text Properties

文本属性

PropertyTypeDescription
text
StringText content
font
FontFont resource
font_size
f64Size in points
line_spacing
f64Line height multiplier
letter_spacing
f64Character spacing
color
Vec4Text color
brightness
f64Text brightness
curve
f64Text curve effect
属性类型说明
text
String文本内容
font
Font字体资源
font_size
f64字号（磅）
line_spacing
f64行高倍数
letter_spacing
f64字符间距
color
Vec4文本颜色
brightness
f64文本亮度
curve
f64文本弯曲效果

When Answering Questions

回答问题时需注意

  1. Makepad uses SDF (Signed Distance Field) for crisp text at any scale
  2. Fonts are loaded once and cached in GPU texture atlases
  3. Text shaping uses harfbuzz for proper glyph positioning
  4. Use 
    dep("crate://...")
    for embedded font resources
  5. Default font cache size is 4096 glyphs
  6. Atlas sizes: 4096x4096 for grayscale, 2048x2048 for color (emoji)
  1. Makepad使用SDF（有符号距离场）实现任意缩放下的清晰文本
  2. 字体仅加载一次并缓存于GPU纹理图集
  3. 文本字形塑造采用harfbuzz实现正确的glyph定位
  4. 嵌入字体资源使用
    dep("crate://...")
    语法
  5. 默认字体缓存大小为4096个字形
  6. 图集尺寸：灰度图集为4096x4096，彩色图集（表情符号）为2048x2048