/usr/share/psychtoolbox-3/PsychDocumentation/DrawTextEncodingLocaleSettings.m is in psychtoolbox-3-common 3.0.11.20131230.dfsg1-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 | % DrawTextEncodingLocaleSettings
%
% If you are just concerned with drawing "standard" ASCII text with the
% Screen('DrawText', window, text); command, i.e. text that only contains
% "standard" latin characters, e.g., abcdef....ABCDEF.... and numbers
% 01234567890 and a few punctuation marks and symbols like .,!?#@$%& etc.
% then there's nothing you'd need to do. Screen('DrawText') and
% DrawFormattedText() will process these just fine.
%
% If you want to draw "native" unicode text strings conforming to
% UTF-16 encoding with characters or code points in the BMP (Basic
% multilingual plane), you can simply convert your string of unicode code
% points into a vector of doubles, ie., pass it as a vector of numbers of
% class double(), e.g., text = [1424, 1425, 1426] for the first three
% characters of the hebrew alphabet.
%
% Direct drawing of unicode text characters outside the BMP is possible in the
% same way on GNU/Linux with its default textrenderer, and on OS/X with
% Screen('Preference','TextRenderer', 2); set, if you've installed the
% neccessary software as described in "help DrawTextPlugin". In that case,
% the unicode code points may have values greater than 65535, ie., they are
% processed internally as UTF-32 / UCS-4 characters - Each single number
% represents exactly one character and the numbers can be codepoints from
% any Unicode plane.
%
% The standard OS/X text renderer and MS-Windows text renderer only support
% UTF-16 / UCS-2 encoding. Therefore, characters outside of the BMP must be
% represented by pairs of codepoints, each with a value between 0 and 65535
% - Two consecutive values in your double vector will represent one
% character from outside the BMP.
%
% You can also draw non-ASCII character strings encoded into some single-byte
% encoding scheme, multibyte encoding scheme or unicode characters that are
% not encoded as doubles but as a sequence of UTF-8 encoded bytes. To do
% so, first you have to tell Screen() the encoding scheme of the character
% string by a call to Screen('Preference','TextEncodingLoale', newloc);
% newloc is the name of the text encoding scheme to use. Example names for
% valid locales could be 'en_US.ISO8859-1' for single-byte ISO8859-1
% "Latin-1" encoding, or 'UTF-8' for UTF-8 encoded unicode text, or 'C' for
% default C language character encoding. Passing an empty string '' will
% reset the setting to the system default of your operating system. The
% function returns the previous setting. On OS/X and Linux you can type
% "locale -a" in a terminal window to list all supported settings. For
% MS-Windows you can find supported codepages under this URL:
% http://msdn.microsoft.com/en-us/library/dd317756%28VS.85%29.aspx
% e.g., setting a locale of '.1252' would select MS-Windows codepage 1252,
% aka 'windows-1252'.
% A setting of 'UTF-8' for UTF-8 encoded unicode should always work. The
% set of other supported encodings is highly operating system dependent.
%
% After you've told Screen the encoding to use, you can pass strings to
% Screen('DrawText'). If you want to make sure that Matlab or Octave don't
% tamper in unexpected or uncontrollable ways with your string, you can
% pass the string as a uint8 vector. Passing the string as uint8 vector is
% recommended in most cases. Different versions of Matlab and Octave store
% and process regular char() character strings in different ways on
% different operating systems which can often lead to unexpected results.
% On some setups you will be able to directly pass regular text strings,
% but this is not guaranteed to be portable across different computer
% systems, Matlab or Octave versions.
%
% If you get unexpected results for given text strings you can call
% Screen('Preference','Verbosity', 10); before a drawtext operation. The
% function will then print the passed string as a sequence of numbers after
% conversion into unicode format. This allows to check what kind of unicode
% characters were generated.
%
%
% Assuming Screen('DrawText') managed to receive your final (unicode) text
% string correctly, you'll also have to make sure that a font is selected
% that supports the characters in your string. E.g., not all fonts support
% hebrew characters. Use Screen('TextFont', window, fontName); to select a
% proper font fontName. How to find such a font is operating system
% specific. On Linux, the text renderer allows to select fonts by
% properties instead of names as well, e.g., it allows to select a font
% that supports a requested language:
% Screen('Textfont', window, '-:lang=he'); would select a font that
% supports hebrew. Screen('Textfont', window, '-:lang=ja'); would select a
% font that supports japanese script. See some more examples in the code of
% DrawHighQualityUnicodeTextDemo.m. The same works on OS/X with text
% renderer type 2.
%
% If you type DrawTextEncodingLocaleSettings to run this script, you may
% see some hebrew characters rendered if your systems fonts and text
% renderers do support this. This code also acts as a sample on how to pass
% UTF-8 unicode strings to 'DrawText'.
%
PsychDefaultSetup(1);
try
screenid = max(Screen('Screens'));
w = Screen('Openwindow', screenid, 255);
Screen('TextSize', w, 48);
if ~IsWin
Screen('Preference', 'TextRenderer', 2);
Screen('TextFont', w, '-:lang=he');
end
% Some uint8 vector with UTF-8 encoded hebrew characters:
y = uint8([215 148 215 169 215 160 215 153 215 157 44 32 215 149 215 160 215 162 215 169 215 148]);
if ~IsLinux
oldone = Screen('Preference', 'TextEncodingLocale', 'UTF-8');
else
oldone = Screen('Preference', 'TextEncodingLocale', 'en_US.UTF-8');
end
Screen('DrawText', w, y, 10, 100);
Screen('Flip', w);
KbStrokeWait;
Screen('CloseAll');
Screen('Preference', 'TextEncodingLocale', oldone);
catch
sca;
if exist('oldone','var')
Screen('Preference', 'TextEncodingLocale', oldone);
end
psychrethrow(psychlasterror);
end
|