JOGL v2.6.0-rc-20250712
JOGL, High-Performance Graphics Binding for Java™ (public API).
Vec3f.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 * 3D Vector based upon three float components.
33 *
34 * Implementation borrowed from [gfxbox2](https://jausoft.com/cgit/cs_class/gfxbox2.git/tree/include/pixel/pixel3f.hpp#n29)
35 * and its data layout from JOAL's Vec3f.
36 */
37public final class Vec3f {
38 public static final Vec3f ONE = new Vec3f(1f, 1f, 1f);
39 public static final Vec3f UNIT_X = new Vec3f(1f, 0f, 0f);
40 public static final Vec3f UNIT_X_NEG = new Vec3f(-1f, 0f, 0f);
41 public static final Vec3f UNIT_Y = new Vec3f(0f, 1f, 0f);
42 public static final Vec3f UNIT_Y_NEG = new Vec3f(0f, -1f, 0f);
43 public static final Vec3f UNIT_Z = new Vec3f(0f, 0f, 1f);
44 public static final Vec3f UNIT_Z_NEG = new Vec3f(0f, 0f, -1f);
45
46 private float x;
47 private float y;
48 private float z;
49
50 public Vec3f() {}
51
52 public Vec3f(final Vec3f o) {
53 set(o);
54 }
55
56 /** Creating new Vec3f using Vec4f, dropping w. */
57 public Vec3f(final Vec4f o) {
58 set(o);
59 }
60
61 /** Creating new Vec3f using { Vec2f, z}. */
62 public Vec3f(final Vec2f o, final float z) {
63 set(o, z);
64 }
65
66 public Vec3f copy() {
67 return new Vec3f(this);
68 }
69
70 public Vec3f(final float[/*3*/] xyz) {
71 set(xyz);
72 }
73
74 public Vec3f(final float x, final float y, final float z) {
75 set(x, y, z);
76 }
77
78 /** this = o, returns this. */
79 public Vec3f set(final Vec3f o) {
80 this.x = o.x;
81 this.y = o.y;
82 this.z = o.z;
83 return this;
84 }
85
86 /** this = { o, z }, returns this. */
87 public Vec3f set(final Vec2f o, final float z) {
88 this.x = o.x();
89 this.y = o.y();
90 this.z = z;
91 return this;
92 }
93
94 /** this = o while dropping w, returns this. */
95 public Vec3f set(final Vec4f o) {
96 this.x = o.x();
97 this.y = o.y();
98 this.z = o.z();
99 return this;
100 }
101
102 /** this = { x, y, z }, returns this. */
103 public Vec3f set(final float x, final float y, final float z) {
104 this.x = x;
105 this.y = y;
106 this.z = z;
107 return this;
108 }
109
110 /** this = xyz, returns this. */
111 public Vec3f set(final float[/*3*/] xyz) {
112 this.x = xyz[0];
113 this.y = xyz[1];
114 this.z = xyz[2];
115 return this;
116 }
117
118 /** xyz[0..2] = this.{x, y, z}, returns this. */
119 public Vec3f toArray(final float[/*3*/] xyz) {
120 xyz[0] = this.x;
121 xyz[1] = this.y;
122 xyz[2] = this.z;
123 return this;
124 }
125
126 /** Sets the ith component, 0 <= i < 3 */
127 public void set(final int i, final float val) {
128 switch (i) {
129 case 0: x = val; break;
130 case 1: y = val; break;
131 case 2: z = val; break;
132 default: throw new IndexOutOfBoundsException();
133 }
134 }
135
136 /** xyz = this, returns xyz. */
137 public float[] get(final float[/*3*/] xyz) {
138 xyz[0] = this.x;
139 xyz[1] = this.y;
140 xyz[2] = this.z;
141 return xyz;
142 }
143
144 /** Gets the ith component, 0 <= i < 3 */
145 public float get(final int i) {
146 switch (i) {
147 case 0: return x;
148 case 1: return y;
149 case 2: return z;
150 default: throw new IndexOutOfBoundsException();
151 }
152 }
153
154 public float x() { return x; }
155 public float y() { return y; }
156 public float z() { return z; }
157
158 public void setX(final float x) { this.x = x; }
159 public void setY(final float y) { this.y = y; }
160 public void setZ(final float z) { this.z = z; }
161
162 /** this = max(this, m), returns this. */
163 public Vec3f max(final Vec3f m) {
164 this.x = Math.max(this.x, m.x);
165 this.y = Math.max(this.y, m.y);
166 this.z = Math.max(this.z, m.z);
167 return this;
168 }
169 /** this = min(this, m), returns this. */
170 public Vec3f min(final Vec3f m) {
171 this.x = Math.min(this.x, m.x);
172 this.y = Math.min(this.y, m.y);
173 this.z = Math.min(this.z, m.z);
174 return this;
175 }
176
177 /** Returns this * val; creates new vector */
178 public Vec3f mul(final float val) {
179 return new Vec3f(this).scale(val);
180 }
181
182 /** this = a * b, returns this. */
183 public Vec3f mul(final Vec3f a, final Vec3f b) {
184 x = a.x * b.x;
185 y = a.y * b.y;
186 z = a.z * b.z;
187 return this;
188 }
189
190 /** this = this * s, returns this. */
191 public Vec3f mul(final Vec3f s) { return mul(s.x, s.y, s.z); }
192
193 /** this = this * { sx, sy, sz }, returns this. */
194 public Vec3f mul(final float sx, final float sy, final float sz) {
195 x *= sx;
196 y *= sy;
197 z *= sz;
198 return this;
199 }
200
201 /** this = a / b, returns this. */
202 public Vec3f div(final Vec3f a, final Vec3f b) {
203 x = a.x / b.x;
204 y = a.y / b.y;
205 z = a.z / b.z;
206 return this;
207 }
208
209 /** this = this / a, returns this. */
210 public Vec3f div(final Vec3f a) {
211 x /= a.x;
212 y /= a.y;
213 z /= a.z;
214 return this;
215 }
216
217 /** this = this * s, returns this. */
218 public Vec3f scale(final float s) {
219 x *= s;
220 y *= s;
221 z *= s;
222 return this;
223 }
224
225 /** Returns this + arg; creates new vector */
226 public Vec3f plus(final Vec3f arg) {
227 return new Vec3f(this).add(arg);
228 }
229
230 /** this = a + b, returns this. */
231 public Vec3f plus(final Vec3f a, final Vec3f b) {
232 x = a.x + b.x;
233 y = a.y + b.y;
234 z = a.z + b.z;
235 return this;
236 }
237
238 /** this = this + { dx, dy, dz }, returns this. */
239 public Vec3f add(final float dx, final float dy, final float dz) {
240 x += dx;
241 y += dy;
242 z += dz;
243 return this;
244 }
245
246 /** this = this + b, returns this. */
247 public Vec3f add(final Vec3f b) {
248 x += b.x;
249 y += b.y;
250 z += b.z;
251 return this;
252 }
253
254 /** Returns this - arg; creates new vector */
255 public Vec3f minus(final Vec3f arg) {
256 return new Vec3f(this).sub(arg);
257 }
258
259 /** this = a - b, returns this. */
260 public Vec3f minus(final Vec3f a, final Vec3f b) {
261 x = a.x - b.x;
262 y = a.y - b.y;
263 z = a.z - b.z;
264 return this;
265 }
266
267 /** this = this - b, returns this. */
268 public Vec3f sub(final Vec3f b) {
269 x -= b.x;
270 y -= b.y;
271 z -= b.z;
272 return this;
273 }
274
275 /** Return true if all components are zero, i.e. it's absolute value < {@link #EPSILON}. */
276 public boolean isZero() {
277 return FloatUtil.isZero(x) && FloatUtil.isZero(y) && FloatUtil.isZero(z);
278 }
279
280 /**
281 * Return the length of this vector, a.k.a the <i>norm</i> or <i>magnitude</i>
282 */
283 public float length() {
284 return (float) Math.sqrt(lengthSq());
285 }
286
287 /**
288 * Return the squared length of this vector, a.k.a the squared <i>norm</i> or squared <i>magnitude</i>
289 */
290 public float lengthSq() {
291 return x*x + y*y + z*z;
292 }
293
294 /**
295 * Normalize this vector in place
296 */
297 public Vec3f normalize() {
298 final float lengthSq = lengthSq();
299 if ( FloatUtil.isZero( lengthSq ) ) {
300 x = 0.0f;
301 y = 0.0f;
302 z = 0.0f;
303 } else {
304 final float invSqr = 1.0f / (float)Math.sqrt(lengthSq);
305 x *= invSqr;
306 y *= invSqr;
307 z *= invSqr;
308 }
309 return this;
310 }
311
312 /**
313 * Return the squared distance between this vector and the given one.
314 * <p>
315 * When comparing the relative distance between two points it is usually sufficient to compare the squared
316 * distances, thus avoiding an expensive square root operation.
317 * </p>
318 */
319 public float distSq(final Vec3f o) {
320 final float dx = x - o.x;
321 final float dy = y - o.y;
322 final float dz = z - o.z;
323 return dx*dx + dy*dy + dz*dz;
324 }
325
326 /**
327 * Return the distance between this vector and the given one.
328 */
329 public float dist(final Vec3f o) {
330 return (float)Math.sqrt(distSq(o));
331 }
332
333
334 /**
335 * Return the dot product of this vector and the given one
336 * @return the dot product as float
337 */
338 public float dot(final Vec3f o) {
339 return x*o.x + y*o.y + z*o.z;
340 }
341
342 /** Returns this cross arg; creates new vector */
343 public Vec3f cross(final Vec3f arg) {
344 return new Vec3f().cross(this, arg);
345 }
346
347 /** this = a cross b. NOTE: "this" must be a different vector than
348 both a and b. */
349 public Vec3f cross(final Vec3f a, final Vec3f b) {
350 x = a.y * b.z - a.z * b.y;
351 y = a.z * b.x - a.x * b.z;
352 z = a.x * b.y - a.y * b.x;
353 return this;
354 }
355
356 /**
357 * Return the cosine of the angle between two vectors using {@link #dot(Vec3f)}
358 */
359 public float cosAngle(final Vec3f o) {
360 return dot(o) / ( length() * o.length() ) ;
361 }
362
363 /**
364 * Return the angle between two vectors in radians using {@link Math#acos(double)} on {@link #cosAngle(Vec3f)}.
365 */
366 public float angle(final Vec3f o) {
367 return (float) Math.acos( cosAngle(o) );
368 }
369
370 /**
371 * Equals check using a given {@link FloatUtil#EPSILON} value and {@link FloatUtil#isEqual(float, float, float)}.
372 * <p>
373 * Implementation considers following corner cases:
374 * <ul>
375 * <li>NaN == NaN</li>
376 * <li>+Inf == +Inf</li>
377 * <li>-Inf == -Inf</li>
378 * </ul>
379 * @param o comparison value
380 * @param epsilon consider using {@link FloatUtil#EPSILON}
381 * @return true if all components differ less than {@code epsilon}, otherwise false.
382 */
383 public boolean isEqual(final Vec3f o, final float epsilon) {
384 if( this == o ) {
385 return true;
386 } else {
387 return FloatUtil.isEqual(x, o.x, epsilon) &&
388 FloatUtil.isEqual(y, o.y, epsilon) &&
389 FloatUtil.isEqual(z, o.z, epsilon);
390 }
391 }
392
393 /**
394 * Equals check using {@link FloatUtil#EPSILON} in {@link FloatUtil#isEqual(float, float)}.
395 * <p>
396 * Implementation considers following corner cases:
397 * <ul>
398 * <li>NaN == NaN</li>
399 * <li>+Inf == +Inf</li>
400 * <li>-Inf == -Inf</li>
401 * </ul>
402 * @param o comparison value
403 * @return true if all components differ less than {@link FloatUtil#EPSILON}, otherwise false.
404 */
405 public boolean isEqual(final Vec3f o) {
406 if( this == o ) {
407 return true;
408 } else {
409 return FloatUtil.isEqual(x, o.x) &&
410 FloatUtil.isEqual(y, o.y) &&
411 FloatUtil.isEqual(z, o.z);
412 }
413 }
414
415 @Override
416 public boolean equals(final Object o) {
417 if( o instanceof Vec3f ) {
418 return isEqual((Vec3f)o);
419 } else {
420 return false;
421 }
422 }
423
424 @Override
425 public String toString() {
426 return x + " / " + y + " / " + z;
427 }
428}
Basic Float math utility functions.
Definition: FloatUtil.java:83
static boolean isZero(final float a, final float epsilon)
Returns true if value is zero, i.e.
static boolean isEqual(final float a, final float b, final float 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 float components.
Definition: Vec3f.java:37
float lengthSq()
Return the squared length of this vector, a.k.a the squared norm or squared magnitude
Definition: Vec3f.java:290
static final Vec3f ONE
Definition: Vec3f.java:38
Vec3f mul(final float val)
Returns this * val; creates new vector.
Definition: Vec3f.java:178
Vec3f mul(final Vec3f s)
this = this * s, returns this.
Definition: Vec3f.java:191
Vec3f div(final Vec3f a, final Vec3f b)
this = a / b, returns this.
Definition: Vec3f.java:202
static final Vec3f UNIT_X_NEG
Definition: Vec3f.java:40
float angle(final Vec3f o)
Return the angle between two vectors in radians using Math#acos(double) on cosAngle(Vec3f).
Definition: Vec3f.java:366
static final Vec3f UNIT_Y_NEG
Definition: Vec3f.java:42
void setX(final float x)
Definition: Vec3f.java:158
float cosAngle(final Vec3f o)
Return the cosine of the angle between two vectors using dot(Vec3f).
Definition: Vec3f.java:359
Vec3f scale(final float s)
this = this * s, returns this.
Definition: Vec3f.java:218
static final Vec3f UNIT_Z_NEG
Definition: Vec3f.java:44
boolean equals(final Object o)
Definition: Vec3f.java:416
Vec3f max(final Vec3f m)
this = max(this, m), returns this.
Definition: Vec3f.java:163
Vec3f(final float[] xyz)
Definition: Vec3f.java:70
Vec3f sub(final Vec3f b)
this = this - b, returns this.
Definition: Vec3f.java:268
Vec3f mul(final Vec3f a, final Vec3f b)
this = a * b, returns this.
Definition: Vec3f.java:183
boolean isZero()
Return true if all components are zero, i.e.
Definition: Vec3f.java:276
Vec3f div(final Vec3f a)
this = this / a, returns this.
Definition: Vec3f.java:210
Vec3f normalize()
Normalize this vector in place.
Definition: Vec3f.java:297
Vec3f plus(final Vec3f arg)
Returns this + arg; creates new vector.
Definition: Vec3f.java:226
Vec3f toArray(final float[] xyz)
xyz[0..2] = this.
Definition: Vec3f.java:119
Vec3f mul(final float sx, final float sy, final float sz)
this = this * { sx, sy, sz }, returns this.
Definition: Vec3f.java:194
float dot(final Vec3f o)
Return the dot product of this vector and the given one.
Definition: Vec3f.java:338
Vec3f(final Vec3f o)
Definition: Vec3f.java:52
Vec3f(final Vec2f o, final float z)
Creating new Vec3f using { Vec2f, z}.
Definition: Vec3f.java:62
boolean isEqual(final Vec3f o, final float epsilon)
Equals check using a given FloatUtil#EPSILON value and FloatUtil#isEqual(float, float,...
Definition: Vec3f.java:383
float distSq(final Vec3f o)
Return the squared distance between this vector and the given one.
Definition: Vec3f.java:319
void setZ(final float z)
Definition: Vec3f.java:160
Vec3f(final Vec4f o)
Creating new Vec3f using Vec4f, dropping w.
Definition: Vec3f.java:57
Vec3f(final float x, final float y, final float z)
Definition: Vec3f.java:74
Vec3f cross(final Vec3f a, final Vec3f b)
this = a cross b.
Definition: Vec3f.java:349
float dist(final Vec3f o)
Return the distance between this vector and the given one.
Definition: Vec3f.java:329
float length()
Return the length of this vector, a.k.a the norm or magnitude
Definition: Vec3f.java:283
static final Vec3f UNIT_X
Definition: Vec3f.java:39
boolean isEqual(final Vec3f o)
Equals check using FloatUtil#EPSILON in FloatUtil#isEqual(float, float).
Definition: Vec3f.java:405
Vec3f minus(final Vec3f a, final Vec3f b)
this = a - b, returns this.
Definition: Vec3f.java:260
Vec3f minus(final Vec3f arg)
Returns this - arg; creates new vector.
Definition: Vec3f.java:255
Vec3f cross(final Vec3f arg)
Returns this cross arg; creates new vector.
Definition: Vec3f.java:343
static final Vec3f UNIT_Z
Definition: Vec3f.java:43
void setY(final float y)
Definition: Vec3f.java:159
Vec3f add(final Vec3f b)
this = this + b, returns this.
Definition: Vec3f.java:247
Vec3f min(final Vec3f m)
this = min(this, m), returns this.
Definition: Vec3f.java:170
static final Vec3f UNIT_Y
Definition: Vec3f.java:41
Vec3f add(final float dx, final float dy, final float dz)
this = this + { dx, dy, dz }, returns this.
Definition: Vec3f.java:239
Vec3f plus(final Vec3f a, final Vec3f b)
this = a + b, returns this.
Definition: Vec3f.java:231
4D Vector based upon four float components.
Definition: Vec4f.java:37