Debian Codegraph @

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

raw
1 // Copyright 2008 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 * @fileoverview Defines a 3-element vector class that can be used for
17 * coordinate math, useful for animation systems and point manipulation.
18 *
19 * Based heavily on code originally by:
20 * @author [email protected] (Shawn Brenneman)
21 */
22
23
24 goog.provide('goog.math.Vec3');
25
26 goog.require('goog.math');
27 goog.require('goog.math.Coordinate3');
28
29
30
31 /**
32 * Class for a three-dimensional vector object and assorted functions useful for
33 * manipulation.
34 *
35 * Inherits from goog.math.Coordinate3 so that a Vec3 may be passed in to any
36 * function that requires a Coordinate.
37 *
38 * @param {number} x The x value for the vector.
39 * @param {number} y The y value for the vector.
40 * @param {number} z The z value for the vector.
41 * @struct
42 * @constructor
43 * @extends {goog.math.Coordinate3}
44 */
45 goog.math.Vec3 = function(x, y, z) {
46 /**
47 * X-value
48 * @type {number}
49 */
50 this.x = x;
51
52 /**
53 * Y-value
54 * @type {number}
55 */
56 this.y = y;
57
58 /**
59 * Z-value
60 * @type {number}
61 */
62 this.z = z;
63 };
64 goog.inherits(goog.math.Vec3, goog.math.Coordinate3);
65
66
67 /**
68 * Generates a random unit vector.
69 *
70 * http://mathworld.wolfram.com/SpherePointPicking.html
71 * Using (6), (7), and (8) to generate coordinates.
72 * @return {!goog.math.Vec3} A random unit-length vector.
73 */
74 goog.math.Vec3.randomUnit = function() {
75 var theta = Math.random() * Math.PI * 2;
76 var phi = Math.random() * Math.PI * 2;
77
78 var z = Math.cos(phi);
79 var x = Math.sqrt(1 - z * z) * Math.cos(theta);
80 var y = Math.sqrt(1 - z * z) * Math.sin(theta);
81
82 return new goog.math.Vec3(x, y, z);
83 };
84
85
86 /**
87 * Generates a random vector inside the unit sphere.
88 *
89 * @return {!goog.math.Vec3} A random vector.
90 */
91 goog.math.Vec3.random = function() {
92 return goog.math.Vec3.randomUnit().scale(Math.random());
93 };
94
95
96 /**
97 * Returns a new Vec3 object from a given coordinate.
98 *
99 * @param {goog.math.Coordinate3} a The coordinate.
100 * @return {!goog.math.Vec3} A new vector object.
101 */
102 goog.math.Vec3.fromCoordinate3 = function(a) {
103 return new goog.math.Vec3(a.x, a.y, a.z);
104 };
105
106
107 /**
108 * Creates a new copy of this Vec3.
109 *
110 * @return {!goog.math.Vec3} A new vector with the same coordinates as this one.
111 * @override
112 */
113 goog.math.Vec3.prototype.clone = function() {
114 return new goog.math.Vec3(this.x, this.y, this.z);
115 };
116
117
118 /**
119 * Returns the magnitude of the vector measured from the origin.
120 *
121 * @return {number} The length of the vector.
122 */
123 goog.math.Vec3.prototype.magnitude = function() {
124 return Math.sqrt(this.x * this.x + this.y * this.y + this.z * this.z);
125 };
126
127
128 /**
129 * Returns the squared magnitude of the vector measured from the origin.
130 * NOTE(brenneman): Leaving out the square root is not a significant
131 * optimization in JavaScript.
132 *
133 * @return {number} The length of the vector, squared.
134 */
135 goog.math.Vec3.prototype.squaredMagnitude = function() {
136 return this.x * this.x + this.y * this.y + this.z * this.z;
137 };
138
139
140 /**
141 * Scales the current vector by a constant.
142 *
143 * @param {number} s The scale factor.
144 * @return {!goog.math.Vec3} This vector, scaled.
145 */
146 goog.math.Vec3.prototype.scale = function(s) {
147 this.x *= s;
148 this.y *= s;
149 this.z *= s;
150 return this;
151 };
152
153
154 /**
155 * Reverses the sign of the vector. Equivalent to scaling the vector by -1.
156 *
157 * @return {!goog.math.Vec3} This vector, inverted.
158 */
159 goog.math.Vec3.prototype.invert = function() {
160 this.x = -this.x;
161 this.y = -this.y;
162 this.z = -this.z;
163 return this;
164 };
165
166
167 /**
168 * Normalizes the current vector to have a magnitude of 1.
169 *
170 * @return {!goog.math.Vec3} This vector, normalized.
171 */
172 goog.math.Vec3.prototype.normalize = function() {
173 return this.scale(1 / this.magnitude());
174 };
175
176
177 /**
178 * Adds another vector to this vector in-place.
179 *
180 * @param {goog.math.Vec3} b The vector to add.
181 * @return {!goog.math.Vec3} This vector with {@code b} added.
182 */
183 goog.math.Vec3.prototype.add = function(b) {
184 this.x += b.x;
185 this.y += b.y;
186 this.z += b.z;
187 return this;
188 };
189
190
191 /**
192 * Subtracts another vector from this vector in-place.
193 *
194 * @param {goog.math.Vec3} b The vector to subtract.
195 * @return {!goog.math.Vec3} This vector with {@code b} subtracted.
196 */
197 goog.math.Vec3.prototype.subtract = function(b) {
198 this.x -= b.x;
199 this.y -= b.y;
200 this.z -= b.z;
201 return this;
202 };
203
204
205 /**
206 * Compares this vector with another for equality.
207 *
208 * @param {goog.math.Vec3} b The other vector.
209 * @return {boolean} True if this vector's x, y and z equal the given vector's
210 * x, y, and z, respectively.
211 */
212 goog.math.Vec3.prototype.equals = function(b) {
213 return this == b || !!b && this.x == b.x && this.y == b.y && this.z == b.z;
214 };
215
216
217 /**
218 * Returns the distance between two vectors.
219 *
220 * @param {goog.math.Vec3} a The first vector.
221 * @param {goog.math.Vec3} b The second vector.
222 * @return {number} The distance.
223 */
224 goog.math.Vec3.distance = goog.math.Coordinate3.distance;
225
226
227 /**
228 * Returns the squared distance between two vectors.
229 *
230 * @param {goog.math.Vec3} a The first vector.
231 * @param {goog.math.Vec3} b The second vector.
232 * @return {number} The squared distance.
233 */
234 goog.math.Vec3.squaredDistance = goog.math.Coordinate3.squaredDistance;
235
236
237 /**
238 * Compares vectors for equality.
239 *
240 * @param {goog.math.Vec3} a The first vector.
241 * @param {goog.math.Vec3} b The second vector.
242 * @return {boolean} True if the vectors have equal x, y, and z coordinates.
243 */
244 goog.math.Vec3.equals = goog.math.Coordinate3.equals;
245
246
247 /**
248 * Returns the sum of two vectors as a new Vec3.
249 *
250 * @param {goog.math.Vec3} a The first vector.
251 * @param {goog.math.Vec3} b The second vector.
252 * @return {!goog.math.Vec3} The sum vector.
253 */
254 goog.math.Vec3.sum = function(a, b) {
255 return new goog.math.Vec3(a.x + b.x, a.y + b.y, a.z + b.z);
256 };
257
258
259 /**
260 * Returns the difference of two vectors as a new Vec3.
261 *
262 * @param {goog.math.Vec3} a The first vector.
263 * @param {goog.math.Vec3} b The second vector.
264 * @return {!goog.math.Vec3} The difference vector.
265 */
266 goog.math.Vec3.difference = function(a, b) {
267 return new goog.math.Vec3(a.x - b.x, a.y - b.y, a.z - b.z);
268 };
269
270
271 /**
272 * Returns the dot-product of two vectors.
273 *
274 * @param {goog.math.Vec3} a The first vector.
275 * @param {goog.math.Vec3} b The second vector.
276 * @return {number} The dot-product of the two vectors.
277 */
278 goog.math.Vec3.dot = function(a, b) {
279 return a.x * b.x + a.y * b.y + a.z * b.z;
280 };
281
282
283 /**
284 * Returns the cross-product of two vectors.
285 *
286 * @param {goog.math.Vec3} a The first vector.
287 * @param {goog.math.Vec3} b The second vector.
288 * @return {!goog.math.Vec3} The cross-product of the two vectors.
289 */
290 goog.math.Vec3.cross = function(a, b) {
291 return new goog.math.Vec3(
292 a.y * b.z - a.z * b.y, a.z * b.x - a.x * b.z, a.x * b.y - a.y * b.x);
293 };
294
295
296 /**
297 * Returns a new Vec3 that is the linear interpolant between vectors a and b at
298 * scale-value x.
299 *
300 * @param {goog.math.Vec3} a Vector a.
301 * @param {goog.math.Vec3} b Vector b.
302 * @param {number} x The proportion between a and b.
303 * @return {!goog.math.Vec3} The interpolated vector.
304 */
305 goog.math.Vec3.lerp = function(a, b, x) {
306 return new goog.math.Vec3(
307 goog.math.lerp(a.x, b.x, x), goog.math.lerp(a.y, b.y, x),
308 goog.math.lerp(a.z, b.z, x));
309 };
310
311
312 /**
313 * Returns a new Vec3 that is a copy of the vector a, but rescaled by a factor s
314 * in all dimensions.
315 * @param {!goog.math.Vec3} a Vector a.
316 * @param {number} s Scale factor.
317 * @return {!goog.math.Vec3} A new rescaled vector.
318 */
319 goog.math.Vec3.rescaled = function(a, s) {
320 return new goog.math.Vec3(a.x * s, a.y * s, a.z * s);
321 };