Shumate.VectorSpriteSheet¶

Subclasses:: None

Methods¶

Inherited:: GObject.Object (37)
Structs:: GObject.ObjectClass (5)

class	`new` ()
	`add_page` (texture, json, default_scale)
	`add_sprite` (name, sprite)
	`get_sprite` (name, scale)
	`set_fallback` (fallback, *user_data)

Virtual Methods¶

Inherited:: GObject.Object (7)

Properties¶

None

Signals¶

Inherited:: GObject.Object (1)

Fields¶

Inherited:: GObject.Object (1)

Class Details¶

class Shumate.VectorSpriteSheet(**kwargs)¶

Bases:: GObject.Object
Abstract:: No
Structure:: Shumate.VectorSpriteSheetClass

A collection of [class`VectorSprite`]s.

Sprites are used as icons in symbols or as the pattern for a fill layer.

Most MapLibre stylesheets provide their spritesheet as a PNG image and a JSON description of the sprites. This spritesheet can be added using [method`VectorSpriteSheet`.add_page]. Sprites can also be added individually using [method`VectorSpriteSheet`.add_sprite].

Some map styles rely on application code to provide some or all of their sprites. This is supported using a fallback function, which can be set using [method`VectorSpriteSheet`.set_fallback]. This function can generate sprites on demand. For example, it could load a symbolic icon from the [class`Gtk`.IconTheme] or render a custom highway shield.

HiDPI support

Map styles should provide a double resolution spritesheet for high DPI displays. That spritesheet can be added as a separate page. The [class`VectorSpriteSheet`] will pick the best sprites for the display’s scale factor.

If a fallback function is set, it receives the requested scale factor as an argument. It should use this to generate the sprite at the correct size. For example, if the scale factor is 2, the image should be twice as large (but the *sprite’s* width and height should be the same).

Thread Safety

[class`VectorSpriteSheet`] is thread safe.

New in version 1.1.

classmethod new()¶

Returns:: a new [class`VectorSpriteSheet`]
Return type:: Shumate.VectorSpriteSheet

Creates a new, empty [class`VectorSpriteSheet`].

New in version 1.1.

add_page(texture, json, default_scale)¶

Parameters:

texture (Gdk.Texture) – a [class`Gdk`.Texture]
json (str) – a JSON string
default_scale (float) – the default scale factor of the page

Raises:

GLib.Error

Returns:

True if the page was added successfully, False otherwise

Return type:

bool

Adds a page to the spritesheet.

See <https://maplibre.org/maplibre-gl-js-docs/style-spec/sprite/> for details about the spritesheet format. Most stylesheets provide these files along with the main style JSON.

Map styles should provide a double resolution spritesheet for high DPI displays. That spritesheet should be added as its own page, with a default_scale of 2.

New in version 1.1.

add_sprite(name, sprite)¶

Parameters:

name (str) – the name of the sprite
sprite (Shumate.VectorSprite) – a [class`VectorSprite`]

Adds a sprite to the spritesheet.

New in version 1.1.

get_sprite(name, scale)¶

Parameters:

name (str) – an icon name
scale (float) – the scale factor of the icon

Returns:

a [class`VectorSprite`], or None if the icon does not exist.

Return type:

Shumate.VectorSprite or None

Gets a sprite from the spritesheet.

The returned sprite might not be at the requested scale factor if an exact match is not found.

New in version 1.1.

set_fallback(fallback, *user_data)¶

Parameters:

fallback (Shumate.VectorSpriteFallbackFunc or None) – a [callback`ShumateVectorSpriteFallbackFunc`] or None
user_data (object or None) – user data to pass to fallback

Sets a fallback function to generate sprites.

The fallback function is called when a texture is not found in the sprite sheet. It receives the icon name and scale factor, and should return a [class`VectorSprite`], or None if the icon could not be generated. It may be called in a different thread, and it may be called multiple times for the same icon name.

If a previous fallback function was set, it will be replaced and any sprites it generated will be cleared.

fallback may be None to clear the fallback function.

New in version 1.1.