Font Drawing (blf)

This module provides access to Blender’s text drawing functions.

Hello World Text Example

Example of using the blf module. For this module to work we need to use the GPU module gpu as well.

# Import stand alone modules.
import blf
import bpy

font_info = {
    "font_id": 0,
    "handler": None,
}


def init():
    """init function - runs once"""
    import os
    # Create a new font object, use external TTF file.
    font_path = bpy.path.abspath('//Zeyada.ttf')
    # Store the font index - to use later.
    if os.path.exists(font_path):
        font_info["font_id"] = blf.load(font_path)
    else:
        # Default font.
        font_info["font_id"] = 0

    # Set the font drawing routine to run every frame.
    font_info["handler"] = bpy.types.SpaceView3D.draw_handler_add(
        draw_callback_px, (None, None), 'WINDOW', 'POST_PIXEL')


def draw_callback_px(self, context):
    """Draw on the viewports"""
    # BLF drawing routine.
    font_id = font_info["font_id"]
    blf.position(font_id, 2, 80, 0)
    blf.size(font_id, 50.0)
    blf.draw(font_id, "Hello World")


if __name__ == '__main__':
    init()

Drawing Text to an Image

Example showing how text can be drawn into an image. This can be done by binding an image buffer (imbuf) to the font’s ID.

import blf
import imbuf

image_size = 512, 512
font_size = 20

ibuf = imbuf.new(image_size)

font_id = blf.load("/path/to/font.ttf")

blf.color(font_id, 1.0, 1.0, 1.0, 1.0)
blf.size(font_id, font_size)
blf.position(font_id, 0, image_size[1] - font_size, 0)

blf.enable(font_id, blf.WORD_WRAP)
blf.word_wrap(font_id, image_size[0])

with blf.bind_imbuf(font_id, ibuf, display_name="sRGB"):
    blf.draw_buffer(font_id, "Lots of wrapped text. " * 50)

imbuf.write(ibuf, filepath="/path/to/image.png")

blf.ascender(fontid)

Return the max height of the glyphs from the baseline.

Parameters:: fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
Returns:: The ascender.
Return type:: float

blf.aspect(fontid, aspect)

Set the aspect for drawing text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
aspect (float) – The aspect ratio for non-uniform scaling of text.

blf.bind_imbuf(fontid, imbuf, *, display_name=None)

Context manager to draw text into an image buffer instead of the GPU’s context.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
imbuf (imbuf.types.ImBuf) – The image to draw into.
display_name (str | None) – Ignored (formerly a color-space transform name), kept for backwards compatibility.

Returns:

The BLF ImBuf context manager.

Return type:

BLFImBufContext

blf.boundbox(fontid, text)

Return the bounding box of the text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
text (str) – the text to measure.

Returns:

the bounding box (xmin, ymin, xmax, ymax).

Return type:

tuple[int, int, int, int]

blf.bounds_max(fontid)

Return the maximum bounding box of the font.

Parameters:: fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
Returns:: the maximum bounding box (xmin, ymin, xmax, ymax).
Return type:: tuple[float, float, float, float]

blf.clipping(fontid, xmin, ymin, xmax, ymax)

Set the clipping, enable/disable using CLIPPING.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
xmin (float) – Left edge of the clipping rectangle.
ymin (float) – Bottom edge of the clipping rectangle.
xmax (float) – Right edge of the clipping rectangle.
ymax (float) – Top edge of the clipping rectangle.

blf.color(fontid, r, g, b, a)

Set the color for drawing text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
r (float) – Red channel 0.0 - 1.0.
g (float) – Green channel 0.0 - 1.0.
b (float) – Blue channel 0.0 - 1.0.
a (float) – Alpha channel 0.0 - 1.0.

blf.descender(fontid)

Return the max depth of the glyphs from the baseline.

Parameters:: fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
Returns:: The descender.
Return type:: float

blf.dimensions(fontid, text)

Return the width and height of the text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
text (str) – The text to measure.

Returns:

The width and height of the text.

Return type:

tuple[float, float]

blf.disable(fontid, option)

Disable a font drawing option.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
option (int) – One of ROTATION, CLIPPING, SHADOW, MONOCHROME or WORD_WRAP.

blf.draw(fontid, text)

Draw text in the current context.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
text (str) – The text to draw.

blf.draw_buffer(fontid, text)

Draw text into the image buffer bound via blf.bind_imbuf().

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
text (str) – The text to draw into the bound image buffer.

blf.enable(fontid, option)

Enable a font drawing option.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
option (int) – One of ROTATION, CLIPPING, SHADOW, MONOCHROME or WORD_WRAP.

blf.fixed_width(fontid)

Return the fixed width of the font (0.0 if variable width).

Parameters:: fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
Returns:: The fixed width.
Return type:: float

blf.glyph_advance(fontid, text)

Return the advance width of the first character in the text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
text (str) – the text (glyph) to measure.

Returns:

The glyph advance.

Return type:

float

blf.height_max(fontid)

Return the maximum height of the font (typically ascender - descender).

Parameters:: fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
Returns:: The maximum height.
Return type:: float

blf.load(filepath)

Load a new font.

Parameters:: filepath (str | bytes) – The filepath of the font.
Returns:: The new font’s fontid or -1 if there was an error.
Return type:: int

blf.position(fontid, x, y, z)

Set the position for drawing text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
x (float) – X axis position to draw the text.
y (float) – Y axis position to draw the text.
z (float) – Z axis position to draw the text (typically 0).

blf.rotation(fontid, angle)

Set the text rotation angle, enable/disable using ROTATION.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
angle (float) – The angle for text drawing to use (in radians).

blf.shadow(fontid, level, r, g, b, a)

Shadow options, enable/disable using SHADOW.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
level (int) – The shadow type: 0 for none, 3 for 3x3 blur, 5 for 5x5 blur or 6 for outline. Other values raise a TypeError.
r (float) – Shadow color (red channel 0.0 - 1.0).
g (float) – Shadow color (green channel 0.0 - 1.0).
b (float) – Shadow color (blue channel 0.0 - 1.0).
a (float) – Shadow color (alpha channel 0.0 - 1.0).

blf.shadow_offset(fontid, x, y)

Set the offset for shadow text, enable/disable using SHADOW.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
x (int) – Horizontal shadow offset value in pixels.
y (int) – Vertical shadow offset value in pixels.

blf.size(fontid, size)

Set the size for drawing text.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
size (float) – Point size of the font.

blf.unload(filepath)

Unload an existing font.

Parameters:: filepath (str | bytes) – The filepath of the font.

blf.word_wrap(fontid, wrap_width)

Set the wrap width, enable/disable using WORD_WRAP.

Parameters:

fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
wrap_width (int) – The width (in pixels) to wrap words at.

blf.CLIPPING: Constant value 2

blf.MONOCHROME: Constant value 128

blf.ROTATION: Constant value 1

blf.SHADOW: Constant value 4

blf.WORD_WRAP: Constant value 64