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 OpenGL wrapper bgl 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 indice - 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, 72)
    blf.draw(font_id, "Hello World")


if __name__ == '__main__':
    init()

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 text drawing to use.

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) – Clip the drawing area by these bounds.
• ymin (float) – Clip the drawing area by these bounds.
• xmax (float) – Clip the drawing area by these bounds.
• ymax (float) – Clip the drawing area by these bounds.

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.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 (string) – the text to draw.

Returns:

the width and height of the text.

Return type:

tuple of 2 floats

blf.disable(fontid, option)

Disable 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 or KERNING_DEFAULT.

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 (string) – the text to draw.

blf.enable(fontid, option)

Enable 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 or KERNING_DEFAULT.

blf.load(filename)

Load a new font.

Parameters:filename (string) – the filename of the font. Returns:the new font’s fontid or -1 if there was an error. Return type:integer

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.

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.

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 blur level, can be 3, 5 or 0.
• 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.

Parameters:

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

blf.size(fontid, size, dpi)

Set the size and dpi for drawing text.

Parameters:

• fontid (int) – The id of the typeface as returned by blf.load(), for default font use 0.
• size (int) – Point size of the font.
• dpi (int) – dots per inch value to use for drawing.

blf.unload(filename)

Unload an existing font.

Parameters:filename (string) – the filename 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.KERNING_DEFAULT

constant value 8

blf.MONOCHROME

constant value 128

blf.ROTATION

constant value 1

blf.SHADOW

constant value 4

blf.WORD_WRAP

constant value 64