View Javadoc
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 }