javax.vecmath/src/javax/vecmath/Tuple3b.java

   1 /*
   2  * $RCSfile: Tuple3b.java,v $
   3  *
   4  * Copyright 1997-2008 Sun Microsystems, Inc.  All Rights Reserved.
   5  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   6  *
   7  * This code is free software; you can redistribute it and/or modify it
   8  * under the terms of the GNU General Public License version 2 only, as
   9  * published by the Free Software Foundation.  Sun designates this
  10  * particular file as subject to the "Classpath" exception as provided
  11  * by Sun in the LICENSE file that accompanied this code.
  12  *
  13  * This code is distributed in the hope that it will be useful, but WITHOUT
  14  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  15  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  16  * version 2 for more details (a copy is included in the LICENSE file that
  17  * accompanied this code).
  18  *
  19  * You should have received a copy of the GNU General Public License version
  20  * 2 along with this work; if not, write to the Free Software Foundation,
  21  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  22  *
  23  * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  24  * CA 95054 USA or visit www.sun.com if you need additional information or
  25  * have any questions.
  26  *
  27  * $Revision: 1.7 $
  28  * $Date: 2008/02/28 20:18:51 $
  29  * $State: Exp $
  30  */
  31
  32 package javax.vecmath;
  33
  34 import java.lang.Math;
  35
  36 /**
  37  * A three byte tuple.  Note that Java defines a byte as a signed integer
  38  * in the range [-128, 127]. However, colors are more typically
  39  * represented by values in the range [0, 255]. Java 3D recognizes this
  40  * and, in those cases where Tuple3b is used to represent color, treats
  41  * the bytes as if the range were [0, 255]---in other words, as if the
  42  * bytes were unsigned.
  43  * Values greater than 127 can be assigned to a byte variable using a
  44  * type cast.  For example:
  45  * <ul>byteVariable = (byte) intValue; // intValue can be > 127</ul>
  46  * If intValue is greater than 127, then byteVariable will be negative.  The
  47  * correct value will be extracted when it is used (by masking off the upper
  48  * bits).
  49  */
  50 public abstract class Tuple3b implements java.io.Serializable, Cloneable {
  51
  52     static final long serialVersionUID = -483782685323607044L;
  53
  54     /**
  55      * The first value.
  56      */
  57     public      byte    x;
  58
  59     /**
  60      * The second value.
  61      */
  62     public      byte    y;
  63
  64     /**
  65      * The third value.
  66      */
  67     public      byte    z;
  68
  69
  70     /**
  71      * Constructs and initializes a Tuple3b from the specified three values.
  72      * @param b1 the first value
  73      * @param b2 the second value
  74      * @param b3 the third value
  75      */
  76     public Tuple3b(byte b1, byte b2, byte b3)
  77     {
  78         this.x = b1;
  79         this.y = b2;
  80         this.z = b3;
  81     }
  82
  83
  84     /**
  85      * Constructs and initializes a Tuple3b from input array of length 3.
  86      * @param t the array of length 3 containing b1 b2 b3 in order
  87      */
  88     public Tuple3b(byte[] t)
  89     {
  90         this.x = t[0];
  91         this.y = t[1];
  92         this.z = t[2];
  93     }
  94
  95
  96     /**
  97      * Constructs and initializes a Tuple3b from the specified Tuple3b.
  98      * @param t1  the Tuple3b containing the initialization x y z data
  99      */
 100     public Tuple3b(Tuple3b t1)
 101     {
 102         this.x = t1.x;
 103         this.y = t1.y;
 104         this.z = t1.z;
 105     }
 106
 107
 108     /**
 109      * Constructs and initializes a Tuple3b to (0,0,0).
 110      */
 111     public Tuple3b()
 112     {
 113         this.x = (byte) 0;
 114         this.y = (byte) 0;
 115         this.z = (byte) 0;
 116     }
 117
 118
 119    /**
 120      * Returns a string that contains the values of this Tuple3b.
 121      * @return a String with the values
 122      */
 123     public String toString()
 124     {
 125         return("("  + ((int)this.x & 0xff) +
 126                ", " + ((int)this.y & 0xff) +
 127                ", " + ((int)this.z & 0xff) + ")");
 128     }
 129
 130
 131    /**
 132      * Places the value of the x,y,z components of this Tuple3b
 133      * into the array of length 3.
 134      * @param t array of length 3 into which the component values are copied
 135      */
 136     public final void get(byte[] t)
 137     {
 138
 139         t[0] = this.x;
 140         t[1] = this.y;
 141         t[2] = this.z;
 142     }
 143
 144
 145    /**
 146      * Places the value of the x,y,z components of this tuple into
 147      * the tuple t1.
 148      * @param t1  the tuple into which the values are placed
 149      */
 150     public final void get(Tuple3b t1)
 151     {
 152        t1.x = this.x;
 153        t1.y = this.y;
 154        t1.z = this.z;
 155     }
 156
 157
 158    /**
 159      * Sets the value of the data members of this tuple to the value
 160      * of the argument tuple t1.
 161      * @param t1  the source tuple for the memberwise copy
 162      */
 163     public final void set(Tuple3b t1)
 164     {
 165         this.x = t1.x;
 166         this.y = t1.y;
 167         this.z = t1.z;
 168     }
 169
 170
 171    /**
 172      * Sets the value of the x,y,z, data members of this tuple to the
 173      * values in the array t of length 3.
 174      * @param t  array of length 3 which is the source for the memberwise copy
 175      */
 176     public final void set(byte[] t)
 177     {
 178         this.x = t[0];
 179         this.y = t[1];
 180         this.z = t[2];
 181     }
 182
 183
 184    /**
 185      * Returns true if all of the data members of tuple t1 are equal to
 186      * the corresponding data members in this tuple.
 187      * @param t1  the tuple with which the comparison is made
 188      * @return  true or false
 189      */
 190     public boolean equals(Tuple3b t1)
 191     {
 192         try {
 193         return(this.x == t1.x && this.y == t1.y && this.z == t1.z);
 194         }
 195         catch (NullPointerException e2) {return false;}
 196
 197     }
 198
 199    /**
 200      * Returns true if the Object t1 is of type Tuple3b and all of the
 201      * data members of t1 are equal to the corresponding data members in
 202      * this Tuple3b.
 203      * @param t1  the object with which the comparison is made
 204      */
 205     public boolean equals(Object t1)
 206     {
 207         try {
 208            Tuple3b t2 = (Tuple3b) t1;
 209            return(this.x == t2.x && this.y == t2.y && this.z == t2.z);
 210         }
 211         catch (NullPointerException e2) {return false;}
 212         catch (ClassCastException   e1) {return false;}
 213
 214     }
 215
 216     /**
 217      * Returns a hash code value based on the data values in this
 218      * object.  Two different Tuple3b objects with identical data values
 219      * (i.e., Tuple3b.equals returns true) will return the same hash
 220      * code value.  Two objects with different data members may return the
 221      * same hash value, although this is not likely.
 222      * @return the integer hash code value
 223      */
 224     public int hashCode() {
 225         return ((((int)x & 0xff) <<  0) |
 226                 (((int)y & 0xff) <<  8) |
 227                 (((int)z & 0xff) << 16));
 228     }
 229
 230     /**
 231      * Creates a new object of the same class as this object.
 232      *
 233      * @return a clone of this instance.
 234      * @exception OutOfMemoryError if there is not enough memory.
 235      * @see java.lang.Cloneable
 236      * @since vecmath 1.3
 237      */
 238     public Object clone() {
 239         // Since there are no arrays we can just use Object.clone()
 240         try {
 241             return super.clone();
 242         } catch (CloneNotSupportedException e) {
 243             // this shouldn't happen, since we are Cloneable
 244             throw new InternalError();
 245         }
 246     }
 247
 248
 249     /**
 250          * Get <i>x</i>, the  first value.
 251          *
 252          * @return the first value.
 253          *
 254          * @since vecmath 1.5
 255          */
 256         public final byte getX() {
 257                 return x;
 258         }
 259
 260
 261         /**
 262          * Set <i>x</i>, the first value.
 263          *
 264          * @param x the first value to set.
 265          *
 266          * @since vecmath 1.5
 267          */
 268         public final void setX(byte x) {
 269                 this.x = x;
 270         }
 271
 272
 273         /**
 274          * Get <i>y</i>, the second value.
 275          *
 276          * @return the second value.
 277          *
 278          * @since vecmath 1.5
 279          */
 280         public final byte getY() {
 281                 return y;
 282         }
 283
 284
 285         /**
 286          * Set <i>y</i>, the second value.
 287          *
 288          * @param y the second value to set.
 289          *
 290          * @since vecmath 1.5
 291          */
 292         public final void setY(byte y) {
 293                 this.y = y;
 294         }
 295
 296         /**
 297          * Get <i>z</i>, the third value.
 298          *
 299          * @return the third value.
 300          *
 301          * @since vecmath 1.5
 302          */
 303         public final byte getZ() {
 304                 return z;
 305         }
 306
 307
 308         /**
 309          * Set <i>z</i>, the third value.
 310          *
 311          * @param z the third value to set.
 312          *
 313          * @since vecmath 1.5
 314          */
 315         public final void setZ(byte z) {
 316                 this.z = z;
 317         }
 318
 319 }