Struct Sprite

pub struct Sprite { /* private fields */ }

A single icon within a spritesheet.

A sprite is a rectangular icon stored as an SVG image and converted to a bitmap. The bitmap is saved to a spritesheet.

Implementations

impl Sprite

pub fn new(tree: Tree, pixel_ratio: u8) -> Option<Self>

pub fn new_sdf(tree: Tree, pixel_ratio: u8) -> Option<Self>

Create a sprite by rasterising an SVG, generating its signed distance field, and storing that in the sprite’s alpha channel.

The method comes from Valve’s original 2007 paper, Improved alpha-tested magnification for vector textures and special effects and its general implementation is available in the sdf_glyph_renderer crate. There are further details in this blog post from demofox.org.

There are SDF value cut-offs and ranges specific to Mapbox and MapLibre icons:

To render images with signed distance fields, we create a glyph texture that stores the distance to the next outline in every pixel. Inside of a glyph, the distance is negative; outside, it is positive. As an additional optimization, to fit into a one-byte unsigned integer, Mapbox shifts these ranges so that values between 192 and 255 represent “inside” a glyph and values from 0 to 191 represent “outside”. This gives the appearance of a range of values from black (0) to white (255).

JavaScript code for handling the cut-off is available in Elastic’s fork of Fontnik.

Note SDF icons are buffered by 3px on each side and so are 6px wider and 6px higher than the original SVG image..

Panics

This function can panic if:

• The Color::from_rgba function fails to create a color.

pub fn tree(&self) -> &Tree

Get the sprite’s SVG tree.

pub fn pixel_ratio(&self) -> u8

Get the sprite’s pixel ratio.

pub fn pixmap(&self) -> &Pixmap

Generate a bitmap image from the sprite’s SVG tree.

The bitmap is generated at the sprite’s pixel ratio.

pub fn content_area(&self) -> Option<Rect>

Metadata for a stretchable icon.

Describes the content area of an icon as a Rect. The metadata comes from the bounding box of an element in the SVG image that has the id mapbox-content.

Most icons do not specify a content area. But if it is present and the MapLibre/Mapbox map symbol uses icon-text-fit, the symbol’s text will be fitted inside this content box.

pub fn stretch_x_areas(&self) -> Option<Vec<Rect>>

Metadata for a stretchable icon.

Describes the horizontal position of areas that can be stretched. There may be multiple areas. The metadata comes from the bounding boxes of elements in the SVG image that have ids like mapbox-stretch-x-1. Although the entire bounding box is provided, only the left and right edges are stored in the index file and used by MapLibre/Mapbox to define the stretchable area.

Most icons do not specify stretchable areas. See also Sprite::content_area.

pub fn stretch_y_areas(&self) -> Option<Vec<Rect>>

Metadata for a stretchable icon.

Describes the vertical position of areas that can be stretched. There may be multiple areas. The metadata comes from the bounding boxes of elements in the SVG image that have ids like mapbox-stretch-y-1. Although the entire bounding box is provided, only the top and bottom edges are stored in the index file and used by MapLibre/Mapbox to define the stretchable area.

Most icons do not specify stretchable areas. See also Sprite::content_area.

Trait Implementations

impl Clone for Sprite

fn clone(&self) -> Sprite

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.