1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
|
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<base href="../../../" />
<script src="list.js"></script>
<script src="page.js"></script>
<link type="text/css" rel="stylesheet" href="page.css" />
</head>
<body>
<h1>[name]</h1>
<p class="desc">
A class representing a 4x4 [link:https://en.wikipedia.org/wiki/Matrix_(mathematics) matrix].<br /><br />
The most common use of a 4x4 matrix in 3D computer graphics is as a
[link:https://en.wikipedia.org/wiki/Transformation_matrix Transformation Matrix].
For an introduction to transformation matrices as used in WebGL, check out
[link:http://www.opengl-tutorial.org/beginners-tutorials/tutorial-3-matrices this tutorial].<br /><br />
This allows a [page:Vector3] representing a point in 3D space to undergo transformations
such as translation, rotation, shear, scale, reflection, orthogonal or perspective projection
and so on, by being multiplied by the matrix. This is known as <em>applying</em>
the matrix to the vector.<br /><br />
Every [page:Object3D] has three associated Matrix4s:
<ul>
<li>
[page:Object3D.matrix]: This stores the local transform of the object. This is the object's transformation relative to its parent.
</li>
<li>
[page:Object3D.matrixWorld]: The global or world transform of the object. If the object has no parent, then this is identical to the local transform stored in [page:Object3D.matrix matrix].
</li>
<li>
[page:Object3D.modelViewMatrix]: This represents the object's transformation relative to the camera's coordinate system.
An object's modelViewMatrix is the object's matrixWorld pre-multiplied by the camera's matrixWorldInverse.
</li>
</ul>
[page:Camera Cameras] have two additional Matrix4s:
<ul>
<li>
[page:Camera.matrixWorldInverse]: The view matrix - the inverse of the Camera's [page:Object3D.matrixWorld matrixWorld].
</li>
<li>
[page:Camera.projectionMatrix]: Represents the information how to project the scene to clip space.
</li>
</ul>
Note: [page:Object3D.normalMatrix] is not a Matrix4, but a [page:Matrix3].
</p>
<h2>A Note on Row-Major and Column-Major Ordering</h2>
<p>
The [page:set]() method takes arguments in [link:https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order row-major]
order, while internally they are stored in the [page:.elements elements] array in column-major order.<br /><br />
This means that calling
<code>
var m = new THREE.Matrix4();
m.set( 11, 12, 13, 14,
21, 22, 23, 24,
31, 32, 33, 34,
41, 42, 43, 44 );
</code>
will result in the [page:.elements elements] array containing:
<code>
m.elements = [ 11, 21, 31, 41,
12, 22, 32, 42,
13, 23, 33, 43,
14, 24, 34, 44 ];
</code>
and internally all calculations are performed using column-major ordering. However, as the actual ordering
makes no difference mathematically and most people are used to thinking about matrices in row-major order,
the three.js documentation shows matrices in row-major order. Just bear in mind that if you are reading the source
code, you'll have to take the [link:https://en.wikipedia.org/wiki/Transpose transpose] of any matrices outlined here to make sense of the calculations.
</p>
<h2>Constructor</h2>
<h3>[name]()</h3>
<p>
Creates and initializes the [name] to the 4x4
[link:https://en.wikipedia.org/wiki/Identity_matrix identity matrix].
</p>
<h2>Properties</h2>
<h3>[property:Array elements]</h3>
<p>
A [link:https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major]
list of matrix values.
</p>
<h3>[property:Boolean isMatrix4]</h3>
<p>
Used to check whether this or derived classes are Matrix4s. Default is *true*.<br /><br />
You should not change this, as it used internally for optimisation.
</p>
<h2>Methods</h2>
<h3>[method:Array applyToBufferAttribute]( [param:BufferAttribute attribute] )</h3>
<p>
[page:BufferAttribute attribute] - An attribute of floats that represent 3D vectors.<br /><br />
Multiplies (applies) this matrix to every 3D vector in the [page:BufferAttribute attribute].
</p>
<h3>[method:Matrix4 clone]()</h3>
<p>Creates a new Matrix4 with identical [page:.elements elements] to this one.</p>
<h3>[method:this compose]( [param:Vector3 position], [param:Quaternion quaternion], [param:Vector3 scale] )</h3>
<p>
Sets this matrix to the transformation composed of [page:Vector3 position],
[page:Quaternion quaternion] and [page:Vector3 scale]. Internally this calls
[page:.makeRotationFromQuaternion makeRotationFromQuaternion]( [page:Quaternion quaternion] )
followed by [page:.scale scale]( [page:Vector3 scale] ), then finally
[page:.setPosition setPosition]( [page:Vector3 position] ).
</p>
<h3>[method:this copy]( [param:Matrix4 m] )</h3>
<p>Copies the [page:.elements elements] of matrix [page:Matrix4 m] into this matrix.</p>
<h3>[method:this copyPosition]( [param:Matrix4 m] )</h3>
<p>
Copies the translation component of the supplied matrix [page:Matrix4 m] into this
matrix's translation component.
</p>
<h3>[method:null decompose]( [param:Vector3 position], [param:Quaternion quaternion], [param:Vector3 scale] )</h3>
<p>
Decomposes this matrix into it's [page:Vector3 position], [page:Quaternion quaternion] and
[page:Vector3 scale] components.
</p>
<h3>[method:Float determinant]()</h3>
<p>
Computes and returns the
[link:https://en.wikipedia.org/wiki/Determinant determinant] of this matrix.<br /><br />
Based on the method outlined [link:http://www.euclideanspace.com/maths/algebra/matrix/functions/inverse/fourD/index.htm here].
</p>
<h3>[method:Boolean equals]( [param:Matrix4 m] )</h3>
<p>Return true if this matrix and [page:Matrix4 m] are equal.</p>
<h3>[method:this extractBasis]( [param:Vector3 xAxis], [param:Vector3 yAxis], [param:Vector3 zAxis] )</h3>
<p>
Extracts the [link:https://en.wikipedia.org/wiki/Basis_(linear_algebra) basis] of this
matrix into the three axis vectors provided. If this matrix is:
<code>
a, b, c, d,
e, f, g, h,
i, j, k, l,
m, n, o, p
</code>
then the [page:Vector3 xAxis], [page:Vector3 yAxis], [page:Vector3 zAxis] will be set to:
<code>
xAxis = (a, e, i)
yAxis = (b, f, j)
zAxis = (c, g, k)
</code>
</p>
<h3>[method:this extractRotation]( [param:Matrix4 m] )</h3>
<p>
Extracts the rotation component of the supplied matrix [page:Matrix4 m] into this matrix's
rotation component.
</p>
<h3>[method:this fromArray]( [param:Array array], [param:Integer offset] )</h3>
<p>
[page:Array array] - the array to read the elements from.<br />
[page:Integer offset] - ( optional ) offset into the array. Default is 0.<br /><br />
Sets the elements of this matrix based on an [page:Array array] in
[link:https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major] format.
</p>
<h3>[method:this getInverse]( [param:Matrix4 m], [param:Boolean throwOnDegenerate] )</h3>
<p>
[page:Matrix4 m] - the matrix to take the inverse of.<br />
[page:Boolean throwOnDegenerate] - (optional) If true, throw an error if the matrix is degenerate (not invertible).<br /><br />
Set this matrix to the [link:https://en.wikipedia.org/wiki/Invertible_matrix inverse] of the passed matrix [page:Matrix4 m],
using the method outlined [link:http://www.euclideanspace.com/maths/algebra/matrix/functions/inverse/fourD/index.htm here].
If [page:Boolean throwOnDegenerate] is not set and the matrix is not invertible, set this to the 4x4 identity matrix.
</p>
<h3>[method:Float getMaxScaleOnAxis]()</h3>
<p>Gets the maximum scale value of the 3 axes.</p>
<h3>[method:this identity]()</h3>
<p>Resets this matrix to the [link:https://en.wikipedia.org/wiki/Identity_matrix identity matrix].</p>
<h3>[method:this lookAt]( [param:Vector3 eye], [param:Vector3 center], [param:Vector3 up], )</h3>
<p>
Constructs a rotation matrix, looking from [page:Vector3 eye] towards [page:Vector3 center]
oriented by the [page:Vector3 up] vector.
</p>
<h3>[method:this makeRotationAxis]( [param:Vector3 axis], [param:Float theta] )</h3>
<p>
[page:Vector3 axis] — Rotation axis, should be normalized.<br />
[page:Float theta] — Rotation angle in radians.<br /><br />
Sets this matrix as rotation transform around [page:Vector3 axis] by [page:Float theta] radians.<br />
This is a somewhat controversial but mathematically sound alternative to rotating via [page:Quaternions].
See the discussion [link:https://www.gamedev.net/articles/programming/math-and-physics/do-we-really-need-quaternions-r1199 here].
</p>
<h3>[method:this makeBasis]( [param:Vector3 xAxis], [param:Vector3 yAxis], [param:Vector3 zAxis] )</h3>
<p>
Set this to the [link:https://en.wikipedia.org/wiki/Basis_(linear_algebra) basis] matrix consisting
of the three provided basis vectors:
<code>
xAxis.x, yAxis.x, zAxis.x, 0,
xAxis.y, yAxis.y, zAxis.y, 0,
xAxis.z, yAxis.z, zAxis.z, 0,
0, 0, 0, 1
</code>
</p>
<h3>[method:this makePerspective]( [param:Float left], [param:Float right], [param:Float top], [param:Float bottom], [param:Float near], [param:Float far] )</h3>
<p>
Creates a [link:https://en.wikipedia.org/wiki/3D_projection#Perspective_projection perspective projection] matrix.
This is used internally by [page:PerspectiveCamera.updateProjectionMatrix]()
</p>
<h3>[method:this makeOrthographic]( [param:Float left], [param:Float right], [param:Float top], [param:Float bottom], [param:Float near], [param:Float far] )</h3>
<p>
Creates an [link:https://en.wikipedia.org/wiki/Orthographic_projection orthographic projection] matrix.
This is used internally by [page:OrthographicCamera.updateProjectionMatrix]().
</p>
<h3>[method:this makeRotationFromEuler]( [param:Euler euler] )</h3>
<p>
Sets the rotation component (the upper left 3x3 matrix) of this matrix to the rotation specified by the given [page:Euler Euler Angle].
The rest of the matrix is set to the identity. Depending on the [page:Euler.order order] of the [page:Euler euler], there are six possible outcomes.
See [link:https://en.wikipedia.org/wiki/Euler_angles#Rotation_matrix this page] for a complete list.
</p>
<h3>[method:this makeRotationFromQuaternion]( [param:Quaternion q] )</h3>
<p>
Sets the rotation component of this matrix to the rotation specified by [page:Quaternion q], as outlined
[link:https://en.wikipedia.org/wiki/Rotation_matrix#Quaternion here].
The rest of the matrix is set to the identity. So, given [page:Quaternion q] = w + xi + yj + zk, the resulting matrix will be:
<code>
1-2y²-2z² 2xy-2zw 2xz+2yw 0
2xy+2zw 1-2x²-2z² 2yz-2xw 0
2xz-2yw 2yz+2xw 1-2x²-2y² 0
0 0 0 1
</code>
</p>
<h3>[method:this makeRotationX]( [param:Float theta] )</h3>
<p>
[page:Float theta] — Rotation angle in radians.<br /><br />
Sets this matrix as a rotational transformation around the X axis by [page:Float theta] (θ) radians.
The resulting matrix will be:
<code>
1 0 0 0
0 cos(θ) -sin(θ) 0
0 sin(θ) cos(θ) 0
0 0 0 1
</code>
</p>
<h3>[method:this makeRotationY]( [param:Float theta] )</h3>
<p>
[page:Float theta] — Rotation angle in radians.<br /><br />
Sets this matrix as a rotational transformation around the Y axis by [page:Float theta] (θ) radians.
The resulting matrix will be:
<code>
cos(θ) 0 sin(θ) 0
0 1 0 0
-sin(θ) 0 cos(θ) 0
0 0 0 1
</code>
</p>
<h3>[method:this makeRotationZ]( [param:Float theta] )</h3>
<p>
[page:Float theta] — Rotation angle in radians.<br /><br />
Sets this matrix as a rotational transformation around the Z axis by [page:Float theta] (θ) radians.
The resulting matrix will be:
<code>
cos(θ) -sin(θ) 0 0
sin(θ) cos(θ) 0 0
0 0 1 0
0 0 0 1
</code>
</p>
<h3>[method:this makeScale]( [param:Float x], [param:Float y], [param:Float z] )</h3>
<p>
[page:Float x] - the amount to scale in the X axis.<br />
[page:Float y] - the amount to scale in the Y axis.<br />
[page:Float z] - the amount to scale in the Z axis.<br /><br />
Sets this matrix as scale transform:
<code>
x, 0, 0, 0,
0, y, 0, 0,
0, 0, z, 0,
0, 0, 0, 1
</code>
</p>
<h3>[method:this makeShear]( [param:Float x], [param:Float y], [param:Float z] )</h3>
<p>
[page:Float x] - the amount to shear in the X axis.<br />
[page:Float y] - the amount to shear in the Y axis.<br />
[page:Float z] - the amount to shear in the Z axis.<br /><br />
Sets this matrix as a shear transform:
<code>
1, y, z, 0,
x, 1, z, 0,
x, y, 1, 0,
0, 0, 0, 1
</code>
</p>
<h3>[method:this makeTranslation]( [param:Float x], [param:Float y], [param:Float z] )</h3>
<p>
[page:Float x] - the amount to translate in the X axis.<br />
[page:Float y] - the amount to translate in the Y axis.<br />
[page:Float z] - the amount to translate in the Z axis.<br /><br />
Sets this matrix as a translation transform:
<code>
1, 0, 0, x,
0, 1, 0, y,
0, 0, 1, z,
0, 0, 0, 1
</code>
</p>
<h3>[method:this multiply]( [param:Matrix4 m] )</h3>
<p>Post-multiplies this matrix by [page:Matrix4 m].</p>
<h3>[method:this multiplyMatrices]( [param:Matrix4 a], [param:Matrix4 b] )</h3>
<p>Sets this matrix to [page:Matrix4 a] x [page:Matrix4 b].</p>
<h3>[method:this multiplyScalar]( [param:Float s] )</h3>
<p>Multiplies every component of the matrix by a scalar value [page:Float s].</p>
<h3>[method:this premultiply]( [param:Matrix4 m] )</h3>
<p>Pre-multiplies this matrix by [page:Matrix4 m].</p>
<h3>[method:this scale]( [param:Vector3 v] )</h3>
<p>Multiplies the columns of this matrix by vector [page:Vector3 v].</p>
<h3>[method:this set]( [param:Float n11], [param:Float n12], [param:Float n13], [param:Float n14], [param:Float n21], [param:Float n22], [param:Float n23], [param:Float n24], [param:Float n31], [param:Float n32], [param:Float n33], [param:Float n34], [param:Float n41], [param:Float n42], [param:Float n43], [param:Float n44] )</h3>
<p>
Set the [page:.elements elements] of this matrix to the supplied row-major values [page:Float n11],
[page:Float n12], ... [page:Float n44].
</p>
<h3>[method:this setPosition]( [param:Vector3 v] )</h3>
<h3>[method:this setPosition]( [param:Float x], [param:Float y], [param:Float z] ) // optional API</h3>
<p>
Sets the position component for this matrix from vector [page:Vector3 v], without affecting the
rest of the matrix - i.e. if the matrix is currently:
<code>
a, b, c, d,
e, f, g, h,
i, j, k, l,
m, n, o, p
</code>
This becomes:
<code>
a, b, c, v.x,
e, f, g, v.y,
i, j, k, v.z,
m, n, o, p
</code>
</p>
<h3>[method:Array toArray]( [param:Array array], [param:Integer offset] )</h3>
<p>
[page:Array array] - (optional) array to store the resulting vector in.<br />
[page:Integer offset] - (optional) offset in the array at which to put the result.<br /><br />
Writes the elements of this matrix to an array in
[link:https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major] format.
</p>
<h3>[method:this transpose]()</h3>
<p>[link:https://en.wikipedia.org/wiki/Transpose Transposes] this matrix.</p>
<h2>Source</h2>
<p>
[link:https://github.com/mrdoob/three.js/blob/master/src/[path].js src/[path].js]
</p>
</body>
</html>
|
