/usr/share/doc/xgridfit/html/round.html is in xgridfit-doc 2.3-1.
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 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<title>Xgridfit</title>
<link rel="stylesheet" href="oeg.css" media="screen" type="text/css" />
<link rel="stylesheet" href="parchment.css" media="screen"
type="text/css" title="parchment" />
<link rel="alternate stylesheet" href="legible.css" media="screen"
type="text/css" title="legible" />
<style type="text/css" media="print"> @import "oeg.print.css"; </style>
<meta name="AUTHOR" content="Peter S. Baker" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
</head>
<body>
<div id="jumplist">
<a href="http://sourceforge.net"><img src="" width="125" height="37" border="0" alt="SourceForge.net Logo" /></a>
<a href="http://xgridfit.sourceforge.net/">Home Page</a>
<a href="http://sourceforge.net/projects/xgridfit">Project Page</a>
<a href="http://sourceforge.net/project/showfiles.php?group_id=159705">Download</a>
<a href="http://xgridfit.cvs.sourceforge.net/xgridfit/xgridfit/">CVS repository</a>
<hr/>
</div>
<div id="content">
<h1>Rounding</h1>
<h2>The Round State</h2>
<p><move>, Xgridfit's primary point-moving element, allows you to round
the distance a point is to be positioned from a reference point or
the grid origin. You can also use the <round> element to round
any number that represents a distance:
for example, it is a good idea to round some of the
most commonly used control values in the <pre-program>, and
you can do this very simply:</p>
<pre>
<round value="control-value-id"/>
</pre>
<p>More often than not, you will use rounding to ensure that the point
you are moving lands on a grid line. The kind of rounding
needed for that task is straightforward--a matter of
rounding a fixed-point number to
the nearest integer. But the TrueType engine offers several
kinds of rounding, which Xgridfit labels as follows:</p>
<ul>
<li><b>to-grid:</b> Rounds to the nearest integer</li>
<li><b>to-half-grid:</b> Rounds to the nearest half-number
(for example, 1.45 is rounded to 1.5)</li>
<li><b>to-double-grid:</b> Rounds to an integer or
half-number, whichever is nearer</li>
<li><b>up-to-grid:</b> Always rounds to the higher integer
(for example, 1.1 is rounded to 2.0)</li>
<li><b>down-to-grid:</b> Always rounds to the lower integer
(for example, 1.9 is rounded to 1.0)</li>
</ul>
<p>The kind of rounding performed is determined by the current setting
of the round state. You can change the round state (or turn
off rounding altogether) with the
<set-round-state> or the
<with-round-state> element. You can specify a round
state for a single <move> element by passing one of
the values listed above via the <tt>round</tt> attribute, or
you can use the value "yes" to round
according to the current round state.</p>
<h2 id="custom">Custom Round States</h2>
<p>TrueType's standard round states are sufficient most of the
time; but it is also possible to create custom round-states
by directly controlling the three variables that control
rounding:</p>
<ul>
<li><b>period:</b> the distance between rounded
positions (the default is 1.0)</li>
<li><b>phase:</b> where the rounded positions fall (the
default is 0, meaning that they fall on integer
boundaries)</li>
<li><b>threshold:</b> the point at which the direction of
rounding changes (0.5 by default):
if the number is less than this
the direction of rounding is down; if equal or
greater, the direction is up</li>
</ul>
<p>The available documentation on how rounding works is far from
clear, but the <a
href="http://developer.apple.com/fonts/TTRefMan/RM02/Chap2.html#rounding_operations">Apple
specification</a> offers a useful walk-through of the
rounding operation. If the distance we need to round is
<i>n</i>:</p>
<ol>
<li>add engine compensation to n</li>
<li>subtract the phase from n</li>
<li>add the threshold to n</li>
<li>truncate n to the next lowest periodic value (ignore the
phase)</li>
<li>add the phase back to n</li>
<li>if rounding caused a positive number to become negative,
set n to the positive round value closest to 0</li>
<li>if rounding caused a negative number to become positive,
set n to the negative round value closest to 0</li>
</ol>
<p>Let's walk through a few examples, an easy one first. When the
round state is in its default value ("to-grid"), the period
is one, the phase zero, and the threshold one half of the
period. Suppose that n is 1.3 after "engine compensation"
has been added (a complication which we need not address).</p>
<ol>
<li>subtract phase: 1.3 - 0 = 1.3</li>
<li>add threshold: 1.3 + 0.5 = 1.8</li>
<li>truncate: floor(1.8) = 1.0</li>
<li>add phase: 1.0 + 0 = 1.0</li>
</ol>
<p>Try it with n = 1.6:</p>
<ol>
<li>subtract phase: 1.6 - 0 = 1.6</li>
<li>add threshold: 1.6 + 0.5 = 2.1</li>
<li>truncate: floor(2.1) = 2.0</li>
<li>add phase: 2.0 + 0 = 2.0</li>
</ol>
<p>The round state "to-half-grid" is like "to-grid" but with a phase
of one half of the period. Let's try it with n = 1.6
again:</p>
<ol>
<li>subtract phase: 1.6 - 0.5 = 1.1</li>
<li>add threshold: 1.1 + 0.5 = 1.6</li>
<li>truncate: floor(1.6) = 1.0</li>
<li>add phase: 1.0 + 0.5 = 1.5</li>
</ol>
<p>Now let us concoct a custom round state: period one, phase one
quarter, threshold seven eighths (0.875), and try it with n
= 1.6</p>
<ol>
<li>subtract phase: 1.6 - 0.25 = 1.35</li>
<li>add threshold: 1.35 + 0.875 = 2.225</li>
<li>truncate: floor(2.225) = 2.0</li>
<li>add phase: 2.0 + 0.25 = 2.25</li>
</ol>
<p>Notice that the low threshold has forced the engine to round
upwards even though the distance from 1.6 to the next
rounded point, 2.25, is more than 0.5. Finally, since the
threshold can be negative, let's look at the effect of a
negative threshold. Now our custom round state is period
one, phase 0, threshold minus one eighth (-0.125); and n =
1.1:</p>
<ol>
<li>subtract phase: 1.1 - 0 = 1.1</li>
<li>add threshold: 1.1 - 0.125 = 0.975</li>
<li>truncate: floor(0.975) = 0.0</li>
<li>add phase: 0.0 + 0 = 0.0</li>
</ol>
<p>So a negative threshold <i>can</i> force a number to round to the
rounding-point <i>below</i> the next lowest rounding-point
(though it need not do so--and would not with n = 1.6).</p>
<p>
A custom round state is defined with the
<round-state> element, which can only come in the
top of the Xgridfit file, as a child of
<xgridfit>. Then one can set the round state to this
value simply by passing its name to any element that takes
a <tt>round</tt> attribute.
</p>
<h2>Rounded Numbers and Distance on the Grid</h2>
<p>A number with no fractional part always represents a distance equal
to a multiple of the width or height of one pixel. A point
that is positioned a rounded distance from the grid origin
at 0,0 must always fall on one of the grid lines that runs
between pixels: this is because 0,0 itself is always
positioned on such a grid line. Thus this sequence:</p>
<pre>
<with-vectors axis="y">
<move distance="lc-x-height">
<point num="top"/>
</move>
</with-vectors>
</pre>
<p>will place point "top" on a grid line if the round state is
"to-grid" (the default), for the <move> element uses
rounding by default.</p>
<p>However, rounding "to-grid" with the <move> element <i>does
not</i> guarantee that the point moved lands on a grid line:
that happens only if you plan properly. For example, the
following code</p>
<pre>
<with-vectors axis="y">
<move distance="lc-rnd-horz-stem">
<reference>
<point num="a"/>
</reference>
<point num="b"/>
</move>
</with-vectors>
</pre>
<p>positions point <b>b</b> a rounded distance from point <b>a</b>. If
point <b>a</b> has
not yet been rounded to the grid, you get the undesirable
result on the left. If point <b>a</b> has already been
rounded, you get the much better result on the right.</p>
<table>
<tr><td>
<img alt="point a not rounded" src="o-bottom-unrounded.gif"/>
</td>
<td>
<img alt="point a rounded" src="o-bottom-rounded.gif"/>
</td>
</tr>
</table>
<p>And when the projection vector is not set to the x or the y axis,
rounding generally will not position points on grid lines.
Indeed, it is usually best to turn rounding off when
instructing diagonal stems.</p>
<h2>Instructions Relating to Rounding</h2>
<p>These also include the <a
href="arithmetic.html#round"><round></a> and <a
href="arithmetic.html#no-round"><no-round></a>
elements, described in the chapter on <a
href="arithmetic.html">arithmetic</a>. You should also be
aware of the <a href="expressions.html#op-table">round</a>
operator, used in <a
href="expressions.html">expressions</a>.</p>
<h3><round-state></h3>
<p>
Declares a custom round state whose name can be passed to
<set-round-state>, <with-round-state>, or any
element that takes a <tt>round</tt> attribute. For an
explanation of the <tt>period</tt>, <tt>phase</tt> and
<tt>threshold</tt> attribute, see above. Note that only a
limited number of values is permitted for each of these
attributes. This element is permitted only in top level of
the program, as a child of <xgridfit>.
</p>
<h3><set-round-state><br/>
<with-round-state></h3>
<p>
Sets the round state. If the <tt>round</tt> attribute
matches the name of a <round-state> element, that
round state is used. If not, one of TrueType's
prefabricated round states may be used:
</p>
<ul>
<li>to-grid</li>
<li>to-half-grid</li>
<li>to-double-grid</li>
<li>up-to-grid</li>
<li>down-to-grid</li>
</ul>
<p>If the <tt>round</tt> attribute is not one of these, and not one of the
custom round-states, Xgridfit tries to resolve it as a
number, constant, variable or function parameter and use
that as an argument to SROUND. You had better know what
you're doing if you intend to use a raw number in this way;
it is safer, more intelligible and just as effective to
supply a custom <round-state> element.</p>
<p>The distinction between the element beginning with "set" and the
one beginning with "with" is the same as it is for the <a
href="vectors.html#vect-inst">vector-setting
elements</a>: briefly, the round state set by the
"set" element affects the instructions that follow it; the
round state set by the "with" instruction affects only the
instructions that it contains.</p>
<p>Xgridfit generates instructions that keep track of the round
state (since the TrueType engine provides no way to read
it), but it may lose track if Xgridfit instructions are
not used exclusively.</p>
</div>
</body>
</html>
|