1/**************************************************************************/
2/* transform_3d.h */
3/**************************************************************************/
4/* This file is part of: */
5/* GODOT ENGINE */
6/* https://godotengine.org */
7/**************************************************************************/
8/* Copyright (c) 2014-present Godot Engine contributors (see AUTHORS.md). */
9/* Copyright (c) 2007-2014 Juan Linietsky, Ariel Manzur. */
10/* */
11/* Permission is hereby granted, free of charge, to any person obtaining */
12/* a copy of this software and associated documentation files (the */
13/* "Software"), to deal in the Software without restriction, including */
14/* without limitation the rights to use, copy, modify, merge, publish, */
15/* distribute, sublicense, and/or sell copies of the Software, and to */
16/* permit persons to whom the Software is furnished to do so, subject to */
17/* the following conditions: */
18/* */
19/* The above copyright notice and this permission notice shall be */
20/* included in all copies or substantial portions of the Software. */
21/* */
22/* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, */
23/* EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF */
24/* MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. */
25/* IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY */
26/* CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, */
27/* TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE */
28/* SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */
29/**************************************************************************/
30
31#ifndef TRANSFORM_3D_H
32#define TRANSFORM_3D_H
33
34#include "core/math/aabb.h"
35#include "core/math/basis.h"
36#include "core/math/plane.h"
37#include "core/templates/vector.h"
38
39struct _NO_DISCARD_ Transform3D {
40 Basis basis;
41 Vector3 origin;
42
43 void invert();
44 Transform3D inverse() const;
45
46 void affine_invert();
47 Transform3D affine_inverse() const;
48
49 Transform3D rotated(const Vector3 &p_axis, real_t p_angle) const;
50 Transform3D rotated_local(const Vector3 &p_axis, real_t p_angle) const;
51
52 void rotate(const Vector3 &p_axis, real_t p_angle);
53 void rotate_basis(const Vector3 &p_axis, real_t p_angle);
54
55 void set_look_at(const Vector3 &p_eye, const Vector3 &p_target, const Vector3 &p_up = Vector3(0, 1, 0), bool p_use_model_front = false);
56 Transform3D looking_at(const Vector3 &p_target, const Vector3 &p_up = Vector3(0, 1, 0), bool p_use_model_front = false) const;
57
58 void scale(const Vector3 &p_scale);
59 Transform3D scaled(const Vector3 &p_scale) const;
60 Transform3D scaled_local(const Vector3 &p_scale) const;
61 void scale_basis(const Vector3 &p_scale);
62 void translate_local(real_t p_tx, real_t p_ty, real_t p_tz);
63 void translate_local(const Vector3 &p_translation);
64 Transform3D translated(const Vector3 &p_translation) const;
65 Transform3D translated_local(const Vector3 &p_translation) const;
66
67 const Basis &get_basis() const { return basis; }
68 void set_basis(const Basis &p_basis) { basis = p_basis; }
69
70 const Vector3 &get_origin() const { return origin; }
71 void set_origin(const Vector3 &p_origin) { origin = p_origin; }
72
73 void orthonormalize();
74 Transform3D orthonormalized() const;
75 void orthogonalize();
76 Transform3D orthogonalized() const;
77 bool is_equal_approx(const Transform3D &p_transform) const;
78 bool is_finite() const;
79
80 bool operator==(const Transform3D &p_transform) const;
81 bool operator!=(const Transform3D &p_transform) const;
82
83 _FORCE_INLINE_ Vector3 xform(const Vector3 &p_vector) const;
84 _FORCE_INLINE_ AABB xform(const AABB &p_aabb) const;
85 _FORCE_INLINE_ Vector<Vector3> xform(const Vector<Vector3> &p_array) const;
86
87 // NOTE: These are UNSAFE with non-uniform scaling, and will produce incorrect results.
88 // They use the transpose.
89 // For safe inverse transforms, xform by the affine_inverse.
90 _FORCE_INLINE_ Vector3 xform_inv(const Vector3 &p_vector) const;
91 _FORCE_INLINE_ AABB xform_inv(const AABB &p_aabb) const;
92 _FORCE_INLINE_ Vector<Vector3> xform_inv(const Vector<Vector3> &p_array) const;
93
94 // Safe with non-uniform scaling (uses affine_inverse).
95 _FORCE_INLINE_ Plane xform(const Plane &p_plane) const;
96 _FORCE_INLINE_ Plane xform_inv(const Plane &p_plane) const;
97
98 // These fast versions use precomputed affine inverse, and should be used in bottleneck areas where
99 // multiple planes are to be transformed.
100 _FORCE_INLINE_ Plane xform_fast(const Plane &p_plane, const Basis &p_basis_inverse_transpose) const;
101 static _FORCE_INLINE_ Plane xform_inv_fast(const Plane &p_plane, const Transform3D &p_inverse, const Basis &p_basis_transpose);
102
103 void operator*=(const Transform3D &p_transform);
104 Transform3D operator*(const Transform3D &p_transform) const;
105 void operator*=(const real_t p_val);
106 Transform3D operator*(const real_t p_val) const;
107
108 Transform3D interpolate_with(const Transform3D &p_transform, real_t p_c) const;
109
110 _FORCE_INLINE_ Transform3D inverse_xform(const Transform3D &t) const {
111 Vector3 v = t.origin - origin;
112 return Transform3D(basis.transpose_xform(t.basis),
113 basis.xform(v));
114 }
115
116 void set(real_t xx, real_t xy, real_t xz, real_t yx, real_t yy, real_t yz, real_t zx, real_t zy, real_t zz, real_t tx, real_t ty, real_t tz) {
117 basis.set(xx, xy, xz, yx, yy, yz, zx, zy, zz);
118 origin.x = tx;
119 origin.y = ty;
120 origin.z = tz;
121 }
122
123 operator String() const;
124
125 Transform3D() {}
126 Transform3D(const Basis &p_basis, const Vector3 &p_origin = Vector3());
127 Transform3D(const Vector3 &p_x, const Vector3 &p_y, const Vector3 &p_z, const Vector3 &p_origin);
128 Transform3D(real_t xx, real_t xy, real_t xz, real_t yx, real_t yy, real_t yz, real_t zx, real_t zy, real_t zz, real_t ox, real_t oy, real_t oz);
129};
130
131_FORCE_INLINE_ Vector3 Transform3D::xform(const Vector3 &p_vector) const {
132 return Vector3(
133 basis[0].dot(p_vector) + origin.x,
134 basis[1].dot(p_vector) + origin.y,
135 basis[2].dot(p_vector) + origin.z);
136}
137
138_FORCE_INLINE_ Vector3 Transform3D::xform_inv(const Vector3 &p_vector) const {
139 Vector3 v = p_vector - origin;
140
141 return Vector3(
142 (basis.rows[0][0] * v.x) + (basis.rows[1][0] * v.y) + (basis.rows[2][0] * v.z),
143 (basis.rows[0][1] * v.x) + (basis.rows[1][1] * v.y) + (basis.rows[2][1] * v.z),
144 (basis.rows[0][2] * v.x) + (basis.rows[1][2] * v.y) + (basis.rows[2][2] * v.z));
145}
146
147// Neither the plane regular xform or xform_inv are particularly efficient,
148// as they do a basis inverse. For xforming a large number
149// of planes it is better to pre-calculate the inverse transpose basis once
150// and reuse it for each plane, by using the 'fast' version of the functions.
151_FORCE_INLINE_ Plane Transform3D::xform(const Plane &p_plane) const {
152 Basis b = basis.inverse();
153 b.transpose();
154 return xform_fast(p_plane, b);
155}
156
157_FORCE_INLINE_ Plane Transform3D::xform_inv(const Plane &p_plane) const {
158 Transform3D inv = affine_inverse();
159 Basis basis_transpose = basis.transposed();
160 return xform_inv_fast(p_plane, inv, basis_transpose);
161}
162
163_FORCE_INLINE_ AABB Transform3D::xform(const AABB &p_aabb) const {
164 /* https://dev.theomader.com/transform-bounding-boxes/ */
165 Vector3 min = p_aabb.position;
166 Vector3 max = p_aabb.position + p_aabb.size;
167 Vector3 tmin, tmax;
168 for (int i = 0; i < 3; i++) {
169 tmin[i] = tmax[i] = origin[i];
170 for (int j = 0; j < 3; j++) {
171 real_t e = basis[i][j] * min[j];
172 real_t f = basis[i][j] * max[j];
173 if (e < f) {
174 tmin[i] += e;
175 tmax[i] += f;
176 } else {
177 tmin[i] += f;
178 tmax[i] += e;
179 }
180 }
181 }
182 AABB r_aabb;
183 r_aabb.position = tmin;
184 r_aabb.size = tmax - tmin;
185 return r_aabb;
186}
187
188_FORCE_INLINE_ AABB Transform3D::xform_inv(const AABB &p_aabb) const {
189 /* define vertices */
190 Vector3 vertices[8] = {
191 Vector3(p_aabb.position.x + p_aabb.size.x, p_aabb.position.y + p_aabb.size.y, p_aabb.position.z + p_aabb.size.z),
192 Vector3(p_aabb.position.x + p_aabb.size.x, p_aabb.position.y + p_aabb.size.y, p_aabb.position.z),
193 Vector3(p_aabb.position.x + p_aabb.size.x, p_aabb.position.y, p_aabb.position.z + p_aabb.size.z),
194 Vector3(p_aabb.position.x + p_aabb.size.x, p_aabb.position.y, p_aabb.position.z),
195 Vector3(p_aabb.position.x, p_aabb.position.y + p_aabb.size.y, p_aabb.position.z + p_aabb.size.z),
196 Vector3(p_aabb.position.x, p_aabb.position.y + p_aabb.size.y, p_aabb.position.z),
197 Vector3(p_aabb.position.x, p_aabb.position.y, p_aabb.position.z + p_aabb.size.z),
198 Vector3(p_aabb.position.x, p_aabb.position.y, p_aabb.position.z)
199 };
200
201 AABB ret;
202
203 ret.position = xform_inv(vertices[0]);
204
205 for (int i = 1; i < 8; i++) {
206 ret.expand_to(xform_inv(vertices[i]));
207 }
208
209 return ret;
210}
211
212Vector<Vector3> Transform3D::xform(const Vector<Vector3> &p_array) const {
213 Vector<Vector3> array;
214 array.resize(p_array.size());
215
216 const Vector3 *r = p_array.ptr();
217 Vector3 *w = array.ptrw();
218
219 for (int i = 0; i < p_array.size(); ++i) {
220 w[i] = xform(r[i]);
221 }
222 return array;
223}
224
225Vector<Vector3> Transform3D::xform_inv(const Vector<Vector3> &p_array) const {
226 Vector<Vector3> array;
227 array.resize(p_array.size());
228
229 const Vector3 *r = p_array.ptr();
230 Vector3 *w = array.ptrw();
231
232 for (int i = 0; i < p_array.size(); ++i) {
233 w[i] = xform_inv(r[i]);
234 }
235 return array;
236}
237
238_FORCE_INLINE_ Plane Transform3D::xform_fast(const Plane &p_plane, const Basis &p_basis_inverse_transpose) const {
239 // Transform a single point on the plane.
240 Vector3 point = p_plane.normal * p_plane.d;
241 point = xform(point);
242
243 // Use inverse transpose for correct normals with non-uniform scaling.
244 Vector3 normal = p_basis_inverse_transpose.xform(p_plane.normal);
245 normal.normalize();
246
247 real_t d = normal.dot(point);
248 return Plane(normal, d);
249}
250
251_FORCE_INLINE_ Plane Transform3D::xform_inv_fast(const Plane &p_plane, const Transform3D &p_inverse, const Basis &p_basis_transpose) {
252 // Transform a single point on the plane.
253 Vector3 point = p_plane.normal * p_plane.d;
254 point = p_inverse.xform(point);
255
256 // Note that instead of precalculating the transpose, an alternative
257 // would be to use the transpose for the basis transform.
258 // However that would be less SIMD friendly (requiring a swizzle).
259 // So the cost is one extra precalced value in the calling code.
260 // This is probably worth it, as this could be used in bottleneck areas. And
261 // where it is not a bottleneck, the non-fast method is fine.
262
263 // Use transpose for correct normals with non-uniform scaling.
264 Vector3 normal = p_basis_transpose.xform(p_plane.normal);
265 normal.normalize();
266
267 real_t d = normal.dot(point);
268 return Plane(normal, d);
269}
270
271#endif // TRANSFORM_3D_H
272