Glyphon

https://docs.rs/glyphon
Admin
Glyphon is a Rust library that simplifies rendering 2D text using wgpu, cosmic-text, and etagere. It...
Tokens:44,076
Snippets:400
Trust Score:9.7
Update:1 week ago
Show doc for...
Tokens:
Raw
### Get or create cached render pipeline for glyphs

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html?search=std%3A%3Avec

Returns a cached RenderPipeline matching the given format, multisample state, and depth-stencil state, or creates a new one. The pipeline uses the stored shader with entry points "vs_main" and "fs_main", alpha blending, and triangle strip topology. The cache is locked with "Write pipeline cache" expectation.

```rust
199    pub(crate) fn get_or_create_pipeline(
200        &self,
201        device: &Device,
202        format: TextureFormat,
203        multisample: MultisampleState,
204        depth_stencil: Option<DepthStencilState>,
205    ) -> RenderPipeline {
206        let Inner {
207            cache,
208            pipeline_layout,
209            shader,
210            vertex_buffers,
211            ..
212        } = self.0.deref();
213
214        let mut cache = cache.lock().expect("Write pipeline cache");
215
216        cache
217            .iter()
218            .find(|(fmt, ms, ds, _)| fmt == &format && ms == &multisample && ds == &depth_stencil)
219            .map(|(_, _, _, p)| p.clone())
220            .unwrap_or_else(|| {
221                let pipeline = device.create_render_pipeline(&RenderPipelineDescriptor {
222                    label: Some("glyphon pipeline"),
223                    layout: Some(pipeline_layout),
224                    vertex: VertexState {
225                        module: shader,
226                        entry_point: Some("vs_main"),
227                        buffers: vertex_buffers,
228                        compilation_options: PipelineCompilationOptions::default(),
229                    },
230                    fragment: Some(FragmentState {
231                        module: shader,
232                        entry_point: Some("fs_main"),
233                        targets: &[Some(ColorTargetState {
234                            format,
235                            blend: Some(BlendState::ALPHA_BLENDING),
236                            write_mask: ColorWrites::default(),
237                        })],
238                        compilation_options: PipelineCompilationOptions::default(),
239                    }),
240                    primitive: PrimitiveState {
241                        topology: PrimitiveTopology::TriangleStrip,
242                        ..Default::default()
243                    },
```

--------------------------------

### Viewport::new

Source: https://docs.rs/glyphon/latest/src/glyphon/viewport.rs.html?search=

Constructor for creating a new Viewport instance.

```APIDOC
## Viewport::new

### Description
Creates a new `Viewport` with the given `device` and `cache`. The viewport is initialized with a zero resolution and a uniform buffer for parameters.

### Method
Constructor

### Signature
```rust
pub fn new(device: &Device, cache: &Cache) -> Self
```

### Parameters
- **device** (`&Device`) - Required - The wgpu device used to create the uniform buffer.
- **cache** (`&Cache`) - Required - The cache used to create the uniform bind group.

### Returns
- `Viewport` - The newly created viewport.

### Example
```rust
let viewport = Viewport::new(&device, &cache);
```
```

--------------------------------

### TextRenderer::prepare_with_depth_and_custom method

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=std%3A%3Avec

Core preparation method that clears glyph vertices, creates a State, and initializes a GlyphSystem with the provided atlas, cache, and font system.

```rust
/// Prepares all of the provided text areas for rendering.
    pub fn prepare_with_depth_and_custom<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
        mut metadata_to_depth: impl FnMut(usize) -> f32,
        mut rasterize_custom_glyph: impl FnMut(
            RasterizeCustomGlyphRequest,
        ) -> Option<RasterizedCustomGlyph>,
    ) -> Result<(), PrepareError> {
        self.glyph_vertices.clear();

        let state = State { device, queue };
        let mut system = GlyphSystem {
            atlas,
            cache,
            font_system,
```

--------------------------------

### Viewport::new

Source: https://docs.rs/glyphon/latest/glyphon/struct.Viewport.html?search=

Creates a new Viewport with the given device and cache.

```APIDOC
## Viewport::new

### Description
Creates a new `Viewport` with the given `device` and `cache`.

### Method
`pub fn new(device: &Device, cache: &Cache) -> Self`

### Parameters
- **device** (`&Device`) - Required - The graphics device to associate with the viewport.
- **cache** (`&Cache`) - Required - The cache to use for text rendering.

### Returns
- `Self` - A new `Viewport` instance.
```

--------------------------------

### Cache::new method

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html?search=

Creates a new Cache with the given device. It creates a sampler with nearest filtering, a shader module from the included shader.wgsl, a vertex buffer layout for GlyphToRender instances, and bind group layouts for the atlas texture and uniforms.

```rust
impl Cache {
    /// Creates a new `Cache` with the given `device`.
    pub fn new(device: &Device) -> Self {
        let sampler = device.create_sampler(&SamplerDescriptor {
            label: Some("glyphon sampler"),
            min_filter: FilterMode::Nearest,
            mag_filter: FilterMode::Nearest,
            mipmap_filter: MipmapFilterMode::Nearest,
            lod_min_clamp: 0f32,
            lod_max_clamp: 0f32,
            ..Default::default()
        });

        let shader = device.create_shader_module(ShaderModuleDescriptor {
            label: Some("glyphon shader"),
            source: ShaderSource::Wgsl(Cow::Borrowed(include_str!("shader.wgsl"))),
        });

        let vertex_buffer_layout = wgpu::VertexBufferLayout {
            array_stride: mem::size_of::<GlyphToRender>() as wgpu::BufferAddress,
            step_mode: wgpu::VertexStepMode::Instance,
            attributes: &[
                wgpu::VertexAttribute {
                    format: VertexFormat::Sint32x2,
                    offset: 0,
                    shader_location: 0,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 2,
                    shader_location: 1,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 3,
                    shader_location: 2,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 4,
                    shader_location: 3,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 5,
                    shader_location: 4,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Float32,
                    offset: mem::size_of::<u32>() as u64 * 6,
                    shader_location: 5,
                },
            ],
        };

        let atlas_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                BindGroupLayoutEntry {
                    binding: 0,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        view_dimension: TextureViewDimension::D2,
                        sample_type: TextureSampleType::Float { filterable: true },
                    },
                    count: None,
                },
                BindGroupLayoutEntry {
                    binding: 1,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        view_dimension: TextureViewDimension::D2,
                        sample_type: TextureSampleType::Float { filterable: true },
                    },
                    count: None,
                },
            ],
            label: Some("glyphon atlas layout"),
        });

        let uniforms_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                BindGroupLayoutEntry {
                    binding: 0,
                    visibility: ShaderStages::VERTEX,
                    ty: BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
            ],
            label: Some("glyphon uniforms layout"),
        });

        let pipeline_layout = device.create_pipeline_layout(&PipelineLayoutDescriptor {
            label: Some("glyphon pipeline layout"),
            bind_group_layouts: &[&atlas_layout, &uniforms_layout],
            push_constant_ranges: &[],
        });

        Self(Arc::new(Inner {
            sampler,
            shader,
            vertex_buffers: [Some(vertex_buffer_layout)],
            atlas_layout,
            uniforms_layout,
            pipeline_layout,
            cache: Mutex::new(Vec::new()),
        }))
    }
}
```

--------------------------------

### TextRenderer::prepare_with_custom

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html?search=u32+-%3E+bool

Prepares all provided text areas for rendering with custom glyph rasterization.

```APIDOC
## TextRenderer::prepare_with_custom

### Description
Prepares all of the provided text areas for rendering, with a custom glyph rasterization function.

### Method
`pub fn prepare_with_custom<'a>(&mut self, device: &Device, queue: &Queue, font_system: &mut FontSystem, atlas: &mut TextAtlas, viewport: &Viewport, text_areas: impl IntoIterator<Item = TextArea<'a>>, cache: &mut SwashCache, rasterize_custom_glyph: impl FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>) -> Result<(), PrepareError>`

### Parameters
- `device` (`&Device`) - Required - The device to use.
- `queue` (`&Queue`) - Required - The queue to use.
- `font_system` (`&mut FontSystem`) - Required - The font system.
- `atlas` (`&mut TextAtlas`) - Required - The text atlas.
- `viewport` (`&Viewport`) - Required - The viewport.
- `text_areas` (`impl IntoIterator<Item = TextArea<'a>>`) - Required - The text areas to prepare.
- `cache` (`&mut SwashCache`) - Required - The swash cache.
- `rasterize_custom_glyph` (`impl FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>`) - Required - A function to rasterize custom glyphs.

### Returns
`Result<(), PrepareError>` - Ok if preparation succeeded, otherwise a PrepareError.
```

--------------------------------

### Pipeline creation with cache push

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Shows the tail of a pipeline creation closure that clones the depth_stencil, sets multisample, cache, and multiview_mask fields, pushes the pipeline into a cache, and returns the cloned pipeline.

```rust
depth_stencil: depth_stencil.clone(),
multisample,
cache: None,
multiview_mask: None,
});

cache.push((format, multisample, depth_stencil, pipeline.clone()));

pipeline
})
.clone()
}
```

--------------------------------

### TextRenderer::prepare_with_custom method

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=std%3A%3Avec

Prepares text areas with a custom glyph rasterization callback and default depth (zero).

```rust
/// Prepares all of the provided text areas for rendering.
    pub fn prepare_with_custom<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
        rasterize_custom_glyph: impl FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>,
    ) -> Result<(), PrepareError> {
        self.prepare_with_depth_and_custom(
            device,
            queue,
            font_system,
            atlas,
            viewport,
            text_areas,
            cache,
            zero_depth,
            rasterize_custom_glyph,
        )
    }
```

--------------------------------

### Cache::new

Source: https://docs.rs/glyphon/latest/glyphon/struct.Cache.html?search=std%3A%3Avec

Creates a new Cache with the given device.

```APIDOC
## Cache::new

### Description
Creates a new `Cache` with the given `device`.

### Method
`pub fn new(device: &Device) -> Self`

### Parameters
- **device** (`&Device`) - Required - The device used to create the cache.

### Returns
- **Self** - A new `Cache` instance.
```

--------------------------------

### render

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html

Renders all layouts that were previously provided to `prepare` into the given render pass.

```APIDOC
## render

### Description
Renders all layouts that were previously provided to `prepare`.

### Method
Method

### Signature
```rust
pub fn render(
    &self,
    atlas: &TextAtlas,
    viewport: &Viewport,
    pass: &mut RenderPass<'_>,
) -> Result<(), RenderError>
```

### Parameters
- `atlas` (&TextAtlas) - Required - The text atlas.
- `viewport` (&Viewport) - Required - The viewport.
- `pass` (&mut RenderPass<'_>) - Required - The render pass to render into.

### Returns
- `Result<(), RenderError>` - Ok if rendering succeeded, otherwise an error.
```

--------------------------------

### TextRenderer::prepare method

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=std%3A%3Avec

Prepares text areas for rendering using default depth (zero) and no custom glyph rasterization.

```rust
/// Prepares all of the provided text areas for rendering.
    pub fn prepare<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
    ) -> Result<(), PrepareError> {
        self.prepare_with_depth_and_custom(
            device,
            queue,
            font_system,
            atlas,
            viewport,
            text_areas,
            cache,
            zero_depth,
            |_| None,
        )
    }
```

--------------------------------

### Create atlas and uniforms bind group layouts and pipeline layout

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html?search=std%3A%3Avec

Creates the atlas bind group layout with bindings 0 (color atlas texture), 1 (mask atlas texture), and 2 (filtering sampler), plus a uniforms bind group layout for a uniform buffer with a minimum size of Params. The pipeline layout references both layouts. The resulting Inner struct stores the layouts, sampler, shader, vertex buffers, and an empty pipeline cache.

```rust
120                    count: None,
121                },
122                BindGroupLayoutEntry {
123                    binding: 2,
124                    visibility: ShaderStages::FRAGMENT,
125                    ty: BindingType::Sampler(SamplerBindingType::Filtering),
126                    count: None,
127                },
128            ],
129            label: Some("glyphon atlas bind group layout"),
130        });
131
132        let uniforms_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
133            entries: &[BindGroupLayoutEntry {
134                binding: 0,
135                visibility: ShaderStages::VERTEX,
136                ty: BindingType::Buffer {
137                    ty: BufferBindingType::Uniform,
138                    has_dynamic_offset: false,
139                    min_binding_size: NonZeroU64::new(mem::size_of::<Params>() as u64),
140                },
141                count: None,
142            }],
143            label: Some("glyphon uniforms bind group layout"),
144        });
145
146        let pipeline_layout = device.create_pipeline_layout(&PipelineLayoutDescriptor {
147            bind_group_layouts: &[Some(&atlas_layout), Some(&uniforms_layout)],
148            ..Default::default()
149        });
150
151        Self(Arc::new(Inner {
152            sampler,
153            shader,
154            vertex_buffers: [Some(vertex_buffer_layout)],
155            uniforms_layout,
156            atlas_layout,
157            pipeline_layout,
158            cache: Mutex::new(Vec::new()),
159        }))
```

--------------------------------

### TextRenderer::new

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html?search=

Constructor for creating a new TextRenderer instance.

```APIDOC
## TextRenderer::new

### Description
Creates a new `TextRenderer`.

### Method
Constructor

### Signature
```rust
pub fn new(
    atlas: &mut TextAtlas,
    device: &Device,
    multisample: MultisampleState,
    depth_stencil: Option<DepthStencilState>,
) -> Self
```

### Parameters
- **atlas** (`&mut TextAtlas`) - Required - The text atlas to use for glyph caching.
- **device** (`&Device`) - Required - The GPU device.
- **multisample** (`MultisampleState`) - Required - The multisample state.
- **depth_stencil** (`Option<DepthStencilState>`) - Required - Optional depth-stencil state.

### Returns
- `Self` - A new `TextRenderer` instance.
```

--------------------------------

### TextRenderer::prepare

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html?search=u32+-%3E+bool

Prepares all provided text areas for rendering.

```APIDOC
## TextRenderer::prepare

### Description
Prepares all of the provided text areas for rendering.

### Method
`pub fn prepare<'a>(&mut self, device: &Device, queue: &Queue, font_system: &mut FontSystem, atlas: &mut TextAtlas, viewport: &Viewport, text_areas: impl IntoIterator<Item = TextArea<'a>>, cache: &mut SwashCache) -> Result<(), PrepareError>`

### Parameters
- `device` (`&Device`) - Required - The device to use.
- `queue` (`&Queue`) - Required - The queue to use.
- `font_system` (`&mut FontSystem`) - Required - The font system.
- `atlas` (`&mut TextAtlas`) - Required - The text atlas.
- `viewport` (`&Viewport`) - Required - The viewport.
- `text_areas` (`impl IntoIterator<Item = TextArea<'a>>`) - Required - The text areas to prepare.
- `cache` (`&mut SwashCache`) - Required - The swash cache.

### Returns
`Result<(), PrepareError>` - Ok if preparation succeeded, otherwise a PrepareError.
```

--------------------------------

### TextRenderer::prepare_with_depth method

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=std%3A%3Avec

Prepares text areas with a custom depth mapping function and no custom glyph rasterization.

```rust
/// Prepares all of the provided text areas for rendering.
    pub fn prepare_with_depth<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
        metadata_to_depth: impl FnMut(usize) -> f32,
    ) -> Result<(), PrepareError> {
        self.prepare_with_depth_and_custom(
            device,
            queue,
            font_system,
            atlas,
            viewport,
            text_areas,
            cache,
            metadata_to_depth,
            |_| None,
        )
    }
```

--------------------------------

### Prepare glyph for rendering

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=std%3A%3Avec

Main function to prepare a glyph for rendering. It checks the mask and color atlases for cached glyphs, otherwise retrieves the glyph image, allocates space in the atlas, and uploads the texture data. Returns a GlyphToRender or an error.

```rust
fn prepare_glyph<R>(
    state: &State,
    system: &mut GlyphSystem,
    metadata: GlyphMetadata,
    bounds: GlyphBounds,
    get_glyph_image: impl FnOnce(&mut GlyphSystem, &mut R) -> Option<GetGlyphImageResult>,
    mut metadata_to_depth: impl FnMut(usize) -> f32,
    mut rasterize_custom_glyph: R,
) -> Result<Option<GlyphToRender>, PrepareError>
where
    R: FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>,
{
    let details =
        if let Some(details) = system.atlas.mask_atlas.glyph_cache.get(&metadata.cache_key) {
            system
                .atlas
                .mask_atlas
                .glyphs_in_use
                .insert(metadata.cache_key);
            details
        } else if let Some(details) = system
            .atlas
            .color_atlas
            .glyph_cache
            .get(&metadata.cache_key)
        {
            system
                .atlas
                .color_atlas
                .glyphs_in_use
                .insert(metadata.cache_key);
            details
        } else {
            let Some(image) = (get_glyph_image)(system, &mut rasterize_custom_glyph) else {
                return Ok(None);
            };

            let should_rasterize = image.width > 0 && image.height > 0;

            let (gpu_cache, atlas_id, inner) = if should_rasterize {
                let mut inner = system.atlas.inner_for_content_mut(image.content_type);

                // Find a position in the packer
                let allocation = loop {
                    match inner.try_allocate(image.width as usize, image.height as usize) {
                        Some(a) => break a,
                        None => {
                            if !system.atlas.grow(
                                state,
                                system.font_system,
                                system.cache,
                                image.content_type,
                                metadata.scale_factor,
                                &mut rasterize_custom_glyph,
                            ) {
                                return Err(PrepareError::AtlasFull);
                            }

                            inner = system.atlas.inner_for_content_mut(image.content_type);
                        }
                    }
                };
                let atlas_min = allocation.rectangle.min;

                state.queue.write_texture(
                    TexelCopyTextureInfo {
                        texture: &inner.texture,
                        mip_level: 0,
                        origin: Origin3d {
                            x: atlas_min.x as u32,
                            y: atlas_min.y as u32,
                            z: 0,
                        },
                        aspect: TextureAspect::All,
                    },
                    &image.data,
                    TexelCopyBufferLayout {
                        offset: 0,
                        bytes_per_row: Some(image.width as u32 * inner.num_channels() as u32),
                        rows_per_image: None,
                    },
                    Extent3d {
                        width: image.width as u32,
                        height: image.height as u32,
                        depth_or_array_layers: 1,
                    },
                );

                (
                    GpuCacheStatus::InAtlas {
                        x: atlas_min.x as u16,
                        y: atlas_min.y as u16,
                        content_type: image.content_type,
                    },
                    Some(allocation.id),
                    inner,
                )
            } else {
                let inner = &mut system.atlas.color_atlas;
```

--------------------------------

### TextRenderer::prepare_with_depth

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html?search=u32+-%3E+bool

Prepares all provided text areas for rendering with a depth metadata mapping.

```APIDOC
## TextRenderer::prepare_with_depth

### Description
Prepares all of the provided text areas for rendering, with a custom depth mapping.

### Method
`pub fn prepare_with_depth<'a>(&mut self, device: &Device, queue: &Queue, font_system: &mut FontSystem, atlas: &mut TextAtlas, viewport: &Viewport, text_areas: impl IntoIterator<Item = TextArea<'a>>, cache: &mut SwashCache, metadata_to_depth: impl FnMut(usize) -> f32) -> Result<(), PrepareError>`

### Parameters
- `device` (`&Device`) - Required - The device to use.
- `queue` (`&Queue`) - Required - The queue to use.
- `font_system` (`&mut FontSystem`) - Required - The font system.
- `atlas` (`&mut TextAtlas`) - Required - The text atlas.
- `viewport` (`&Viewport`) - Required - The viewport.
- `text_areas` (`impl IntoIterator<Item = TextArea<'a>>`) - Required - The text areas to prepare.
- `cache` (`&mut SwashCache`) - Required - The swash cache.
- `metadata_to_depth` (`impl FnMut(usize) -> f32`) - Required - A function mapping metadata to depth.

### Returns
`Result<(), PrepareError>` - Ok if preparation succeeded, otherwise a PrepareError.
```

--------------------------------

### TextRenderer::prepare_with_depth_and_custom

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html?search=u32+-%3E+bool

Prepares all provided text areas for rendering with both depth mapping and custom glyph rasterization.

```APIDOC
## TextRenderer::prepare_with_depth_and_custom

### Description
Prepares all of the provided text areas for rendering, with both a custom depth mapping and custom glyph rasterization.

### Method
`pub fn prepare_with_depth_and_custom<'a>(&mut self, device: &Device, queue: &Queue, font_system: &mut FontSystem, atlas: &mut TextAtlas, viewport: &Viewport, text_areas: impl IntoIterator<Item = TextArea<'a>>, cache: &mut SwashCache, metadata_to_depth: impl FnMut(usize) -> f32, rasterize_custom_glyph: impl FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>) -> Result<(), PrepareError>`

### Parameters
- `device` (`&Device`) - Required - The device to use.
- `queue` (`&Queue`) - Required - The queue to use.
- `font_system` (`&mut FontSystem`) - Required - The font system.
- `atlas` (`&mut TextAtlas`) - Required - The text atlas.
- `viewport` (`&Viewport`) - Required - The viewport.
- `text_areas` (`impl IntoIterator<Item = TextArea<'a>>`) - Required - The text areas to prepare.
- `cache` (`&mut SwashCache`) - Required - The swash cache.
- `metadata_to_depth` (`impl FnMut(usize) -> f32`) - Required - A function mapping metadata to depth.
- `rasterize_custom_glyph` (`impl FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>`) - Required - A function to rasterize custom glyphs.

### Returns
`Result<(), PrepareError>` - Ok if preparation succeeded, otherwise a PrepareError.
```

--------------------------------

### prepare

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html

Prepares all provided text areas for rendering. This method processes the text areas and updates the atlas and cache as needed.

```APIDOC
## prepare

### Description
Prepares all of the provided text areas for rendering.

### Method
Method

### Signature
```rust
pub fn prepare<'a>(
    &mut self,
    device: &Device,
    queue: &Queue,
    font_system: &mut FontSystem,
    atlas: &mut TextAtlas,
    viewport: &Viewport,
    text_areas: impl IntoIterator<Item = TextArea<'a>>,
    cache: &mut SwashCache,
) -> Result<(), PrepareError>
```

### Parameters
- `device` (&Device) - Required - The GPU device.
- `queue` (&Queue) - Required - The GPU queue.
- `font_system` (&mut FontSystem) - Required - The font system.
- `atlas` (&mut TextAtlas) - Required - The text atlas.
- `viewport` (&Viewport) - Required - The viewport.
- `text_areas` (impl IntoIterator<Item = TextArea<'a>>) - Required - The text areas to prepare.
- `cache` (&mut SwashCache) - Required - The swash cache.

### Returns
- `Result<(), PrepareError>` - Ok if preparation succeeded, otherwise an error.
```

--------------------------------

### Cache::new creates shared wgpu resources

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html

Defines the `Cache` struct and its `new` method, which creates a sampler, shader module, vertex buffer layout, bind group layouts, and pipeline layout for sharing between text renderers. The sampler uses nearest filtering and the shader is loaded from `shader.wgsl` via `include_str!`. The vertex buffer layout uses instance step mode with attributes matching `GlyphToRender`.

```rust
use crate::{GlyphToRender, Params};
use std::{
    borrow::Cow,
    mem,
    num::NonZeroU64,
    ops::Deref,
    sync::{Arc, Mutex},
};
use wgpu::{
    BindGroup, BindGroupDescriptor, BindGroupEntry, BindGroupLayout, BindGroupLayoutEntry,
    BindingResource, BindingType, BlendState, Buffer, BufferBindingType, ColorTargetState,
    ColorWrites, DepthStencilState, Device, FilterMode, FragmentState, MipmapFilterMode,
    MultisampleState, PipelineCompilationOptions, PipelineLayout, PipelineLayoutDescriptor,
    PrimitiveState, PrimitiveTopology, RenderPipeline, RenderPipelineDescriptor, Sampler,
    SamplerBindingType, SamplerDescriptor, ShaderModule, ShaderModuleDescriptor, ShaderSource,
    ShaderStages, TextureFormat, TextureSampleType, TextureView, TextureViewDimension,
    VertexFormat, VertexState,
};

/// A cache to share common resources (e.g., pipelines, layouts, shaders) between multiple text
/// renderers.
#[derive(Debug, Clone)]
pub struct Cache(Arc<Inner>);

type InnerCache = Mutex<
    Vec<(
        TextureFormat,
        MultisampleState,
        Option<DepthStencilState>,
        RenderPipeline,
    )>,
>;

#[derive(Debug)]
struct Inner {
    sampler: Sampler,
    shader: ShaderModule,
    vertex_buffers: [Option<wgpu::VertexBufferLayout<'static>>; 1],
    atlas_layout: BindGroupLayout,
    uniforms_layout: BindGroupLayout,
    pipeline_layout: PipelineLayout,
    cache: InnerCache,
}

impl Cache {
    /// Creates a new `Cache` with the given `device`.
    pub fn new(device: &Device) -> Self {
        let sampler = device.create_sampler(&SamplerDescriptor {
            label: Some("glyphon sampler"),
            min_filter: FilterMode::Nearest,
            mag_filter: FilterMode::Nearest,
            mipmap_filter: MipmapFilterMode::Nearest,
            lod_min_clamp: 0f32,
            lod_max_clamp: 0f32,
            ..Default::default()
        });

        let shader = device.create_shader_module(ShaderModuleDescriptor {
            label: Some("glyphon shader"),
            source: ShaderSource::Wgsl(Cow::Borrowed(include_str!("shader.wgsl"))),
        });

        let vertex_buffer_layout = wgpu::VertexBufferLayout {
            array_stride: mem::size_of::<GlyphToRender>() as wgpu::BufferAddress,
            step_mode: wgpu::VertexStepMode::Instance,
            attributes: &[
                wgpu::VertexAttribute {
                    format: VertexFormat::Sint32x2,
                    offset: 0,
                    shader_location: 0,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 2,
                    shader_location: 1,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 3,
                    shader_location: 2,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 4,
                    shader_location: 3,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 5,
                    shader_location: 4,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Float32,
                    offset: mem::size_of::<u32>() as u64 * 6,
                    shader_location: 5,
                },
            ],
        };

        let atlas_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                BindGroupLayoutEntry {
                    binding: 0,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        view_dimension: TextureViewDimension::D2,
                        sample_type: TextureSampleType::Float { filterable: true },
                    },
                    count: None,
                },
                BindGroupLayoutEntry {
                    binding: 1,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        view_dimension: TextureViewDimension::D2,
                        sample_type: TextureSampleType::Float { filterable: true },
                    },
                    count: None,
                },
            ],
        });

        let uniforms_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                BindGroupLayoutEntry {
                    binding: 0,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Buffer {
                        ty: wgpu::BufferBindingType::Uniform,
                        has_dynamic_offset: false,
                        min_binding_size: None,
                    },
                    count: None,
                },
            ],
        });

        let pipeline_layout = device.create_pipeline_layout(&PipelineLayoutDescriptor {
            label: Some("glyphon pipeline layout"),
            bind_group_layouts: &[&atlas_layout, &uniforms_layout],
            push_constant_ranges: &[],
        });

        let cache = Mutex::new(Vec::new());

        Cache(Arc::new(Inner {
            sampler,
            shader,
            vertex_buffers: [Some(vertex_buffer_layout)],
            atlas_layout,
            uniforms_layout,
            pipeline_layout,
            cache,
        }))
    }
}
```

--------------------------------

### TextRenderer struct and prepare methods

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=

Defines the TextRenderer struct with a vertex buffer, pipeline, and glyph vertices. Provides prepare methods that accept text areas and optional depth/custom glyph callbacks, returning Result<(), PrepareError>.

```rust
use crate::{
    custom_glyph::CustomGlyphCacheKey, ColorMode, ContentType, FontSystem, GlyphDetails,
    GlyphToRender, GpuCacheStatus, PrepareError, RasterizeCustomGlyphRequest,
    RasterizedCustomGlyph, RenderError, State, SwashCache, SwashContent, TextArea, TextAtlas,
    Viewport,
};
use cosmic_text::{Color, SubpixelBin};
use std::slice;
use wgpu::{
    Buffer, BufferDescriptor, BufferUsages, DepthStencilState, Device, Extent3d, MultisampleState,
    Origin3d, Queue, RenderPass, RenderPipeline, TexelCopyBufferLayout, TexelCopyTextureInfo,
    TextureAspect, COPY_BUFFER_ALIGNMENT,
};

/// A text renderer that uses cached glyphs to render text into an existing render pass.
pub struct TextRenderer {
    vertex_buffer: Buffer,
    vertex_buffer_size: u64,
    pipeline: RenderPipeline,
    glyph_vertices: Vec<GlyphToRender>,
}

impl TextRenderer {
    /// Creates a new `TextRenderer`.
    pub fn new(
        atlas: &mut TextAtlas,
        device: &Device,
        multisample: MultisampleState,
        depth_stencil: Option<DepthStencilState>,
    ) -> Self {
        let vertex_buffer_size = next_copy_buffer_size(4096);
        let vertex_buffer = device.create_buffer(&BufferDescriptor {
            label: Some("glyphon vertices"),
            size: vertex_buffer_size,
            usage: BufferUsages::VERTEX | BufferUsages::COPY_DST,
            mapped_at_creation: false,
        });

        let pipeline = atlas.get_or_create_pipeline(device, multisample, depth_stencil);

        Self {
            vertex_buffer,
            vertex_buffer_size,
            pipeline,
            glyph_vertices: Vec::new(),
        }
    }

    /// Prepares all of the provided text areas for rendering.
    pub fn prepare<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
    ) -> Result<(), PrepareError> {
        self.prepare_with_depth_and_custom(
            device,
            queue,
            font_system,
            atlas,
            viewport,
            text_areas,
            cache,
            zero_depth,
            |_| None,
        )
    }

    /// Prepares all of the provided text areas for rendering.
    pub fn prepare_with_depth<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
        metadata_to_depth: impl FnMut(usize) -> f32,
    ) -> Result<(), PrepareError> {
        self.prepare_with_depth_and_custom(
            device,
            queue,
            font_system,
            atlas,
            viewport,
            text_areas,
            cache,
            metadata_to_depth,
            |_| None,
        )
    }

    /// Prepares all of the provided text areas for rendering.
    pub fn prepare_with_custom<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
        rasterize_custom_glyph: impl FnMut(RasterizeCustomGlyphRequest) -> Option<RasterizedCustomGlyph>,
    ) -> Result<(), PrepareError> {
        self.prepare_with_depth_and_custom(
            device,
            queue,
            font_system,
            atlas,
            viewport,
            text_areas,
            cache,
            zero_depth,
            rasterize_custom_glyph,
        )
    }

    /// Prepares all of the provided text areas for rendering.
    pub fn prepare_with_depth_and_custom<'a>(
        &mut self,
        device: &Device,
        queue: &Queue,
        font_system: &mut FontSystem,
        atlas: &mut TextAtlas,
        viewport: &Viewport,
        text_areas: impl IntoIterator<Item = TextArea<'a>>,
        cache: &mut SwashCache,
        mut metadata_to_depth: impl FnMut(usize) -> f32,
        mut rasterize_custom_glyph: impl FnMut(
            RasterizeCustomGlyphRequest,
        ) -> Option<RasterizedCustomGlyph>,
    ) -> Result<(), PrepareError> {
        self.glyph_vertices.clear();

        let state = State { device, queue };
        let mut system = GlyphSystem {
            atlas,
            cache,
            font_system,
```

--------------------------------

### TextRenderer::render

Source: https://docs.rs/glyphon/latest/glyphon/struct.TextRenderer.html?search=u32+-%3E+bool

Renders all layouts that were previously provided to prepare.

```APIDOC
## TextRenderer::render

### Description
Renders all layouts that were previously provided to `prepare`.

### Method
`pub fn render(&self, atlas: &TextAtlas, viewport: &Viewport, pass: &mut RenderPass<'_>) -> Result<(), RenderError>`

### Parameters
- `atlas` (`&TextAtlas`) - Required - The text atlas.
- `viewport` (`&Viewport`) - Required - The viewport.
- `pass` (`&mut RenderPass<'_>`) - Required - The render pass to render into.

### Returns
`Result<(), RenderError>` - Ok if rendering succeeded, otherwise a RenderError.
```

--------------------------------

### Cache pipeline with multisample and depth_stencil

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html?search=u32+-%3E+bool

Pushes a pipeline into a cache keyed by format, multisample, and depth_stencil, then returns the pipeline. Used when a pipeline is created and cached for later reuse.

```rust
depth_stencil: depth_stencil.clone(),
multisample,
cache: None,
multiview_mask: None,
});

cache.push((format, multisample, depth_stencil, pipeline.clone()));

pipeline

```

--------------------------------

### TextRenderer::new

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=u32+-%3E+bool

Creates a new TextRenderer with a vertex buffer and render pipeline.

```APIDOC
## TextRenderer::new

### Description
Creates a new `TextRenderer` with the provided atlas, device, multisample state, and optional depth-stencil state.

### Method
`pub fn new(atlas: &mut TextAtlas, device: &Device, multisample: MultisampleState, depth_stencil: Option<DepthStencilState>) -> Self`

### Parameters
- **atlas** (`&mut TextAtlas`) - Required - The text atlas to use for glyph caching and pipeline creation.
- **device** (`&Device`) - Required - The wgpu device used to create the vertex buffer and pipeline.
- **multisample** (`MultisampleState`) - Required - The multisample state for the render pipeline.
- **depth_stencil** (`Option<DepthStencilState>`) - Optional - The depth-stencil state for the render pipeline.

### Returns
- **Self** - A new `TextRenderer` instance.

### Example
```rust
let renderer = TextRenderer::new(&mut atlas, &device, multisample, depth_stencil);
```
```

--------------------------------

### Cache struct and new method in cache.rs

Source: https://docs.rs/glyphon/latest/src/glyphon/cache.rs.html?search=Option%3CT%3E%2C+%28T+-%3E+U%29+-%3E+Option%3CU%3E

Defines the Cache struct and its constructor. The new method creates a sampler, shader module, vertex buffer layout, bind group layouts, and pipeline layout using the given wgpu Device. The shader is loaded from an embedded WGSL file via include_str!.

```rust
use crate::{GlyphToRender, Params};
use std::{
    borrow::Cow,
    mem,
    num::NonZeroU64,
    ops::Deref,
    sync::{Arc, Mutex},
};
use wgpu::{
    BindGroup, BindGroupDescriptor, BindGroupEntry, BindGroupLayout, BindGroupLayoutEntry,
    BindingResource, BindingType, BlendState, Buffer, BufferBindingType, ColorTargetState,
    ColorWrites, DepthStencilState, Device, FilterMode, FragmentState, MipmapFilterMode,
    MultisampleState, PipelineCompilationOptions, PipelineLayout, PipelineLayoutDescriptor,
    PrimitiveState, PrimitiveTopology, RenderPipeline, RenderPipelineDescriptor, Sampler,
    SamplerBindingType, SamplerDescriptor, ShaderModule, ShaderModuleDescriptor, ShaderSource,
    ShaderStages, TextureFormat, TextureSampleType, TextureView, TextureViewDimension,
    VertexFormat, VertexState,
};

/// A cache to share common resources (e.g., pipelines, layouts, shaders) between multiple text
/// renderers.
#[derive(Debug, Clone)]
pub struct Cache(Arc<Inner>);

type InnerCache = Mutex<
    Vec<(
        TextureFormat,
        MultisampleState,
        Option<DepthStencilState>,
        RenderPipeline,
    )>,
>;

#[derive(Debug)]
struct Inner {
    sampler: Sampler,
    shader: ShaderModule,
    vertex_buffers: [Option<wgpu::VertexBufferLayout<'static>>; 1],
    atlas_layout: BindGroupLayout,
    uniforms_layout: BindGroupLayout,
    pipeline_layout: PipelineLayout,
    cache: InnerCache,
}

impl Cache {
    /// Creates a new `Cache` with the given `device`.
    pub fn new(device: &Device) -> Self {
        let sampler = device.create_sampler(&SamplerDescriptor {
            label: Some("glyphon sampler"),
            min_filter: FilterMode::Nearest,
            mag_filter: FilterMode::Nearest,
            mipmap_filter: MipmapFilterMode::Nearest,
            lod_min_clamp: 0f32,
            lod_max_clamp: 0f32,
            ..Default::default()
        });

        let shader = device.create_shader_module(ShaderModuleDescriptor {
            label: Some("glyphon shader"),
            source: ShaderSource::Wgsl(Cow::Borrowed(include_str!("shader.wgsl"))),
        });

        let vertex_buffer_layout = wgpu::VertexBufferLayout {
            array_stride: mem::size_of::<GlyphToRender>() as wgpu::BufferAddress,
            step_mode: wgpu::VertexStepMode::Instance,
            attributes: &[
                wgpu::VertexAttribute {
                    format: VertexFormat::Sint32x2,
                    offset: 0,
                    shader_location: 0,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 2,
                    shader_location: 1,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 3,
                    shader_location: 2,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 4,
                    shader_location: 3,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Uint32,
                    offset: mem::size_of::<u32>() as u64 * 5,
                    shader_location: 4,
                },
                wgpu::VertexAttribute {
                    format: VertexFormat::Float32,
                    offset: mem::size_of::<u32>() as u64 * 6,
                    shader_location: 5,
                },
            ],
        };

        let atlas_layout = device.create_bind_group_layout(&wgpu::BindGroupLayoutDescriptor {
            entries: &[
                BindGroupLayoutEntry {
                    binding: 0,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        view_dimension: TextureViewDimension::D2,
                        sample_type: TextureSampleType::Float { filterable: true },
                    },
                    count: None,
                },
                BindGroupLayoutEntry {
                    binding: 1,
                    visibility: ShaderStages::VERTEX | ShaderStages::FRAGMENT,
                    ty: BindingType::Texture {
                        multisampled: false,
                        view_dimension: TextureViewDimension::D2,
                        sample_type: TextureSampleType::Float { filterable: true },
                    },

```

--------------------------------

### TextRenderer::prepare

Source: https://docs.rs/glyphon/latest/src/glyphon/text_render.rs.html?search=

Prepares all provided text areas for rendering using default depth and no custom glyph rasterization.

```APIDOC
## TextRenderer::prepare

### Description
Prepares all of the provided text areas for rendering. Uses default depth (zero) and no custom glyph rasterization.

### Method
`pub fn prepare<'a>(&mut self, device: &Device, queue: &Queue, font_system: &mut FontSystem, atlas: &mut TextAtlas, viewport: &Viewport, text_areas: impl IntoIterator<Item = TextArea<'a>>, cache: &mut SwashCache) -> Result<(), PrepareError>`

### Parameters
- `device` (`&Device`) - Required - The wgpu device.
- `queue` (`&Queue`) - Required - The wgpu queue.
- `font_system` (`&mut FontSystem`) - Required - The font system.
- `atlas` (`&mut TextAtlas`) - Required - The text atlas.
- `viewport` (`&Viewport`) - Required - The viewport.
- `text_areas` (`impl IntoIterator<Item = TextArea<'a>>`) - Required - The text areas to prepare.
- `cache` (`&mut SwashCache`) - Required - The swash cache.

### Returns
- `Result<(), PrepareError>` - Ok if preparation succeeded, otherwise an error.
```
Tokens:
Raw