javax.vecmath/src/javax/vecmath/Tuple3f.java

   1 /*
   2  * $RCSfile: Tuple3f.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.8 $
  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 generic 3-element tuple that is represented by single precision-floating
  38  * point x,y,z coordinates.
  39  *
  40  */
  41 public abstract class Tuple3f implements java.io.Serializable, Cloneable {
  42
  43     static final long serialVersionUID=5019834619484343712L;
  44
  45     /**
  46      * The x coordinate.
  47      */
  48     public      float   x;
  49
  50     /**
  51      * The y coordinate.
  52      */
  53     public      float   y;
  54
  55     /**
  56      * The z coordinate.
  57      */
  58     public      float   z;
  59
  60
  61     /**
  62      * Constructs and initializes a Tuple3f from the specified xyz coordinates.
  63      * @param x the x coordinate
  64      * @param y the y coordinate
  65      * @param z the z coordinate
  66      */
  67     public Tuple3f(float x, float y, float z)
  68     {
  69         this.x = x;
  70         this.y = y;
  71         this.z = z;
  72     }
  73
  74
  75     /**
  76      * Constructs and initializes a Tuple3f from the array of length 3.
  77      * @param t the array of length 3 containing xyz in order
  78      */
  79     public Tuple3f(float[] t)
  80     {
  81         this.x = t[0];
  82         this.y = t[1];
  83         this.z = t[2];
  84     }
  85
  86
  87     /**
  88      * Constructs and initializes a Tuple3f from the specified Tuple3f.
  89      * @param t1 the Tuple3f containing the initialization x y z data
  90      */
  91     public Tuple3f(Tuple3f t1)
  92     {
  93         this.x = t1.x;
  94         this.y = t1.y;
  95         this.z = t1.z;
  96     }
  97
  98
  99     /**
 100      * Constructs and initializes a Tuple3f from the specified Tuple3d.
 101      * @param t1 the Tuple3d containing the initialization x y z data
 102      */
 103     public Tuple3f(Tuple3d t1)
 104     {
 105         this.x = (float) t1.x;
 106         this.y = (float) t1.y;
 107         this.z = (float) t1.z;
 108     }
 109
 110
 111     /**
 112      * Constructs and initializes a Tuple3f to (0,0,0).
 113      */
 114     public Tuple3f()
 115     {
 116         this.x = 0.0f;
 117         this.y = 0.0f;
 118         this.z = 0.0f;
 119     }
 120
 121
 122    /**
 123      * Returns a string that contains the values of this Tuple3f.
 124      * The form is (x,y,z).
 125      * @return the String representation
 126      */
 127     public String toString() {
 128         return "(" + this.x + ", " + this.y + ", " + this.z + ")";
 129     }
 130
 131
 132     /**
 133      * Sets the value of this tuple to the specified xyz coordinates.
 134      * @param x the x coordinate
 135      * @param y the y coordinate
 136      * @param z the z coordinate
 137      */
 138     public final void set(float x, float y, float z)
 139     {
 140         this.x = x;
 141         this.y = y;
 142         this.z = z;
 143     }
 144
 145
 146     /**
 147      * Sets the value of this tuple to the xyz coordinates specified in
 148      * the array of length 3.
 149      * @param t the array of length 3 containing xyz in order
 150      */
 151     public final void set(float[] t)
 152     {
 153         this.x = t[0];
 154         this.y = t[1];
 155         this.z = t[2];
 156     }
 157
 158
 159     /**
 160      * Sets the value of this tuple to the value of tuple t1.
 161      * @param t1 the tuple to be copied
 162      */
 163     public final void set(Tuple3f 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 this tuple to the value of tuple t1.
 173      * @param t1 the tuple to be copied
 174      */
 175     public final void set(Tuple3d t1)
 176     {
 177         this.x = (float) t1.x;
 178         this.y = (float) t1.y;
 179         this.z = (float) t1.z;
 180     }
 181
 182
 183    /**
 184      * Gets the value of this tuple and copies the values into t.
 185      * @param t  the array of length 3 into which the values are copied
 186      */
 187     public final void get(float[] t)
 188     {
 189        t[0] = this.x;
 190        t[1] = this.y;
 191        t[2] = this.z;
 192     }
 193
 194
 195    /**
 196      * Gets the value of this tuple and copies the values into t.
 197      * @param t  the Tuple3f object into which the values of this object are copied
 198      */
 199     public final void get(Tuple3f t)
 200     {
 201        t.x = this.x;
 202        t.y = this.y;
 203        t.z = this.z;
 204     }
 205
 206
 207     /**
 208      * Sets the value of this tuple to the vector sum of tuples t1 and t2.
 209      * @param t1 the first tuple
 210      * @param t2 the second tuple
 211      */
 212     public final void add(Tuple3f t1, Tuple3f t2)
 213     {
 214         this.x = t1.x + t2.x;
 215         this.y = t1.y + t2.y;
 216         this.z = t1.z + t2.z;
 217     }
 218
 219
 220     /**
 221      * Sets the value of this tuple to the vector sum of itself and tuple t1.
 222      * @param t1 the other tuple
 223      */
 224     public final void add(Tuple3f t1)
 225     {
 226         this.x += t1.x;
 227         this.y += t1.y;
 228         this.z += t1.z;
 229     }
 230
 231
 232     /**
 233      * Sets the value of this tuple to the vector difference
 234      * of tuples t1 and t2 (this = t1 - t2).
 235      * @param t1 the first tuple
 236      * @param t2 the second tuple
 237      */
 238     public final void sub(Tuple3f t1, Tuple3f t2)
 239     {
 240         this.x = t1.x - t2.x;
 241         this.y = t1.y - t2.y;
 242         this.z = t1.z - t2.z;
 243     }
 244
 245
 246    /**
 247      * Sets the value of this tuple to the vector difference of
 248      * itself and tuple t1 (this = this - t1) .
 249      * @param t1 the other tuple
 250      */
 251     public final void sub(Tuple3f t1)
 252     {
 253         this.x -= t1.x;
 254         this.y -= t1.y;
 255         this.z -= t1.z;
 256     }
 257
 258
 259     /**
 260      * Sets the value of this tuple to the negation of tuple t1.
 261      * @param t1 the source tuple
 262      */
 263     public final void negate(Tuple3f t1)
 264     {
 265         this.x = -t1.x;
 266         this.y = -t1.y;
 267         this.z = -t1.z;
 268     }
 269
 270
 271     /**
 272      * Negates the value of this tuple in place.
 273      */
 274     public final void negate()
 275     {
 276         this.x = -this.x;
 277         this.y = -this.y;
 278         this.z = -this.z;
 279     }
 280
 281
 282     /**
 283      * Sets the value of this vector to the scalar multiplication
 284      * of tuple t1.
 285      * @param s the scalar value
 286      * @param t1 the source tuple
 287      */
 288     public final void scale(float s, Tuple3f t1)
 289     {
 290         this.x = s*t1.x;
 291         this.y = s*t1.y;
 292         this.z = s*t1.z;
 293     }
 294
 295
 296     /**
 297      * Sets the value of this tuple to the scalar multiplication
 298      * of the scale factor with this.
 299      * @param s the scalar value
 300      */
 301     public final void scale(float s)
 302     {
 303         this.x *= s;
 304         this.y *= s;
 305         this.z *= s;
 306     }
 307
 308
 309     /**
 310      * Sets the value of this tuple to the scalar multiplication
 311      * of tuple t1 and then adds tuple t2 (this = s*t1 + t2).
 312      * @param s the scalar value
 313      * @param t1 the tuple to be scaled and added
 314      * @param t2 the tuple to be added without a scale
 315      */
 316     public final void scaleAdd(float s, Tuple3f t1, Tuple3f t2)
 317     {
 318         this.x = s*t1.x + t2.x;
 319         this.y = s*t1.y + t2.y;
 320         this.z = s*t1.z + t2.z;
 321     }
 322
 323
 324
 325     /**
 326      * Sets the value of this tuple to the scalar multiplication
 327      * of itself and then adds tuple t1 (this = s*this + t1).
 328      * @param s the scalar value
 329      * @param t1 the tuple to be added
 330      */
 331     public final void scaleAdd(float s, Tuple3f t1)
 332     {
 333         this.x = s*this.x + t1.x;
 334         this.y = s*this.y + t1.y;
 335         this.z = s*this.z + t1.z;
 336     }
 337
 338
 339    /**
 340      * Returns true if the Object t1 is of type Tuple3f and all of the
 341      * data members of t1 are equal to the corresponding data members in
 342      * this Tuple3f.
 343      * @param t1  the vector with which the comparison is made
 344      * @return  true or false
 345      */
 346     public boolean equals(Tuple3f t1)
 347     {
 348         try {
 349            return(this.x == t1.x && this.y == t1.y && this.z == t1.z);
 350         }
 351         catch (NullPointerException e2) {return false;}
 352     }
 353    /**
 354      * Returns true if the Object t1 is of type Tuple3f and all of the
 355      * data members of t1 are equal to the corresponding data members in
 356      * this Tuple3f.
 357      * @param t1  the Object with which the comparison is made
 358      * @return  true or false
 359      */
 360     public boolean equals(Object t1)
 361     {
 362         try {
 363            Tuple3f t2 = (Tuple3f) t1;
 364            return(this.x == t2.x && this.y == t2.y && this.z == t2.z);
 365         }
 366         catch (NullPointerException e2) {return false;}
 367         catch (ClassCastException   e1) {return false;}
 368     }
 369
 370
 371    /**
 372      * Returns true if the L-infinite distance between this tuple
 373      * and tuple t1 is less than or equal to the epsilon parameter,
 374      * otherwise returns false.  The L-infinite
 375      * distance is equal to MAX[abs(x1-x2), abs(y1-y2), abs(z1-z2)].
 376      * @param t1  the tuple to be compared to this tuple
 377      * @param epsilon  the threshold value
 378      * @return  true or false
 379      */
 380     public boolean epsilonEquals(Tuple3f t1, float epsilon)
 381     {
 382        float diff;
 383
 384        diff = x - t1.x;
 385        if(Float.isNaN(diff)) return false;
 386        if((diff<0?-diff:diff) > epsilon) return false;
 387
 388        diff = y - t1.y;
 389        if(Float.isNaN(diff)) return false;
 390        if((diff<0?-diff:diff) > epsilon) return false;
 391
 392        diff = z - t1.z;
 393        if(Float.isNaN(diff)) return false;
 394        if((diff<0?-diff:diff) > epsilon) return false;
 395
 396        return true;
 397
 398     }
 399
 400
 401     /**
 402      * Returns a hash code value based on the data values in this
 403      * object.  Two different Tuple3f objects with identical data values
 404      * (i.e., Tuple3f.equals returns true) will return the same hash
 405      * code value.  Two objects with different data members may return the
 406      * same hash value, although this is not likely.
 407      * @return the integer hash code value
 408      */
 409     public int hashCode() {
 410         long bits = 1L;
 411         bits = 31L * bits + (long)VecMathUtil.floatToIntBits(x);
 412         bits = 31L * bits + (long)VecMathUtil.floatToIntBits(y);
 413         bits = 31L * bits + (long)VecMathUtil.floatToIntBits(z);
 414         return (int) (bits ^ (bits >> 32));
 415     }
 416
 417
 418
 419   /**
 420     *  Clamps the tuple parameter to the range [low, high] and
 421     *  places the values into this tuple.
 422     *  @param min   the lowest value in the tuple after clamping
 423     *  @param max  the highest value in the tuple after clamping
 424     *  @param t   the source tuple, which will not be modified
 425     */
 426    public final void clamp(float min, float max, Tuple3f t)
 427    {
 428         if( t.x > max ) {
 429           x = max;
 430         } else if( t.x < min ){
 431           x = min;
 432         } else {
 433           x = t.x;
 434         }
 435
 436         if( t.y > max ) {
 437           y = max;
 438         } else if( t.y < min ){
 439           y = min;
 440         } else {
 441           y = t.y;
 442         }
 443
 444         if( t.z > max ) {
 445           z = max;
 446         } else if( t.z < min ){
 447           z = min;
 448         } else {
 449           z = t.z;
 450         }
 451
 452    }
 453
 454
 455   /**
 456     *  Clamps the minimum value of the tuple parameter to the min
 457     *  parameter and places the values into this tuple.
 458     *  @param min   the lowest value in the tuple after clamping
 459     *  @param t   the source tuple, which will not be modified
 460     */
 461    public final void clampMin(float min, Tuple3f t)
 462    {
 463         if( t.x < min ) {
 464           x = min;
 465         } else {
 466           x = t.x;
 467         }
 468
 469         if( t.y < min ) {
 470           y = min;
 471         } else {
 472           y = t.y;
 473         }
 474
 475         if( t.z < min ) {
 476           z = min;
 477         } else {
 478           z = t.z;
 479         }
 480
 481    }
 482
 483
 484   /**
 485     *  Clamps the maximum value of the tuple parameter to the max
 486     *  parameter and places the values into this tuple.
 487     *  @param max   the highest value in the tuple after clamping
 488     *  @param t   the source tuple, which will not be modified
 489     */
 490    public final void clampMax(float max, Tuple3f t)
 491    {
 492         if( t.x > max ) {
 493           x = max;
 494         } else {
 495           x = t.x;
 496         }
 497
 498         if( t.y > max ) {
 499           y = max;
 500         } else {
 501           y = t.y;
 502         }
 503
 504         if( t.z > max ) {
 505           z = max;
 506         } else {
 507           z = t.z;
 508         }
 509
 510    }
 511
 512
 513   /**
 514     *  Sets each component of the tuple parameter to its absolute
 515     *  value and places the modified values into this tuple.
 516     *  @param t   the source tuple, which will not be modified
 517     */
 518   public final void absolute(Tuple3f t)
 519   {
 520        x = Math.abs(t.x);
 521        y = Math.abs(t.y);
 522        z = Math.abs(t.z);
 523   }
 524
 525
 526
 527   /**
 528     *  Clamps this tuple to the range [low, high].
 529     *  @param min  the lowest value in this tuple after clamping
 530     *  @param max  the highest value in this tuple after clamping
 531     */
 532    public final void clamp(float min, float max)
 533    {
 534         if( x > max ) {
 535           x = max;
 536         } else if( x < min ){
 537           x = min;
 538         }
 539
 540         if( y > max ) {
 541           y = max;
 542         } else if( y < min ){
 543           y = min;
 544         }
 545
 546         if( z > max ) {
 547           z = max;
 548         } else if( z < min ){
 549           z = min;
 550         }
 551
 552    }
 553
 554
 555   /**
 556     *  Clamps the minimum value of this tuple to the min parameter.
 557     *  @param min   the lowest value in this tuple after clamping
 558     */
 559    public final void clampMin(float min)
 560    {
 561       if( x < min ) x=min;
 562       if( y < min ) y=min;
 563       if( z < min ) z=min;
 564
 565    }
 566
 567
 568   /**
 569     *  Clamps the maximum value of this tuple to the max parameter.
 570     *  @param max   the highest value in the tuple after clamping
 571     */
 572    public final void clampMax(float max)
 573    {
 574       if( x > max ) x=max;
 575       if( y > max ) y=max;
 576       if( z > max ) z=max;
 577
 578    }
 579
 580
 581   /**
 582     *  Sets each component of this tuple to its absolute value.
 583     */
 584   public final void absolute()
 585   {
 586      x = Math.abs(x);
 587      y = Math.abs(y);
 588      z = Math.abs(z);
 589
 590   }
 591
 592
 593   /**
 594     *  Linearly interpolates between tuples t1 and t2 and places the
 595     *  result into this tuple:  this = (1-alpha)*t1 + alpha*t2.
 596     *  @param t1  the first tuple
 597     *  @param t2  the second tuple
 598     *  @param alpha  the alpha interpolation parameter
 599     */
 600   public final void interpolate(Tuple3f t1, Tuple3f t2, float alpha)
 601   {
 602            this.x = (1-alpha)*t1.x + alpha*t2.x;
 603            this.y = (1-alpha)*t1.y + alpha*t2.y;
 604            this.z = (1-alpha)*t1.z + alpha*t2.z;
 605
 606
 607   }
 608
 609
 610   /**
 611     *  Linearly interpolates between this tuple and tuple t1 and
 612     *  places the result into this tuple:  this = (1-alpha)*this + alpha*t1.
 613     *  @param t1  the first tuple
 614     *  @param alpha  the alpha interpolation parameter
 615     */
 616   public final void interpolate(Tuple3f t1, float alpha)
 617   {
 618      this.x = (1-alpha)*this.x + alpha*t1.x;
 619      this.y = (1-alpha)*this.y + alpha*t1.y;
 620      this.z = (1-alpha)*this.z + alpha*t1.z;
 621
 622
 623   }
 624
 625     /**
 626      * Creates a new object of the same class as this object.
 627      *
 628      * @return a clone of this instance.
 629      * @exception OutOfMemoryError if there is not enough memory.
 630      * @see java.lang.Cloneable
 631      * @since vecmath 1.3
 632      */
 633     public Object clone() {
 634         // Since there are no arrays we can just use Object.clone()
 635         try {
 636             return super.clone();
 637         } catch (CloneNotSupportedException e) {
 638             // this shouldn't happen, since we are Cloneable
 639             throw new InternalError();
 640         }
 641     }
 642
 643
 644     /**
 645          * Get the <i>x</i> coordinate.
 646          *
 647          * @return the  <i>x</i> coordinate.
 648          *
 649          * @since vecmath 1.5
 650          */
 651         public final float getX() {
 652                 return x;
 653         }
 654
 655
 656         /**
 657          * Set the <i>x</i> coordinate.
 658          *
 659          * @param x  value to <i>x</i> coordinate.
 660          *
 661          * @since vecmath 1.5
 662          */
 663         public final void setX(float x) {
 664                 this.x = x;
 665         }
 666
 667
 668         /**
 669          * Get the <i>y</i> coordinate.
 670          *
 671          * @return the <i>y</i> coordinate.
 672          *
 673          * @since vecmath 1.5
 674          */
 675         public final float getY() {
 676                 return y;
 677         }
 678
 679
 680         /**
 681          * Set the <i>y</i> coordinate.
 682          *
 683          * @param y value to <i>y</i> coordinate.
 684          *
 685          * @since vecmath 1.5
 686          */
 687         public final void setY(float y) {
 688                 this.y = y;
 689         }
 690
 691         /**
 692          * Get the <i>z</i> coordinate.
 693          *
 694          * @return the <i>z</i> coordinate
 695          *
 696          * @since vecmath 1.5
 697          */
 698         public final float getZ() {
 699                 return z;
 700         }
 701
 702
 703         /**
 704          * Set the <i>Z</i> coordinate.
 705          *
 706          * @param z value to <i>z</i> coordinate.
 707          *
 708          * @since vecmath 1.5
 709          */
 710         public final void setZ(float z) {
 711                 this.z = z;
 712         }
 713 }