diff options
Diffstat (limited to 'libjava/classpath/java/awt/geom/doc-files/FlatteningPathIterator-1.html')
| -rw-r--r-- | libjava/classpath/java/awt/geom/doc-files/FlatteningPathIterator-1.html | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/libjava/classpath/java/awt/geom/doc-files/FlatteningPathIterator-1.html b/libjava/classpath/java/awt/geom/doc-files/FlatteningPathIterator-1.html new file mode 100644 index 000000000..5a52d693e --- /dev/null +++ b/libjava/classpath/java/awt/geom/doc-files/FlatteningPathIterator-1.html @@ -0,0 +1,481 @@ +<?xml version="1.0" encoding="US-ASCII"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> +<head> + <title>The GNU Implementation of java.awt.geom.FlatteningPathIterator</title> + <meta name="author" content="Sascha Brawer" /> + <style type="text/css"><!-- + td { white-space: nowrap; } + li { margin: 2mm 0; } + --></style> +</head> +<body> + +<h1>The GNU Implementation of FlatteningPathIterator</h1> + +<p><i><a href="http://www.dandelis.ch/people/brawer/">Sascha +Brawer</a>, November 2003</i></p> + +<p>This document describes the GNU implementation of the class +<code>java.awt.geom.FlatteningPathIterator</code>. It does +<em>not</em> describe how a programmer should use this class; please +refer to the generated API documentation for this purpose. Instead, it +is intended for maintenance programmers who want to understand the +implementation, for example because they want to extend the class or +fix a bug.</p> + + +<h2>Data Structures</h2> + +<p>The algorithm uses a stack. Its allocation is delayed to the time +when the source path iterator actually returns the first curved +segment (either <code>SEG_QUADTO</code> or <code>SEG_CUBICTO</code>). +If the input path does not contain any curved segments, the value of +the <code>stack</code> variable stays <code>null</code>. In this quite +common case, the memory consumption is minimal.</p> + +<dl><dt><code>stack</code></dt><dd>The variable <code>stack</code> is +a <code>double</code> array that holds the start, control and end +points of individual sub-segments.</dd> + +<dt><code>recLevel</code></dt><dd>The variable <code>recLevel</code> +holds how many recursive sub-divisions were needed to calculate a +segment. The original curve has recursion level 0. For each +sub-division, the corresponding recursion level is increased by +one.</dd> + +<dt><code>stackSize</code></dt><dd>Finally, the variable +<code>stackSize</code> indicates how many sub-segments are stored on +the stack.</dd></dl> + +<h2>Algorithm</h2> + +<p>The implementation separately processes each segment that the +base iterator returns.</p> + +<p>In the case of <code>SEG_CLOSE</code>, +<code>SEG_MOVETO</code> and <code>SEG_LINETO</code> segments, the +implementation simply hands the segment to the consumer, without actually +doing anything.</p> + +<p>Any <code>SEG_QUADTO</code> and <code>SEG_CUBICTO</code> segments +need to be flattened. Flattening is performed with a fixed-sized +stack, holding the coordinates of subdivided segments. When the base +iterator returns a <code>SEG_QUADTO</code> and +<code>SEG_CUBICTO</code> segments, it is recursively flattened as +follows:</p> + +<ol><li>Intialization: Allocate memory for the stack (unless a +sufficiently large stack has been allocated previously). Push the +original quadratic or cubic curve onto the stack. Mark that segment as +having a <code>recLevel</code> of zero.</li> + +<li>If the stack is empty, flattening the segment is complete, +and the next segment is fetched from the base iterator.</li> + +<li>If the stack is not empty, pop a curve segment from the +stack. + + <ul><li>If its <code>recLevel</code> exceeds the recursion limit, + hand the current segment to the consumer.</li> + + <li>Calculate the squared flatness of the segment. If it smaller + than <code>flatnessSq</code>, hand the current segment to the + consumer.</li> + + <li>Otherwise, split the segment in two halves. Push the right + half onto the stack. Then, push the left half onto the stack. + Continue with step two.</li></ul></li> +</ol> + +<p>The implementation is slightly complicated by the fact that +consumers <em>pull</em> the flattened segments from the +<code>FlatteningPathIterator</code>. This means that we actually +cannot “hand the curent segment over to the consumer.” +But the algorithm is easier to understand if one assumes a +<em>push</em> paradigm.</p> + + +<h2>Example</h2> + +<p>The following example shows how a +<code>FlatteningPathIterator</code> processes a +<code>SEG_QUADTO</code> segment. It is (arbitrarily) assumed that the +recursion limit was set to 2.</p> + +<blockquote> +<table border="1" cellspacing="0" cellpadding="8"> + <tr align="center" valign="baseline"> + <th></th><th>A</th><th>B</th><th>C</th> + <th>D</th><th>E</th><th>F</th><th>G</th><th>H</th> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[0]</code></th> + <td>—</td> + <td>—</td> + <td><i>S<sub>ll</sub>.x</i></td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[1]</code></th> + <td>—</td> + <td>—</td> + <td><i>S<sub>ll</sub>.y</i></td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[2]</code></th> + <td>—</td> + <td>—</td> + <td><i>C<sub>ll</sub>.x</i></td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[3]</code></th> + <td>—</td> + <td>—</td> + <td><i>C<sub>ll</sub>.y</i></td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[4]</code></th> + <td>—</td> + <td><i>S<sub>l</sub>.x</i></td> + <td><i>E<sub>ll</sub>.x</i> + = <i>S<sub>lr</sub>.x</i></td> + <td><i>S<sub>lr</sub>.x</i></td> + <td>—</td> + <td><i>S<sub>rl</sub>.x</i></td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[5]</code></th> + <td>—</td> + <td><i>S<sub>l</sub>.y</i></td> + <td><i>E<sub>ll</sub>.x</i> + = <i>S<sub>lr</sub>.y</i></td> + <td><i>S<sub>lr</sub>.y</i></td> + <td>—</td> + <td><i>S<sub>rl</sub>.y</i></td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[6]</code></th> + <td>—</td> + <td><i>C<sub>l</sub>.x</i></td> + <td><i>C<sub>lr</sub>.x</i></td> + <td><i>C<sub>lr</sub>.x</i></td> + <td>—</td> + <td><i>C<sub>rl</sub>.x</i></td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[7]</code></th> + <td>—</td> + <td><i>C<sub>l</sub>.y</i></td> + <td><i>C<sub>lr</sub>.y</i></td> + <td><i>C<sub>lr</sub>.y</i></td> + <td>—</td> + <td><i>C<sub>rl</sub>.y</i></td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[8]</code></th> + <td><i>S.x</i></td> + <td><i>E<sub>l</sub>.x</i> + = <i>S<sub>r</sub>.x</i></td> + <td><i>E<sub>lr</sub>.x</i> + = <i>S<sub>r</sub>.x</i></td> + <td><i>E<sub>lr</sub>.x</i> + = <i>S<sub>r</sub>.x</i></td> + <td><i>S<sub>r</sub>.x</i></td> + <td><i>E<sub>rl</sub>.x</i> + = <i>S<sub>rr</sub>.x</i></td> + <td><i>S<sub>rr</sub>.x</i></td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[9]</code></th> + <td><i>S.y</i></td> + <td><i>E<sub>l</sub>.y</i> + = <i>S<sub>r</sub>.y</i></td> + <td><i>E<sub>lr</sub>.y</i> + = <i>S<sub>r</sub>.y</i></td> + <td><i>E<sub>lr</sub>.y</i> + = <i>S<sub>r</sub>.y</i></td> + <td><i>S<sub>r</sub>.y</i></td> + <td><i>E<sub>rl</sub>.y</i> + = <i>S<sub>rr</sub>.y</i></td> + <td><i>S<sub>rr</sub>.y</i></td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[10]</code></th> + <td><i>C.x</i></td> + <td><i>C<sub>r</sub>.x</i></td> + <td><i>C<sub>r</sub>.x</i></td> + <td><i>C<sub>r</sub>.x</i></td> + <td><i>C<sub>r</sub>.x</i></td> + <td><i>C<sub>rr</sub>.x</i></td> + <td><i>C<sub>rr</sub>.x</i></td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[11]</code></th> + <td><i>C.y</i></td> + <td><i>C<sub>r</sub>.y</i></td> + <td><i>C<sub>r</sub>.y</i></td> + <td><i>C<sub>r</sub>.y</i></td> + <td><i>C<sub>r</sub>.y</i></td> + <td><i>C<sub>rr</sub>.y</i></td> + <td><i>C<sub>rr</sub>.y</i></td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[12]</code></th> + <td><i>E.x</i></td> + <td><i>E<sub>r</sub>.x</i></td> + <td><i>E<sub>r</sub>.x</i></td> + <td><i>E<sub>r</sub>.x</i></td> + <td><i>E<sub>r</sub>.x</i></td> + <td><i>E<sub>rr</sub>.x</i></td> + <td><i>E<sub>rr</sub>.x</i></td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stack[13]</code></th> + <td><i>E.y</i></td> + <td><i>E<sub>r</sub>.y</i></td> + <td><i>E<sub>r</sub>.y</i></td> + <td><i>E<sub>r</sub>.y</i></td> + <td><i>E<sub>r</sub>.y</i></td> + <td><i>E<sub>rr</sub>.y</i></td> + <td><i>E<sub>rr</sub>.x</i></td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>stackSize</code></th> + <td>1</td> + <td>2</td> + <td>3</td> + <td>2</td> + <td>1</td> + <td>2</td> + <td>1</td> + <td>0</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>recLevel[2]</code></th> + <td>—</td> + <td>—</td> + <td>2</td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>recLevel[1]</code></th> + <td>—</td> + <td>1</td> + <td>2</td> + <td>2</td> + <td>—</td> + <td>2</td> + <td>—</td> + <td>—</td> + </tr> + <tr align="center" valign="baseline"> + <th><code>recLevel[0]</code></th> + <td>0</td> + <td>1</td> + <td>1</td> + <td>1</td> + <td>1</td> + <td>2</td> + <td>2</td> + <td>—</td> + </tr> + </table> +</blockquote> + +<ol> + +<li>The data structures are initialized as follows. + +<ul><li>The segment’s end point <i>E</i>, control point +<i>C</i>, and start point <i>S</i> are pushed onto the stack.</li> + + <li>Currently, the curve in the stack would be approximated by one + single straight line segment (<i>S</i> – <i>E</i>). + Therefore, <code>stackSize</code> is set to 1.</li> + + <li>This single straight line segment is approximating the original + curve, which can be seen as the result of zero recursive + splits. Therefore, <code>recLevel[0]</code> is set to + zero.</li></ul> + +Column A shows the state after the initialization step.</li> + +<li>The algorithm proceeds by taking the topmost curve segment +(<i>S</i> – <i>C</i> – <i>E</i>) from the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[0]</code>) is zero, which is smaller than + the limit 2.</li> + + <li>The method <code>java.awt.geom.QuadCurve2D.getFlatnessSq</code> + is called to calculate the squared flatness.</li> + + <li>For the sake of argument, we assume that the squared flatness is + exceeding the threshold stored in <code>flatnessSq</code>. Thus, the + curve segment <i>S</i> – <i>C</i> – <i>E</i> gets + subdivided into a left and a right half, namely + <i>S<sub>l</sub></i> – <i>C<sub>l</sub></i> – + <i>E<sub>l</sub></i> and <i>S<sub>r</sub></i> – + <i>C<sub>r</sub></i> – <i>E<sub>r</sub></i>. Both halves are + pushed onto the stack, so the left half is now on top. + + <br /> <br />The left half starts at the same point + as the original curve, so <i>S<sub>l</sub></i> has the same + coordinates as <i>S</i>. Similarly, the end point of the right + half and of the original curve are identical + (<i>E<sub>r</sub></i> = <i>E</i>). More interestingly, the left + half ends where the right half starts. Because + <i>E<sub>l</sub></i> = <i>S<sub>r</sub></i>, their coordinates need + to be stored only once, which amounts to saving 16 bytes (two + <code>double</code> values) for each iteration.</li></ul> + +Column B shows the state after the first iteration.</li> + +<li>Again, the topmost curve segment (<i>S<sub>l</sub></i> +– <i>C<sub>l</sub></i> – <i>E<sub>l</sub></i>) is +taken from the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[1]</code>) is 1, which is smaller than + the limit 2.</li> + + <li>The method <code>java.awt.geom.QuadCurve2D.getFlatnessSq</code> + is called to calculate the squared flatness.</li> + + <li>Assuming that the segment is still not considered + flat enough, it gets subdivided into a left + (<i>S<sub>ll</sub></i> – <i>C<sub>ll</sub></i> – + <i>E<sub>ll</sub></i>) and a right (<i>S<sub>lr</sub></i> + – <i>C<sub>lr</sub></i> – <i>E<sub>lr</sub></i>) + half.</li></ul> + +Column C shows the state after the second iteration.</li> + +<li>The topmost curve segment (<i>S<sub>ll</sub></i> – +<i>C<sub>ll</sub></i> – <i>E<sub>ll</sub></i>) is popped from +the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[2]</code>) is 2, which is <em>not</em> smaller than + the limit 2. Therefore, a <code>SEG_LINETO</code> (from + <i>S<sub>ll</sub></i> to <i>E<sub>ll</sub></i>) is passed to the + consumer.</li></ul> + + The new state is shown in column D.</li> + + +<li>The topmost curve segment (<i>S<sub>lr</sub></i> – +<i>C<sub>lr</sub></i> – <i>E<sub>lr</sub></i>) is popped from +the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[1]</code>) is 2, which is <em>not</em> smaller than + the limit 2. Therefore, a <code>SEG_LINETO</code> (from + <i>S<sub>lr</sub></i> to <i>E<sub>lr</sub></i>) is passed to the + consumer.</li></ul> + + The new state is shown in column E.</li> + +<li>The algorithm proceeds by taking the topmost curve segment +(<i>S<sub>r</sub></i> – <i>C<sub>r</sub></i> – +<i>E<sub>r</sub></i>) from the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[0]</code>) is 1, which is smaller than + the limit 2.</li> + + <li>The method <code>java.awt.geom.QuadCurve2D.getFlatnessSq</code> + is called to calculate the squared flatness.</li> + + <li>For the sake of argument, we again assume that the squared + flatness is exceeding the threshold stored in + <code>flatnessSq</code>. Thus, the curve segment + (<i>S<sub>r</sub></i> – <i>C<sub>r</sub></i> – + <i>E<sub>r</sub></i>) is subdivided into a left and a right half, + namely + <i>S<sub>rl</sub></i> – <i>C<sub>rl</sub></i> – + <i>E<sub>rl</sub></i> and <i>S<sub>rr</sub></i> – + <i>C<sub>rr</sub></i> – <i>E<sub>rr</sub></i>. Both halves + are pushed onto the stack.</li></ul> + + The new state is shown in column F.</li> + +<li>The topmost curve segment (<i>S<sub>rl</sub></i> – +<i>C<sub>rl</sub></i> – <i>E<sub>rl</sub></i>) is popped from +the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[2]</code>) is 2, which is <em>not</em> smaller than + the limit 2. Therefore, a <code>SEG_LINETO</code> (from + <i>S<sub>rl</sub></i> to <i>E<sub>rl</sub></i>) is passed to the + consumer.</li></ul> + + The new state is shown in column G.</li> + +<li>The topmost curve segment (<i>S<sub>rr</sub></i> – +<i>C<sub>rr</sub></i> – <i>E<sub>rr</sub></i>) is popped from +the stack. + + <ul><li>The recursion level of this segment (stored in + <code>recLevel[2]</code>) is 2, which is <em>not</em> smaller than + the limit 2. Therefore, a <code>SEG_LINETO</code> (from + <i>S<sub>rr</sub></i> to <i>E<sub>rr</sub></i>) is passed to the + consumer.</li></ul> + + The new state is shown in column H.</li> + +<li>The stack is now empty. The FlatteningPathIterator will fetch the +next segment from the base iterator, and process it.</li> + +</ol> + +<p>In order to split the most recently pushed segment, the +<code>subdivideQuadratic()</code> method passes <code>stack</code> +directly to +<code>QuadCurve2D.subdivide(double[],int,double[],int,double[],int)</code>. +Because the stack grows towards the beginning of the array, no data +needs to be copied around: <code>subdivide</code> will directly store +the result into the stack, which will have the contents shown to the +right.</p> + +</body> +</html> |