Additions:
%%(matlab;Usage)[newX,newY]=Screen('DrawText', windowPtr, text [,x] [,y] [,color] [,backgroundColor] [,yPositionIsBaseline] [,swapTextDirection]);%%
Draw text. "text" may include Unicode characters (e.g. Chinese).
A standard Matlab/Octave char()acter text string is interpreted according to
[[Screen]]'s current character encoding setting. By default this is the "system
default locale", as selected in the language settings of your user account. You
can change the encoding anytime via a call to [[Screen]]('[[Preference]]',
'TextEncodingLocale', newencoding); E.g., for UTF-8 multibyte character encoding
you'd call [[Screen]]('[[Preference]]','TextEncodingLocale','UTF-8');
If you have a non-ASCII text string and want to make sure that Matlab or Octave
doesn't meddle with your string, convert it into a uint8() datatype before
passing to this function.
If you want to pass a string which contains unicode characters directly, convert
the text to a double matrix, e.g., mytext = double(myunicodetext); then pass the
double matrix to this function. [[Screen]] will interpret all double numbers
directly as unicode code points.
Unicode text drawing is supported on all operating systems if you select the
default high quality text renderer. Of course you also have to select a text
font which contains the unicode character sets you want to draw - not all fonts
contain all unicode characters.
With the optionally selectable fast, low quality renderer, neither anti-aliasing
nor Unicode are supported and text positioning may be less accurate, but it is a
good choice if you are in need for speed over everything else. Select it via the
The following optional parameters allow to control location and color of the
drawn text:
"x" "y" defines the text pen startlocation. Default is the location of the pen
from previous draw text commands, or (0,0) at startup. "color" is the CLUT index
(scalar or [r g b] triplet or [r g b a] quadruple) for drawing the text; default
produces black.
"backgroundColor" is the color of the background area behind the text. By
default, text is drawn transparent in front of whatever image content is stored
in the window. You need to set an explicit backgroundColor and possibly enable
user defined alpha-blending with [[Screen]]('[[Preference]]', 'TextAlphaBlending', 1);
and [[Screen]]('Blendfunction', ...) to make use of text background drawing.
Appearance of the background + text may be different accross different operating
systems and text renderers, or it may not be supported at all, so this is not a
feature to rely on.
"yPositionIsBaseline" If specified, will override the global preference setting
for text positioning: It defaults to off. If it is set to 1, then the "y" pen
start location defines the base line of drawn text, otherwise it defines the top
of the drawn text. Old PTB's had a behaviour equivalent to setting 1,
unfortunately this behaviour wasn't replicated in early versions of
Psychtoolbox-3, so now we stick to the new behaviour by default.
"swapTextDirection" If specified and set to 1, then the direction of the text is
swapped from the default left-to-right to the swapped right-to-left direction,
e.g., to handle scripts with right-to-left writing order like hebrew.
"newX, newY" optionally return the final pen location.
Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of interesting text
preference settings that affect text drawing, e.g., setting alpha blending and
anti-aliasing modes.
Selectable text renderers: The [[Screen]]('[[Preference]]', 'TextRenderer', Type);
command allows to select among different text rendering engines with different
properties:
Type 0 is the fast OS specific text renderer: No unicode support, no
anti-aliasing, low flexibility but high speed for fast text drawing. Supported
on Windows and Linux as a OpenGL display list renderer.
Type 1 is the OS specific high quality renderer: Slower, but supports unicode,
anti-aliasing, and many interesting features. On Windows, this is a GDI based
renderer, on OS/X it is Apple's ATSU text renderer which is also used for Type 0
on OS/X. On Linux it is a renderer based on FTGL.
Type 2 is a renderer based on FTGL, the same as type 1 on Linux, also available
on OS/X, not supported on Windows.
This function doesn't provide support for text layout. Use the higher level
DrawFormattedText() function if you need basic support for text layout, e.g,
centered text output, line wrapping etc.
<<=====See also:=====
TextBounds TextSize TextFont TextStyle TextColor TextBackgroundColor Preference<<""</div>""
Deletions:
%%(matlab;Usage)[newX,newY]=Screen('DrawText', windowPtr, text [,x] [,y] [,color] [,backgroundColor] [,yPositionIsBaseline]);%%
Draw text. On MS-Windows, "text" may include two-byte (16 bit) Unicode
characters (e.g. Chinese). A standard Matlab/Octave text string is interpreted
as 8 bit ASCII string. If you want to pass a string which contains 16 bit UTF-16
unicode characters, convert the text to a double matrix, ie, mytext =
double(myunicodetext); then pass the double matrix to this function. Unicode
text drawing is supported if you select the default high quality, but slower GDI
text renderer on Windows.
With the optional fast, low quality renderer, neither anti-aliasing nor Unicode
are supported and text positioning may be a bit less accurate, but it is a good
choice if you are in need for speed over everything else. Select it via the
On Linux, Unicode and anti-aliasing aren't supported yet.
Default "x" "y" is current pen location. "color" is the CLUT index (scalar or [r
g b] triplet) that you want to poke into each pixel; default produces black with
the standard CLUT for this window's pixelSize. "yPositionIsBaseline" If
specified, will override the global preference setting for text positioning: It
defaults to off. If it is set to 1, the y pen location defines the base line of
drawn text, otherwise it defines the top of the drawn text. Old PTB's had a
behaviour equivalent to setting 1, unfortunately this behaviour wasn't
replicated in pre 3.0.8 PTB's so now we stick to the new behaviour by default.
"newX, newY" return the final pen location. On GNU/Linux the font renderer is
currently a very simple bitmap renderer which doesn't allow for Unicode
rendering or anti-aliasing.Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of
interesting text preference settings that affect text drawing, e.g., setting
alpha blending and anti-aliasing modes.
""</div>""
Additions:
""<div class="subfct" id="Screen">""===[[DrawText Screen('DrawText')]]===
Deletions:
""<div class="subfct" id="Screen" style="background-color:#eee; padding:1em; border-width:1px; border-style:solid; border-color:#ddd; margin-bottom: 2em;border-top: 5px solid #999999;">""===[[DrawText Screen('DrawText')]]===
Additions:
""<div class="subfct" id="Screen" style="background-color:#eee; padding:1em; border-width:1px; border-style:solid; border-color:#ddd; margin-bottom: 2em;border-top: 5px solid #999999;">""===[[DrawText Screen('DrawText')]]===
Draw text. On MS-Windows, "text" may include two-byte (16 bit) Unicode
characters (e.g. Chinese). A standard Matlab/Octave text string is interpreted
as 8 bit ASCII string. If you want to pass a string which contains 16 bit UTF-16
unicode characters, convert the text to a double matrix, ie, mytext =
double(myunicodetext); then pass the double matrix to this function. Unicode
text drawing is supported if you select the default high quality, but slower GDI
text renderer on Windows.
With the optional fast, low quality renderer, neither anti-aliasing nor Unicode
are supported and text positioning may be a bit less accurate, but it is a good
choice if you are in need for speed over everything else. Select it via the
command:
[[Screen]]('[[Preference]]', 'TextRenderer', 0); inserted at the top of your script.
On Linux, Unicode and anti-aliasing aren't supported yet.
the standard CLUT for this window's pixelSize. "yPositionIsBaseline" If
specified, will override the global preference setting for text positioning: It
defaults to off. If it is set to 1, the y pen location defines the base line of
drawn text, otherwise it defines the top of the drawn text. Old PTB's had a
behaviour equivalent to setting 1, unfortunately this behaviour wasn't
replicated in pre 3.0.8 PTB's so now we stick to the new behaviour by default.
"newX, newY" return the final pen location. On GNU/Linux the font renderer is
currently a very simple bitmap renderer which doesn't allow for Unicode
rendering or anti-aliasing.Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of
interesting text preference settings that affect text drawing, e.g., setting
alpha blending and anti-aliasing modes.
""</div>""
Deletions:
===[[DrawText Screen('DrawText')]]===
Draw text. "text" may include two-byte (16 bit) Unicode characters (e.g.
Chinese). A standard Matlab/Octave text string is interpreted as 8 bit ASCII
string. If you want to pass a string which contains 16 bit UTF-16 unicode
characters, convert the text to a double matrix, ie, mytext =
double(myunicodetext); then pass the double matrix to this function.
the standard CLUT for this window's pixelSize. "backgroundColor" is the color of
the text background. "yPositionIsBaseline" If specified, will override the
global preference setting for text positioning: It defaults to off. If it is set
to 1, the y pen location defines the base line of drawn text, otherwise it
defines the top of the drawn text. Old PTB's had a behaviour equivalent to
setting 1, unfortunately this behaviour wasn't replicated in pre 3.0.8 PTB's so
now we stick to the new behaviour by default. "newX, newY" return the final pen
location.
Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of interesting text
preference settings that affect text drawing, e.g., setting alpha blending and
anti-aliasing modes.
Additions:
Draw text. "text" may include two-byte (16 bit) Unicode characters (e.g.
Chinese). A standard Matlab/Octave text string is interpreted as 8 bit ASCII
string. If you want to pass a string which contains 16 bit UTF-16 unicode
characters, convert the text to a double matrix, ie, mytext =
double(myunicodetext); then pass the double matrix to this function.
the standard CLUT for this window's pixelSize. "backgroundColor" is the color of
the text background. "yPositionIsBaseline" If specified, will override the
global preference setting for text positioning: It defaults to off. If it is set
to 1, the y pen location defines the base line of drawn text, otherwise it
defines the top of the drawn text. Old PTB's had a behaviour equivalent to
setting 1, unfortunately this behaviour wasn't replicated in pre 3.0.8 PTB's so
now we stick to the new behaviour by default. "newX, newY" return the final pen
location.
Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of interesting text
preference settings that affect text drawing, e.g., setting alpha blending and
anti-aliasing modes.
Deletions:
Draw text. On MS-Windows, "text" may include two-byte (16 bit) Unicode
characters (e.g. Chinese). A standard Matlab/Octave text string is interpreted
as 8 bit ASCII string. If you want to pass a string which contains 16 bit UTF-16
unicode characters, convert the text to a double matrix, ie, mytext =
double(myunicodetext); then pass the double matrix to this function. Unicode
text drawing is supported if you select the default high quality, but slower GDI
text renderer on Windows.
With the optional fast, low quality renderer, neither anti-aliasing nor Unicode
are supported and text positioning may be a bit less accurate, but it is a good
choice if you are in need for speed over everything else. Select it via the
command:
[[Screen]]('[[Preference]]', 'TextRenderer', 0); inserted at the top of your script.
On Linux, Unicode and anti-aliasing aren't supported yet.
the standard CLUT for this window's pixelSize. "yPositionIsBaseline" If
specified, will override the global preference setting for text positioning: It
defaults to off. If it is set to 1, the y pen location defines the base line of
drawn text, otherwise it defines the top of the drawn text. Old PTB's had a
behaviour equivalent to setting 1, unfortunately this behaviour wasn't
replicated in pre 3.0.8 PTB's so now we stick to the new behaviour by default.
"newX, newY" return the final pen location. On GNU/Linux the font renderer is
currently a very simple bitmap renderer which doesn't allow for Unicode
rendering or anti-aliasing.Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of
interesting text preference settings that affect text drawing, e.g., setting
alpha blending and anti-aliasing modes.
Additions:
===[[DrawText Screen('DrawText')]]===
==[[Psychtoolbox]] › [[Screen]].{mex*,dll} subfunction==
%%(matlab;Usage)[newX,newY]=Screen('DrawText', windowPtr, text [,x] [,y] [,color] [,backgroundColor] [,yPositionIsBaseline]);%%
[[Screen]]('[[Preference]]', 'TextRenderer', 0); inserted at the top of your script.
rendering or anti-aliasing.Btw.: [[Screen]]('[[Preference]]', ...); provides a couple of
Deletions:
===[[DrawText]]===
==ScreenFunctions==
Usage:
[newX,newY]=Screen('DrawText', windowPtr, text [,x] [,y] [,color] [,backgroundColor] [,yPositionIsBaseline]);
Screen('Preference', 'TextRenderer', 0); inserted at the top of your script.
rendering or anti-aliasing.Btw.: Screen('Preference', ...); provides a couple of
ScreenFunctions