1 #ifndef __DALI_VECTOR_3_H__
2 #define __DALI_VECTOR_3_H__
5 * Copyright (c) 2015 Samsung Electronics Co., Ltd.
7 * Licensed under the Apache License, Version 2.0 (the "License");
8 * you may not use this file except in compliance with the License.
9 * You may obtain a copy of the License at
11 * http://www.apache.org/licenses/LICENSE-2.0
13 * Unless required by applicable law or agreed to in writing, software
14 * distributed under the License is distributed on an "AS IS" BASIS,
15 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 * See the License for the specific language governing permissions and
17 * limitations under the License.
25 #include <dali/public-api/common/dali-common.h>
26 #include <dali/public-api/common/type-traits.h>
31 * @addtogroup dali-core-math
40 * @brief A three dimensional vector.
42 struct DALI_IMPORT_API Vector3
50 // (x width r), (y height g), (z depth b) must be consecutive in memory.
51 // No other data must be added before (x width r) member.
52 // No virtual methods must be added to this struct.
63 * @param [in] x (or width) component
64 * @param [in] y (or height) component
65 * @param [in] z (or depth) component
67 explicit Vector3(float x, float y, float z)
75 * @brief Conversion constructor from an array of three floats.
77 * @param [in] array of xyz
79 explicit Vector3(const float* array)
89 * @param [in] vec2 Vector2 to create this vector from
91 explicit Vector3( const Vector2& vec2 );
96 * @param [in] vec4 Vector4 to create this vector from
98 explicit Vector3( const Vector4& vec4 );
102 static const Vector3 ONE; ///< (1.0f,1.0f,1.0f)
103 static const Vector3 XAXIS; ///< Vector representing the X axis
104 static const Vector3 YAXIS; ///< Vector representing the Y axis
105 static const Vector3 ZAXIS; ///< Vector representing the Z axis
106 static const Vector3 NEGATIVE_XAXIS; ///< Vector representing the negative X axis
107 static const Vector3 NEGATIVE_YAXIS; ///< Vector representing the negative Y axis
108 static const Vector3 NEGATIVE_ZAXIS; ///< Vector representing the negative Z axis
109 static const Vector3 ZERO; ///< (0.0f, 0.0f, 0.0f)
114 * @brief Assignment operator.
116 * @param[in] array of floats
119 Vector3& operator=(const float* array)
129 * @brief Assignment operator.
131 * @param[in] rhs vector to assign.
134 Vector3& operator=(const Vector2& rhs);
137 * @brief Assignment operator.
139 * @param[in] rhs vector to assign.
142 Vector3& operator=(const Vector4& rhs);
145 * @brief Addition operator.
147 * @param[in] rhs vector to add.
148 * @return A vector containing the result of the addition
150 Vector3 operator+(const Vector3& rhs) const
158 * @brief Addition assignment operator.
160 * @param[in] rhs vector to add.
163 Vector3& operator+=(const Vector3& rhs)
173 * @brief Subtraction operator.
175 * @param[in] rhs the vector to subtract
176 * @return A vector containing the result of the subtraction
178 Vector3 operator-(const Vector3& rhs) const
186 * @brief Subtraction assignment operator.
188 * @param[in] rhs the vector to subtract
191 Vector3& operator-=(const Vector3& rhs)
201 * @brief Multiplication operator.
203 * @param[in] rhs the vector to multiply
204 * @return A vector containing the result of the multiplication
206 Vector3 operator*(const Vector3& rhs) const
214 * @brief Multiplication operator.
216 * @param[in] rhs the float value to scale the vector
217 * @return A vector containing the result of the scaling
219 Vector3 operator*(float rhs) const
221 return Vector3(x * rhs, y * rhs, z * rhs);
225 * @brief Multiplication assignment operator.
227 * @param[in] rhs the vector to multiply
230 Vector3& operator*=(const Vector3& rhs)
240 * @brief Multiplication assignment operator.
242 * @param[in] rhs the float value to scale the vector
245 Vector3& operator*=(float rhs)
255 * @brief Multiplication assignment operator.
257 * @param[in] rhs the Quaternion value to multiply the vector by
260 Vector3& operator*=(const Quaternion& rhs);
263 * @brief Division operator.
265 * @param[in] rhs the vector to divide
266 * @return A vector containing the result of the division
268 Vector3 operator/(const Vector3& rhs) const
276 * @brief Division operator.
278 * @param[in] rhs The float value to scale the vector by
279 * @return A vector containing the result of the scaling
281 Vector3 operator/(float rhs) const
283 return Vector3(x / rhs, y / rhs, z / rhs);
287 * @brief Division assignment operator.
289 * @param[in] rhs the vector to divide
292 Vector3& operator/=(const Vector3& rhs)
302 * @brief Division assignment operator.
304 * @param[in] rhs the float value to scale the vector by
307 Vector3& operator/=(float rhs)
309 float oneOverRhs = 1.0f / rhs;
318 * @brief Unary negation operator.
320 * @return A vector containg the negation
322 Vector3 operator-() const
324 Vector3 temp(-x, -y, -z);
330 * @brief Equality operator.
332 * utilises appropriate machine epsilon values;
334 * @param[in] rhs The vector to test against
335 * @return true if the vectors are equal
337 bool operator==(const Vector3& rhs) const;
340 * @brief Inequality operator.
342 * utilises appropriate machine epsilon values;
344 * @param[in] rhs The vector to test against
345 * @return true if the vectors are not equal
347 bool operator!=(const Vector3& rhs) const
349 return !(*this == rhs);
353 * @brief Const array subscript operator overload.
355 * Asserts if index is out of range. Should be 0, 1 or 2
356 * @param[in] index Subscript
357 * @return The float at the given index.
359 const float& operator[](const unsigned int index) const
361 DALI_ASSERT_ALWAYS( index < 3 && "Vector element index out of bounds" );
363 return AsFloat()[index];
367 * @brief Mutable array subscript operator overload.
369 * Asserts if index is out of range. Should be 0, 1 or 2
370 * @param[in] index Subscript index
371 * @return The float at the given index.
373 float& operator[](const unsigned int index)
375 DALI_ASSERT_ALWAYS( index < 3 && "Vector element index out of bounds" );
377 return AsFloat()[index];
381 * @brief Returns the dot product of this vector and another vector.
383 * The dot product is the length of one vector in the direction of another vector.
384 * This is great for lighting, threshold testing the angle between two unit vectors,
385 * calculating the distance between two points in a particular direction.
386 * @param [in] other the other vector
387 * @return the dot product
389 float Dot(const Vector3& other) const;
392 * @brief Returns the cross produce of this vector and another vector.
394 * The cross produce of two vectors is a vector which is perpendicular to the plane of the
395 * two vectors. This is great for calculating normals and making matrices orthogonal.
397 * @param [in] other the other vector
398 * @return the cross product
400 Vector3 Cross(const Vector3& other) const;
403 * @brief Returns the length of the vector.
405 * @return the length of the vector
407 float Length() const;
410 * @brief Returns the length of the vector squared.
412 * This is more efficient than Length() for threshold
413 * testing as it avoids the use of a square root.
414 * @return the length of the vector squared.
416 float LengthSquared() const;
419 * @brief Sets the vector to be unit length, whilst maintaining its direction.
425 * @brief Clamps the vector between minimum and maximum vectors.
427 * @param [in] min the minimum vector
428 * @param [in] max the maximum vector
430 void Clamp( const Vector3& min, const Vector3& max );
433 * @brief Returns the contents of the vector as an array of 3 floats.
435 * The order of the values in this array are as follows:
436 * 0: x (or width, or r)
437 * 1: y (or height, or g)
438 * 2: z (or depth, or b)
439 * @note inlined for performance reasons (generates less code than a function call)
440 * @return the vector contents as an array of 3 floats.
442 const float* AsFloat() const {return &x;}
445 * @brief Returns the contents of the vector as an array of 3 floats.
447 * The order of the values in this array are as follows:
448 * 0: x (or width, or r)
449 * 1: y (or height, or g)
450 * 2: z (or depth, or b)
451 * @note inlined for performance reasons (generates less code than a function call)
452 * @return the vector contents as an array of 3 floats.
454 float* AsFloat() {return &x;}
457 * @brief Returns the x & y components (or width & height, or r & g) as a Vector2.
459 * @note inlined for performance reasons (generates less code than a function call)
460 * @return the partial vector contents as Vector2 (x,y)
462 const Vector2& GetVectorXY() const {return reinterpret_cast<const Vector2&>(x);}
465 * @brief Returns the x & y components (or width & height, or r & g) as a Vector2.
467 * @note inlined for performance reasons (generates less code than a function call)
468 * @return the partial vector contents as Vector2 (x,y)
470 Vector2& GetVectorXY() {return reinterpret_cast<Vector2&>(x);}
473 * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2.
475 * @note inlined for performance reasons (generates less code than a function call)
476 * @return the partial vector contents as Vector2 (y,z)
478 const Vector2& GetVectorYZ() const {return reinterpret_cast<const Vector2&>(y);}
481 * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2.
483 * @note inlined for performance reasons (generates less code than a function call)
484 * @return the partial vector contents as Vector2 (y,z)
486 Vector2& GetVectorYZ() {return reinterpret_cast<Vector2&>(y);}
491 // (x width r), (y height g), (z depth b) must be consecutive in memory.
492 // No other data must be added before (x width r) member.
493 // No virtual methods must be added to this struct.
496 float x; ///< x component
497 float width; ///< width component
498 float r; ///< red component
502 float y; ///< y component
503 float height; ///< height component
504 float g; ///< green component
508 float z; ///< z component
509 float depth; ///< depth component
510 float b; ///< blue component
515 * @brief Print a Vector3.
517 * @param [in] o The output stream operator.
518 * @param [in] vector The vector to print.
519 * @return The output stream operator.
521 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Vector3& vector);
524 * @brief Returns a vector with components set to the minimum of the corresponding component in a and b.
526 * If a=0,1,2 and b=2,1,0 returns a vector of 2,1,2.
527 * @param [in] a a vector
528 * @param [in] b a vector
529 * @return a vector containing the minimum of each component from a and b
531 inline Vector3 Min( const Vector3& a, const Vector3& b )
533 return Vector3( a.x < b.x ? a.x : b.x ,
534 a.y < b.y ? a.y : b.y,
535 a.z < b.z ? a.z : b.z );
539 * @brief Returns a vector with components set to the maximum of the corresponding component in a and b.
541 * If a=0,1 and b=1,0 returns a vector of 1,1
542 * @param [in] a a vector
543 * @param [in] b a vector
544 * @return a vector containing the maximum of each component from a and b
546 inline Vector3 Max( const Vector3& a, const Vector3& b )
548 return Vector3( a.x > b.x ? a.x : b.x,
549 a.y > b.y ? a.y : b.y,
550 a.z > b.z ? a.z : b.z );
554 * @brief Clamps each of vector v's components between minimum and maximum values.
556 * @param [in] v a vector
557 * @param [in] min the minimum value
558 * @param [in] max the maximum value
559 * @return a vector containing the clamped components of v
561 DALI_IMPORT_API Vector3 Clamp( const Vector3& v, const float& min, const float& max );
563 // Allow Vector3 to be treated as a POD type
564 template <> struct TypeTraits< Vector3 > : public BasicTypes< Vector3 > { enum { IS_TRIVIAL_TYPE = true }; };
571 #endif // __DALI_VECTOR_3_H__