added docs for font 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 95fd772..b14e7da 100644 (file)
--- a/pages/SDL-TTF.html-inc
+++ b/pages/SDL-TTF.html-inc
@@ -28,6 +28,8 @@
 <li><a href="#Font_style">Font style</a>
 <ul><li><a href="#get_font_style">get_font_style</a></li>
 <li><a href="#set_font_style">set_font_style</a></li>
+<li><a href="#get_font_outline">get_font_outline</a></li>
+<li><a href="#set_font_outline">set_font_outline</a></li>
 </ul>
 </li>
 <li><a href="#Font_settings">Font settings</a>
@@ -277,6 +279,24 @@ Still, sometimes the underline or strikethrough may be outside of the generated
 this case, you should probably turn off these styles and draw your own strikethroughs and underlines. </p>
 
 </div>
+<h4 id="get_font_outline">get_font_outline</h4>
+<div id="get_font_outline_CONTENT">
+<pre> my $outline = SDL::TTF::get_font_outline($font);
+
+</pre>
+<p>Get the current outline width of the font, in pixels.</p>
+<p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
+
+</div>
+<h4 id="set_font_outline">set_font_outline</h4>
+<div id="set_font_outline_CONTENT">
+<pre> SDL::TTF::get_font_outline($font, $outline);
+
+</pre>
+<p>Set the outline pixel width of the loaded font. Use <code>0</code>(zero) to turn off outlining.</p>
+<p><strong>Note</strong>: at least SDL_ttf 2.0.10 needed</p>
+
+</div>
 <h3 id="Font_settings">Font settings</h3>
 <div id="Font_settings_CONTENT">
 
@@ -343,12 +363,24 @@ overlapping glyphs or abnormal spacing within words.</p>
 <pre> my $font_height = SDL::TTF::font_height($font);
 
 </pre>
+<p>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 
+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 
+printing, so you are responsible for line spacing, see the <a href="/SDL-TTF.html#font_line_skip">SDL::TTF::font_line_skip</a> as well.</p>
 
 </div>
 <h4 id="font_ascent">font_ascent</h4>
 <div id="font_ascent_CONTENT">
 <pre> my $font_ascent = SDL::TTF::font_ascent($font);
- like( $font_ascent,                                       '/^[-]?\d+$/',       &quot;[font_ascent] offset from the baseline to the top of the font is $font_ascent&quot; );
+
+</pre>
+<p>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 
+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') };
+
+ $rect-&gt;y( $top + SDL::TTF::font_ascent($font) - $maxy );
 
 </pre>
 
@@ -356,7 +388,16 @@ overlapping glyphs or abnormal spacing within words.</p>
 <h4 id="font_descent">font_descent</h4>
 <div id="font_descent_CONTENT">
 <pre> my $font_descent = SDL::TTF::font_descent($font);
- like( $font_descent,                                      '/^[-]?\d+$/',       &quot;[font_descent] offset from the baseline to the bottom of the font is $font_descent&quot; );
+
+</pre>
+<p>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 
+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') };
+
+ $rect-&gt;y( $bottom - SDL::TTF::font_descent($font) - $maxy );
 
 </pre>
 
@@ -364,9 +405,10 @@ overlapping glyphs or abnormal spacing within words.</p>
 <h4 id="font_line_skip">font_line_skip</h4>
 <div id="font_line_skip_CONTENT">
 <pre> my $font_line_skip = SDL::TTF::font_line_skip($font);
- like( $font_line_skip,                                    '/^[-]?\d+$/',       &quot;[font_line_skip] recommended spacing between lines of text is $font_line_skip&quot; );
 
 </pre>
+<p>Get the recommended pixel height of a rendered line of text of the loaded font. This is usually larger than the <a href="/SDL-TTF.html#font_height">SDL::TTF::font_height</a> of the 
+font.</p>
 
 </div>
 <h3 id="Face_attributes">Face attributes</h3>