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 
  38 import static sun.java2d.StateTrackable.State.*;
  39 
  40 /**
  41  * This class extends <CODE>DataBuffer</CODE> and stores data internally as bytes.
  42  * Values stored in the byte array(s) of this <CODE>DataBuffer</CODE> are treated as
  43  * unsigned values.
  44  * <p>
  45  * <a name="optimizations">
  46  * Note that some implementations may function more efficiently
  47  * if they can maintain control over how the data for an image is
  48  * stored.
  49  * For example, optimizations such as caching an image in video
  50  * memory require that the implementation track all modifications
  51  * to that data.
  52  * Other implementations may operate better if they can store the
  53  * data in locations other than a Java array.
  54  * To maintain optimum compatibility with various optimizations
  55  * it is best to avoid constructors and methods which expose the
  56  * underlying storage as a Java array, as noted below in the
  57  * documentation for those methods.
  58  * </a>
  59  */
  60 public final class DataBufferByte extends DataBuffer
  61 {
  62     /** The default data bank. */
  63     byte data[];
  64 
  65     /** All data banks */
  66     byte bankdata[][];
  67 
  68     /**
  69      * Constructs a byte-based <CODE>DataBuffer</CODE> with a single bank and the
  70      * specified size.
  71      *
  72      * @param size The size of the <CODE>DataBuffer</CODE>.
  73      */
  74     public DataBufferByte(int size) {
  75       super(STABLE, TYPE_BYTE, size);
  76       data = new byte[size];
  77       bankdata = new byte[1][];
  78       bankdata[0] = data;
  79     }
  80 
  81     /**
  82      * Constructs a byte based <CODE>DataBuffer</CODE> with the specified number of
  83      * banks all of which are the specified size.
  84      *
  85      * @param size The size of the banks in the <CODE>DataBuffer</CODE>.
  86      * @param numBanks The number of banks in the a<CODE>DataBuffer</CODE>.
  87      */
  88     public DataBufferByte(int size, int numBanks) {
  89         super(STABLE, TYPE_BYTE, size, numBanks);
  90         bankdata = new byte[numBanks][];
  91         for (int i= 0; i < numBanks; i++) {
  92             bankdata[i] = new byte[size];
  93         }
  94         data = bankdata[0];
  95     }
  96 
  97     /**
  98      * Constructs a byte-based <CODE>DataBuffer</CODE> with a single bank using the
  99      * specified array.
 100      * Only the first <CODE>size</CODE> elements should be used by accessors of
 101      * this <CODE>DataBuffer</CODE>.  <CODE>dataArray</CODE> must be large enough to
 102      * hold <CODE>size</CODE> elements.
 103      * <p>
 104      * Note that {@code DataBuffer} objects created by this constructor
 105      * may be incompatible with <a href="#optimizations">performance
 106      * optimizations</a> used by some implementations (such as caching
 107      * an associated image in video memory).
 108      *
 109      * @param dataArray The byte array for the <CODE>DataBuffer</CODE>.
 110      * @param size The size of the <CODE>DataBuffer</CODE> bank.
 111      */
 112     public DataBufferByte(byte dataArray[], int size) {
 113         super(UNTRACKABLE, TYPE_BYTE, size);
 114         data = dataArray;
 115         bankdata = new byte[1][];
 116         bankdata[0] = data;
 117     }
 118 
 119     /**
 120      * Constructs a byte-based <CODE>DataBuffer</CODE> with a single bank using the
 121      * specified array, size, and offset.  <CODE>dataArray</CODE> must have at least
 122      * <CODE>offset</CODE> + <CODE>size</CODE> elements.  Only elements <CODE>offset</CODE>
 123      * through <CODE>offset</CODE> + <CODE>size</CODE> - 1
 124      * should be used by accessors of this <CODE>DataBuffer</CODE>.
 125      * <p>
 126      * Note that {@code DataBuffer} objects created by this constructor
 127      * may be incompatible with <a href="#optimizations">performance
 128      * optimizations</a> used by some implementations (such as caching
 129      * an associated image in video memory).
 130      *
 131      * @param dataArray The byte array for the <CODE>DataBuffer</CODE>.
 132      * @param size The size of the <CODE>DataBuffer</CODE> bank.
 133      * @param offset The offset into the <CODE>dataArray</CODE>. <CODE>dataArray</CODE>
 134      * must have at least <CODE>offset</CODE> + <CODE>size</CODE> elements.
 135      */
 136     public DataBufferByte(byte dataArray[], int size, int offset){
 137         super(UNTRACKABLE, TYPE_BYTE, size, 1, offset);
 138         data = dataArray;
 139         bankdata = new byte[1][];
 140         bankdata[0] = data;
 141     }
 142 
 143     /**
 144      * Constructs a byte-based <CODE>DataBuffer</CODE> with the specified arrays.
 145      * The number of banks is equal to <CODE>dataArray.length</CODE>.
 146      * Only the first <CODE>size</CODE> elements of each array should be used by
 147      * accessors of this <CODE>DataBuffer</CODE>.
 148      * <p>
 149      * Note that {@code DataBuffer} objects created by this constructor
 150      * may be incompatible with <a href="#optimizations">performance
 151      * optimizations</a> used by some implementations (such as caching
 152      * an associated image in video memory).
 153      *
 154      * @param dataArray The byte arrays for the <CODE>DataBuffer</CODE>.
 155      * @param size The size of the banks in the <CODE>DataBuffer</CODE>.
 156      */
 157     public DataBufferByte(byte dataArray[][], int size) {
 158         super(UNTRACKABLE, TYPE_BYTE, size, dataArray.length);
 159         bankdata = (byte[][]) dataArray.clone();
 160         data = bankdata[0];
 161     }
 162 
 163     /**
 164      * Constructs a byte-based <CODE>DataBuffer</CODE> with the specified arrays, size,
 165      * and offsets.
 166      * The number of banks is equal to <CODE>dataArray.length</CODE>.  Each array must
 167      * be at least as large as <CODE>size</CODE> + the corresponding <CODE>offset</CODE>.
 168      * There must be an entry in the <CODE>offset</CODE> array for each <CODE>dataArray</CODE>
 169      * entry.  For each bank, only elements <CODE>offset</CODE> through
 170      * <CODE>offset</CODE> + <CODE>size</CODE> - 1 should be used by accessors of this
 171      * <CODE>DataBuffer</CODE>.
 172      * <p>
 173      * Note that {@code DataBuffer} objects created by this constructor
 174      * may be incompatible with <a href="#optimizations">performance
 175      * optimizations</a> used by some implementations (such as caching
 176      * an associated image in video memory).
 177      *
 178      * @param dataArray The byte arrays for the <CODE>DataBuffer</CODE>.
 179      * @param size The size of the banks in the <CODE>DataBuffer</CODE>.
 180      * @param offsets The offsets into each array.
 181      */
 182     public DataBufferByte(byte dataArray[][], int size, int offsets[]) {
 183         super(UNTRACKABLE, TYPE_BYTE, size, dataArray.length, offsets);
 184         bankdata = (byte[][]) dataArray.clone();
 185         data = bankdata[0];
 186     }
 187 
 188     /**
 189      * Returns the default (first) byte data array.
 190      * <p>
 191      * Note that calling this method may cause this {@code DataBuffer}
 192      * object to be incompatible with <a href="#optimizations">performance
 193      * optimizations</a> used by some implementations (such as caching
 194      * an associated image in video memory).
 195      *
 196      * @return The first byte data array.
 197      */
 198     public byte[] getData() {
 199         theTrackable.setUntrackable();
 200         return data;
 201     }
 202 
 203     /**
 204      * Returns the data array for the specified bank.
 205      * <p>
 206      * Note that calling this method may cause this {@code DataBuffer}
 207      * object to be incompatible with <a href="#optimizations">performance
 208      * optimizations</a> used by some implementations (such as caching
 209      * an associated image in video memory).
 210      *
 211      * @param bank The bank whose data array you want to get.
 212      * @return The data array for the specified bank.
 213      */
 214     public byte[] getData(int bank) {
 215         theTrackable.setUntrackable();
 216         return bankdata[bank];
 217     }
 218 
 219     /**
 220      * Returns the data arrays for all banks.
 221      * <p>
 222      * Note that calling this method may cause this {@code DataBuffer}
 223      * object to be incompatible with <a href="#optimizations">performance
 224      * optimizations</a> used by some implementations (such as caching
 225      * an associated image in video memory).
 226      *
 227      * @return All of the data arrays.
 228      */
 229     public byte[][] getBankData() {
 230         theTrackable.setUntrackable();
 231         return (byte[][]) bankdata.clone();
 232     }
 233 
 234     /**
 235      * Returns the requested data array element from the first (default) bank.
 236      *
 237      * @param i The data array element you want to get.
 238      * @return The requested data array element as an integer.
 239      * @see #setElem(int, int)
 240      * @see #setElem(int, int, int)
 241      */
 242     public int getElem(int i) {
 243         return (int)(data[i+offset]) & 0xff;
 244     }
 245 
 246     /**
 247      * Returns the requested data array element from the specified bank.
 248      *
 249      * @param bank The bank from which you want to get a data array element.
 250      * @param i The data array element you want to get.
 251      * @return The requested data array element as an integer.
 252      * @see #setElem(int, int)
 253      * @see #setElem(int, int, int)
 254      */
 255     public int getElem(int bank, int i) {
 256         return (int)(bankdata[bank][i+offsets[bank]]) & 0xff;
 257     }
 258 
 259     /**
 260      * Sets the requested data array element in the first (default) bank
 261      * to the specified value.
 262      *
 263      * @param i The data array element you want to set.
 264      * @param val The integer value to which you want to set the data array element.
 265      * @see #getElem(int)
 266      * @see #getElem(int, int)
 267      */
 268     public void setElem(int i, int val) {
 269         data[i+offset] = (byte)val;
 270         theTrackable.markDirty();
 271     }
 272 
 273     /**
 274      * Sets the requested data array element in the specified bank
 275      * from the given integer.
 276      * @param bank The bank in which you want to set the data array element.
 277      * @param i The data array element you want to set.
 278      * @param val The integer value to which you want to set the specified data array element.
 279      * @see #getElem(int)
 280      * @see #getElem(int, int)
 281      */
 282     public void setElem(int bank, int i, int val) {
 283         bankdata[bank][i+offsets[bank]] = (byte)val;
 284         theTrackable.markDirty();
 285     }
 286 }