Docs @ Psychtoolbox Wiki : DrawText

Search PTB Function help:
homepsychtoolbox.orgpage updateslogin

Screen('DrawText')

PsychtoolboxScreen.{mex*,dll} subfunction

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
command:
Screen('Preference', 'TextRenderer', 0); inserted at the top of your script.
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.


Valid XHTML 1.0 Transitional :: Valid CSS :: Powered by WikkaWiki
Page was generated in 0.1383 seconds