1 /*
   2  * Copyright (c) 1998, 1999, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package sun.java2d.pipe;
  27 
  28 /**
  29  * This interface defines a general method for iterating through the
  30  * rectangular "spans" that represent the interior of a filled path.
  31  * <p>
  32  * There can be many kinds of span iterators used in the rendering
  33  * pipeline, the most basic being an iterator that scan converts a
  34  * path defined by any PathIterator, or an nested iterator which
  35  * intersects another iterator's spans with a clip region.
  36  * Other iterators can be created for scan converting some of the
  37  * primitive shapes more explicitly for speed or quality.
  38  *
  39  * @author Jim Graham
  40  */
  41 public interface SpanIterator {
  42     /**
  43      * This method returns the bounding box of the spans that the
  44      * iterator will be returning.
  45      * The array must be of length at least 4 and upon return, it
  46      * will be filled with the values:
  47      * <pre>
  48      *     {PathMinX, PathMinY, PathMaxX, PathMaxY}.
  49      * </pre>
  50      */
  51     public void getPathBox(int pathbox[]);
  52 
  53     /**
  54      * This method constrains the spans returned by nextSpan() to the
  55      * rectangle whose bounds are given.
  56      */
  57     public void intersectClipBox(int lox, int loy, int hix, int hiy);
  58 
  59     /**
  60      * This method returns the next span in the shape being iterated.
  61      * The array must be of length at least 4 and upon return, it
  62      * will be filled with the values:
  63      * <pre>
  64      *     {SpanMinX, SpanMinY, SpanMaxX, SpanMaxY}.
  65      * </pre>
  66      */
  67     public boolean nextSpan(int spanbox[]);
  68 
  69     /**
  70      * This method tells the iterator that it may skip all spans
  71      * whose Y range is completely above the indicated Y coordinate.
  72      * This method is used to provide feedback from the caller when
  73      * clipping prevents the display of any data in a given Y range.
  74      * Typically it will only be called when this iterator has returned
  75      * a span whose MaxY coordinate is less than the indicated Y and
  76      * the calling mechanism wants to avoid unnecessary iteration work.
  77      * While this request could technically be ignored (i.e. a NOP),
  78      * doing so could potentially cause the caller to make this callback
  79      * for each span that is being skipped.
  80      */
  81     public void skipDownTo(int y);
  82 
  83     /**
  84      * This method returns a native pointer to a function block that
  85      * can be used by a native method to perform the same iteration
  86      * cycle that the above methods provide while avoiding upcalls to
  87      * the Java object.
  88      * The definition of the structure whose pointer is returned by
  89      * this method is defined in:
  90      * <pre>
  91      *     src/share/native/sun/java2d/pipe/SpanIterator.h
  92      * </pre>
  93      */
  94     public long getNativeIterator();
  95 }