Debian Codegraph @

closure-library/closure/goog/vec/vec3.js

raw
1 // Copyright 2011 The Closure Library Authors. All Rights Reserved.
2 //
3 // Licensed under the Apache License, Version 2.0 (the "License");
4 // you may not use this file except in compliance with the License.
5 // You may obtain a copy of the License at
6 //
7 // http://www.apache.org/licenses/LICENSE-2.0
8 //
9 // Unless required by applicable law or agreed to in writing, software
10 // distributed under the License is distributed on an "AS-IS" BASIS,
11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12 // See the License for the specific language governing permissions and
13 // limitations under the License.
14
15
16 /**
17 * @fileoverview Supplies 3 element vectors that are compatible with WebGL.
18 * Each element is a float32 since that is typically the desired size of a
19 * 3-vector in the GPU. The API is structured to avoid unnecessary memory
20 * allocations. The last parameter will typically be the output vector and
21 * an object can be both an input and output parameter to all methods except
22 * where noted.
23 *
24 */
25 goog.provide('goog.vec.Vec3');
26
27 /** @suppress {extraRequire} */
28 goog.require('goog.vec');
29
30 /** @typedef {goog.vec.Float32} */ goog.vec.Vec3.Float32;
31 /** @typedef {goog.vec.Float64} */ goog.vec.Vec3.Float64;
32 /** @typedef {goog.vec.Number} */ goog.vec.Vec3.Number;
33 /** @typedef {goog.vec.AnyType} */ goog.vec.Vec3.AnyType;
34
35 // The following two types are deprecated - use the above types instead.
36 /** @typedef {Float32Array} */ goog.vec.Vec3.Type;
37 /** @typedef {goog.vec.ArrayType} */ goog.vec.Vec3.Vec3Like;
38
39
40 /**
41 * Creates a 3 element vector of Float32. The array is initialized to zero.
42 *
43 * @return {!goog.vec.Vec3.Float32} The new 3 element array.
44 */
45 goog.vec.Vec3.createFloat32 = function() {
46 return new Float32Array(3);
47 };
48
49
50 /**
51 * Creates a 3 element vector of Float64. The array is initialized to zero.
52 *
53 * @return {!goog.vec.Vec3.Float64} The new 3 element array.
54 */
55 goog.vec.Vec3.createFloat64 = function() {
56 return new Float64Array(3);
57 };
58
59
60 /**
61 * Creates a 3 element vector of Number. The array is initialized to zero.
62 *
63 * @return {!goog.vec.Vec3.Number} The new 3 element array.
64 */
65 goog.vec.Vec3.createNumber = function() {
66 var a = new Array(3);
67 goog.vec.Vec3.setFromValues(a, 0, 0, 0);
68 return a;
69 };
70
71
72 /**
73 * Creates a 3 element vector of Float32Array. The array is initialized to zero.
74 *
75 * @deprecated Use createFloat32.
76 * @return {!goog.vec.Vec3.Type} The new 3 element array.
77 */
78 goog.vec.Vec3.create = function() {
79 return new Float32Array(3);
80 };
81
82
83 /**
84 * Creates a new 3 element Float32 vector initialized with the value from the
85 * given array.
86 *
87 * @param {goog.vec.Vec3.AnyType} vec The source 3 element array.
88 * @return {!goog.vec.Vec3.Float32} The new 3 element array.
89 */
90 goog.vec.Vec3.createFloat32FromArray = function(vec) {
91 var newVec = goog.vec.Vec3.createFloat32();
92 goog.vec.Vec3.setFromArray(newVec, vec);
93 return newVec;
94 };
95
96
97 /**
98 * Creates a new 3 element Float32 vector initialized with the supplied values.
99 *
100 * @param {number} v0 The value for element at index 0.
101 * @param {number} v1 The value for element at index 1.
102 * @param {number} v2 The value for element at index 2.
103 * @return {!goog.vec.Vec3.Float32} The new vector.
104 */
105 goog.vec.Vec3.createFloat32FromValues = function(v0, v1, v2) {
106 var a = goog.vec.Vec3.createFloat32();
107 goog.vec.Vec3.setFromValues(a, v0, v1, v2);
108 return a;
109 };
110
111
112 /**
113 * Creates a clone of the given 3 element Float32 vector.
114 *
115 * @param {goog.vec.Vec3.Float32} vec The source 3 element vector.
116 * @return {!goog.vec.Vec3.Float32} The new cloned vector.
117 */
118 goog.vec.Vec3.cloneFloat32 = goog.vec.Vec3.createFloat32FromArray;
119
120
121 /**
122 * Creates a new 3 element Float64 vector initialized with the value from the
123 * given array.
124 *
125 * @param {goog.vec.Vec3.AnyType} vec The source 3 element array.
126 * @return {!goog.vec.Vec3.Float64} The new 3 element array.
127 */
128 goog.vec.Vec3.createFloat64FromArray = function(vec) {
129 var newVec = goog.vec.Vec3.createFloat64();
130 goog.vec.Vec3.setFromArray(newVec, vec);
131 return newVec;
132 };
133
134
135 /**
136 * Creates a new 3 element Float64 vector initialized with the supplied values.
137 *
138 * @param {number} v0 The value for element at index 0.
139 * @param {number} v1 The value for element at index 1.
140 * @param {number} v2 The value for element at index 2.
141 * @return {!goog.vec.Vec3.Float64} The new vector.
142 */
143 goog.vec.Vec3.createFloat64FromValues = function(v0, v1, v2) {
144 var vec = goog.vec.Vec3.createFloat64();
145 goog.vec.Vec3.setFromValues(vec, v0, v1, v2);
146 return vec;
147 };
148
149
150 /**
151 * Creates a clone of the given 3 element vector.
152 *
153 * @param {goog.vec.Vec3.Float64} vec The source 3 element vector.
154 * @return {!goog.vec.Vec3.Float64} The new cloned vector.
155 */
156 goog.vec.Vec3.cloneFloat64 = goog.vec.Vec3.createFloat64FromArray;
157
158
159 /**
160 * Creates a new 3 element vector initialized with the value from the given
161 * array.
162 *
163 * @deprecated Use createFloat32FromArray.
164 * @param {goog.vec.Vec3.Vec3Like} vec The source 3 element array.
165 * @return {!goog.vec.Vec3.Type} The new 3 element array.
166 */
167 goog.vec.Vec3.createFromArray = function(vec) {
168 var newVec = goog.vec.Vec3.create();
169 goog.vec.Vec3.setFromArray(newVec, vec);
170 return newVec;
171 };
172
173
174 /**
175 * Creates a new 3 element vector initialized with the supplied values.
176 *
177 * @deprecated Use createFloat32FromValues.
178 * @param {number} v0 The value for element at index 0.
179 * @param {number} v1 The value for element at index 1.
180 * @param {number} v2 The value for element at index 2.
181 * @return {!goog.vec.Vec3.Type} The new vector.
182 */
183 goog.vec.Vec3.createFromValues = function(v0, v1, v2) {
184 var vec = goog.vec.Vec3.create();
185 goog.vec.Vec3.setFromValues(vec, v0, v1, v2);
186 return vec;
187 };
188
189
190 /**
191 * Creates a clone of the given 3 element vector.
192 *
193 * @deprecated Use cloneFloat32.
194 * @param {goog.vec.Vec3.Vec3Like} vec The source 3 element vector.
195 * @return {!goog.vec.Vec3.Type} The new cloned vector.
196 */
197 goog.vec.Vec3.clone = function(vec) {
198 var newVec = goog.vec.Vec3.create();
199 goog.vec.Vec3.setFromArray(newVec, vec);
200 return newVec;
201 };
202
203
204 /**
205 * Initializes the vector with the given values.
206 *
207 * @param {goog.vec.Vec3.AnyType} vec The vector to receive the values.
208 * @param {number} v0 The value for element at index 0.
209 * @param {number} v1 The value for element at index 1.
210 * @param {number} v2 The value for element at index 2.
211 * @return {!goog.vec.Vec3.AnyType} Return vec so that operations can be
212 * chained together.
213 */
214 goog.vec.Vec3.setFromValues = function(vec, v0, v1, v2) {
215 vec[0] = v0;
216 vec[1] = v1;
217 vec[2] = v2;
218 return vec;
219 };
220
221
222 /**
223 * Initializes the vector with the given array of values.
224 *
225 * @param {goog.vec.Vec3.AnyType} vec The vector to receive the
226 * values.
227 * @param {goog.vec.Vec3.AnyType} values The array of values.
228 * @return {!goog.vec.Vec3.AnyType} Return vec so that operations can be
229 * chained together.
230 */
231 goog.vec.Vec3.setFromArray = function(vec, values) {
232 vec[0] = values[0];
233 vec[1] = values[1];
234 vec[2] = values[2];
235 return vec;
236 };
237
238
239 /**
240 * Performs a component-wise addition of vec0 and vec1 together storing the
241 * result into resultVec.
242 *
243 * @param {goog.vec.Vec3.AnyType} vec0 The first addend.
244 * @param {goog.vec.Vec3.AnyType} vec1 The second addend.
245 * @param {goog.vec.Vec3.AnyType} resultVec The vector to
246 * receive the result. May be vec0 or vec1.
247 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
248 * chained together.
249 */
250 goog.vec.Vec3.add = function(vec0, vec1, resultVec) {
251 resultVec[0] = vec0[0] + vec1[0];
252 resultVec[1] = vec0[1] + vec1[1];
253 resultVec[2] = vec0[2] + vec1[2];
254 return resultVec;
255 };
256
257
258 /**
259 * Performs a component-wise subtraction of vec1 from vec0 storing the
260 * result into resultVec.
261 *
262 * @param {goog.vec.Vec3.AnyType} vec0 The minuend.
263 * @param {goog.vec.Vec3.AnyType} vec1 The subtrahend.
264 * @param {goog.vec.Vec3.AnyType} resultVec The vector to
265 * receive the result. May be vec0 or vec1.
266 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
267 * chained together.
268 */
269 goog.vec.Vec3.subtract = function(vec0, vec1, resultVec) {
270 resultVec[0] = vec0[0] - vec1[0];
271 resultVec[1] = vec0[1] - vec1[1];
272 resultVec[2] = vec0[2] - vec1[2];
273 return resultVec;
274 };
275
276
277 /**
278 * Negates vec0, storing the result into resultVec.
279 *
280 * @param {goog.vec.Vec3.AnyType} vec0 The vector to negate.
281 * @param {goog.vec.Vec3.AnyType} resultVec The vector to
282 * receive the result. May be vec0.
283 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
284 * chained together.
285 */
286 goog.vec.Vec3.negate = function(vec0, resultVec) {
287 resultVec[0] = -vec0[0];
288 resultVec[1] = -vec0[1];
289 resultVec[2] = -vec0[2];
290 return resultVec;
291 };
292
293
294 /**
295 * Takes the absolute value of each component of vec0 storing the result in
296 * resultVec.
297 *
298 * @param {goog.vec.Vec3.AnyType} vec0 The source vector.
299 * @param {goog.vec.Vec3.AnyType} resultVec The vector to receive the result.
300 * May be vec0.
301 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
302 * chained together.
303 */
304 goog.vec.Vec3.abs = function(vec0, resultVec) {
305 resultVec[0] = Math.abs(vec0[0]);
306 resultVec[1] = Math.abs(vec0[1]);
307 resultVec[2] = Math.abs(vec0[2]);
308 return resultVec;
309 };
310
311
312 /**
313 * Multiplies each component of vec0 with scalar storing the product into
314 * resultVec.
315 *
316 * @param {goog.vec.Vec3.AnyType} vec0 The source vector.
317 * @param {number} scalar The value to multiply with each component of vec0.
318 * @param {goog.vec.Vec3.AnyType} resultVec The vector to
319 * receive the result. May be vec0.
320 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
321 * chained together.
322 */
323 goog.vec.Vec3.scale = function(vec0, scalar, resultVec) {
324 resultVec[0] = vec0[0] * scalar;
325 resultVec[1] = vec0[1] * scalar;
326 resultVec[2] = vec0[2] * scalar;
327 return resultVec;
328 };
329
330
331 /**
332 * Returns the magnitudeSquared of the given vector.
333 *
334 * @param {goog.vec.Vec3.AnyType} vec0 The vector.
335 * @return {number} The magnitude of the vector.
336 */
337 goog.vec.Vec3.magnitudeSquared = function(vec0) {
338 var x = vec0[0], y = vec0[1], z = vec0[2];
339 return x * x + y * y + z * z;
340 };
341
342
343 /**
344 * Returns the magnitude of the given vector.
345 *
346 * @param {goog.vec.Vec3.AnyType} vec0 The vector.
347 * @return {number} The magnitude of the vector.
348 */
349 goog.vec.Vec3.magnitude = function(vec0) {
350 var x = vec0[0], y = vec0[1], z = vec0[2];
351 return Math.sqrt(x * x + y * y + z * z);
352 };
353
354
355 /**
356 * Normalizes the given vector storing the result into resultVec.
357 *
358 * @param {goog.vec.Vec3.AnyType} vec0 The vector to normalize.
359 * @param {goog.vec.Vec3.AnyType} resultVec The vector to
360 * receive the result. May be vec0.
361 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
362 * chained together.
363 */
364 goog.vec.Vec3.normalize = function(vec0, resultVec) {
365 var ilen = 1 / goog.vec.Vec3.magnitude(vec0);
366 resultVec[0] = vec0[0] * ilen;
367 resultVec[1] = vec0[1] * ilen;
368 resultVec[2] = vec0[2] * ilen;
369 return resultVec;
370 };
371
372
373 /**
374 * Returns the scalar product of vectors v0 and v1.
375 *
376 * @param {goog.vec.Vec3.AnyType} v0 The first vector.
377 * @param {goog.vec.Vec3.AnyType} v1 The second vector.
378 * @return {number} The scalar product.
379 */
380 goog.vec.Vec3.dot = function(v0, v1) {
381 return v0[0] * v1[0] + v0[1] * v1[1] + v0[2] * v1[2];
382 };
383
384
385 /**
386 * Computes the vector (cross) product of v0 and v1 storing the result into
387 * resultVec.
388 *
389 * @param {goog.vec.Vec3.AnyType} v0 The first vector.
390 * @param {goog.vec.Vec3.AnyType} v1 The second vector.
391 * @param {goog.vec.Vec3.AnyType} resultVec The vector to receive the
392 * results. May be either v0 or v1.
393 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
394 * chained together.
395 */
396 goog.vec.Vec3.cross = function(v0, v1, resultVec) {
397 var x0 = v0[0], y0 = v0[1], z0 = v0[2];
398 var x1 = v1[0], y1 = v1[1], z1 = v1[2];
399 resultVec[0] = y0 * z1 - z0 * y1;
400 resultVec[1] = z0 * x1 - x0 * z1;
401 resultVec[2] = x0 * y1 - y0 * x1;
402 return resultVec;
403 };
404
405
406 /**
407 * Returns the squared distance between two points.
408 *
409 * @param {goog.vec.Vec3.AnyType} vec0 First point.
410 * @param {goog.vec.Vec3.AnyType} vec1 Second point.
411 * @return {number} The squared distance between the points.
412 */
413 goog.vec.Vec3.distanceSquared = function(vec0, vec1) {
414 var x = vec0[0] - vec1[0];
415 var y = vec0[1] - vec1[1];
416 var z = vec0[2] - vec1[2];
417 return x * x + y * y + z * z;
418 };
419
420
421 /**
422 * Returns the distance between two points.
423 *
424 * @param {goog.vec.Vec3.AnyType} vec0 First point.
425 * @param {goog.vec.Vec3.AnyType} vec1 Second point.
426 * @return {number} The distance between the points.
427 */
428 goog.vec.Vec3.distance = function(vec0, vec1) {
429 return Math.sqrt(goog.vec.Vec3.distanceSquared(vec0, vec1));
430 };
431
432
433 /**
434 * Returns a unit vector pointing from one point to another.
435 * If the input points are equal then the result will be all zeros.
436 *
437 * @param {goog.vec.Vec3.AnyType} vec0 Origin point.
438 * @param {goog.vec.Vec3.AnyType} vec1 Target point.
439 * @param {goog.vec.Vec3.AnyType} resultVec The vector to receive the
440 * results (may be vec0 or vec1).
441 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
442 * chained together.
443 */
444 goog.vec.Vec3.direction = function(vec0, vec1, resultVec) {
445 var x = vec1[0] - vec0[0];
446 var y = vec1[1] - vec0[1];
447 var z = vec1[2] - vec0[2];
448 var d = Math.sqrt(x * x + y * y + z * z);
449 if (d) {
450 d = 1 / d;
451 resultVec[0] = x * d;
452 resultVec[1] = y * d;
453 resultVec[2] = z * d;
454 } else {
455 resultVec[0] = resultVec[1] = resultVec[2] = 0;
456 }
457 return resultVec;
458 };
459
460
461 /**
462 * Linearly interpolate from vec0 to v1 according to f. The value of f should be
463 * in the range [0..1] otherwise the results are undefined.
464 *
465 * @param {goog.vec.Vec3.AnyType} v0 The first vector.
466 * @param {goog.vec.Vec3.AnyType} v1 The second vector.
467 * @param {number} f The interpolation factor.
468 * @param {goog.vec.Vec3.AnyType} resultVec The vector to receive the
469 * results (may be v0 or v1).
470 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
471 * chained together.
472 */
473 goog.vec.Vec3.lerp = function(v0, v1, f, resultVec) {
474 var x = v0[0], y = v0[1], z = v0[2];
475 resultVec[0] = (v1[0] - x) * f + x;
476 resultVec[1] = (v1[1] - y) * f + y;
477 resultVec[2] = (v1[2] - z) * f + z;
478 return resultVec;
479 };
480
481
482 /**
483 * Compares the components of vec0 with the components of another vector or
484 * scalar, storing the larger values in resultVec.
485 *
486 * @param {goog.vec.Vec3.AnyType} vec0 The source vector.
487 * @param {goog.vec.Vec3.AnyType|number} limit The limit vector or scalar.
488 * @param {goog.vec.Vec3.AnyType} resultVec The vector to receive the
489 * results (may be vec0 or limit).
490 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
491 * chained together.
492 */
493 goog.vec.Vec3.max = function(vec0, limit, resultVec) {
494 if (goog.isNumber(limit)) {
495 resultVec[0] = Math.max(vec0[0], limit);
496 resultVec[1] = Math.max(vec0[1], limit);
497 resultVec[2] = Math.max(vec0[2], limit);
498 } else {
499 resultVec[0] = Math.max(vec0[0], limit[0]);
500 resultVec[1] = Math.max(vec0[1], limit[1]);
501 resultVec[2] = Math.max(vec0[2], limit[2]);
502 }
503 return resultVec;
504 };
505
506
507 /**
508 * Compares the components of vec0 with the components of another vector or
509 * scalar, storing the smaller values in resultVec.
510 *
511 * @param {goog.vec.Vec3.AnyType} vec0 The source vector.
512 * @param {goog.vec.Vec3.AnyType|number} limit The limit vector or scalar.
513 * @param {goog.vec.Vec3.AnyType} resultVec The vector to receive the
514 * results (may be vec0 or limit).
515 * @return {!goog.vec.Vec3.AnyType} Return resultVec so that operations can be
516 * chained together.
517 */
518 goog.vec.Vec3.min = function(vec0, limit, resultVec) {
519 if (goog.isNumber(limit)) {
520 resultVec[0] = Math.min(vec0[0], limit);
521 resultVec[1] = Math.min(vec0[1], limit);
522 resultVec[2] = Math.min(vec0[2], limit);
523 } else {
524 resultVec[0] = Math.min(vec0[0], limit[0]);
525 resultVec[1] = Math.min(vec0[1], limit[1]);
526 resultVec[2] = Math.min(vec0[2], limit[2]);
527 }
528 return resultVec;
529 };
530
531
532 /**
533 * Returns true if the components of v0 are equal to the components of v1.
534 *
535 * @param {goog.vec.Vec3.AnyType} v0 The first vector.
536 * @param {goog.vec.Vec3.AnyType} v1 The second vector.
537 * @return {boolean} True if the vectors are equal, false otherwise.
538 */
539 goog.vec.Vec3.equals = function(v0, v1) {
540 return v0.length == v1.length && v0[0] == v1[0] && v0[1] == v1[1] &&
541 v0[2] == v1[2];
542 };