Home » openjdk-7 » java » awt » image » [javadoc | source]

    1   /*
    2    * Copyright (c) 1997, 2008, 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   /* ****************************************************************
   27    ******************************************************************
   28    ******************************************************************
   29    *** COPYRIGHT (c) Eastman Kodak Company, 1997
   30    *** As  an unpublished  work pursuant to Title 17 of the United
   31    *** States Code.  All rights reserved.
   32    ******************************************************************
   33    ******************************************************************
   34    ******************************************************************/
   35   
   36   package java.awt.image;
   37   import java.awt.Point;
   38   
   39   /**
   40    * WriteableRenderedImage is a common interface for objects which
   41    * contain or can produce image data in the form of Rasters and
   42    * which can be modified and/or written over.  The image
   43    * data may be stored/produced as a single tile or a regular array
   44    * of tiles.
   45    * <p>
   46    * WritableRenderedImage provides notification to other interested
   47    * objects when a tile is checked out for writing (via the
   48    * getWritableTile method) and when the last writer of a particular
   49    * tile relinquishes its access (via a call to releaseWritableTile).
   50    * Additionally, it allows any caller to determine whether any tiles
   51    * are currently checked out (via hasTileWriters), and to obtain a
   52    * list of such tiles (via getWritableTileIndices, in the form of a Vector
   53    * of Point objects).
   54    * <p>
   55    * Objects wishing to be notified of changes in tile writability must
   56    * implement the TileObserver interface, and are added by a
   57    * call to addTileObserver.  Multiple calls to
   58    * addTileObserver for the same object will result in multiple
   59    * notifications.  An existing observer may reduce its notifications
   60    * by calling removeTileObserver; if the observer had no
   61    * notifications the operation is a no-op.
   62    * <p>
   63    * It is necessary for a WritableRenderedImage to ensure that
   64    * notifications occur only when the first writer acquires a tile and
   65    * the last writer releases it.
   66    *
   67    */
   68   
   69   public interface WritableRenderedImage extends RenderedImage
   70   {
   71   
   72     /**
   73      * Adds an observer.  If the observer is already present,
   74      * it will receive multiple notifications.
   75      * @param to the specified <code>TileObserver</code>
   76      */
   77     public void addTileObserver(TileObserver to);
   78   
   79     /**
   80      * Removes an observer.  If the observer was not registered,
   81      * nothing happens.  If the observer was registered for multiple
   82      * notifications, it will now be registered for one fewer.
   83      * @param to the specified <code>TileObserver</code>
   84      */
   85     public void removeTileObserver(TileObserver to);
   86   
   87     /**
   88      * Checks out a tile for writing.
   89      *
   90      * The WritableRenderedImage is responsible for notifying all
   91      * of its TileObservers when a tile goes from having
   92      * no writers to having one writer.
   93      *
   94      * @param tileX the X index of the tile.
   95      * @param tileY the Y index of the tile.
   96      * @return a writable tile.
   97      */
   98     public WritableRaster getWritableTile(int tileX, int tileY);
   99   
  100     /**
  101      * Relinquishes the right to write to a tile.  If the caller
  102      * continues to write to the tile, the results are undefined.
  103      * Calls to this method should only appear in matching pairs
  104      * with calls to getWritableTile; any other use will lead
  105      * to undefined results.
  106      *
  107      * The WritableRenderedImage is responsible for notifying all of
  108      * its TileObservers when a tile goes from having one writer
  109      * to having no writers.
  110      *
  111      * @param tileX the X index of the tile.
  112      * @param tileY the Y index of the tile.
  113      */
  114     public void releaseWritableTile(int tileX, int tileY);
  115   
  116     /**
  117      * Returns whether a tile is currently checked out for writing.
  118      *
  119      * @param tileX the X index of the tile.
  120      * @param tileY the Y index of the tile.
  121      * @return <code>true</code> if specified tile is checked out
  122      *         for writing; <code>false</code> otherwise.
  123      */
  124     public boolean isTileWritable(int tileX, int tileY);
  125   
  126     /**
  127      * Returns an array of Point objects indicating which tiles
  128      * are checked out for writing.  Returns null if none are
  129      * checked out.
  130      * @return an array containing the locations of tiles that are
  131      *         checked out for writing.
  132      */
  133     public Point[] getWritableTileIndices();
  134   
  135     /**
  136      * Returns whether any tile is checked out for writing.
  137      * Semantically equivalent to (getWritableTileIndices() != null).
  138      * @return <code>true</code> if any tiles are checked out for
  139      *         writing; <code>false</code> otherwise.
  140      */
  141     public boolean hasTileWriters();
  142   
  143     /**
  144      * Sets a rect of the image to the contents of the Raster r, which is
  145      * assumed to be in the same coordinate space as the WritableRenderedImage.
  146      * The operation is clipped to the bounds of the WritableRenderedImage.
  147      * @param r the specified <code>Raster</code>
  148      */
  149     public void setData(Raster r);
  150   
  151   }

Home » openjdk-7 » java » awt » image » [javadoc | source]