/lib/pods/SDL/TTF.pod

http://github.com/PerlGameDev/SDL · Unknown · 676 lines · 378 code · 298 blank · 0 comment · 0 complexity · 33ab0c10a52b8cfffb070d79d66a1d9d MD5 · raw file

  1. =pod
  2. =head1 NAME
  3. SDL::TTF - True Type Font functions (libfreetype)
  4. =head1 CATEGORY
  5. TTF
  6. =head1 CONSTANTS
  7. The constants are exported by default. You can avoid this by doing:
  8. use SDL::TTF ();
  9. and access them directly:
  10. SDL::TTF::TTF_HINTING_NORMAL;
  11. Available constants for "hinting":
  12. =over 4
  13. =item *
  14. TTF_HINTING_NORMAL
  15. =item *
  16. TTF_HINTING_LIGHT
  17. =item *
  18. TTF_HINTING_MONO
  19. =item *
  20. TTF_HINTING_NONE
  21. =back
  22. Available constants for "style":
  23. =over 4
  24. =item *
  25. TTF_STYLE_NORMAL
  26. =item *
  27. TTF_STYLE_BOLD
  28. =item *
  29. TTF_STYLE_ITALIC
  30. =item *
  31. TTF_STYLE_UNDERLINE
  32. =item *
  33. TTF_STYLE_STRIKETHROUGH
  34. =back
  35. =head1 METHODS
  36. =head2 General methods
  37. =head3 linked_version
  38. my $version = SDL::TTF::linked_version();
  39. This gives you the SDL::Version object which SDL_ttf lib is used on the system.
  40. No prior initialization needs to be done before these function is called.
  41. Example:
  42. use SDL::TTF;
  43. use SDL::Version;
  44. my $version = SDL::TTF::linked_version();
  45. printf("got version: %d.%d.%d\n", $version->major, $version->minor, $version->patch);
  46. =head3 compile_time_version
  47. my $version = SDL::TTF::compile_time_version();
  48. This gives you the SDL::Version object which SDL_ttf was present at compile time.
  49. =head3 init
  50. my $success = SDL::TTF::init();
  51. Initialize the truetype font API.
  52. This must be called before using other functions in this library, except L<SDL::TTF::was_init|SDL::TTF/"was_init"> and L<SDL::TTF::linked_version|SDL::TTF/"linked_version">.
  53. SDL does not have to be initialized before this call.
  54. Returns: C<0> on success, C<-1> on any error.
  55. =head3 was_init
  56. my $was_init = SDL::TTF::was_init();
  57. Query the initialization status of the truetype font API.
  58. You may, of course, use this before L<SDL::TTF::init|SDL::TTF/"init"> to avoid initializing twice in a row. Or use this to determine if you need to
  59. call L<SDL::TTF::quit|SDL::TTF/"quit">.
  60. =head3 quit
  61. SDL::TTF::quit();
  62. Shutdown and cleanup the truetype font API.
  63. After calling this the SDL::TTF functions should not be used, excepting L<SDL::TTF::was_init|SDL::TTF/"was_init">. You may, of course, use
  64. L<SDL::TTF::init|SDL::TTF/"init"> to use the functionality again
  65. =head2 Management functions
  66. =head3 open_font
  67. my $font = SDL::TTF::open_font($font_file, $point_size);
  68. Load file for use as a font, at the given size. This is actually C<SDL::TTF::open_font_index(..., ..., $index = 0)>. This can load TTF, OTF and FON files.
  69. Returns: a L<SDL::TTF::Font> object. C<undef> is returned on errors.
  70. Example:
  71. use SDL::TTF;
  72. use SDL::TTF::Font;
  73. my $font = SDL::TTF::open_font('arial.ttf', 24);
  74. =head3 open_font_index
  75. my $font = SDL::TTF::open_font($font_file, $point_size, $face_index);
  76. This is the same as L<SDL::TTF::open_font|SDL::TTF/"open_font">, except you can specify the face index of a font file containing multiple faces.
  77. This can load TTF and FON files.
  78. =head3 open_font_RW
  79. my $font = SDL::TTF::open_font_RW($rwops_object, $free, $point_size);
  80. This is the same as L<SDL::TTF::open_font|SDL::TTF/"open_font">, except you can pass an L<SDL::RWOps>-object. If you pass true as C<$free>, the L<SDL::RWOps>-object
  81. will be freed by SDL_ttf library. Don't do this, perl will free this object for you.
  82. Example:
  83. my $font = SDL::TTF::open_font_RW(SDL::RWOps->new_file($font_file, 'r'), 0, 24);
  84. =head3 open_font_index_RW
  85. my $font = SDL::TTF::open_font_index_RW($rwops_object, $free, $point_size, $face_index);
  86. This is the same as L<SDL::TTF::open_font_index|SDL::TTF/"open_font_index">, except you can pass an L<SDL::RWOps>-object. If you pass true as C<$free>, the
  87. L<SDL::RWOps>-object will be freed by SDL_ttf library. Don't do this, perl will free this object for you.
  88. =head2 Attributes
  89. =head3 Global attributes
  90. =head4 byte_swapped_unicode
  91. SDL::TTF::byte_swapped_unicode( $bool );
  92. This function tells SDL_ttf whether UNICODE (2 bytes per character) text is generally byteswapped. A C<UNICODE_BOM_NATIVE> or
  93. C<UNICODE_BOM_SWAPPED> character in a string will temporarily override this setting for the remainder of that string, however this setting
  94. will be restored for the next one. The default mode is non-swapped, native endianness of the CPU.
  95. =head3 Font style
  96. =head4 get_font_style
  97. SDL::TTF::get_font_style($font);
  98. Returns: The style as a bitmask composed of the following masks:
  99. =over 4
  100. =item *
  101. TTF_STYLE_NORMAL
  102. =item *
  103. TTF_STYLE_BOLD
  104. =item *
  105. TTF_STYLE_ITALIC
  106. =item *
  107. TTF_STYLE_UNDERLINE
  108. =item *
  109. TTF_STYLE_STRIKETHROUGH (since SDL_ttf 2.0.10)
  110. =back
  111. Example:
  112. my $style = SDL::TTF::get_font_style($font);
  113. print("normal\n") if $style == TTF_STYLE_NORMAL;
  114. print("bold\n") if $style & TTF_STYLE_BOLD;
  115. print("italic\n") if $style & TTF_STYLE_ITALIC;
  116. print("underline\n") if $style & TTF_STYLE_UNDERLINE;
  117. print("strikethrough\n") if $style & TTF_STYLE_STRIKETHROUGH;
  118. =head4 set_font_style
  119. SDL::TTF::set_font_style($font, $style);
  120. Set the rendering style of the loaded font.
  121. B<Note>: C<TTF_STYLE_UNDERLINE> may cause surfaces created by C<SDL::TTF::render_glyph_*> functions to be extended vertically, downward only,
  122. to encompass the underline if the original glyph metrics didn't allow for the underline to be drawn below. This does not change the math used
  123. to place a glyph using glyph metrics.
  124. On the other hand C<TTF_STYLE_STRIKETHROUGH> doesn't extend the glyph, since this would invalidate the metrics used to position the glyph when
  125. blitting, because they would likely be extended vertically upward. There is perhaps a workaround, but it would require programs to be smarter
  126. about glyph blitting math than they are currently designed for.
  127. Still, sometimes the underline or strikethrough may be outside of the generated surface, and thus not visible when blitted to the screen. In
  128. this case, you should probably turn off these styles and draw your own strikethroughs and underlines.
  129. =head4 get_font_outline
  130. my $outline = SDL::TTF::get_font_outline($font);
  131. Get the current outline width of the font, in pixels.
  132. B<Note>: at least SDL_ttf 2.0.10 needed
  133. =head4 set_font_outline
  134. SDL::TTF::set_font_outline($font, $outline);
  135. Set the outline pixel width of the loaded font. Use C<0>(zero) to turn off outlining.
  136. B<Note>: at least SDL_ttf 2.0.10 needed
  137. =head3 Font settings
  138. =head4 get_font_hinting
  139. my $hinting = SDL::TTF::get_font_hinting($font);
  140. Get the current hinting setting of the loaded font.
  141. B<Note>: at least SDL_ttf 2.0.10 needed
  142. Returns the hinting type matching one of the following defined values:
  143. =over 4
  144. =item *
  145. TTF_HINTING_NORMAL
  146. =item *
  147. TTF_HINTING_LIGHT
  148. =item *
  149. TTF_HINTING_MONO
  150. =item *
  151. TTF_HINTING_NONE
  152. =back
  153. =head4 set_font_hinting
  154. SDL::TTF::set_font_hinting($font, $hinting);
  155. Set the hinting of the loaded font. You should experiment with this setting if you know which font you are using beforehand, especially when
  156. using smaller sized fonts. If the user is selecting a font, you may wish to let them select the hinting mode for that font as well.
  157. B<Note>: at least SDL_ttf 2.0.10 needed
  158. Example:
  159. SDL::TTF::set_font_hinting($font, TTF_HINTING_LIGHT);
  160. =head4 get_font_kerning
  161. my $kerning_enabled = SDL::TTF::get_font_kerning($font);
  162. Get the current kerning setting of the loaded font.
  163. Returns: C<0>(zero) if kerning is disabled. A non-zero value is returned when enabled. The default for a newly loaded font is enabled(C<1>).
  164. B<Note>: at least SDL_ttf 2.0.10 needed
  165. B<Note>: This function returns wrong values: See L<http://bugzilla.libsdl.org/show_bug.cgi?id=973>
  166. =head4 set_font_kerning
  167. SDL::TTF::set_font_kerning($font, $kerning_enabled);
  168. Set whether to use kerning when rendering the loaded font. This has no effect on individual glyphs, but rather when rendering whole strings of
  169. characters, at least a word at a time. Perhaps the only time to disable this is when kerning is not working for a specific font, resulting in
  170. overlapping glyphs or abnormal spacing within words.
  171. Pass C<0> to disable kerning, 1 to enable.
  172. B<Note>: at least SDL_ttf 2.0.10 needed
  173. =head3 Font metrics
  174. =head4 font_height
  175. my $font_height = SDL::TTF::font_height($font);
  176. Get the maximum pixel height of all glyphs of the loaded font. You may use this height for rendering text as close together vertically as
  177. possible, though adding at least one pixel height to it will space it so they can't touch. Remember that SDL_ttf doesn't handle multiline
  178. printing, so you are responsible for line spacing, see the L<SDL::TTF::font_line_skip|SDL::TTF/"font_line_skip"> as well.
  179. =head4 font_ascent
  180. my $font_ascent = SDL::TTF::font_ascent($font);
  181. Get the maximum pixel ascent of all glyphs of the loaded font. This can also be interpreted as the distance from the top of the font to the
  182. baseline.
  183. It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's C<maxy> metric to resolve the top
  184. of the rectangle used when blitting the glyph on the screen.
  185. Example:
  186. my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
  187. $rect->y( $top + SDL::TTF::font_ascent($font) - $maxy );
  188. =head4 font_descent
  189. my $font_descent = SDL::TTF::font_descent($font);
  190. Get the maximum pixel descent of all glyphs of the loaded font. This can also be interpreted as the distance from the baseline to the bottom of
  191. the font.
  192. It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's C<maxy> metric to resolve the top
  193. of the rectangle used when blitting the glyph on the screen.
  194. Example:
  195. my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
  196. $rect->y( $bottom - SDL::TTF::font_descent($font) - $maxy );
  197. =head4 font_line_skip
  198. my $font_line_skip = SDL::TTF::font_line_skip($font);
  199. Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the L<SDL::TTF::font_height|SDL::TTF/"font_height"> of the
  200. font.
  201. =head3 Face attributes
  202. =head4 font_faces
  203. my $font_faces = SDL::TTF::font_faces($font);
  204. Get the number of faces ("sub-fonts") available in the loaded font. This is a count of the number of specific fonts (based on size and style
  205. and other typographical features perhaps) contained in the font itself.
  206. =head4 font_face_is_fixed_width
  207. my $font_face_is_fixed_width = SDL::TTF::font_face_is_fixed_width($font);
  208. Test if the current font face of the loaded font is a fixed width font. Fixed width fonts are monospace, meaning every character that exists
  209. in the font is the same width, thus you can assume that a rendered string's width is going to be the result of C<glyph_width * string_length>.
  210. Returns: C<E<gt>0> if font is a fixed width font. C<0> if not a fixed width font.
  211. =head4 font_face_family_name
  212. my $font_face_family_name = SDL::TTF::font_face_family_name($font);
  213. Get the current font face family name from the loaded font. This information is not for every font available.
  214. Example:
  215. my $font = SDL::TTF::open_font('arialuni.ttf', 8);
  216. printf("%s\n", SDL::TTF::font_face_family_name($font)); # will print "Arial Unicode MS"
  217. =head4 font_face_style_name
  218. my $font_face_style_name = SDL::TTF::font_face_style_name($font);
  219. Get the current font face style name from the loaded font. This information is not for every font available.
  220. Example:
  221. my $font = SDL::TTF::open_font('arialuni.ttf', 8);
  222. printf("%s\n", SDL::TTF::font_face_style_name($font)); # will print "Regular"
  223. =head3 Glyphs
  224. =head4 glyph_is_provided
  225. my $glyph_is_provided = SDL::TTF::glyph_is_provided($font, $unicode_char);
  226. Get the status of the availability of the glyph from the loaded font.
  227. Returns: the index of the glyph in font, or 0 for an undefined character code.
  228. B<Note>: You have to pass this unicode character either as UTF16/UCS-2 big endian without BOM, or with BOM as UTF16/UCS-2 big/little endian.
  229. B<Note>: at least SDL_ttf 2.0.10 needed
  230. Example:
  231. print("We have this char!\n") if SDL::TTF::glyph_is_provided($font, "\0M");
  232. =head4 glyph_metrics
  233. my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, $unicode_char) };
  234. Get desired glyph metrics of the UNICODE char from the loaded font.
  235. See also: L<The FreeType2 Documentation Tutorial|http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html>
  236. B<Note>: You have to pass this unicode character either as UTF16/UCS-2 big endian without BOM, or with BOM as UTF16/UCS-2 big/little endian.
  237. Example:
  238. my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, "\0M") };
  239. =head3 Text metrics
  240. =head4 size_text
  241. my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
  242. Calculate the resulting surface size of the LATIN1 encoded text rendered using C<$font>. No actual rendering is done, however correct kerning
  243. is done to get the actual width. The height returned is the same as you can get using L<SDL::TTF::font_height|SDL::TTF/"font_height">.
  244. =head4 size_utf8
  245. my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) };
  246. Calculate the resulting surface size of the UTF8 encoded text rendered using C<$font>. No actual rendering is done, however correct kerning is
  247. done to get the actual width. The height returned in h is the same as you can get using L<SDL::TTF::font_height|SDL::TTF/"font_height">.
  248. Note that the first example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.
  249. Examples:
  250. ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hello World!') }; # plain text, if your script is in utf8 or ansi-format
  251. # or
  252. ($width, $height) = @{ SDL::TTF::size_utf8($font, "\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF") }; # utf8 hex-data
  253. # or
  254. use Unicode::String;
  255. my $unicode = utf8($data_from_somewhere);
  256. ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode->utf8) }; # utf8 via Unicode::String
  257. =head4 size_unicode
  258. my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) };
  259. Calculate the resulting surface size of the UNICODE encoded text rendered using C<$font>. No actual rendering is done, however correct kerning
  260. is done to get the actual width. The height returned in h is the same as you can get using L<SDL::TTF::font_height|SDL::TTF/"font_height">.
  261. C<$text> has to be:
  262. =over 4
  263. =item UTF16BE without BOM
  264. "hello" will look like "\0h\0e\0l\0l\0o"
  265. =item UTF16BE with BOM
  266. "hello" will look like "\xFE\xFF\0h\0e\0l\0l\0o"
  267. =item UTF16LE with BOM
  268. "hello" will look like "\xFF\xFEh\0e\0l\0l\0o\0"
  269. =back
  270. You may use Unicode::String for this.
  271. =head2 Font Rendering
  272. =head3 Solid
  273. =head4 render_glyph_solid
  274. my $surface = SDL::TTF::render_glyph_solid($font, $char, $color);
  275. Render the unicode encoded char onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
  276. B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
  277. B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least version 2.3.5
  278. =head4 render_text_solid
  279. my $surface = SDL::TTF::render_text_solid($font, $text, $color);
  280. Render the LATIN1 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
  281. B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least
  282. version 2.3.5
  283. Example:
  284. use SDL;
  285. use SDL::Rect;
  286. use SDL::Video;
  287. use SDL::Color;
  288. use SDL::TTF;
  289. use SDL::TTF::Font;
  290. SDL::init(SDL_INIT_VIDEO);
  291. SDL::TTF::init();
  292. my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
  293. my $font = SDL::TTF::open_font('somefont.ttf', '24');
  294. die 'Coudnt make font '. SDL::get_error if !$font;
  295. my $surface = SDL::TTF::render_text_solid($font, 'Hello!', SDL::Color->new(0xFF,0xFF,0xFF));
  296. SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
  297. SDL::Video::update_rect($display, 0, 0, 0, 0);
  298. SDL::delay(5000);
  299. =head4 render_utf8_solid
  300. my $surface = SDL::TTF::render_utf8_solid($font, $text, $color);
  301. Render the UTF8 encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
  302. B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least
  303. version 2.3.5
  304. =head4 render_unicode_solid
  305. my $surface = SDL::TTF::render_unicode_solid($font, $text, $color);
  306. Render the unicode encoded text onto a new surface, using the Solid mode. After that you can blit this surface to your display-surface.
  307. B<Note>: The unicode test has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
  308. B<Note>: L<See space-character bug|http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=374062>. You have to upgrade libfreetype2 to at least
  309. version 2.3.5
  310. =head3 Shaded
  311. =head4 render_glyph_shaded
  312. my $surface = SDL::TTF::render_glyph_shaded($font, $char, $color, $background_color);
  313. Render the unicode encoded char onto a new surface. The surface is filled with C<$background_color>. After that you can blit this surface to
  314. your display-surface.
  315. B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
  316. =head4 render_text_shaded
  317. my $surface = SDL::TTF::render_text_shaded($font, $text, $color, $background_color);
  318. Render the LATIN1 encoded text onto a new surface. The surface is filled with C<$background_color>. After that you can blit this surface to
  319. your display-surface.
  320. Example:
  321. use SDL;
  322. use SDL::Video;
  323. use SDL::Color;
  324. use SDL::TTF;
  325. use SDL::TTF::Font;
  326. SDL::init(SDL_INIT_VIDEO);
  327. SDL::TTF::init();
  328. my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
  329. my $font = SDL::TTF::open_font('arial.ttf', '24');
  330. my $white = SDL::Color->new(0xFF, 0xFF, 0xFF);
  331. my $black = SDL::Color->new(0x00, 0x00, 0x00);
  332. my $surface = SDL::TTF::render_text_solid($font, 'Hello!', $white, $black);
  333. SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
  334. SDL::Video::update_rect($display, 0, 0, 0, 0);
  335. SDL::delay(5000);
  336. =head4 render_utf8_shaded
  337. my $surface = SDL::TTF::render_utf8_shaded($font, $text, $color, $background_color);
  338. Render the UTF8 encoded text onto a new surface. The surface is filled with C<$background_color>. After that you can blit this surface to
  339. your display-surface.
  340. =head4 render_unicode_shaded
  341. my $surface = SDL::TTF::render_unicode_shaded($font, $text, $color, $background_color);
  342. Render the unicode encoded text onto a new surface. The surface is filled with C<$background_color>. After that you can blit this surface to
  343. your display-surface.
  344. B<Note>: The unicode text has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
  345. =head3 Blended
  346. =head4 render_glyph_blended
  347. my $surface = SDL::TTF::render_glyph_blended($font, $char, $color);
  348. Render the unicode encoded char onto a new surface. After that you can blit this surface to your display-surface.
  349. B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
  350. =head4 render_text_blended
  351. my $surface = SDL::TTF::render_text_blended($font, $text, $color);
  352. Render the LATIN1 encoded text onto a new surface. After that you can blit this surface to your display-surface.
  353. Example:
  354. use SDL;
  355. use SDL::Video;
  356. use SDL::Color;
  357. use SDL::TTF;
  358. use SDL::TTF::Font;
  359. SDL::init(SDL_INIT_VIDEO);
  360. SDL::TTF::init();
  361. my $display = SDL::Video::set_video_mode(640, 480, 32, SDL_SWSURFACE);
  362. my $font = SDL::TTF::open_font('arial.ttf', '24');
  363. my $surface = SDL::TTF::render_text_blended($font, 'Hello!', SDL::Color->new(0xFF,0xFF,0xFF));
  364. SDL::Video::blit_surface($surface, SDL::Rect->new(0, 0, 640, 480), $display, SDL::Rect->new(10, 10, 640, 480));
  365. SDL::Video::update_rect($display, 0, 0, 0, 0);
  366. SDL::delay(5000);
  367. =head4 render_utf8_blended
  368. my $surface = SDL::TTF::render_utf8_blended($font, $text, $color);
  369. Render the UTF8 encoded text onto a new surface. After that you can blit this surface to your display-surface.
  370. =head4 render_unicode_blended
  371. my $surface = SDL::TTF::render_unicode_blended($font, $text, $color);
  372. Render the unicode encoded text onto a new surface. After that you can blit this surface to your display-surface.
  373. B<Note>: The unicode char has to be passed exactly like for L<SDL::TTF::size_unicode|SDL::TTF/"size_unicode">.
  374. =head1 AUTHORS
  375. See L<SDL/AUTHORS>.
  376. =head1 SEE ALSO
  377. L<SDL::TTF::Font>, L<Unicode::String>, L<SDL::Video>, L<SDL::Surface>
  378. =cut