| <?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> |
