added text metrics

[sdlgit/SDL-Site.git] / pages / SDL-TTF.html-inc

diff --git a/pages/SDL-TTF.html-inc b/pages/SDL-TTF.html-inc
index 394a88d..709d1d3 100644 (file)
--- a/pages/SDL-TTF.html-inc
+++ b/pages/SDL-TTF.html-inc
@@ -378,7 +378,7 @@ baseline.
 It could be used when drawing an individual glyph relative to a top point, by combining it with the glyph's <code>maxy</code> metric to resolve the top 
 of the rectangle used when blitting the glyph on the screen.</p>
 <p>Example:</p>
-<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, 'M') };
+<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
 
  $rect-&gt;y( $top + SDL::TTF::font_ascent($font) - $maxy );
 
@@ -395,7 +395,7 @@ the font.
 It could be used when drawing an individual glyph relative to a bottom point, by combining it with the glyph's <code>maxy</code> metric to resolve the top 
 of the rectangle used when blitting the glyph on the screen.</p>
 <p>Example:</p>
-<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, 'M') };
+<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
 
  $rect-&gt;y( $bottom - SDL::TTF::font_descent($font) - $maxy );
 
@@ -468,11 +468,29 @@ in the font is the same width, thus you can assume that a rendered string's widt
 </div>
 <h4 id="glyph_is_provided">glyph_is_provided</h4>
 <div id="glyph_is_provided_CONTENT">
+<pre> my $glyph_is_provided = SDL::TTF::glyph_is_provided($font, $unicode_char);
+
+</pre>
+<p>Get the status of the availability of the glyph from the loaded font.</p>
+<p>Returns: the index of the glyph in font, or 0 for an undefined character code.</p>
+<p><strong>Note</strong>: 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.</p>
+<p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
+<p>Example:</p>
+<pre> print(&quot;We have this char!\n&quot;) if SDL::TTF::glyph_is_provided($font, &quot;\0M&quot;);
+
+</pre>
 
 </div>
 <h4 id="glyph_metrics">glyph_metrics</h4>
 <div id="glyph_metrics_CONTENT">
-<pre> my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, 'M') };
+<pre> my @glyph_metrics = @{ SDL::TTF::glyph_metrics($font, $unicode_char) };
+
+</pre>
+<p>Get desired glyph metrics of the UNICODE char from the loaded font.</p>
+<p>See also: <a href="http://freetype.sourceforge.net/freetype2/docs/tutorial/step2.html">The FreeType2 Documentation Tutorial</a></p>
+<p><strong>Note</strong>: 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.</p>
+<p>Example:</p>
+<pre> my ($minx, $maxx, $miny, $maxy, $advance) = @{ SDL::TTF::glyph_metrics($font, &quot;\0M&quot;) };
 
 </pre>
 
@@ -483,23 +501,60 @@ in the font is the same width, thus you can assume that a rendered string's widt
 </div>
 <h4 id="size_text">size_text</h4>
 <div id="size_text_CONTENT">
-<pre> my ($width, $height) = @{ SDL::TTF::size_text($font, 'Hallo World!') };
+<pre> my ($width, $height) = @{ SDL::TTF::size_text($font, $text) };
 
 </pre>
+<p>Calculate the resulting surface size of the LATIN1 encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning 
+is done to get the actual width. The height returned is the same as you can get using <a href="/SDL-TTF.html#font_height">SDL::TTF::font_height</a>.</p>
 
 </div>
 <h4 id="size_utf8">size_utf8</h4>
 <div id="size_utf8_CONTENT">
-<pre> my ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') };
+<pre> my ($width, $height) = @{ SDL::TTF::size_utf8($font, $text) };
+
+</pre>
+<p>Calculate the resulting surface size of the UTF8 encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning is 
+done to get the actual width. The height returned in h is the same as you can get using <a href="/SDL-TTF.html#font_height">SDL::TTF::font_height</a>.</p>
+<p>Note that the first example uses the same text as in the LATIN1 example, that is because plain ASCII is UTF8 compatible.</p>
+<p>Examples:</p>
+<pre> ($width, $height) = @{ SDL::TTF::size_utf8($font, 'Hallo World!') }; # plain text, if your script is in utf8 or ansi-format
+
+ # or
+
+ ($width, $height) = @{ SDL::TTF::size_utf8($font, &quot;\xE4\xBB\x8A\xE6\x97\xA5\xE3\x81\xAF&quot;) }; # utf8 hex-data
+
+ # or
+
+ use Unicode::String;
+ my $unicode       = utf8($data_from_somwhere);
+ ($width, $height) = @{ SDL::TTF::size_utf8($font, $unicode-&gt;utf8) }; # utf8 via Unicode::String
 
 </pre>
 
 </div>
 <h4 id="size_unicode">size_unicode</h4>
 <div id="size_unicode_CONTENT">
-<pre> my ($width, $height) = @{ SDL::TTF::size_unicode($font, 'Hallo World!') };
-
-</pre>
+<pre> my ($width, $height) = @{ SDL::TTF::size_unicode($font, $text) };
+
+</pre>
+<p>Calculate the resulting surface size of the UNICODE encoded text rendered using <code>$font</code>. No actual rendering is done, however correct kerning 
+is done to get the actual width. The height returned in h is the same as you can get using <a href="/SDL-TTF.html#font_height">SDL::TTF::font_height</a>.</p>
+<p><code>$text</code> has to be:</p>
+<dl>
+       <dt>UTF16BE without BOM</dt>
+       <dd>
+               <p>&quot;hallo&quot; will look like &quot;\0h\0a\0l\0l\0o&quot;</p>
+       </dd>
+       <dt>UTF16BE with BOM</dt>
+       <dd>
+               <p>&quot;hallo&quot; will look like &quot;\xFE\xFF\0h\0a\0l\0l\0o&quot;</p>
+       </dd>
+       <dt>UTF16LE with BOM</dt>
+       <dd>
+               <p>&quot;hallo&quot; will look like &quot;\xFF\xFEh\0a\0l\0l\0o\0&quot;</p>
+       </dd>
+</dl>
+<p>You may use Unicode::String for this.</p>
 
 </div>
 <h2 id="Font_Rendering">Font Rendering</h2>