JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
Vec3d.java
Go to the documentation of this file.
1/**
2 * Copyright 2022-2023 JogAmp Community. All rights reserved.
3 *
4 * Redistribution and use in source and binary forms, with or without modification, are
5 * permitted provided that the following conditions are met:
6 *
7 * 1. Redistributions of source code must retain the above copyright notice, this list of
8 * conditions and the following disclaimer.
9 *
10 * 2. Redistributions in binary form must reproduce the above copyright notice, this list
11 * of conditions and the following disclaimer in the documentation and/or other materials
12 * provided with the distribution.
13 *
14 * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
15 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
16 * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
17 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
18 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
19 * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
20 * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
21 * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
22 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
23 *
24 * The views and conclusions contained in the software and documentation are those of the
25 * authors and should not be interpreted as representing official policies, either expressed
26 * or implied, of JogAmp Community.
27 */
28
29package com.jogamp.math;
30
31
32/**
33 * 3D Vector based upon three double components.
34 *
35 * Implementation borrowed from [gfxbox2](https://jausoft.com/cgit/cs_class/gfxbox2.git/tree/include/pixel/pixel3f.hpp#n29)
36 * and its data layout from JOAL's Vec3f.
37 */
38public final class Vec3d {
39 private double x;
40 private double y;
41 private double z;
42
43 public Vec3d() {}
44
45 public Vec3d(final Vec3d o) {
46 set(o);
47 }
48
49 /** Creating new Vec3f using Vec4f, dropping w. */
50 public Vec3d(final Vec4f o) {
51 set(o);
52 }
53
54 /** Creating new Vec3f using { Vec2f, z}. */
55 public Vec3d(final Vec2f o, final double z) {
56 set(o, z);
57 }
58
59 public Vec3d copy() {
60 return new Vec3d(this);
61 }
62
63 public Vec3d(final double[/*3*/] xyz) {
64 set(xyz);
65 }
66
67 public Vec3d(final double x, final double y, final double z) {
68 set(x, y, z);
69 }
70
71 /** this = o, returns this. */
72 public Vec3d set(final Vec3d o) {
73 this.x = o.x;
74 this.y = o.y;
75 this.z = o.z;
76 return this;
77 }
78
79 /** this = { o, z }, returns this. */
80 public Vec3d set(final Vec2f o, final double z) {
81 this.x = o.x();
82 this.y = o.y();
83 this.z = z;
84 return this;
85 }
86
87 /** this = o while dropping w, returns this. */
88 public Vec3d set(final Vec4f o) {
89 this.x = o.x();
90 this.y = o.y();
91 this.z = o.z();
92 return this;
93 }
94
95 /** this = { x, y, z }, returns this. */
96 public Vec3d set(final double x, final double y, final double z) {
97 this.x = x;
98 this.y = y;
99 this.z = z;
100 return this;
101 }
102
103 /** this = xyz, returns this. */
104 public Vec3d set(final double[/*3*/] xyz) {
105 this.x = xyz[0];
106 this.y = xyz[1];
107 this.z = xyz[2];
108 return this;
109 }
110
111 /** xyz[0..2] = this.{x, y, z}, returns this. */
112 public Vec3d toArray(final double[/*3*/] xyz) {
113 xyz[0] = this.x;
114 xyz[1] = this.y;
115 xyz[2] = this.z;
116 return this;
117 }
118
119 /** Sets the ith component, 0 <= i < 3 */
120 public void set(final int i, final double val) {
121 switch (i) {
122 case 0: x = val; break;
123 case 1: y = val; break;
124 case 2: z = val; break;
125 default: throw new IndexOutOfBoundsException();
126 }
127 }
128
129 /** xyz = this, returns xyz. */
130 public double[] get(final double[/*3*/] xyz) {
131 xyz[0] = this.x;
132 xyz[1] = this.y;
133 xyz[2] = this.z;
134 return xyz;
135 }
136
137 /** Gets the ith component, 0 <= i < 3 */
138 public double get(final int i) {
139 switch (i) {
140 case 0: return x;
141 case 1: return y;
142 case 2: return z;
143 default: throw new IndexOutOfBoundsException();
144 }
145 }
146
147 public double x() { return x; }
148 public double y() { return y; }
149 public double z() { return z; }
150
151 public void setX(final double x) { this.x = x; }
152 public void setY(final double y) { this.y = y; }
153 public void setZ(final double z) { this.z = z; }
154
155 /** this = max(this, m), returns this. */
156 public Vec3d max(final Vec3d m) {
157 this.x = Math.max(this.x, m.x);
158 this.y = Math.max(this.y, m.y);
159 this.z = Math.max(this.z, m.z);
160 return this;
161 }
162 /** this = min(this, m), returns this. */
163 public Vec3d min(final Vec3d m) {
164 this.x = Math.min(this.x, m.x);
165 this.y = Math.min(this.y, m.y);
166 this.z = Math.min(this.z, m.z);
167 return this;
168 }
169
170 /** Returns this * val; creates new vector */
171 public Vec3d mul(final double val) {
172 return new Vec3d(this).scale(val);
173 }
174
175 /** this = a * b, returns this. */
176 public Vec3d mul(final Vec3d a, final Vec3d b) {
177 x = a.x * b.x;
178 y = a.y * b.y;
179 z = a.z * b.z;
180 return this;
181 }
182
183 /** this = this * s, returns this. */
184 public Vec3d mul(final Vec3d s) { return mul(s.x, s.y, s.z); }
185
186 /** this = this * { sx, sy, sz }, returns this. */
187 public Vec3d mul(final double sx, final double sy, final double sz) {
188 x *= sx;
189 y *= sy;
190 z *= sz;
191 return this;
192 }
193
194 /** this = a / b, returns this. */
195 public Vec3d div(final Vec3d a, final Vec3d b) {
196 x = a.x / b.x;
197 y = a.y / b.y;
198 z = a.z / b.z;
199 return this;
200 }
201
202 /** this = this / a, returns this. */
203 public Vec3d div(final Vec3d a) {
204 x /= a.x;
205 y /= a.y;
206 z /= a.z;
207 return this;
208 }
209
210 /** this = this * s, returns this. */
211 public Vec3d scale(final double s) {
212 x *= s;
213 y *= s;
214 z *= s;
215 return this;
216 }
217
218 /** Returns this + arg; creates new vector */
219 public Vec3d plus(final Vec3d arg) {
220 return new Vec3d(this).add(arg);
221 }
222
223 /** this = a + b, returns this. */
224 public Vec3d plus(final Vec3d a, final Vec3d b) {
225 x = a.x + b.x;
226 y = a.y + b.y;
227 z = a.z + b.z;
228 return this;
229 }
230
231 /** this = this + { dx, dy, dz }, returns this. */
232 public Vec3d add(final double dx, final double dy, final double dz) {
233 x += dx;
234 y += dy;
235 z += dz;
236 return this;
237 }
238
239 /** this = this + b, returns this. */
240 public Vec3d add(final Vec3d b) {
241 x += b.x;
242 y += b.y;
243 z += b.z;
244 return this;
245 }
246
247 /** Returns this - arg; creates new vector */
248 public Vec3d minus(final Vec3d arg) {
249 return new Vec3d(this).sub(arg);
250 }
251
252 /** this = a - b, returns this. */
253 public Vec3d minus(final Vec3d a, final Vec3d b) {
254 x = a.x - b.x;
255 y = a.y - b.y;
256 z = a.z - b.z;
257 return this;
258 }
259
260 /** this = this - b, returns this. */
261 public Vec3d sub(final Vec3d b) {
262 x -= b.x;
263 y -= b.y;
264 z -= b.z;
265 return this;
266 }
267
268 /** Return true if all components are zero, i.e. it's absolute value < {@link #EPSILON}. */
269 public boolean isZero() {
270 return DoubleUtil.isZero(x) && DoubleUtil.isZero(y) && DoubleUtil.isZero(z);
271 }
272
273 /**
274 * Return the length of this vector, a.k.a the <i>norm</i> or <i>magnitude</i>
275 */
276 public double length() {
277 return Math.sqrt(lengthSq());
278 }
279
280 /**
281 * Return the squared length of this vector, a.k.a the squared <i>norm</i> or squared <i>magnitude</i>
282 */
283 public double lengthSq() {
284 return x*x + y*y + z*z;
285 }
286
287 /**
288 * Normalize this vector in place
289 */
290 public Vec3d normalize() {
291 final double lengthSq = lengthSq();
292 if ( DoubleUtil.isZero( lengthSq ) ) {
293 x = 0.0f;
294 y = 0.0f;
295 z = 0.0f;
296 } else {
297 final double invSqr = 1.0f / Math.sqrt(lengthSq);
298 x *= invSqr;
299 y *= invSqr;
300 z *= invSqr;
301 }
302 return this;
303 }
304
305 /**
306 * Return the squared distance between this vector and the given one.
307 * <p>
308 * When comparing the relative distance between two points it is usually sufficient to compare the squared
309 * distances, thus avoiding an expensive square root operation.
310 * </p>
311 */
312 public double distSq(final Vec3d o) {
313 final double dx = x - o.x;
314 final double dy = y - o.y;
315 final double dz = z - o.z;
316 return dx*dx + dy*dy + dz*dz;
317 }
318
319 /**
320 * Return the distance between this vector and the given one.
321 */
322 public double dist(final Vec3d o) {
323 return Math.sqrt(distSq(o));
324 }
325
326
327 /**
328 * Return the dot product of this vector and the given one
329 * @return the dot product as double
330 */
331 public double dot(final Vec3d o) {
332 return x*o.x + y*o.y + z*o.z;
333 }
334
335 /** Returns this cross arg; creates new vector */
336 public Vec3d cross(final Vec3d arg) {
337 return new Vec3d().cross(this, arg);
338 }
339
340 /** this = a cross b. NOTE: "this" must be a different vector than
341 both a and b. */
342 public Vec3d cross(final Vec3d a, final Vec3d b) {
343 x = a.y * b.z - a.z * b.y;
344 y = a.z * b.x - a.x * b.z;
345 z = a.x * b.y - a.y * b.x;
346 return this;
347 }
348
349 /**
350 * Return the cosine of the angle between two vectors using {@link #dot(Vec3d)}
351 */
352 public double cosAngle(final Vec3d o) {
353 return dot(o) / ( length() * o.length() ) ;
354 }
355
356 /**
357 * Return the angle between two vectors in radians using {@link Math#acos(double)} on {@link #cosAngle(Vec3d)}.
358 */
359 public double angle(final Vec3d o) {
360 return Math.acos( cosAngle(o) );
361 }
362
363 /**
364 * Equals check using a given {@link DoubleUtil#EPSILON} value and {@link DoubleUtil#isEqual(double, double, double)}.
365 * <p>
366 * Implementation considers following corner cases:
367 * <ul>
368 * <li>NaN == NaN</li>
369 * <li>+Inf == +Inf</li>
370 * <li>-Inf == -Inf</li>
371 * </ul>
372 * @param o comparison value
373 * @param epsilon consider using {@link DoubleUtil#EPSILON}
374 * @return true if all components differ less than {@code epsilon}, otherwise false.
375 */
376 public boolean isEqual(final Vec3d o, final double epsilon) {
377 if( this == o ) {
378 return true;
379 } else {
380 return DoubleUtil.isEqual(x, o.x, epsilon) &&
381 DoubleUtil.isEqual(y, o.y, epsilon) &&
382 DoubleUtil.isEqual(z, o.z, epsilon);
383 }
384 }
385
386 /**
387 * Equals check using {@link DoubleUtil#EPSILON} in {@link DoubleUtil#isEqual(double, double)}.
388 * <p>
389 * Implementation considers following corner cases:
390 * <ul>
391 * <li>NaN == NaN</li>
392 * <li>+Inf == +Inf</li>
393 * <li>-Inf == -Inf</li>
394 * </ul>
395 * @param o comparison value
396 * @return true if all components differ less than {@link DoubleUtil#EPSILON}, otherwise false.
397 */
398 public boolean isEqual(final Vec3d o) {
399 if( this == o ) {
400 return true;
401 } else {
402 return DoubleUtil.isEqual(x, o.x) &&
403 DoubleUtil.isEqual(y, o.y) &&
404 DoubleUtil.isEqual(z, o.z);
405 }
406 }
407
408 @Override
409 public boolean equals(final Object o) {
410 if( o instanceof Vec3d ) {
411 return isEqual((Vec3d)o);
412 } else {
413 return false;
414 }
415 }
416
417 @Override
418 public String toString() {
419 return x + " / " + y + " / " + z;
420 }
421}
Basic Double math utility functions.
Definition: DoubleUtil.java:33
static boolean isZero(final double a, final double epsilon)
Returns true if value is zero, i.e.
static boolean isEqual(final double a, final double b, final double epsilon)
Returns true if both values are equal, i.e.
2D Vector based upon two float components.
Definition: Vec2f.java:37
3D Vector based upon three double components.
Definition: Vec3d.java:38
Vec3d plus(final Vec3d a, final Vec3d b)
this = a + b, returns this.
Definition: Vec3d.java:224
void setX(final double x)
Definition: Vec3d.java:151
Vec3d mul(final Vec3d a, final Vec3d b)
this = a * b, returns this.
Definition: Vec3d.java:176
Vec3d(final double[] xyz)
Definition: Vec3d.java:63
double lengthSq()
Return the squared length of this vector, a.k.a the squared norm or squared magnitude
Definition: Vec3d.java:283
Vec3d(final Vec2f o, final double z)
Creating new Vec3f using { Vec2f, z}.
Definition: Vec3d.java:55
Vec3d add(final double dx, final double dy, final double dz)
this = this + { dx, dy, dz }, returns this.
Definition: Vec3d.java:232
double dot(final Vec3d o)
Return the dot product of this vector and the given one.
Definition: Vec3d.java:331
Vec3d mul(final Vec3d s)
this = this * s, returns this.
Definition: Vec3d.java:184
Vec3d(final Vec4f o)
Creating new Vec3f using Vec4f, dropping w.
Definition: Vec3d.java:50
Vec3d minus(final Vec3d arg)
Returns this - arg; creates new vector.
Definition: Vec3d.java:248
Vec3d min(final Vec3d m)
this = min(this, m), returns this.
Definition: Vec3d.java:163
double cosAngle(final Vec3d o)
Return the cosine of the angle between two vectors using dot(Vec3d).
Definition: Vec3d.java:352
Vec3d max(final Vec3d m)
this = max(this, m), returns this.
Definition: Vec3d.java:156
Vec3d div(final Vec3d a)
this = this / a, returns this.
Definition: Vec3d.java:203
Vec3d add(final Vec3d b)
this = this + b, returns this.
Definition: Vec3d.java:240
Vec3d mul(final double sx, final double sy, final double sz)
this = this * { sx, sy, sz }, returns this.
Definition: Vec3d.java:187
Vec3d mul(final double val)
Returns this * val; creates new vector.
Definition: Vec3d.java:171
Vec3d normalize()
Normalize this vector in place.
Definition: Vec3d.java:290
Vec3d div(final Vec3d a, final Vec3d b)
this = a / b, returns this.
Definition: Vec3d.java:195
Vec3d plus(final Vec3d arg)
Returns this + arg; creates new vector.
Definition: Vec3d.java:219
boolean isEqual(final Vec3d o)
Equals check using DoubleUtil#EPSILON in DoubleUtil#isEqual(double, double).
Definition: Vec3d.java:398
double distSq(final Vec3d o)
Return the squared distance between this vector and the given one.
Definition: Vec3d.java:312
Vec3d minus(final Vec3d a, final Vec3d b)
this = a - b, returns this.
Definition: Vec3d.java:253
double length()
Return the length of this vector, a.k.a the norm or magnitude
Definition: Vec3d.java:276
Vec3d cross(final Vec3d arg)
Returns this cross arg; creates new vector.
Definition: Vec3d.java:336
boolean equals(final Object o)
Definition: Vec3d.java:409
Vec3d scale(final double s)
this = this * s, returns this.
Definition: Vec3d.java:211
double dist(final Vec3d o)
Return the distance between this vector and the given one.
Definition: Vec3d.java:322
Vec3d toArray(final double[] xyz)
xyz[0..2] = this.
Definition: Vec3d.java:112
void setZ(final double z)
Definition: Vec3d.java:153
boolean isZero()
Return true if all components are zero, i.e.
Definition: Vec3d.java:269
double angle(final Vec3d o)
Return the angle between two vectors in radians using Math#acos(double) on cosAngle(Vec3d).
Definition: Vec3d.java:359
boolean isEqual(final Vec3d o, final double epsilon)
Equals check using a given DoubleUtil#EPSILON value and DoubleUtil#isEqual(double,...
Definition: Vec3d.java:376
Vec3d sub(final Vec3d b)
this = this - b, returns this.
Definition: Vec3d.java:261
void setY(final double y)
Definition: Vec3d.java:152
Vec3d cross(final Vec3d a, final Vec3d b)
this = a cross b.
Definition: Vec3d.java:342
Vec3d(final Vec3d o)
Definition: Vec3d.java:45
Vec3d(final double x, final double y, final double z)
Definition: Vec3d.java:67
4D Vector based upon four float components.
Definition: Vec4f.java:37