111. opengl.textext — Text rendering on the OpenGL canvas.

This module uses textures on quads to render text on an OpenGL canvas. It is dependent on freetype and the Python bindings freetype-py.

111.1. Classes defined in module opengl.textext

class opengl.textext.FontTexture(filename, size, save=False)[source]

A Texture class for text rendering.

The FontTexture class is a texture containing the most important characters of a font. This texture can then be used to draw text on geometry. In the current implementation only the characters with ASCII ordinal in the range 32..127 are put in the texture.

Parameters:

  • filename (str or Path) – The name of the font file to be used. It should be the full path of an existing monospace font on the system.

  • size (float) – Intended font height. The actual height might differ a bit.

  • save (bool) – If True and filename is a font file (.ttf), the generated texture image will be saved as a .png image for later reload.

generateFromFont(filename, size, save=False)[source]

Initialize a FontTexture

activate(mode=None)[source]

Bind the texture and make it ready for use.

Returns the texture id.

texCoords(char)[source]

Return the texture coordinates for a character or string.

Parameters:

char (int | str) – If an integer, it should be in the range 32..127 (printable ASCII characters). If a string, all its characters should be ASCII printable characters (have an ordinal value in the range 32..127).

Returns:

tuple | array – If char is an int, returns a tuple with the texture coordinates in the FontTexture corresponding with the specified character. This is a sequence of four (x,y) pairs corresponding respectively holding the lower left, lower right, upper right, upper left corners of the character in the texture. Note that values for the lower corners are higher than those for the upper corners. This is because the FontTextures are stored from top to bottom (as in images files), while opengl coordinates are from bottom to top.

If char is a string of length ntext, returns a float array with shape (ntext,4,2) holding the texture coordinates needed to display the given text on a grid of quad4 elements.

classmethod default(size=24)[source]

Set and return the default FontTexture.

class opengl.textext.Text(text, pos, gravity=None, size=18, width=None, font=None, lineskip=1.0, grid=None, texmode=4, rotate=None, colors=None, **kargs)[source]

A text drawn at a 2D or 3D position.

Parameters:

  • text (string) – The text to display. If not a str, the string representation of the object will be drawn. Newlines in the string are supported. After a newline, the remainder of the string is continued from a lower vertical position and the initial horizontal position. The vertical line offset is determined from the font.

  • pos (tuple) – Position where render the text: either a 2D (x,y) or a 3D (x,y,z) tuple. If 2D, the values are measured in pixels. If 3D, it is a point in global 3D space. The text is drawn in 2D, inserted at the specified position.

  • gravity (str, optional) – Specifies the adjustment of the text with respect to the insert position. It can be a combination of one of the characters ‘N or ‘S’ to specify the vertical positon, and ‘W’ or ‘E’ for the horizontal. The default(empty) string centers the text.

  • size (float, optional) – The height of the font. This is the displayed height. The used font can have a different height and is scaled accordingly.

  • width (float, optional) – The width of the font. This is the displayed width of a single character (currently only monospace fonts are supported). The default is set from the size parameter and the aspect ratio of the font. Setting this to a different value allows the creation of condensed and expanded font types. Condensed fonts are often used to save space.

  • font (FontTexture or string, optional.) – The font to be used. If a string, it is the filename of an monospace font file existing on the system.

  • lineskip (float, loptional) – The distance in pixels between subsequent baselines in case of multi-line text. Multi-line text results when the input text contains newlines.

  • grid (Geometry, optional) – A grid geometry for rendering the text upon as a Texture. The default is a grid of rectangles of size (width,``size``) which are juxtaposed horizontally. Each rectangle will be rendered with a single character on it.

  • colors (list, optional) – A list of N color specifications, allowing to draw the subsequent strings in different colors. If provided, it overrides a color parameter specified in kargs. If all strings are to be displayed with the same color, the color parameter instead.

  • **kargs – Other parameters (like color) to be passed to the Actor initalization.

class opengl.textext.TextArray(val, pos, prefix='', colors=None, **kargs)[source]

An array of texts drawn at a 2D or 3D positions.

The text is drawn in 2D, inserted at the specified (2D or 3D) position, with alignment specified by the gravity (see class Text).

Parameters:

  • text (list of str) – A list containing N strings to be displayed. If an item is not a string, the string representation of the object will be drawn.

  • pos (float array) – Either an [N,2] or [N,3] shaped array with the 2D or 3D positions where to display the strings. If 2D, the values are measured in pixels. If 3D, it is a point in the global 3D space.

  • prefix (str, optional) – If specified, it is prepended to all drawn strings.

  • colors (list, optional) – A list of N color specifications, allowing to draw the subsequent strings in different colors. If provided, it overrides a color parameter specified in kargs. If all strings are to be displayed with the same color, the color parameter instead.

  • **kargs – Other parameters (like color) to be passed to the Actor initalization.

class opengl.textext.Mark(pos, tex, size, opak=False, ontop=True, **kargs)[source]

A 2D drawing inserted at a 3D position of the scene.

The minimum attributes and methods are:

  • pos : 3D point where the mark will be drawn