Source for java.awt.image.DataBuffer

   1: /* Copyright (C) 2000, 2002, 2005  Free Software Foundation
   2: 
   3: This file is part of GNU Classpath.
   4: 
   5: GNU Classpath is free software; you can redistribute it and/or modify
   6: it under the terms of the GNU General Public License as published by
   7: the Free Software Foundation; either version 2, or (at your option)
   8: any later version.
   9: 
  10: GNU Classpath is distributed in the hope that it will be useful, but
  11: WITHOUT ANY WARRANTY; without even the implied warranty of
  12: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13: General Public License for more details.
  14: 
  15: You should have received a copy of the GNU General Public License
  16: along with GNU Classpath; see the file COPYING.  If not, write to the
  17: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  18: 02110-1301 USA.
  19: 
  20: Linking this library statically or dynamically with other modules is
  21: making a combined work based on this library.  Thus, the terms and
  22: conditions of the GNU General Public License cover the whole
  23: combination.
  24: 
  25: As a special exception, the copyright holders of this library give you
  26: permission to link this library with independent modules to produce an
  27: executable, regardless of the license terms of these independent
  28: modules, and to copy and distribute the resulting executable under
  29: terms of your choice, provided that you also meet, for each linked
  30: independent module, the terms and conditions of the license of that
  31: module.  An independent module is a module which is not derived from
  32: or based on this library.  If you modify this library, you may extend
  33: this exception to your version of the library, but you are not
  34: obligated to do so.  If you do not wish to do so, delete this
  35: exception statement from your version. */
  36: 
  37: package java.awt.image;
  38: 
  39: /** 
  40:  * Class that manages arrays of data elements. A data buffer consists
  41:  * of one or more banks.  A bank is a continuous region of data
  42:  * elements.
  43:  *
  44:  * @author Rolf W. Rasmussen (rolfwr@ii.uib.no)
  45:  */
  46: public abstract class DataBuffer
  47: {
  48:   /**
  49:    * A constant representing a data type that uses <code>byte</code> primitives
  50:    * as the storage unit.
  51:    */
  52:   public static final int TYPE_BYTE      =  0;
  53: 
  54:   /**
  55:    * A constant representing a data type that uses <code>short</code> 
  56:    * primitives as the storage unit.
  57:    */
  58:   public static final int TYPE_USHORT    =  1;
  59: 
  60:   /**
  61:    * A constant representing a data type that uses <code>short</code> 
  62:    * primitives as the storage unit.
  63:    */
  64:   public static final int TYPE_SHORT     =  2;
  65: 
  66:   /**
  67:    * A constant representing a data type that uses <code>int</code> 
  68:    * primitives as the storage unit.
  69:    */
  70:   public static final int TYPE_INT       =  3;
  71:   
  72:   /**
  73:    * A constant representing a data type that uses <code>float</code> 
  74:    * primitives as the storage unit.
  75:    */
  76:   public static final int TYPE_FLOAT     =  4;
  77: 
  78:   /**
  79:    * A constant representing a data type that uses <code>double</code> 
  80:    * primitives as the storage unit.
  81:    */
  82:   public static final int TYPE_DOUBLE    =  5;
  83: 
  84:   /**
  85:    * A constant representing an undefined data type.
  86:    */
  87:   public static final int TYPE_UNDEFINED = 32;
  88:   
  89:   /** The type of the data elements stored in the data buffer.  */
  90:   protected int dataType;
  91:   
  92:   /** The number of banks in this buffer.  */
  93:   protected int banks = 1;
  94:   
  95:   /** Offset into the default (0'th) bank). */
  96:   protected int offset; // FIXME: Is offsets[0] always mirrored in offset?
  97:   
  98:   /** The size of the banks.  */
  99:   protected int size;
 100:   
 101:   /** Offset into each bank.  */
 102:   protected int[] offsets;
 103:   
 104:   /**
 105:    * Creates a new <code>DataBuffer</code> with the specified data type and
 106:    * size.  The <code>dataType</code> should be one of the constants 
 107:    * {@link #TYPE_BYTE}, {@link #TYPE_SHORT}, {@link #TYPE_USHORT}, 
 108:    * {@link #TYPE_INT}, {@link #TYPE_FLOAT} and {@link #TYPE_DOUBLE}.
 109:    * <p>
 110:    * The physical (array-based) storage is allocated by a subclass.
 111:    * 
 112:    * @param dataType the data type.
 113:    * @param size the number of elements in the buffer.
 114:    */
 115:   protected DataBuffer(int dataType, int size)
 116:   {
 117:     this.dataType = dataType;
 118:     this.size = size;
 119:   }
 120: 
 121:   /**
 122:    * Creates a new <code>DataBuffer</code> with the specified data type,
 123:    * size and number of banks.  The <code>dataType</code> should be one of 
 124:    * the constants {@link #TYPE_BYTE}, {@link #TYPE_SHORT}, 
 125:    * {@link #TYPE_USHORT}, {@link #TYPE_INT}, {@link #TYPE_FLOAT} and 
 126:    * {@link #TYPE_DOUBLE}.
 127:    * <p>
 128:    * The physical (array-based) storage is allocated by a subclass.
 129:    * 
 130:    * @param dataType the data type.
 131:    * @param size the number of elements in the buffer.
 132:    * @param numBanks the number of data banks.
 133:    */
 134:   protected DataBuffer(int dataType, int size, int numBanks) {
 135:     this(dataType, size);
 136:     banks = numBanks;
 137:     offsets = new int[numBanks];
 138:   }
 139: 
 140:   /**
 141:    * Creates a new <code>DataBuffer</code> with the specified data type,
 142:    * size and number of banks.  An offset (which applies to all banks) is
 143:    * also specified.  The <code>dataType</code> should be one of 
 144:    * the constants {@link #TYPE_BYTE}, {@link #TYPE_SHORT}, 
 145:    * {@link #TYPE_USHORT}, {@link #TYPE_INT}, {@link #TYPE_FLOAT} and 
 146:    * {@link #TYPE_DOUBLE}.
 147:    * <p>
 148:    * The physical (array-based) storage is allocated by a subclass.
 149:    * 
 150:    * @param dataType the data type.
 151:    * @param size the number of elements in the buffer.
 152:    * @param numBanks the number of data banks.
 153:    * @param offset the offset to the first element for all banks.
 154:    */
 155:   protected DataBuffer(int dataType, int size, int numBanks, int offset) {
 156:     this(dataType, size, numBanks);
 157:     
 158:     java.util.Arrays.fill(offsets, offset);          
 159:     
 160:     this.offset = offset;
 161:   }
 162: 
 163:   /**
 164:    * Creates a new <code>DataBuffer</code> with the specified data type,
 165:    * size and number of banks.  An offset (which applies to all banks) is
 166:    * also specified.  The <code>dataType</code> should be one of 
 167:    * the constants {@link #TYPE_BYTE}, {@link #TYPE_SHORT}, 
 168:    * {@link #TYPE_USHORT}, {@link #TYPE_INT}, {@link #TYPE_FLOAT} and 
 169:    * {@link #TYPE_DOUBLE}.
 170:    * <p>
 171:    * The physical (array-based) storage is allocated by a subclass.
 172:    * 
 173:    * @param dataType the data type.
 174:    * @param size the number of elements in the buffer.
 175:    * @param numBanks the number of data banks.
 176:    * @param offsets the offsets to the first element for all banks.
 177:    * 
 178:    * @throws ArrayIndexOutOfBoundsException if 
 179:    *         <code>numBanks != offsets.length</code>.
 180:    */
 181:   protected DataBuffer(int dataType, int size, int numBanks, int[] offsets) {
 182:     this(dataType, size);
 183:     if (numBanks != offsets.length) 
 184:       throw new ArrayIndexOutOfBoundsException();
 185:     
 186:     banks = numBanks;
 187:     this.offsets = offsets;
 188:     
 189:     offset = offsets[0];
 190:   }
 191:   
 192:   /**
 193:    * Returns the size (number of bits) of the specified data type. Valid types
 194:    * are defined by the constants {@link #TYPE_BYTE}, {@link #TYPE_SHORT}, 
 195:    * {@link #TYPE_USHORT}, {@link #TYPE_INT}, {@link #TYPE_FLOAT} and 
 196:    * {@link #TYPE_DOUBLE}.
 197:    * 
 198:    * @param dataType the data type.
 199:    * @return The number of bits for the specified data type.
 200:    * @throws IllegalArgumentException if <code>dataType < 0</code> or 
 201:    *         <code>dataType > TYPE_DOUBLE</code>.
 202:    */
 203:   public static int getDataTypeSize(int dataType) {
 204:     // Maybe this should be a lookup table instead.
 205:     switch (dataType)
 206:       {
 207:       case TYPE_BYTE:
 208:     return 8;
 209:       case TYPE_USHORT:
 210:       case TYPE_SHORT:
 211:     return 16;
 212:       case TYPE_INT:
 213:       case TYPE_FLOAT:
 214:     return 32;
 215:       case TYPE_DOUBLE:
 216:     return 64;
 217:       default:
 218:     throw new IllegalArgumentException();
 219:       }
 220:   }
 221: 
 222:   /**
 223:    * Returns the type of the data elements in the data buffer.  Valid types
 224:    * are defined by the constants {@link #TYPE_BYTE}, {@link #TYPE_SHORT}, 
 225:    * {@link #TYPE_USHORT}, {@link #TYPE_INT}, {@link #TYPE_FLOAT} and 
 226:    * {@link #TYPE_DOUBLE}.
 227:    * 
 228:    * @return The type.
 229:    */
 230:   public int getDataType()
 231:   {
 232:     return dataType;
 233:   }
 234:   
 235:   /**
 236:    * Returns the size of the data buffer.
 237:    * 
 238:    * @return The size.
 239:    */
 240:   public int getSize()
 241:   {
 242:     return size;
 243:   }
 244:   
 245:   /**
 246:    * Returns the element offset for the first data bank.
 247:    * 
 248:    * @return The element offset.
 249:    */
 250:   public int getOffset()
 251:   {
 252:     return offset;
 253:   }
 254:   
 255:   /**
 256:    * Returns the offsets for all the data banks used by this 
 257:    * <code>DataBuffer</code>.
 258:    * 
 259:    * @return The offsets.
 260:    */
 261:   public int[] getOffsets()
 262:   {
 263:     if (offsets == null)
 264:     {
 265:       // is this necessary?
 266:       offsets = new int[1];
 267:       offsets[0] = offset;
 268:     }
 269:     return offsets;
 270:   }
 271: 
 272:   /**
 273:    * Returns the number of data banks for this <code>DataBuffer</code>.
 274:    * @return The number of data banks.
 275:    */
 276:   public int getNumBanks()
 277:   {
 278:     return banks;
 279:   }
 280: 
 281:   /**
 282:    * Returns an element from the first data bank.  The offset (specified in
 283:    * the constructor) is added to <code>i</code> before accessing the 
 284:    * underlying data array.
 285:    * 
 286:    * @param i the element index.
 287:    * @return The element.
 288:    */
 289:   public int getElem(int i)
 290:   {
 291:     return getElem(0, i);
 292:   }
 293: 
 294:   /**
 295:    * Returns an element from a particular data bank.  The offset (specified in
 296:    * the constructor) is added to <code>i</code> before accessing the 
 297:    * underlying data array.
 298:    * 
 299:    * @param bank the bank index.
 300:    * @param i the element index.
 301:    * @return The element.
 302:    */
 303:   public abstract int getElem(int bank, int i);
 304:   
 305:   /**
 306:    * Sets an element in the first data bank.  The offset (specified in the
 307:    * constructor) is added to <code>i</code> before updating the underlying
 308:    * data array.
 309:    * 
 310:    * @param i the element index.
 311:    * @param val the new element value.
 312:    */
 313:   public void setElem(int i, int val)
 314:   {
 315:     setElem(0, i, val);
 316:   }
 317: 
 318:   /**
 319:    * Sets an element in a particular data bank.  The offset (specified in the
 320:    * constructor) is added to <code>i</code> before updating the underlying
 321:    * data array.
 322:    * 
 323:    * @param bank the data bank index.
 324:    * @param i the element index.
 325:    * @param val the new element value.
 326:    */
 327:   public abstract void setElem(int bank, int i, int val);
 328:   
 329:   /**
 330:    * Returns an element from the first data bank, converted to a 
 331:    * <code>float</code>.  The offset (specified in the constructor) is added 
 332:    * to <code>i</code> before accessing the underlying data array.
 333:    * 
 334:    * @param i the element index.
 335:    * @return The element.
 336:    */
 337:   public float getElemFloat(int i)
 338:   {
 339:     return getElem(i);
 340:   }
 341:     
 342:   /**
 343:    * Returns an element from a particular data bank, converted to a 
 344:    * <code>float</code>.  The offset (specified in the constructor) is 
 345:    * added to <code>i</code> before accessing the underlying data array.
 346:    * 
 347:    * @param bank the bank index.
 348:    * @param i the element index.
 349:    * @return The element.
 350:    */
 351:   public float getElemFloat(int bank, int i)
 352:   {
 353:     return getElem(bank, i);
 354:   }
 355: 
 356:   /**
 357:    * Sets an element in the first data bank.  The offset (specified in the
 358:    * constructor) is added to <code>i</code> before updating the underlying
 359:    * data array. 
 360:    * 
 361:    * @param i the element index.
 362:    * @param val the new element value.
 363:    */
 364:   public void setElemFloat(int i, float val)
 365:   {
 366:     setElem(i, (int) val);
 367:   }
 368: 
 369:   /**
 370:    * Sets an element in a particular data bank.  The offset (specified in the
 371:    * constructor) is added to <code>i</code> before updating the underlying
 372:    * data array.
 373:    * 
 374:    * @param bank the data bank index.
 375:    * @param i the element index.
 376:    * @param val the new element value.
 377:    */
 378:   public void setElemFloat(int bank, int i, float val)
 379:   {
 380:     setElem(bank, i, (int) val);
 381:   }
 382: 
 383:   /**
 384:    * Returns an element from the first data bank, converted to a 
 385:    * <code>double</code>.  The offset (specified in the constructor) is added
 386:    * to <code>i</code> before accessing the underlying data array.
 387:    * 
 388:    * @param i the element index.
 389:    * @return The element.
 390:    */
 391:   public double getElemDouble(int i)
 392:   {
 393:     return getElem(i);
 394:   }
 395:     
 396:   /**
 397:    * Returns an element from a particular data bank, converted to a 
 398:    * <code>double</code>.  The offset (specified in the constructor) is 
 399:    * added to <code>i</code> before accessing the underlying data array.
 400:    * 
 401:    * @param bank the bank index.
 402:    * @param i the element index.
 403:    * @return The element.
 404:    */
 405:   public double getElemDouble(int bank, int i)
 406:   {
 407:     return getElem(bank, i);
 408:   }
 409: 
 410:   /**
 411:    * Sets an element in the first data bank.  The offset (specified in the
 412:    * constructor) is added to <code>i</code> before updating the underlying
 413:    * data array. 
 414:    * 
 415:    * @param i the element index.
 416:    * @param val the new element value.
 417:    */
 418:   public void setElemDouble(int i, double val)
 419:   {
 420:     setElem(i, (int) val);
 421:   }
 422: 
 423:   /**
 424:    * Sets an element in a particular data bank.  The offset (specified in the
 425:    * constructor) is added to <code>i</code> before updating the underlying
 426:    * data array.
 427:    * 
 428:    * @param bank the data bank index.
 429:    * @param i the element index.
 430:    * @param val the new element value.
 431:    */
 432:   public void setElemDouble(int bank, int i, double val)
 433:   {
 434:     setElem(bank, i, (int) val);
 435:   }
 436: }