Flutter Engine
The Flutter Engine
Loading...
Searching...
No Matches
Public Member Functions | Static Public Member Functions | Public Attributes | List of all members
impeller::Matrix Struct Reference

A 4x4 matrix using column-major storage. More...

#include <matrix.h>

Public Member Functions

constexpr Matrix ()
 
constexpr Matrix (Scalar m0, Scalar m1, Scalar m2, Scalar m3, Scalar m4, Scalar m5, Scalar m6, Scalar m7, Scalar m8, Scalar m9, Scalar m10, Scalar m11, Scalar m12, Scalar m13, Scalar m14, Scalar m15)
 
 Matrix (const MatrixDecomposition &decomposition)
 
constexpr Matrix Basis () const
 The Matrix without its w components (without translation).
 
constexpr Matrix Translate (const Vector3 &t) const
 
constexpr Matrix Scale (const Vector3 &s) const
 
constexpr Matrix Multiply (const Matrix &o) const
 
constexpr Matrix Transpose () const
 
Matrix Invert () const
 
Scalar GetDeterminant () const
 
Scalar GetMaxBasisLength () const
 
constexpr Scalar GetMaxBasisLengthXY () const
 
constexpr Vector3 GetBasisX () const
 
constexpr Vector3 GetBasisY () const
 
constexpr Vector3 GetBasisZ () const
 
constexpr Vector3 GetScale () const
 
constexpr Scalar GetDirectionScale (Vector3 direction) const
 
constexpr bool IsAffine () const
 
constexpr bool HasPerspective2D () const
 
constexpr bool HasPerspective () const
 
constexpr bool IsAligned2D (Scalar tolerance=0) const
 
constexpr bool IsAligned (Scalar tolerance=0) const
 
constexpr bool IsIdentity () const
 
constexpr bool IsTranslationScaleOnly () const
 Returns true if the matrix has a scale-only basis and is non-projective. Note that an identity matrix meets this criteria.
 
std::optional< MatrixDecompositionDecompose () const
 
constexpr bool operator== (const Matrix &m) const
 
constexpr bool operator!= (const Matrix &m) const
 
Matrix operator+ (const Vector3 &t) const
 
Matrix operator- (const Vector3 &t) const
 
Matrix operator* (const Matrix &m) const
 
Matrix operator+ (const Matrix &m) const
 
constexpr Vector4 operator* (const Vector4 &v) const
 
constexpr Vector3 operator* (const Vector3 &v) const
 
constexpr Point operator* (const Point &v) const
 
constexpr Vector3 TransformHomogenous (const Point &v) const
 
constexpr Vector4 TransformDirection (const Vector4 &v) const
 
constexpr Vector3 TransformDirection (const Vector3 &v) const
 
constexpr Vector2 TransformDirection (const Vector2 &v) const
 
constexpr Quad Transform (const Quad &quad) const
 

Static Public Member Functions

static constexpr Matrix MakeColumn (Scalar m0, Scalar m1, Scalar m2, Scalar m3, Scalar m4, Scalar m5, Scalar m6, Scalar m7, Scalar m8, Scalar m9, Scalar m10, Scalar m11, Scalar m12, Scalar m13, Scalar m14, Scalar m15)
 
static constexpr Matrix MakeRow (Scalar m0, Scalar m1, Scalar m2, Scalar m3, Scalar m4, Scalar m5, Scalar m6, Scalar m7, Scalar m8, Scalar m9, Scalar m10, Scalar m11, Scalar m12, Scalar m13, Scalar m14, Scalar m15)
 
static constexpr Matrix MakeTranslation (const Vector3 &t)
 
static constexpr Matrix MakeScale (const Vector3 &s)
 
static constexpr Matrix MakeScale (const Vector2 &s)
 
static constexpr Matrix MakeSkew (Scalar sx, Scalar sy)
 
static Matrix MakeRotation (Quaternion q)
 
static Matrix MakeRotation (Radians radians, const Vector4 &r)
 
static Matrix MakeRotationX (Radians r)
 
static Matrix MakeRotationY (Radians r)
 
static Matrix MakeRotationZ (Radians r)
 
template<class T >
static constexpr Matrix MakeOrthographic (TSize< T > size)
 
static constexpr Matrix MakePerspective (Radians fov_y, Scalar aspect_ratio, Scalar z_near, Scalar z_far)
 
template<class T >
static constexpr Matrix MakePerspective (Radians fov_y, TSize< T > size, Scalar z_near, Scalar z_far)
 
static constexpr Matrix MakeLookAt (Vector3 position, Vector3 target, Vector3 up)
 

Public Attributes

union { 
 
   Scalar   m [16] 
 
   Scalar   e [4][4] 
 
   Vector4   vec [4] 
 
};  
 

Detailed Description

A 4x4 matrix using column-major storage.

        Utility methods that need to make assumptions about normalized
        device coordinates must use the following convention:
          * Left-handed coordinate system. Positive rotation is
            clockwise about axis of rotation.
          * Lower left corner is -1.0f, -1.0.
          * Upper right corner is  1.0f,  1.0.
          * Visible z-space is from 0.0 to 1.0.
            * This is NOT the same as OpenGL! Be careful.
          * NDC origin is at (0.0f, 0.0f, 0.5f). 

Definition at line 37 of file matrix.h.

Constructor & Destructor Documentation

◆ Matrix() [1/3]

constexpr impeller::Matrix::Matrix ( )
inlineconstexpr

Constructs a default identity matrix.

Definition at line 47 of file matrix.h.

49 : vec{ Vector4(1.0f, 0.0f, 0.0f, 0.0f),
50 Vector4(0.0f, 1.0f, 0.0f, 0.0f),
51 Vector4(0.0f, 0.0f, 1.0f, 0.0f),
52 Vector4(0.0f, 0.0f, 0.0f, 1.0f)} {}
Vector4 vec[4]
Definition matrix.h:41

◆ Matrix() [2/3]

constexpr impeller::Matrix::Matrix ( Scalar  m0,
Scalar  m1,
Scalar  m2,
Scalar  m3,
Scalar  m4,
Scalar  m5,
Scalar  m6,
Scalar  m7,
Scalar  m8,
Scalar  m9,
Scalar  m10,
Scalar  m11,
Scalar  m12,
Scalar  m13,
Scalar  m14,
Scalar  m15 
)
inlineconstexpr

Definition at line 56 of file matrix.h.

60 : vec{Vector4(m0, m1, m2, m3),
61 Vector4(m4, m5, m6, m7),
62 Vector4(m8, m9, m10, m11),
63 Vector4(m12, m13, m14, m15)} {}

◆ Matrix() [3/3]

impeller::Matrix::Matrix ( const MatrixDecomposition decomposition)
explicit

Definition at line 12 of file matrix.cc.

12 : Matrix() {
13 /*
14 * Apply perspective.
15 */
16 for (int i = 0; i < 4; i++) {
17 e[i][3] = d.perspective.e[i];
18 }
19
20 /*
21 * Apply translation.
22 */
23 for (int i = 0; i < 3; i++) {
24 for (int j = 0; j < 3; j++) {
25 e[3][i] += d.translation.e[j] * e[j][i];
26 }
27 }
28
29 /*
30 * Apply rotation.
31 */
32
33 Matrix rotation;
34
35 const auto x = -d.rotation.x;
36 const auto y = -d.rotation.y;
37 const auto z = -d.rotation.z;
38 const auto w = d.rotation.w;
39
40 /*
41 * Construct a composite rotation matrix from the quaternion values.
42 */
43
44 rotation.e[0][0] = 1.0 - 2.0 * (y * y + z * z);
45 rotation.e[0][1] = 2.0 * (x * y - z * w);
46 rotation.e[0][2] = 2.0 * (x * z + y * w);
47 rotation.e[1][0] = 2.0 * (x * y + z * w);
48 rotation.e[1][1] = 1.0 - 2.0 * (x * x + z * z);
49 rotation.e[1][2] = 2.0 * (y * z - x * w);
50 rotation.e[2][0] = 2.0 * (x * z - y * w);
51 rotation.e[2][1] = 2.0 * (y * z + x * w);
52 rotation.e[2][2] = 1.0 - 2.0 * (x * x + y * y);
53
54 *this = *this * rotation;
55
56 /*
57 * Apply shear.
58 */
59 Matrix shear;
60
61 if (d.shear.e[2] != 0) {
62 shear.e[2][1] = d.shear.e[2];
63 *this = *this * shear;
64 }
65
66 if (d.shear.e[1] != 0) {
67 shear.e[2][1] = 0.0;
68 shear.e[2][0] = d.shear.e[1];
69 *this = *this * shear;
70 }
71
72 if (d.shear.e[0] != 0) {
73 shear.e[2][0] = 0.0;
74 shear.e[1][0] = d.shear.e[0];
75 *this = *this * shear;
76 }
77
78 /*
79 * Apply scale.
80 */
81 for (int i = 0; i < 3; i++) {
82 for (int j = 0; j < 3; j++) {
83 e[i][j] *= d.scale.e[i];
84 }
85 }
86}
VULKAN_HPP_DEFAULT_DISPATCH_LOADER_DYNAMIC_STORAGE auto & d
Definition main.cc:19
double y
double x
SkScalar w
constexpr Matrix()
Definition matrix.h:47
Scalar e[4][4]
Definition matrix.h:40

Member Function Documentation

◆ Basis()

constexpr Matrix impeller::Matrix::Basis ( ) const
inlineconstexpr

The Matrix without its w components (without translation).

Definition at line 229 of file matrix.h.

229 {
230 // clang-format off
231 return Matrix(
232 m[0], m[1], m[2], 0.0f,
233 m[4], m[5], m[6], 0.0f,
234 m[8], m[9], m[10], 0.0f,
235 0.0f, 0.0f, 0.0f, 1.0
236 );
237 // clang-format on
238 }
Scalar m[16]
Definition matrix.h:39

◆ Decompose()

std::optional< MatrixDecomposition > impeller::Matrix::Decompose ( ) const

Definition at line 209 of file matrix.cc.

209 {
210 /*
211 * Normalize the matrix.
212 */
213 Matrix self = *this;
214
215 if (self.e[3][3] == 0) {
216 return std::nullopt;
217 }
218
219 for (int i = 0; i < 4; i++) {
220 for (int j = 0; j < 4; j++) {
221 self.e[i][j] /= self.e[3][3];
222 }
223 }
224
225 /*
226 * `perspectiveMatrix` is used to solve for perspective, but it also provides
227 * an easy way to test for singularity of the upper 3x3 component.
228 */
229 Matrix perpectiveMatrix = self;
230 for (int i = 0; i < 3; i++) {
231 perpectiveMatrix.e[i][3] = 0;
232 }
233
234 perpectiveMatrix.e[3][3] = 1;
235
236 if (perpectiveMatrix.GetDeterminant() == 0.0) {
237 return std::nullopt;
238 }
239
240 MatrixDecomposition result;
241
242 /*
243 * ==========================================================================
244 * First, isolate perspective.
245 * ==========================================================================
246 */
247 if (self.e[0][3] != 0.0 || self.e[1][3] != 0.0 || self.e[2][3] != 0.0) {
248 /*
249 * prhs is the right hand side of the equation.
250 */
251 const Vector4 rightHandSide(self.e[0][3], //
252 self.e[1][3], //
253 self.e[2][3], //
254 self.e[3][3]);
255
256 /*
257 * Solve the equation by inverting `perspectiveMatrix` and multiplying
258 * prhs by the inverse.
259 */
260
261 result.perspective = perpectiveMatrix.Invert().Transpose() * rightHandSide;
262
263 /*
264 * Clear the perspective partition.
265 */
266 self.e[0][3] = self.e[1][3] = self.e[2][3] = 0;
267 self.e[3][3] = 1;
268 }
269
270 /*
271 * ==========================================================================
272 * Next, the translation.
273 * ==========================================================================
274 */
275 result.translation = {self.e[3][0], self.e[3][1], self.e[3][2]};
276 self.e[3][0] = self.e[3][1] = self.e[3][2] = 0.0;
277
278 /*
279 * ==========================================================================
280 * Next, the scale and shear.
281 * ==========================================================================
282 */
283 Vector3 row[3];
284 for (int i = 0; i < 3; i++) {
285 row[i].x = self.e[i][0];
286 row[i].y = self.e[i][1];
287 row[i].z = self.e[i][2];
288 }
289
290 /*
291 * Compute X scale factor and normalize first row.
292 */
293 result.scale.x = row[0].Length();
294 row[0] = row[0].Normalize();
295
296 /*
297 * Compute XY shear factor and make 2nd row orthogonal to 1st.
298 */
299 result.shear.xy = row[0].Dot(row[1]);
300 row[1] = Vector3::Combine(row[1], 1.0, row[0], -result.shear.xy);
301
302 /*
303 * Compute Y scale and normalize 2nd row.
304 */
305 result.scale.y = row[1].Length();
306 row[1] = row[1].Normalize();
307 result.shear.xy /= result.scale.y;
308
309 /*
310 * Compute XZ and YZ shears, orthogonalize 3rd row.
311 */
312 result.shear.xz = row[0].Dot(row[2]);
313 row[2] = Vector3::Combine(row[2], 1.0, row[0], -result.shear.xz);
314 result.shear.yz = row[1].Dot(row[2]);
315 row[2] = Vector3::Combine(row[2], 1.0, row[1], -result.shear.yz);
316
317 /*
318 * Next, get Z scale and normalize 3rd row.
319 */
320 result.scale.z = row[2].Length();
321 row[2] = row[2].Normalize();
322
323 result.shear.xz /= result.scale.z;
324 result.shear.yz /= result.scale.z;
325
326 /*
327 * At this point, the matrix (in rows[]) is orthonormal.
328 * Check for a coordinate system flip. If the determinant
329 * is -1, then negate the matrix and the scaling factors.
330 */
331 if (row[0].Dot(row[1].Cross(row[2])) < 0) {
332 result.scale.x *= -1;
333 result.scale.y *= -1;
334 result.scale.z *= -1;
335
336 for (int i = 0; i < 3; i++) {
337 row[i].x *= -1;
338 row[i].y *= -1;
339 row[i].z *= -1;
340 }
341 }
342
343 /*
344 * ==========================================================================
345 * Finally, get the rotations out.
346 * ==========================================================================
347 */
348 result.rotation.x =
349 0.5 * sqrt(fmax(1.0 + row[0].x - row[1].y - row[2].z, 0.0));
350 result.rotation.y =
351 0.5 * sqrt(fmax(1.0 - row[0].x + row[1].y - row[2].z, 0.0));
352 result.rotation.z =
353 0.5 * sqrt(fmax(1.0 - row[0].x - row[1].y + row[2].z, 0.0));
354 result.rotation.w =
355 0.5 * sqrt(fmax(1.0 + row[0].x + row[1].y + row[2].z, 0.0));
356
357 if (row[2].y > row[1].z) {
358 result.rotation.x = -result.rotation.x;
359 }
360 if (row[0].z > row[2].x) {
361 result.rotation.y = -result.rotation.y;
362 }
363 if (row[1].x > row[0].y) {
364 result.rotation.z = -result.rotation.z;
365 }
366
367 return result;
368}
GAsyncResult * result
SIN Vec< N, float > sqrt(const Vec< N, float > &x)
Definition SkVx.h:706
static constexpr Vector3 Combine(const Vector3 &a, Scalar aScale, const Vector3 &b, Scalar bScale)
Definition vector.h:192

◆ GetBasisX()

constexpr Vector3 impeller::Matrix::GetBasisX ( ) const
inlineconstexpr

Definition at line 305 of file matrix.h.

305{ return Vector3(m[0], m[1], m[2]); }

◆ GetBasisY()

constexpr Vector3 impeller::Matrix::GetBasisY ( ) const
inlineconstexpr

Definition at line 307 of file matrix.h.

307{ return Vector3(m[4], m[5], m[6]); }

◆ GetBasisZ()

constexpr Vector3 impeller::Matrix::GetBasisZ ( ) const
inlineconstexpr

Definition at line 309 of file matrix.h.

309{ return Vector3(m[8], m[9], m[10]); }

◆ GetDeterminant()

Scalar impeller::Matrix::GetDeterminant ( ) const

Definition at line 162 of file matrix.cc.

162 {
163 auto a00 = e[0][0];
164 auto a01 = e[0][1];
165 auto a02 = e[0][2];
166 auto a03 = e[0][3];
167 auto a10 = e[1][0];
168 auto a11 = e[1][1];
169 auto a12 = e[1][2];
170 auto a13 = e[1][3];
171 auto a20 = e[2][0];
172 auto a21 = e[2][1];
173 auto a22 = e[2][2];
174 auto a23 = e[2][3];
175 auto a30 = e[3][0];
176 auto a31 = e[3][1];
177 auto a32 = e[3][2];
178 auto a33 = e[3][3];
179
180 auto b00 = a00 * a11 - a01 * a10;
181 auto b01 = a00 * a12 - a02 * a10;
182 auto b02 = a00 * a13 - a03 * a10;
183 auto b03 = a01 * a12 - a02 * a11;
184 auto b04 = a01 * a13 - a03 * a11;
185 auto b05 = a02 * a13 - a03 * a12;
186 auto b06 = a20 * a31 - a21 * a30;
187 auto b07 = a20 * a32 - a22 * a30;
188 auto b08 = a20 * a33 - a23 * a30;
189 auto b09 = a21 * a32 - a22 * a31;
190 auto b10 = a21 * a33 - a23 * a31;
191 auto b11 = a22 * a33 - a23 * a32;
192
193 return b00 * b11 - b01 * b10 + b02 * b09 + b03 * b08 - b04 * b07 + b05 * b06;
194}

◆ GetDirectionScale()

constexpr Scalar impeller::Matrix::GetDirectionScale ( Vector3  direction) const
inlineconstexpr

Definition at line 316 of file matrix.h.

316 {
317 return 1.0f / (this->Basis().Invert() * direction.Normalize()).Length() *
318 direction.Length();
319 }
constexpr Matrix Basis() const
The Matrix without its w components (without translation).
Definition matrix.h:229
Matrix Invert() const
Definition matrix.cc:97

◆ GetMaxBasisLength()

Scalar impeller::Matrix::GetMaxBasisLength ( ) const

Definition at line 196 of file matrix.cc.

196 {
197 Scalar max = 0;
198 for (int i = 0; i < 3; i++) {
199 max = std::max(max,
200 e[i][0] * e[i][0] + e[i][1] * e[i][1] + e[i][2] * e[i][2]);
201 }
202 return std::sqrt(max);
203}
static float max(float r, float g, float b)
Definition hsl.cpp:49
float Scalar
Definition scalar.h:18

◆ GetMaxBasisLengthXY()

constexpr Scalar impeller::Matrix::GetMaxBasisLengthXY ( ) const
inlineconstexpr

Definition at line 300 of file matrix.h.

300 {
301 return std::sqrt(std::max(e[0][0] * e[0][0] + e[0][1] * e[0][1],
302 e[1][0] * e[1][0] + e[1][1] * e[1][1]));
303 }

◆ GetScale()

constexpr Vector3 impeller::Matrix::GetScale ( ) const
inlineconstexpr

Definition at line 311 of file matrix.h.

311 {
312 return Vector3(GetBasisX().Length(), GetBasisY().Length(),
313 GetBasisZ().Length());
314 }
constexpr Vector3 GetBasisY() const
Definition matrix.h:307
constexpr Vector3 GetBasisZ() const
Definition matrix.h:309
constexpr Vector3 GetBasisX() const
Definition matrix.h:305

◆ HasPerspective()

constexpr bool impeller::Matrix::HasPerspective ( ) const
inlineconstexpr

Definition at line 330 of file matrix.h.

330 {
331 return m[3] != 0 || m[7] != 0 || m[11] != 0 || m[15] != 1;
332 }

◆ HasPerspective2D()

constexpr bool impeller::Matrix::HasPerspective2D ( ) const
inlineconstexpr

Definition at line 326 of file matrix.h.

326 {
327 return m[3] != 0 || m[7] != 0 || m[15] != 1;
328 }

◆ Invert()

Matrix impeller::Matrix::Invert ( ) const

Definition at line 97 of file matrix.cc.

97 {
98 Matrix tmp{
99 m[5] * m[10] * m[15] - m[5] * m[11] * m[14] - m[9] * m[6] * m[15] +
100 m[9] * m[7] * m[14] + m[13] * m[6] * m[11] - m[13] * m[7] * m[10],
101
102 -m[1] * m[10] * m[15] + m[1] * m[11] * m[14] + m[9] * m[2] * m[15] -
103 m[9] * m[3] * m[14] - m[13] * m[2] * m[11] + m[13] * m[3] * m[10],
104
105 m[1] * m[6] * m[15] - m[1] * m[7] * m[14] - m[5] * m[2] * m[15] +
106 m[5] * m[3] * m[14] + m[13] * m[2] * m[7] - m[13] * m[3] * m[6],
107
108 -m[1] * m[6] * m[11] + m[1] * m[7] * m[10] + m[5] * m[2] * m[11] -
109 m[5] * m[3] * m[10] - m[9] * m[2] * m[7] + m[9] * m[3] * m[6],
110
111 -m[4] * m[10] * m[15] + m[4] * m[11] * m[14] + m[8] * m[6] * m[15] -
112 m[8] * m[7] * m[14] - m[12] * m[6] * m[11] + m[12] * m[7] * m[10],
113
114 m[0] * m[10] * m[15] - m[0] * m[11] * m[14] - m[8] * m[2] * m[15] +
115 m[8] * m[3] * m[14] + m[12] * m[2] * m[11] - m[12] * m[3] * m[10],
116
117 -m[0] * m[6] * m[15] + m[0] * m[7] * m[14] + m[4] * m[2] * m[15] -
118 m[4] * m[3] * m[14] - m[12] * m[2] * m[7] + m[12] * m[3] * m[6],
119
120 m[0] * m[6] * m[11] - m[0] * m[7] * m[10] - m[4] * m[2] * m[11] +
121 m[4] * m[3] * m[10] + m[8] * m[2] * m[7] - m[8] * m[3] * m[6],
122
123 m[4] * m[9] * m[15] - m[4] * m[11] * m[13] - m[8] * m[5] * m[15] +
124 m[8] * m[7] * m[13] + m[12] * m[5] * m[11] - m[12] * m[7] * m[9],
125
126 -m[0] * m[9] * m[15] + m[0] * m[11] * m[13] + m[8] * m[1] * m[15] -
127 m[8] * m[3] * m[13] - m[12] * m[1] * m[11] + m[12] * m[3] * m[9],
128
129 m[0] * m[5] * m[15] - m[0] * m[7] * m[13] - m[4] * m[1] * m[15] +
130 m[4] * m[3] * m[13] + m[12] * m[1] * m[7] - m[12] * m[3] * m[5],
131
132 -m[0] * m[5] * m[11] + m[0] * m[7] * m[9] + m[4] * m[1] * m[11] -
133 m[4] * m[3] * m[9] - m[8] * m[1] * m[7] + m[8] * m[3] * m[5],
134
135 -m[4] * m[9] * m[14] + m[4] * m[10] * m[13] + m[8] * m[5] * m[14] -
136 m[8] * m[6] * m[13] - m[12] * m[5] * m[10] + m[12] * m[6] * m[9],
137
138 m[0] * m[9] * m[14] - m[0] * m[10] * m[13] - m[8] * m[1] * m[14] +
139 m[8] * m[2] * m[13] + m[12] * m[1] * m[10] - m[12] * m[2] * m[9],
140
141 -m[0] * m[5] * m[14] + m[0] * m[6] * m[13] + m[4] * m[1] * m[14] -
142 m[4] * m[2] * m[13] - m[12] * m[1] * m[6] + m[12] * m[2] * m[5],
143
144 m[0] * m[5] * m[10] - m[0] * m[6] * m[9] - m[4] * m[1] * m[10] +
145 m[4] * m[2] * m[9] + m[8] * m[1] * m[6] - m[8] * m[2] * m[5]};
146
147 Scalar det =
148 m[0] * tmp.m[0] + m[1] * tmp.m[4] + m[2] * tmp.m[8] + m[3] * tmp.m[12];
149
150 if (det == 0) {
151 return {};
152 }
153
154 det = 1.0 / det;
155
156 return {tmp.m[0] * det, tmp.m[1] * det, tmp.m[2] * det, tmp.m[3] * det,
157 tmp.m[4] * det, tmp.m[5] * det, tmp.m[6] * det, tmp.m[7] * det,
158 tmp.m[8] * det, tmp.m[9] * det, tmp.m[10] * det, tmp.m[11] * det,
159 tmp.m[12] * det, tmp.m[13] * det, tmp.m[14] * det, tmp.m[15] * det};
160}

◆ IsAffine()

constexpr bool impeller::Matrix::IsAffine ( ) const
inlineconstexpr

Definition at line 321 of file matrix.h.

321 {
322 return (m[2] == 0 && m[3] == 0 && m[6] == 0 && m[7] == 0 && m[8] == 0 &&
323 m[9] == 0 && m[10] == 1 && m[11] == 0 && m[14] == 0 && m[15] == 1);
324 }

◆ IsAligned()

constexpr bool impeller::Matrix::IsAligned ( Scalar  tolerance = 0) const
inlineconstexpr

Definition at line 349 of file matrix.h.

349 {
350 if (HasPerspective()) {
351 return false;
352 }
353 int v[] = {!ScalarNearlyZero(m[0], tolerance), //
354 !ScalarNearlyZero(m[1], tolerance), //
355 !ScalarNearlyZero(m[2], tolerance), //
356 !ScalarNearlyZero(m[4], tolerance), //
357 !ScalarNearlyZero(m[5], tolerance), //
358 !ScalarNearlyZero(m[6], tolerance), //
359 !ScalarNearlyZero(m[8], tolerance), //
360 !ScalarNearlyZero(m[9], tolerance), //
361 !ScalarNearlyZero(m[10], tolerance)};
362 // Check if all three basis vectors are aligned to an axis.
363 if (v[0] + v[1] + v[2] != 1 || //
364 v[3] + v[4] + v[5] != 1 || //
365 v[6] + v[7] + v[8] != 1) {
366 return false;
367 }
368 // Ensure that none of the basis vectors overlap.
369 if (v[0] + v[3] + v[6] != 1 || //
370 v[1] + v[4] + v[7] != 1 || //
371 v[2] + v[5] + v[8] != 1) {
372 return false;
373 }
374 return true;
375 }
constexpr bool ScalarNearlyZero(Scalar x, Scalar tolerance=kEhCloseEnough)
Definition scalar.h:25
constexpr bool HasPerspective() const
Definition matrix.h:330

◆ IsAligned2D()

constexpr bool impeller::Matrix::IsAligned2D ( Scalar  tolerance = 0) const
inlineconstexpr

Definition at line 334 of file matrix.h.

334 {
335 if (HasPerspective2D()) {
336 return false;
337 }
338 if (ScalarNearlyZero(m[1], tolerance) &&
339 ScalarNearlyZero(m[4], tolerance)) {
340 return true;
341 }
342 if (ScalarNearlyZero(m[0], tolerance) &&
343 ScalarNearlyZero(m[5], tolerance)) {
344 return true;
345 }
346 return false;
347 }
constexpr bool HasPerspective2D() const
Definition matrix.h:326

◆ IsIdentity()

constexpr bool impeller::Matrix::IsIdentity ( ) const
inlineconstexpr

Definition at line 377 of file matrix.h.

377 {
378 return (
379 // clang-format off
380 m[0] == 1.0f && m[1] == 0.0f && m[2] == 0.0f && m[3] == 0.0f &&
381 m[4] == 0.0f && m[5] == 1.0f && m[6] == 0.0f && m[7] == 0.0f &&
382 m[8] == 0.0f && m[9] == 0.0f && m[10] == 1.0f && m[11] == 0.0f &&
383 m[12] == 0.0f && m[13] == 0.0f && m[14] == 0.0f && m[15] == 1.0f
384 // clang-format on
385 );
386 }

◆ IsTranslationScaleOnly()

constexpr bool impeller::Matrix::IsTranslationScaleOnly ( ) const
inlineconstexpr

Returns true if the matrix has a scale-only basis and is non-projective. Note that an identity matrix meets this criteria.

Definition at line 390 of file matrix.h.

390 {
391 return (
392 // clang-format off
393 m[0] != 0.0 && m[1] == 0.0 && m[2] == 0.0 && m[3] == 0.0 &&
394 m[4] == 0.0 && m[5] != 0.0 && m[6] == 0.0 && m[7] == 0.0 &&
395 m[8] == 0.0 && m[9] == 0.0 && m[10] != 0.0 && m[11] == 0.0 &&
396 m[15] == 1.0
397 // clang-format on
398 );
399 }

◆ MakeColumn()

static constexpr Matrix impeller::Matrix::MakeColumn ( Scalar  m0,
Scalar  m1,
Scalar  m2,
Scalar  m3,
Scalar  m4,
Scalar  m5,
Scalar  m6,
Scalar  m7,
Scalar  m8,
Scalar  m9,
Scalar  m10,
Scalar  m11,
Scalar  m12,
Scalar  m13,
Scalar  m14,
Scalar  m15 
)
inlinestaticconstexpr

Definition at line 69 of file matrix.h.

73 {
74 return Matrix(m0, m1, m2, m3,
75 m4, m5, m6, m7,
76 m8, m9, m10, m11,
77 m12, m13, m14, m15);
78
79 }

◆ MakeLookAt()

static constexpr Matrix impeller::Matrix::MakeLookAt ( Vector3  position,
Vector3  target,
Vector3  up 
)
inlinestaticconstexpr

Definition at line 530 of file matrix.h.

532 {
533 Vector3 forward = (target - position).Normalize();
534 Vector3 right = up.Cross(forward);
535 up = forward.Cross(right);
536
537 // clang-format off
538 return {
539 right.x, up.x, forward.x, 0.0f,
540 right.y, up.y, forward.y, 0.0f,
541 right.z, up.z, forward.z, 0.0f,
542 -right.Dot(position), -up.Dot(position), -forward.Dot(position), 1.0f
543 };
544 // clang-format on
545 }
static bool right(const SkPoint &p0, const SkPoint &p1)
uint32_t * target

◆ MakeOrthographic()

template<class T >
static constexpr Matrix impeller::Matrix::MakeOrthographic ( TSize< T size)
inlinestaticconstexpr

Definition at line 495 of file matrix.h.

495 {
496 // Per assumptions about NDC documented above.
497 const auto scale =
498 MakeScale({2.0f / static_cast<Scalar>(size.width),
499 -2.0f / static_cast<Scalar>(size.height), 0.0f});
500 const auto translate = MakeTranslation({-1.0f, 1.0f, 0.5f});
501 return translate * scale;
502 }
it will be possible to load the file into Perfetto s trace viewer disable asset Prevents usage of any non test fonts unless they were explicitly Loaded via prefetched default font Indicates whether the embedding started a prefetch of the default font manager before creating the engine run In non interactive keep the shell running after the Dart script has completed enable serial On low power devices with low core running concurrent GC tasks on threads can cause them to contend with the UI thread which could potentially lead to jank This option turns off all concurrent GC activities domain network JSON encoded network policy per domain This overrides the DisallowInsecureConnections switch Embedder can specify whether to allow or disallow insecure connections at a domain level old gen heap size
Definition switches.h:259
const Scalar scale
static constexpr Matrix MakeTranslation(const Vector3 &t)
Definition matrix.h:95
static constexpr Matrix MakeScale(const Vector3 &s)
Definition matrix.h:104

◆ MakePerspective() [1/2]

static constexpr Matrix impeller::Matrix::MakePerspective ( Radians  fov_y,
Scalar  aspect_ratio,
Scalar  z_near,
Scalar  z_far 
)
inlinestaticconstexpr

Definition at line 504 of file matrix.h.

507 {
508 Scalar height = std::tan(fov_y.radians * 0.5f);
509 Scalar width = height * aspect_ratio;
510
511 // clang-format off
512 return {
513 1.0f / width, 0.0f, 0.0f, 0.0f,
514 0.0f, 1.0f / height, 0.0f, 0.0f,
515 0.0f, 0.0f, z_far / (z_far - z_near), 1.0f,
516 0.0f, 0.0f, -(z_far * z_near) / (z_far - z_near), 0.0f,
517 };
518 // clang-format on
519 }
int32_t height
int32_t width

◆ MakePerspective() [2/2]

template<class T >
static constexpr Matrix impeller::Matrix::MakePerspective ( Radians  fov_y,
TSize< T size,
Scalar  z_near,
Scalar  z_far 
)
inlinestaticconstexpr

Definition at line 522 of file matrix.h.

525 {
526 return MakePerspective(fov_y, static_cast<Scalar>(size.width) / size.height,
527 z_near, z_far);
528 }
static constexpr Matrix MakePerspective(Radians fov_y, Scalar aspect_ratio, Scalar z_near, Scalar z_far)
Definition matrix.h:504

◆ MakeRotation() [1/2]

static Matrix impeller::Matrix::MakeRotation ( Quaternion  q)
inlinestatic

Definition at line 126 of file matrix.h.

126 {
127 // clang-format off
128 return Matrix(
129 1.0f - 2.0f * q.y * q.y - 2.0f * q.z * q.z,
130 2.0f * q.x * q.y + 2.0f * q.z * q.w,
131 2.0f * q.x * q.z - 2.0f * q.y * q.w,
132 0.0f,
133
134 2.0f * q.x * q.y - 2.0f * q.z * q.w,
135 1.0f - 2.0f * q.x * q.x - 2.0f * q.z * q.z,
136 2.0f * q.y * q.z + 2.0f * q.x * q.w,
137 0.0f,
138
139 2.0f * q.x * q.z + 2.0f * q.y * q.w,
140 2.0f * q.y * q.z - 2.0f * q.x * q.w,
141 1.0f - 2.0f * q.x * q.x - 2.0f * q.y * q.y,
142 0.0f,
143
144 0.0f,
145 0.0f,
146 0.0f,
147 1.0f);
148 // clang-format on
149 }

◆ MakeRotation() [2/2]

static Matrix impeller::Matrix::MakeRotation ( Radians  radians,
const Vector4 r 
)
inlinestatic

Definition at line 151 of file matrix.h.

151 {
152 const Vector4 v = r.Normalize();
153
154 const Vector2 cos_sin = CosSin(radians);
155 const Scalar cosine = cos_sin.x;
156 const Scalar cosp = 1.0f - cosine;
157 const Scalar sine = cos_sin.y;
158
159 // clang-format off
160 return Matrix(
161 cosine + cosp * v.x * v.x,
162 cosp * v.x * v.y + v.z * sine,
163 cosp * v.x * v.z - v.y * sine,
164 0.0f,
165
166 cosp * v.x * v.y - v.z * sine,
167 cosine + cosp * v.y * v.y,
168 cosp * v.y * v.z + v.x * sine,
169 0.0f,
170
171 cosp * v.x * v.z + v.y * sine,
172 cosp * v.y * v.z - v.x * sine,
173 cosine + cosp * v.z * v.z,
174 0.0f,
175
176 0.0f,
177 0.0f,
178 0.0f,
179 1.0f);
180 // clang-format on
181 }
Point Vector2
Definition point.h:320

◆ MakeRotationX()

static Matrix impeller::Matrix::MakeRotationX ( Radians  r)
inlinestatic

Definition at line 183 of file matrix.h.

183 {
184 const Vector2 cos_sin = CosSin(r);
185 const Scalar cosine = cos_sin.x;
186 const Scalar sine = cos_sin.y;
187
188 // clang-format off
189 return Matrix(
190 1.0f, 0.0f, 0.0f, 0.0f,
191 0.0f, cosine, sine, 0.0f,
192 0.0f, -sine, cosine, 0.0f,
193 0.0f, 0.0f, 0.0f, 1.0f
194 );
195 // clang-format on
196 }

◆ MakeRotationY()

static Matrix impeller::Matrix::MakeRotationY ( Radians  r)
inlinestatic

Definition at line 198 of file matrix.h.

198 {
199 const Vector2 cos_sin = CosSin(r);
200 const Scalar cosine = cos_sin.x;
201 const Scalar sine = cos_sin.y;
202
203 // clang-format off
204 return Matrix(
205 cosine, 0.0f, -sine, 0.0f,
206 0.0f, 1.0f, 0.0f, 0.0f,
207 sine, 0.0f, cosine, 0.0f,
208 0.0f, 0.0f, 0.0f, 1.0f
209 );
210 // clang-format on
211 }

◆ MakeRotationZ()

static Matrix impeller::Matrix::MakeRotationZ ( Radians  r)
inlinestatic

Definition at line 213 of file matrix.h.

213 {
214 const Vector2 cos_sin = CosSin(r);
215 const Scalar cosine = cos_sin.x;
216 const Scalar sine = cos_sin.y;
217
218 // clang-format off
219 return Matrix (
220 cosine, sine, 0.0f, 0.0f,
221 -sine, cosine, 0.0f, 0.0f,
222 0.0f, 0.0f, 1.0f, 0.0f,
223 0.0f, 0.0f, 0.0f, 1.0
224 );
225 // clang-format on
226 }

◆ MakeRow()

static constexpr Matrix impeller::Matrix::MakeRow ( Scalar  m0,
Scalar  m1,
Scalar  m2,
Scalar  m3,
Scalar  m4,
Scalar  m5,
Scalar  m6,
Scalar  m7,
Scalar  m8,
Scalar  m9,
Scalar  m10,
Scalar  m11,
Scalar  m12,
Scalar  m13,
Scalar  m14,
Scalar  m15 
)
inlinestaticconstexpr

Definition at line 83 of file matrix.h.

87 {
88 return Matrix(m0, m4, m8, m12,
89 m1, m5, m9, m13,
90 m2, m6, m10, m14,
91 m3, m7, m11, m15);
92 }

◆ MakeScale() [1/2]

static constexpr Matrix impeller::Matrix::MakeScale ( const Vector2 s)
inlinestaticconstexpr

Definition at line 113 of file matrix.h.

113 {
114 return MakeScale(Vector3(s.x, s.y, 1.0f));
115 }
struct MyStruct s

◆ MakeScale() [2/2]

static constexpr Matrix impeller::Matrix::MakeScale ( const Vector3 s)
inlinestaticconstexpr

Definition at line 104 of file matrix.h.

104 {
105 // clang-format off
106 return Matrix(s.x, 0.0f, 0.0f, 0.0f,
107 0.0f, s.y, 0.0f, 0.0f,
108 0.0f, 0.0f, s.z, 0.0f,
109 0.0f, 0.0f, 0.0f, 1.0f);
110 // clang-format on
111 }

◆ MakeSkew()

static constexpr Matrix impeller::Matrix::MakeSkew ( Scalar  sx,
Scalar  sy 
)
inlinestaticconstexpr

Definition at line 117 of file matrix.h.

117 {
118 // clang-format off
119 return Matrix(1.0f, sy , 0.0f, 0.0f,
120 sx , 1.0f, 0.0f, 0.0f,
121 0.0f, 0.0f, 1.0f, 0.0f,
122 0.0f, 0.0f, 0.0f, 1.0f);
123 // clang-format on
124 }

◆ MakeTranslation()

static constexpr Matrix impeller::Matrix::MakeTranslation ( const Vector3 t)
inlinestaticconstexpr

Definition at line 95 of file matrix.h.

95 {
96 // clang-format off
97 return Matrix(1.0f, 0.0f, 0.0f, 0.0f,
98 0.0f, 1.0f, 0.0f, 0.0f,
99 0.0f, 0.0f, 1.0f, 0.0f,
100 t.x, t.y, t.z, 1.0f);
101 // clang-format on
102 }

◆ Multiply()

constexpr Matrix impeller::Matrix::Multiply ( const Matrix o) const
inlineconstexpr

Definition at line 261 of file matrix.h.

261 {
262 // clang-format off
263 return Matrix(
264 m[0] * o.m[0] + m[4] * o.m[1] + m[8] * o.m[2] + m[12] * o.m[3],
265 m[1] * o.m[0] + m[5] * o.m[1] + m[9] * o.m[2] + m[13] * o.m[3],
266 m[2] * o.m[0] + m[6] * o.m[1] + m[10] * o.m[2] + m[14] * o.m[3],
267 m[3] * o.m[0] + m[7] * o.m[1] + m[11] * o.m[2] + m[15] * o.m[3],
268 m[0] * o.m[4] + m[4] * o.m[5] + m[8] * o.m[6] + m[12] * o.m[7],
269 m[1] * o.m[4] + m[5] * o.m[5] + m[9] * o.m[6] + m[13] * o.m[7],
270 m[2] * o.m[4] + m[6] * o.m[5] + m[10] * o.m[6] + m[14] * o.m[7],
271 m[3] * o.m[4] + m[7] * o.m[5] + m[11] * o.m[6] + m[15] * o.m[7],
272 m[0] * o.m[8] + m[4] * o.m[9] + m[8] * o.m[10] + m[12] * o.m[11],
273 m[1] * o.m[8] + m[5] * o.m[9] + m[9] * o.m[10] + m[13] * o.m[11],
274 m[2] * o.m[8] + m[6] * o.m[9] + m[10] * o.m[10] + m[14] * o.m[11],
275 m[3] * o.m[8] + m[7] * o.m[9] + m[11] * o.m[10] + m[15] * o.m[11],
276 m[0] * o.m[12] + m[4] * o.m[13] + m[8] * o.m[14] + m[12] * o.m[15],
277 m[1] * o.m[12] + m[5] * o.m[13] + m[9] * o.m[14] + m[13] * o.m[15],
278 m[2] * o.m[12] + m[6] * o.m[13] + m[10] * o.m[14] + m[14] * o.m[15],
279 m[3] * o.m[12] + m[7] * o.m[13] + m[11] * o.m[14] + m[15] * o.m[15]);
280 // clang-format on
281 }

◆ operator!=()

constexpr bool impeller::Matrix::operator!= ( const Matrix m) const
inlineconstexpr

Definition at line 412 of file matrix.h.

412 {
413 // clang-format off
414 return vec[0] != m.vec[0]
415 || vec[1] != m.vec[1]
416 || vec[2] != m.vec[2]
417 || vec[3] != m.vec[3];
418 // clang-format on
419 }

◆ operator*() [1/4]

Matrix impeller::Matrix::operator* ( const Matrix m) const
inline

Definition at line 425 of file matrix.h.

425{ return Multiply(m); }
constexpr Matrix Multiply(const Matrix &o) const
Definition matrix.h:261

◆ operator*() [2/4]

constexpr Point impeller::Matrix::operator* ( const Point v) const
inlineconstexpr

Definition at line 450 of file matrix.h.

450 {
451 Scalar w = v.x * m[3] + v.y * m[7] + m[15];
452 Point result(v.x * m[0] + v.y * m[4] + m[12],
453 v.x * m[1] + v.y * m[5] + m[13]);
454
455 // This is Skia's behavior, but it may be reasonable to allow UB for the w=0
456 // case.
457 if (w) {
458 w = 1 / w;
459 }
460 return result * w;
461 }
TPoint< Scalar > Point
Definition point.h:316

◆ operator*() [3/4]

constexpr Vector3 impeller::Matrix::operator* ( const Vector3 v) const
inlineconstexpr

Definition at line 436 of file matrix.h.

436 {
437 Scalar w = v.x * m[3] + v.y * m[7] + v.z * m[11] + m[15];
438 Vector3 result(v.x * m[0] + v.y * m[4] + v.z * m[8] + m[12],
439 v.x * m[1] + v.y * m[5] + v.z * m[9] + m[13],
440 v.x * m[2] + v.y * m[6] + v.z * m[10] + m[14]);
441
442 // This is Skia's behavior, but it may be reasonable to allow UB for the w=0
443 // case.
444 if (w) {
445 w = 1 / w;
446 }
447 return result * w;
448 }

◆ operator*() [4/4]

constexpr Vector4 impeller::Matrix::operator* ( const Vector4 v) const
inlineconstexpr

Definition at line 429 of file matrix.h.

429 {
430 return Vector4(v.x * m[0] + v.y * m[4] + v.z * m[8] + v.w * m[12],
431 v.x * m[1] + v.y * m[5] + v.z * m[9] + v.w * m[13],
432 v.x * m[2] + v.y * m[6] + v.z * m[10] + v.w * m[14],
433 v.x * m[3] + v.y * m[7] + v.z * m[11] + v.w * m[15]);
434 }

◆ operator+() [1/2]

Matrix impeller::Matrix::operator+ ( const Matrix m) const

Definition at line 88 of file matrix.cc.

88 {
89 return Matrix(
90 m[0] + o.m[0], m[1] + o.m[1], m[2] + o.m[2], m[3] + o.m[3], //
91 m[4] + o.m[4], m[5] + o.m[5], m[6] + o.m[6], m[7] + o.m[7], //
92 m[8] + o.m[8], m[9] + o.m[9], m[10] + o.m[10], m[11] + o.m[11], //
93 m[12] + o.m[12], m[13] + o.m[13], m[14] + o.m[14], m[15] + o.m[15] //
94 );
95}

◆ operator+() [2/2]

Matrix impeller::Matrix::operator+ ( const Vector3 t) const
inline

Definition at line 421 of file matrix.h.

421{ return Translate(t); }
constexpr Matrix Translate(const Vector3 &t) const
Definition matrix.h:240

◆ operator-()

Matrix impeller::Matrix::operator- ( const Vector3 t) const
inline

Definition at line 423 of file matrix.h.

423{ return Translate(-t); }

◆ operator==()

constexpr bool impeller::Matrix::operator== ( const Matrix m) const
inlineconstexpr

Definition at line 403 of file matrix.h.

403 {
404 // clang-format off
405 return vec[0] == m.vec[0]
406 && vec[1] == m.vec[1]
407 && vec[2] == m.vec[2]
408 && vec[3] == m.vec[3];
409 // clang-format on
410 }

◆ Scale()

constexpr Matrix impeller::Matrix::Scale ( const Vector3 s) const
inlineconstexpr

Definition at line 252 of file matrix.h.

252 {
253 // clang-format off
254 return Matrix(m[0] * s.x, m[1] * s.x, m[2] * s.x, m[3] * s.x,
255 m[4] * s.y, m[5] * s.y, m[6] * s.y, m[7] * s.y,
256 m[8] * s.z, m[9] * s.z, m[10] * s.z, m[11] * s.z,
257 m[12] , m[13] , m[14] , m[15] );
258 // clang-format on
259 }

◆ Transform()

constexpr Quad impeller::Matrix::Transform ( const Quad quad) const
inlineconstexpr

Definition at line 485 of file matrix.h.

485 {
486 return {
487 *this * quad[0],
488 *this * quad[1],
489 *this * quad[2],
490 *this * quad[3],
491 };
492 }

◆ TransformDirection() [1/3]

constexpr Vector2 impeller::Matrix::TransformDirection ( const Vector2 v) const
inlineconstexpr

Definition at line 481 of file matrix.h.

481 {
482 return Vector2(v.x * m[0] + v.y * m[4], v.x * m[1] + v.y * m[5]);
483 }

◆ TransformDirection() [2/3]

constexpr Vector3 impeller::Matrix::TransformDirection ( const Vector3 v) const
inlineconstexpr

Definition at line 475 of file matrix.h.

475 {
476 return Vector3(v.x * m[0] + v.y * m[4] + v.z * m[8],
477 v.x * m[1] + v.y * m[5] + v.z * m[9],
478 v.x * m[2] + v.y * m[6] + v.z * m[10]);
479 }

◆ TransformDirection() [3/3]

constexpr Vector4 impeller::Matrix::TransformDirection ( const Vector4 v) const
inlineconstexpr

Definition at line 469 of file matrix.h.

469 {
470 return Vector4(v.x * m[0] + v.y * m[4] + v.z * m[8],
471 v.x * m[1] + v.y * m[5] + v.z * m[9],
472 v.x * m[2] + v.y * m[6] + v.z * m[10], v.w);
473 }

◆ TransformHomogenous()

constexpr Vector3 impeller::Matrix::TransformHomogenous ( const Point v) const
inlineconstexpr

Definition at line 463 of file matrix.h.

463 {
464 return Vector3(v.x * m[0] + v.y * m[4] + m[12],
465 v.x * m[1] + v.y * m[5] + m[13],
466 v.x * m[3] + v.y * m[7] + m[15]);
467 }

◆ Translate()

constexpr Matrix impeller::Matrix::Translate ( const Vector3 t) const
inlineconstexpr

Definition at line 240 of file matrix.h.

240 {
241 // clang-format off
242 return Matrix(m[0], m[1], m[2], m[3],
243 m[4], m[5], m[6], m[7],
244 m[8], m[9], m[10], m[11],
245 m[0] * t.x + m[4] * t.y + m[8] * t.z + m[12],
246 m[1] * t.x + m[5] * t.y + m[9] * t.z + m[13],
247 m[2] * t.x + m[6] * t.y + m[10] * t.z + m[14],
248 m[15]);
249 // clang-format on
250 }

◆ Transpose()

constexpr Matrix impeller::Matrix::Transpose ( ) const
inlineconstexpr

Definition at line 283 of file matrix.h.

283 {
284 // clang-format off
285 return {
286 m[0], m[4], m[8], m[12],
287 m[1], m[5], m[9], m[13],
288 m[2], m[6], m[10], m[14],
289 m[3], m[7], m[11], m[15],
290 };
291 // clang-format on
292 }

Member Data Documentation

◆ [union]

union { ... } impeller::Matrix

◆ e

Scalar impeller::Matrix::e[4][4]

Definition at line 40 of file matrix.h.

◆ m

Scalar impeller::Matrix::m[16]

Definition at line 39 of file matrix.h.

◆ vec

Vector4 impeller::Matrix::vec[4]

Definition at line 41 of file matrix.h.


The documentation for this struct was generated from the following files: