2006-07-18 David Gilbert <david.gilbert@object-refinery.com>

	* java/awt/image/WritableRaster.java: Added API docs and reformatted
	source code.
----------------------------------------------------------------------

2 files changed, 261 insertions, 90 deletions

diff --git a/ChangeLog b/ChangeLog
index 9f4e62530..1b2dd40bd 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,8 @@
+2006-07-18  David Gilbert  <david.gilbert@object-refinery.com>
+
+	* java/awt/image/WritableRaster.java: Added API docs and reformatted 
+	source code.
+
 2006-07-18  Sven de Marothy  <sven@physto.se>
 
 	* java/net/Inet6Address.java:
diff --git a/java/awt/image/WritableRaster.java b/java/awt/image/WritableRaster.java
index 2e5462fd9..473c6fe41 100644
--- a/java/awt/image/WritableRaster.java
+++ b/java/awt/image/WritableRaster.java
@@ -1,4 +1,4 @@
-/* Copyright (C) 2000, 2002, 2003  Free Software Foundation
+/* Copyright (C) 2000, 2002, 2003, 2006,  Free Software Foundation
 
 This file is part of GNU Classpath.
 
@@ -41,61 +41,98 @@ import java.awt.Point;
 import java.awt.Rectangle;
 
 /**
+ * A raster with methods to support updating pixel values.
+ * 
  * @author Rolf W. Rasmussen (rolfwr@ii.uib.no)
  */
 public class WritableRaster extends Raster
 {
+  /**
+   * Creates a new <code>WritableRaster</code>.
+   * 
+   * @param sampleModel  the sample model.
+   * @param origin  the origin.
+   */
   protected WritableRaster(SampleModel sampleModel, Point origin) 
   {
     this(sampleModel, sampleModel.createDataBuffer(), origin);
   }
   
-  protected WritableRaster(SampleModel sampleModel,
-			   DataBuffer dataBuffer, Point origin)
+  /**
+   * Creates a new <code>WritableRaster</code> instance.
+   * 
+   * @param sampleModel  the sample model.
+   * @param dataBuffer  the data buffer.
+   * @param origin  the origin.
+   */
+  protected WritableRaster(SampleModel sampleModel, DataBuffer dataBuffer, 
+                           Point origin)
   {
     this(sampleModel, dataBuffer,
-	 new Rectangle(origin != null ? origin.x : 0,
+         new Rectangle(origin != null ? origin.x : 0,
                        origin != null ? origin.y : 0,
-		       sampleModel.getWidth(), sampleModel.getHeight()),
-	 origin,
-	 null);
+                       sampleModel.getWidth(), sampleModel.getHeight()),
+         origin, null);
   }
 
+  /**
+   * Creates a new <code>WritableRaster</code> instance.
+   * 
+   * @param sampleModel  the sample model.
+   * @param dataBuffer  the data buffer.
+   * @param aRegion  the raster's bounds.
+   * @param sampleModelTranslate  the translation.
+   * @param parent  the parent.
+   */
   protected WritableRaster(SampleModel sampleModel, 
-			   DataBuffer dataBuffer,
-			   Rectangle aRegion,
-			   Point sampleModelTranslate,
-			   WritableRaster parent)
+                           DataBuffer dataBuffer,
+                           Rectangle aRegion,
+                           Point sampleModelTranslate,
+                           WritableRaster parent)
   {
-    super(sampleModel, dataBuffer, aRegion, sampleModelTranslate,
-	  parent);
+    super(sampleModel, dataBuffer, aRegion, sampleModelTranslate, parent);
   }
 
+  /**
+   * Returns the raster's parent, cast as a {@link WritableRaster}.
+   * 
+   * @return The raster's parent.
+   */
   public WritableRaster getWritableParent()
   {
     return (WritableRaster) getParent();
   }
   
+  /**
+   * @param childMinX
+   * @param childMinY
+   * @return
+   */
   public WritableRaster createWritableTranslatedChild(int childMinX,
-						      int childMinY)
+                                                      int childMinY)
   {
     // This mirrors the code from the super class
     int tcx = sampleModelTranslateX - minX + childMinX;
     int tcy = sampleModelTranslateY - minY + childMinY;
     
     return new WritableRaster(sampleModel, dataBuffer,
-			      new Rectangle(childMinX, childMinY,
-					    width, height),
-			      new Point(tcx, tcy),
-			      this);
+        new Rectangle(childMinX, childMinY, width, height), 
+        new Point(tcx, tcy), this);
   }
 
-  public WritableRaster createWritableChild(int parentX,
-					    int parentY,
-					    int w, int h,
-					    int childMinX,
-					    int childMinY,
-					    int[] bandList)
+  /**
+   * 
+   * @param parentX
+   * @param parentY
+   * @param w
+   * @param h
+   * @param childMinX
+   * @param childMinY
+   * @param bandList
+   * @return
+   */
+  public WritableRaster createWritableChild(int parentX, int parentY,
+      int w, int h, int childMinX, int childMinY, int[] bandList)
   {
     // This mirrors the code from the super class
     
@@ -106,51 +143,52 @@ public class WritableRaster extends Raster
       sampleModel :
       sampleModel.createSubsetSampleModel(bandList);
     
-    return new
-      WritableRaster(sm, dataBuffer,
-		     new Rectangle(childMinX, childMinY,
-				   w, h),
-		     new Point(sampleModelTranslateX+childMinX-parentX,
-			       sampleModelTranslateY+childMinY-parentY),
-		     this);
+    return new WritableRaster(sm, dataBuffer,
+        new Rectangle(childMinX, childMinY, w, h),
+        new Point(sampleModelTranslateX + childMinX - parentX,
+                  sampleModelTranslateY + childMinY - parentY),
+        this);
   }
 
   public void setDataElements(int x, int y, Object inData)
   {
-    sampleModel.setDataElements(x-sampleModelTranslateX,
-				y-sampleModelTranslateY,
-				inData, dataBuffer);
+    sampleModel.setDataElements(x - sampleModelTranslateX, 
+        y - sampleModelTranslateY, inData, dataBuffer);
   }
 
   public void setDataElements(int x, int y, Raster inRaster)
   {
-    Object dataElements = getDataElements(0, 0,
-					  inRaster.getWidth(),
-					  inRaster.getHeight(),
-					  null);
+    Object dataElements = getDataElements(0, 0, inRaster.getWidth(),
+        inRaster.getHeight(), null);
     setDataElements(x, y, dataElements);
   }
 
-  public void setDataElements(int x, int y, int w, int h,
-			      Object inData)
+  public void setDataElements(int x, int y, int w, int h, Object inData)
   {
-    sampleModel.setDataElements(x-sampleModelTranslateX,
-				y-sampleModelTranslateY,
-				w, h, inData, dataBuffer);
+    sampleModel.setDataElements(x - sampleModelTranslateX,
+        y - sampleModelTranslateY, w, h, inData, dataBuffer);
   }
 
+  /**
+   * 
+   * @param srcRaster
+   */
   public void setRect(Raster srcRaster)
   {
     setRect(0, 0, srcRaster);
   }
 
+  /**
+   * 
+   * @param dx
+   * @param dy
+   * @param srcRaster
+   */
   public void setRect(int dx, int dy, Raster srcRaster) 
   {
-    Rectangle targetUnclipped = new Rectangle(srcRaster.getMinX()+dx,
-					      srcRaster.getMinY()+dy,
-					      srcRaster.getWidth(),
-					      srcRaster.getHeight());
-	
+    Rectangle targetUnclipped = new Rectangle(srcRaster.getMinX() + dx,
+        srcRaster.getMinY() + dy, srcRaster.getWidth(), srcRaster.getHeight());
+        
     Rectangle target = getBounds().intersection(targetUnclipped);
 
     if (target.isEmpty()) return;
@@ -169,97 +207,225 @@ public class WritableRaster extends Raster
        But this is probably not the place to consider such
        optimizations.*/
 
-    int[] pixels = srcRaster.getPixels(sx, sy,
-				       target.width, target.height,
-				       (int[]) null);
+    int[] pixels = srcRaster.getPixels(sx, sy, target.width, target.height,
+                                       (int[]) null);
 
     setPixels(target.x, target.y, target.width, target.height, pixels);
   }
 
+  /**
+   * Sets the samples for the pixel at (x, y) in the raster to the specified 
+   * values. 
+   * 
+   * @param x  the x-coordinate of the pixel.
+   * @param y  the y-coordinate of the pixel.
+   * @param iArray  the sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>iArray</code> is <code>null</code>.
+   */
   public void setPixel(int x, int y, int[] iArray)
   {
-    sampleModel.setPixel(x-sampleModelTranslateX,
-			 y-sampleModelTranslateY,
-			 iArray, dataBuffer);
+    sampleModel.setPixel(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                         iArray, dataBuffer);
   }
 
+  /**
+   * Sets the samples for the pixel at (x, y) in the raster to the specified 
+   * values. 
+   * 
+   * @param x  the x-coordinate of the pixel.
+   * @param y  the y-coordinate of the pixel.
+   * @param fArray  the sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>fArray</code> is <code>null</code>.
+   */
   public void setPixel(int x, int y, float[] fArray)
   {
-    sampleModel.setPixel(x-sampleModelTranslateX,
-			 y-sampleModelTranslateY,
-			 fArray, dataBuffer);
+    sampleModel.setPixel(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                         fArray, dataBuffer);
   }
 
+  /**
+   * Sets the samples for the pixel at (x, y) in the raster to the specified 
+   * values. 
+   * 
+   * @param x  the x-coordinate of the pixel.
+   * @param y  the y-coordinate of the pixel.
+   * @param dArray  the sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>dArray</code> is <code>null</code>.
+   */
   public void setPixel(int x, int y, double[] dArray)
   {
-    sampleModel.setPixel(x-sampleModelTranslateX,
-			 y-sampleModelTranslateY,
-			 dArray, dataBuffer);
+    sampleModel.setPixel(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                         dArray, dataBuffer);
   }
 
+  /**
+   * Sets the sample values for the pixels in the region specified by 
+   * (x, y, w, h) in the raster.  The array is ordered by pixels (that is, all 
+   * the samples for the first pixel are grouped together, followed by all the 
+   * samples for the second pixel, and so on). 
+   *  
+   * @param x  the x-coordinate of the top-left pixel.
+   * @param y  the y-coordinate of the top-left pixel.
+   * @param w  the width of the region of pixels.
+   * @param h  the height of the region of pixels.
+   * @param iArray  the pixel sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>iArray</code> is <code>null</code>.
+   */
   public void setPixels(int x, int y, int w, int h, int[] iArray)
   {
-    sampleModel.setPixels(x-sampleModelTranslateX,
-			  y-sampleModelTranslateY,
-			  w, h, iArray, dataBuffer);
+    sampleModel.setPixels(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                          w, h, iArray, dataBuffer);
   }
 
+  /**
+   * Sets the sample values for the pixels in the region specified by 
+   * (x, y, w, h) in the raster.  The array is ordered by pixels (that is, all 
+   * the samples for the first pixel are grouped together, followed by all the 
+   * samples for the second pixel, and so on). 
+   *  
+   * @param x  the x-coordinate of the top-left pixel.
+   * @param y  the y-coordinate of the top-left pixel.
+   * @param w  the width of the region of pixels.
+   * @param h  the height of the region of pixels.
+   * @param fArray  the pixel sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>fArray</code> is <code>null</code>.
+   */
   public void setPixels(int x, int y, int w, int h, float[] fArray)
   {
-    sampleModel.setPixels(x-sampleModelTranslateX,
-			  y-sampleModelTranslateY,
-			  w, h, fArray, dataBuffer);
+    sampleModel.setPixels(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                          w, h, fArray, dataBuffer);
   }
 
+  /**
+   * Sets the sample values for the pixels in the region specified by 
+   * (x, y, w, h) in the raster.  The array is ordered by pixels (that is, all 
+   * the samples for the first pixel are grouped together, followed by all the 
+   * samples for the second pixel, and so on). 
+   *  
+   * @param x  the x-coordinate of the top-left pixel.
+   * @param y  the y-coordinate of the top-left pixel.
+   * @param w  the width of the region of pixels.
+   * @param h  the height of the region of pixels.
+   * @param dArray  the pixel sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>dArray</code> is <code>null</code>.
+   */
   public void setPixels(int x, int y, int w, int h, double[] dArray)
   {
-    sampleModel.setPixels(x-sampleModelTranslateX,
-			  y-sampleModelTranslateY,
-			  w, h, dArray, dataBuffer);
+    sampleModel.setPixels(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                          w, h, dArray, dataBuffer);
   }
 
+  /**
+   * Sets the sample value for a band for the pixel at (x, y) in the raster. 
+   * 
+   * @param x  the x-coordinate of the pixel.
+   * @param y  the y-coordinate of the pixel.
+   * @param b  the band (in the range <code>0</code> to 
+   *     <code>getNumBands() - 1</code>).
+   * @param s  the sample value.
+   */
   public void setSample(int x, int y, int b, int s)
   {
-    sampleModel.setSample(x-sampleModelTranslateX,
-			  y-sampleModelTranslateY,
-			  b, s, dataBuffer);
+    sampleModel.setSample(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                          b, s, dataBuffer);
   }
 
+  /**
+   * Sets the sample value for a band for the pixel at (x, y) in the raster. 
+   * 
+   * @param x  the x-coordinate of the pixel.
+   * @param y  the y-coordinate of the pixel.
+   * @param b  the band (in the range <code>0</code> to 
+   *     <code>getNumBands() - 1</code>).
+   * @param s  the sample value.
+   */
   public void setSample(int x, int y, int b, float s)
   {
-    sampleModel.setSample(x-sampleModelTranslateX,
-			  y-sampleModelTranslateY,
-			  b, s, dataBuffer);
+    sampleModel.setSample(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                          b, s, dataBuffer);
   }
 
+  /**
+   * Sets the sample value for a band for the pixel at (x, y) in the raster. 
+   * 
+   * @param x  the x-coordinate of the pixel.
+   * @param y  the y-coordinate of the pixel.
+   * @param b  the band (in the range <code>0</code> to 
+   *     <code>getNumBands() - 1</code>).
+   * @param s  the sample value.
+   */
   public void setSample(int x, int y, int b, double s)
   {
-    sampleModel.setSample(x-sampleModelTranslateX,
-			  y-sampleModelTranslateY,
-			  b, s, dataBuffer);
+    sampleModel.setSample(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                          b, s, dataBuffer);
   }
 
+  /**
+   * Sets the sample values for one band for the pixels in the region 
+   * specified by (x, y, w, h) in the raster. 
+   * 
+   * @param x  the x-coordinate of the top-left pixel.
+   * @param y  the y-coordinate of the top-left pixel.
+   * @param w  the width of the region of pixels.
+   * @param h  the height of the region of pixels.
+   * @param b  the band (in the range <code>0</code> to 
+   *     </code>getNumBands() - 1</code>).
+   * @param iArray  the sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>iArray</code> is <code>null</code>.
+   */
   public void setSamples(int x, int y, int w, int h, int b,
-			 int[] iArray)
+                         int[] iArray)
   {
-    sampleModel.setSamples(x-sampleModelTranslateX,
-			   y-sampleModelTranslateY,
-			   w, h, b, iArray, dataBuffer);
+    sampleModel.setSamples(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                           w, h, b, iArray, dataBuffer);
   }
 
+  /**
+   * Sets the sample values for one band for the pixels in the region 
+   * specified by (x, y, w, h) in the raster. 
+   * 
+   * @param x  the x-coordinate of the top-left pixel.
+   * @param y  the y-coordinate of the top-left pixel.
+   * @param w  the width of the region of pixels.
+   * @param h  the height of the region of pixels.
+   * @param b  the band (in the range <code>0</code> to 
+   *     </code>getNumBands() - 1</code>).
+   * @param fArray  the sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>fArray</code> is <code>null</code>.
+   */
   public void setSamples(int x, int y, int w, int h, int b,
-			 float[] fArray)
+                         float[] fArray)
   {
-    sampleModel.setSamples(x-sampleModelTranslateX,
-			   y-sampleModelTranslateY,
-			   w, h, b, fArray, dataBuffer);
+    sampleModel.setSamples(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                           w, h, b, fArray, dataBuffer);
   }
 
+  /**
+   * Sets the sample values for one band for the pixels in the region 
+   * specified by (x, y, w, h) in the raster. 
+   * 
+   * @param x  the x-coordinate of the top-left pixel.
+   * @param y  the y-coordinate of the top-left pixel.
+   * @param w  the width of the region of pixels.
+   * @param h  the height of the region of pixels.
+   * @param b  the band (in the range <code>0</code> to 
+   *     </code>getNumBands() - 1</code>).
+   * @param dArray  the sample values (<code>null</code> not permitted).
+   * 
+   * @throws NullPointerException if <code>dArray</code> is <code>null</code>.
+   */
   public void setSamples(int x, int y, int w, int h, int b,
-			 double[] dArray)
+                         double[] dArray)
   {
-    sampleModel.setSamples(x-sampleModelTranslateX,
-			   y-sampleModelTranslateY,
-			   w, h, b, dArray, dataBuffer);
+    sampleModel.setSamples(x - sampleModelTranslateX, y - sampleModelTranslateY,
+                           w, h, b, dArray, dataBuffer);
   }
 }