>Psychtoolbox>PsychDocumentation

DrawTextPlugin – The plugin-based Screen(‘DrawText’) text renderer.

You may have arrived here because Screen() instructed you to go here
after Screen failed to load the external text renderer plugin.

On all operating systems the functions Screen(‘DrawText’) and
Screen(‘TextBounds’) try to use an external text rendering plugin for
drawing and handling of high quality text. This allows for advanced text
layout and formatting, high-quality anti-aliased rendering of text at
arbitrary text sizes, support for modern fonts like TrueType, and support
for drawing of the full international Unicode character set. Its use across
all operating systems also allows for (more) consistent text appearance on
different systems. Differences between installed fonts on different operating
systems can still cause slight differences in text appearance if you don’t
manage this though.

Which text renderer should be used can be set via
Screen(‘Preference’,’TextRenderer’, type), and after a first call to
Screen(‘DrawText’, …), type = Screen(‘Preference’,’TextRenderer’) will
report which ‘type’ of text renderer is actually used. A ‘type’ of 1 means
that the plugin based renderer is used, a ‘type’ of 0 or -1 would mean the
use of a less high quality fallback renderer, e.g., because loading the
text rendering plugin failed.

If use of the drawtext plugin renderer fails then that likely means that
some required 3rd party library is not installed, or of incompatible version.
The plugin requires a working installation of the FreeType-2 and
FontConfig libraries on your operating system, ie., somewhere stored in
a folder on the system library search path.

How to get those required 3rd party libraries:

Linux

Nothing to do. On Linux these libraries are part of the default installation
of any decent GNU/Linux distribution, so there usually isn’t any need for
manual setup work on your part.

macOS

On macOS with GNU/Octave, these are part of Octave, so you don’t need to
do anything. If you use macOS with Matlab then we recommend installing
[GStreamer](GStreamer) (help [GStreamer](GStreamer)) which also provides multi-media support, as
[GStreamer](GStreamer) provides the required libraries. Other sources than [GStreamer](GStreamer)
are HomeBrew, or XQuartz (X11 for macOS). Other sources of this libraries
may also work, as long as they are findable by the macOS linker, but this
is only tested with [GStreamer](GStreamer) and HomeBrew.

Some recent Matlab versions, e.g., R2015a and R2015b will contain an
outdated and incompatible version of libfreetype.6.dylib which may
cause problems. If you experience such problems, malfunctions or crashes,
then delete (or rename) that file, or move it out of the way.
E.g., for R2015b you’d have to delete or rename this file:

/Applications/MATLAB_R2015b.app/bin/maci64/libfreetype.6.dylib

Windows

On MS-Windows you will need to install the [GStreamer](GStreamer) multi- media framework -
see “help [GStreamer](GStreamer)” for installation instructions - otherwise Psychtoolbox
will use the old lower quality GDI text renderer instead. As of Psychtoolbox
version 3.0.19, you *must* install [GStreamer](GStreamer) v1.22 or later (see the download
link in “help [GStreamer](GStreamer)” for the latest tested version). All earlier versions
will not work!

The first time a script calls a text drawing function after an operating system
update, or after the installation of new text fonts, a long pause of many seconds
or even minutes may occur, while the so called fontconfig cache gets rebuilt.
Patience is the key. If this pause happens not only once, but at each invocation
of text drawing, your system may have developed a glitch, as described in GitHub
issue #429 and #579 on our issue tracker:

https://github.com/Psychtoolbox-3/Psychtoolbox-3/issues/429
https://github.com/Psychtoolbox-3/Psychtoolbox-3/issues/579

The solution is to manually delete the fontconfig cache. E.g., if your user
name would be “paul”, you’d likely need to delete the following file:
“C:\Users\paul[AppData](AppData)\Local\fontconfig\cache”

Some users find that the location of the cache file could be also in a different
place, e.g., following the above example for user “paul” it could be under:
“C:\Users\paul.cache\fontconfig", so files in that folder would need to be
deleted.

More background info about Psychtoolbox’s standard text renderer:

On macOS one can still select Apple’s CoreText text renderer via the command
Screen(‘Preference’,’TextRenderer’, 0); although Apples text renderer is
inferior in essentially any aspect. Apples CoreText renderer would also
get automatically selected if the plugin renderer would not work for some
reason. On MS-Windows one can still select the legacy MS-Windows GDI text
renderer via Screen(‘Preference’,’TextRenderer’, 0). This renderer provides
lower quality anti-aliasing, less accurate computation of text bounding boxes
via Screen(‘TextBounds’), and less accurate text positioning, as well as a
lower text drawing speed. Additionally this legacy GDI text renderer has
problems on HiDPI “Retina” displays and can misrender text in both size and
appearance.

The text renderer plugin implements a high-speed renderer based on a
combination of multiple free software libraries for text rendering and
text handling:

* OGLFT (http://oglft.sourceforge.net/) the OpenGL-FreeType library.
* The FreeType-2 (http://freetype.sourceforge.net/) library.
* The FontConfig (http://www.fontconfig.org) library.

The FontConfig library is used to find the optimal font and font settings,
given a specific font specification by your user code, a process known as
“font mapping”. FontConfig internally uses the FreeType-2 library to handle
the font files on your system and to gather all needed information for the
matching process.

After a font and settings have been selected, FreeType-2 is used to load
the font, and to convert it into high-quality character glyphs. Then the
OGLFT library is used to convert these glyphs into a format optimized for
fast drawing with OpenGL. OGLFT also performs caching of glyphs, text
layout, measurement of text dimensions and bounding boxes and the actual
drawing of the text.

Our actual plugin coordinates all these operations and communicates with
Screen().

The source code of the plugin can be found in the Psychtoolbox source
tree under PsychSourceGL/Cohorts/FTGLTextRenderer/

The plugins themselves are stored in the
Psychtoolbox/PsychBasic/PsychPlugins folder of your Psychtoolbox
installation. This is where Screen() expects to find the plugins for
dynamic loading.