<xml>
<head>
<title>Font Resources</title>
</head>
<body>

<h3>Resource options</h3>

<p>Each font <i>can</i> have the following properties:</p>

<pre>
&lt;font
	name="my_font"
	width_offset="offset"
	height_offset="offset"
	delims="delimiters"&gt;
	
	&lt;system
		font_name="facename"
		height="height_in_pixels"
		width="width_in_pixels"
		bold="[0,1]"
		italic="[0,1]"
		underline="[0,1]"
		strikeout="[0,1]"
		letters="abcdefghijkl..." /&gt;
	
	&lt;bitmap
		glyphs="sprite_resource_id"
		letters="abcdefghijkl..."
		spacelen="pixel_width_of_space"
		monospace="[0,1]" /&gt;

&lt;/font&gt;
</pre>

<p>To setup a font resource, it is required to specify the <i>name</i>
attribute of &lt;font&gt; and at least the required attributes for either a
&lt;system&gt; font or a &lt;bitmap&gt; font. The required attributes for
the system fonts are <i>font_name</i> and <i>height</i>.
Required attributes for bitmap fonts are <i>glyphs</i>, <i>letters</i> and
<i>spacelen</i>.</p>

<h3>Using &lt;system&gt; fonts</h3>

<p>System fonts are generated by the local font system, typically Windows or
X11. For performance reasons, the system font is converted into a bitmap
font internally in ClanLib, which means it can save texture memory if it is
specified more exactly what letters will be used in the font. Aside from
that the only limitations are that the font specified by the
<i>font_name</i> attribute must be available on the system. If it is not
the underlying window system will pick another font, based on criterias that
are platform specific.</p>

<p>For system fonts only the <i>font_name</i> and <i>height</i> (specified
in pixels) needs to be specified. The remaining flag attributes are
optional. If the <i>letters</i> attribute, which specifies characters
should be included when creating the bitmap glyphs, is not specified then it
will include the default characters in the range 32-128. It is highly
adviced to specify the letters as this can save a lot of memory the bigger
the font is.</p>

<h3>Using &lt;bitmap&gt; fonts</h3>

<p>Bitmap fonts are built using a sprite resource. The attributes in the
&lt;bitmap&gt; element specify what sprite resource contains the glyphs
(a glyph is the image of a character) to be used in the font. The sprite
resource is then used together with the <i>letters</i> attribute to link
each frame from the sprite resource to the corresponding glyph character in
the font.</p>

<p>To illustrate this, imagine a sprite that contain 10 frames, containing
the letters A, B, C, D, E, 4, 3, 2, 1, 0 in that order. The <i>letters</i>
attribute should then contain the string "ABCDE43210".</p>

<p>Any character printed not present in the font will be replaced by the space
character. The space character gets the width specified by the
<i>spacelen</i> attribute.</p>

<p><i>monospace</i> is an optional attribute that, if set to "1", will cause
all characters to use the <i>spacelen</i> as the width of the character
(instead of using the glyph's bitmap width).</p>

<h3>Font resource options reference</h3>

<p><b>&lt;font&gt;</b></p>

<ul>
<li>Attribute <b>name</b>: Name of resource.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: None, MUST BE PRESENT.
  </p>
</li>
<li>Attribute <b>width_offset</b>: Width offset of the font.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>height_offset</b>: Height offset of the font.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>delims</b>: Delimiter characters.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: " " (space)
  </p>
</li>
</ul>

<p><b>&lt;system&gt;</b></p>

<ul>
<li>Attribute <b>font_name</b>: Font face name.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: None, MUST BE PRESENT.
  </p>
</li>
<li>Attribute <b>height</b>: Font height in pixels.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: None, MUST BE PRESENT.
  </p>
</li>
<li>Attribute <b>width</b>: Font width in pixels.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>bold</b>: Bold flag.
  <p>
  <i>Valid values</i>: "0", "1"<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>italic</b>: Italic flag.
  <p>
  <i>Valid values</i>: "0", "1"<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>underline</b>: Underline flag.
  <p>
  <i>Valid values</i>: "0", "1"<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>strikeout</b>: Strikeout flag.
  <p>
  <i>Valid values</i>: "0", "1"<br>
  <i>Default value</i>: "0"
  </p>
</li>
<li>Attribute <b>letters</b>: Characters to include in font.
  <p>
  <i>Valid values</i>: <br>
  <i>Default value</i>: "abcdefghijklmnopqrstuvwxyz0123456789.." - (generally all chars from 32 to 128)
  </p>
</li>
</ul>

<p><b>&lt;bitmap&gt;</b></p>

<ul>
<li>Attribute <b>glyphs</b>: Sprite resource containing the glyphs (font characters).
  <p>
  <i>Valid values</i>: Any sprite resource<br>
  <i>Default value</i>: None, MUST BE PRESENT.
  </p>
</li>
<li>Attribute <b>letters</b>: Characters to be linked with each sprite frame.
  <p>
  <i>Valid values</i>: "abcdefghi.."<br>
  <i>Default value</i>: None, MUST BE PRESENT.
  </p>
</li>
<li>Attribute <b>spacelen</b>: Width of the space character.
  <p>
  <i>Valid values</i>:<br>
  <i>Default value</i>: None, MUST BE PRESENT.
  </p>
</li>
<li>Attribute <b>monospace</b>: Monospace flag.
  <p>
  <i>Valid values</i>: "0", "1"<br>
  <i>Default value</i>: "0"
  </p>
</li>
</ul>

</body>
</xml>
