pyglet.font.user

This module defines the usage and creation of user defined fonts in Pyglet.

Previously, pyglet only supported font renderers that are built into the operating system, such as FreeType, DirectWrite, or Quartz. However, there are situations in which a user may not want or need all the features a font can provide. They just need to put characters in a particular order without the hassle of exporting into a separate file.

The UserDefinedMappingFont is provided for most use cases, which will allow you to make an internal font that can be used where a font_name is required to identify a font.

A user defined font is also identified by its name. The name you choose should be unique to ensure it will not conflict with a system font. For example, do not use Arial, as that will collide with Windows systems.

With UserDefinedMappingFont you can pass a mapping of characters that point to your ImageData.

mappings={'c': my_image_data, 'b': my_image_data, 'a': my_image_data}

For more custom behavior, a dict-like object can be used, such as a class.

class MyCustomMapping:
    def get(self, char: str) -> ImageData | None:
        # return ImageData if a character is found.
        # return None if no character is found

mappings = MyCustomMapping()
Once your font is created, you also must register it within pyglet to use it. This can be done through the

add_user_font() function.

When you register a user defined font, only those parameters will used to identify the font. If you have a font, but want to have a italic enabled version. You must make a new instance of your font, but with the italic parameter set as True. Same applies to the size parameter. The weight parameter can also be provided as a string.

Scaling

By default, user font’s will not be scaled. In most use cases, you have a single font at a specific size that you want to use.

There are cases where a user may want to scale their font to be used at any size. We provide the following function: get_scaled_user_font(). By providing the user defined font instance, and a new size, you will get back a new font instance that is scaled to the new size. This new instance must also be registered the same way as the base font.

When specifying the size parameter, that value is used to determine the ratio of scaling between the new size. So if your base font is a size of 12, creating a scaled version at size 24 will be double the size of the base.

Warning

The PIL library is a required dependency to use the scaling functionality.

Added in version 2.0.15.

exception UserDefinedFontException

An exception related to user font creation.

class UserDefinedFontBase

Used as a base for all user defined fonts.

Added in version 2.0.15.

glyph_renderer_class

alias of UserDefinedGlyphRenderer

__init__(
name: str,
default_char: str,
size: int,
ascent: int | None = None,
descent: int | None = None,
weight: str = 'normal',
style: str = 'normal',
stretch: str = 'normal',
dpi: int = 96,
locale: str | None = None,
) → None

Initialize a user defined font.

Parameters:

  • name (str) – Name of the font. Used to identify the font. Must be unique to ensure it does not collide with any system fonts.

  • default_char (str) – If a character in a string is not found in the font, it will use this as fallback.

  • size (int) – Font size, usually in pixels.

  • ascent (int | None) – Maximum ascent above the baseline, in pixels. If None, the image height is used.

  • descent (int | None) – Maximum descent below the baseline, in pixels. Usually negative.

  • weight (str) – The font weight, as a string. Defaults to “normal”.

  • style (str) – If True, this font will be used when italic is enabled for the font name.

  • stretch (str) – If True, this font will be used when stretch is enabled for the font name.

  • dpi (int) – The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Use a default of 96 for standard sizing.

  • locale (str | None) – Used to specify the locale of this font.

enable_scaling(base_size: int) → None
Return type:

None

property name: str

Return the Family Name of the font as a string.

class UserDefinedMappingFont

The class allows the creation of user defined fonts from a set of mappings.

Added in version 2.0.15.

__init__(
name: str,
default_char: str,
size: int,
mappings: DictLikeObject,
ascent: int | None = None,
descent: int | None = None,
weight: str = 'normal',
style: str = 'normal',
stretch: str = 'normal',
dpi: int = 96,
locale: str | None = None,
) → None

Initialize the default parameters of your font.

Parameters:

  • name (str) – Name of the font. Must be unique to ensure it does not collide with any system fonts.

  • default_char (str) – If a character in a string is not found in the font, it will use this as fallback.

  • size (int) – Font size. Should be in pixels. This value will affect scaling if enabled.

  • mappings (DictLikeObject) – A dict or dict-like object with a get function. The get function must take a string character, and output ImageData if found. It also must return None if no character is found.

  • ascent (int | None) – Maximum ascent above the baseline, in pixels. If None, the image height is used.

  • descent (int | None) – Maximum descent below the baseline, in pixels. Usually negative.

  • weight (str) – The font weight, as a string. Defaults to “normal”.

  • style (str) – The font style, as a string. Defaults to “normal”.

  • stretch (str) – The font stretch, as a string. Defaults to “normal”.

  • dpi (int) – The assumed resolution of the display device, for the purposes of determining the pixel size of the font. Use a default of 96 for standard sizing.

  • locale (str | None) – Used to specify the locale of this font.

enable_scaling(base_size: int) → None

Enables scaling the font size.

Parameters:

base_size (int) – The base size is used to calculate the ratio between new sizes and the original.

Return type:

None

get_glyphs(
text: str,
shaping: bool = False,
) → tuple[list[Glyph], list[GlyphPosition]]

Create and return a list of Glyphs for text.

If any characters do not have a known glyph representation in this font, a substitution will be made with the default_char.

Return type:

tuple[list[Glyph], list[GlyphPosition]]

get_scaled_user_font(
font_base: UserDefinedMappingFont,
size: int,
) → UserDefinedMappingFont

This function will return a new font instance which can scale it’s size based off the original base font.

Note

The scaling functionality requires the PIL library to be installed.

Added in version 2.0.15.

Parameters:

  • font_base (UserDefinedMappingFont) – The base font object to create a new size from.

  • size (int) – The new font size. This will be scaled based on the ratio between the base size and the new size.

Return type:

UserDefinedMappingFont