1 #ifndef __DALI_VECTOR_3_H__
2 #define __DALI_VECTOR_3_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_FRAMEWORK
30 #include <dali/public-api/math/math-utils.h>
31 #include <dali/public-api/common/constants.h>
33 namespace Dali DALI_IMPORT_API
43 struct DALI_IMPORT_API Vector3
51 // (x width r), (y height g), (z depth b) must be consecutive in memory.
52 // No other data must be added before (x width r) member.
53 // 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 * Conversion constructor from an array of three floats
76 * @param [in] array of xyz
78 explicit Vector3(const float* array)
87 * @param [in] vec2 Vector2 to create this vector from
89 explicit Vector3( const Vector2& vec2 );
93 * @param [in] vec4 Vector4 to create this vector from
95 explicit Vector3( const Vector4& vec4 );
99 static const Vector3 ONE; ///< (1.0f,1.0f,1.0f)
100 static const Vector3 XAXIS; ///< Vector representing the X axis
101 static const Vector3 YAXIS; ///< Vector representing the Y axis
102 static const Vector3 ZAXIS; ///< Vector representing the Z axis
103 static const Vector3 NEGATIVE_XAXIS; ///< Vector representing the negative X axis
104 static const Vector3 NEGATIVE_YAXIS; ///< Vector representing the negative Y axis
105 static const Vector3 NEGATIVE_ZAXIS; ///< Vector representing the negative Z axis
106 static const Vector3 ZERO; ///< (0.0f, 0.0f, 0.0f)
111 * Assignment operator
112 * @param[in] array of floats
115 Vector3& operator=(const float* array)
125 * Assignment operator
126 * @param[in] rhs vector to assign.
129 Vector3& operator=(const Vector2& rhs);
132 * Assignment operator
133 * @param[in] rhs vector to assign.
136 Vector3& operator=(const Vector4& rhs);
140 * @param[in] rhs vector to add.
141 * @return A vector containing the result of the addition
143 Vector3 operator+(const Vector3& rhs) const
151 * Addition assignment operator
152 * @param[in] rhs vector to add.
155 Vector3& operator+=(const Vector3& rhs)
165 * Subtraction operator
166 * @param[in] rhs the vector to subtract
167 * @return A vector containing the result of the subtraction
169 Vector3 operator-(const Vector3& rhs) const
177 * Subtraction assignment operator
178 * @param[in] rhs the vector to subtract
181 Vector3& operator-=(const Vector3& rhs)
191 * Multiplication operator
192 * @param[in] rhs the vector to multiply
193 * @return A vector containing the result of the multiplication
195 Vector3 operator*(const Vector3& rhs) const
203 * Multiplication operator
204 * @param[in] rhs the float value to scale the vector
205 * @return A vector containing the result of the scaling
207 Vector3 operator*(float rhs) const
209 return Vector3(x * rhs, y * rhs, z * rhs);
213 * Multiplication assignment operator
214 * @param[in] rhs the vector to multiply
217 Vector3& operator*=(const Vector3& rhs)
227 * Multiplication assignment operator
228 * @param[in] rhs the float value to scale the vector
231 Vector3& operator*=(float rhs)
241 * Multiplication assignment operator
242 * @param[in] rhs the Quaternion value to multiply the vector by
245 Vector3& operator*=(const Quaternion& rhs);
249 * @param[in] rhs the vector to divide
250 * @return A vector containing the result of the division
252 Vector3 operator/(const Vector3& rhs) const
261 * @param[in] rhs The float value to scale the vector by
262 * @return A vector containing the result of the scaling
264 Vector3 operator/(float rhs) const
266 return Vector3(x / rhs, y / rhs, z / rhs);
270 * Division assignment operator
271 * @param[in] rhs the vector to divide
274 Vector3& operator/=(const Vector3& rhs)
284 * Division assignment operator
285 * @param[in] rhs the float value to scale the vector by
288 Vector3& operator/=(float rhs)
290 float oneOverRhs = 1.0f / rhs;
299 * Unary negation operator
300 * @return A vector containg the negation
302 Vector3 operator-() const
304 Vector3 temp(-x, -y, -z);
311 * utilises appropriate machine epsilon values;
313 * @param[in] rhs The vector to test against
314 * @return true if the vectors are equal
316 bool operator==(const Vector3& rhs) const;
319 * Inequality operator
320 * utilises appropriate machine epsilon values;
322 * @param[in] rhs The vector to test against
323 * @return true if the vectors are not equal
325 bool operator!=(const Vector3& rhs) const
327 return !(*this == rhs);
331 * Const array subscript operator overload
332 * Asserts if index is out of range. Should be 0, 1 or 2
333 * @param[in] index Subscript
334 * @return The float at the given index.
336 const float& operator[](const unsigned int index) const
338 DALI_ASSERT_ALWAYS( index < 3 && "Vector element index out of bounds" );
340 return AsFloat()[index];
344 * Mutable array subscript operator overload
345 * Asserts if index is out of range. Should be 0, 1 or 2
346 * @param[in] index Subscript index
347 * @return The float at the given index.
349 float& operator[](const unsigned int index)
351 DALI_ASSERT_ALWAYS( index < 3 && "Vector element index out of bounds" );
353 return AsFloat()[index];
357 * Returns the dot product of this vector and another vector.
358 * The dot product is the length of one vector in the direction of another vector.
359 * This is great for lighting, threshold testing the angle between two unit vectors,
360 * calculating the distance between two points in a particular direction.
361 * @param [in] other the other vector
362 * @return the dot product
364 float Dot(const Vector3& other) const;
367 * Returns the cross produce of this vector and another vector.
368 * The cross produce of two vectors is a vector which is perpendicular to the plane of the
369 * two vectors. This is great for calculating normals and making matrices orthogonal.
371 * @param [in] other the other vector
372 * @return the cross product
374 Vector3 Cross(const Vector3& other) const;
377 * Returns the length of the vector.
378 * @return the length of the vector
380 float Length() const;
383 * Returns the length of the vector squared. This is more efficient than Length() for threshold
384 * testing as it avoids the use of a square root.
385 * @return the length of the vector squared.
387 float LengthSquared() const;
390 * Sets the vector to be unit length, whilst maintaining its direction.
395 * Clamps the vector between minimum and maximum vectors
396 * @param [in] min the minimum vector
397 * @param [in] max the maximum vector
399 void Clamp( const Vector3& min, const Vector3& max );
402 * Returns the contents of the vector as an array of 3 floats.
403 * The order of the values in this array are as follows:
404 * 0: x (or width, or r)
405 * 1: y (or height, or g)
406 * 2: z (or depth, or b)
407 * @note inlined for performance reasons (generates less code than a function call)
408 * @return the vector contents as an array of 3 floats.
410 const float* AsFloat() const {return &x;}
413 * Returns the contents of the vector as an array of 3 floats.
414 * The order of the values in this array are as follows:
415 * 0: x (or width, or r)
416 * 1: y (or height, or g)
417 * 2: z (or depth, or b)
418 * @note inlined for performance reasons (generates less code than a function call)
419 * @return the vector contents as an array of 3 floats.
421 float* AsFloat() {return &x;}
424 * Returns the x & y components (or width & height, or r & g)
426 * @note inlined for performance reasons (generates less code than a function call)
427 * @return the partial vector contents as Vector2 (x,y)
429 const Vector2& GetVectorXY() const {return reinterpret_cast<const Vector2&>(x);}
432 * Returns the x & y components (or width & height, or r & g)
434 * @note inlined for performance reasons (generates less code than a function call)
435 * @return the partial vector contents as Vector2 (x,y)
437 Vector2& GetVectorXY() {return reinterpret_cast<Vector2&>(x);}
440 * Returns the y & z components (or height & depth, or g & b)
442 * @note inlined for performance reasons (generates less code than a function call)
443 * @return the partial vector contents as Vector2 (y,z)
445 const Vector2& GetVectorYZ() const {return reinterpret_cast<const Vector2&>(y);}
448 * Returns the y & z components (or height & depth, or g & b)
450 * @note inlined for performance reasons (generates less code than a function call)
451 * @return the partial vector contents as Vector2 (y,z)
453 Vector2& GetVectorYZ() {return reinterpret_cast<Vector2&>(y);}
458 // (x width r), (y height g), (z depth b) must be consecutive in memory.
459 // No other data must be added before (x width r) member.
460 // No virtual methods must be added to this struct.
463 float x; ///< x component
464 float width; ///< width component
465 float r; ///< red component
469 float y; ///< y component
470 float height; ///< height component
471 float g; ///< green component
475 float z; ///< z component
476 float depth; ///< depth component
477 float b; ///< blue component
483 * @param [in] o The output stream operator.
484 * @param [in] vector The vector to print.
485 * @return The output stream operator.
487 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Vector3& vector);
490 * Returns a vector with components set to the minimum of the corresponding component in a and b.
491 * If a=0,1,2 and b=2,1,0 returns a vector of 2,1,2.
492 * @param [in] a a vector
493 * @param [in] b a vector
494 * @return a vector containing the minimum of each component from a and b
496 inline Vector3 Min( const Vector3& a, const Vector3& b )
498 return Vector3( std::min(a.x,b.x), std::min(a.y,b.y), std::min(a.z,b.z) );
502 * Returns a vector with components set to the maximum of the corresponding component in a and b.
503 * If a=0,1 and b=1,0 returns a vector of 1,1
504 * @param [in] a a vector
505 * @param [in] b a vector
506 * @return a vector containing the maximum of each component from a and b
508 inline Vector3 Max( const Vector3& a, const Vector3& b )
510 return Vector3( std::max(a.x,b.x), std::max(a.y,b.y), std::max(a.z,b.z) );
514 * Clamps each of vector v's components between minimum and maximum values
515 * @param [in] v a vector
516 * @param [in] min the minimum value
517 * @param [in] max the maximum value
518 * @return a vector containing the clamped components of v
520 DALI_IMPORT_API Vector3 Clamp( const Vector3& v, const float& min, const float& max );
523 * Scales an Actor, such that it fits within its Parent's Size Keeping the aspect ratio.
524 * f(target, source) = Vector3( min( target.X / source.X, min( target.Y / source.Y, target.Z / source.Z ) )
525 * If any of the source dimensions is zero it will be ignored in the calculation
527 * @param [in] target size
528 * @param [in] source size
529 * @return target scaled inside source
531 DALI_IMPORT_API Vector3 FitKeepAspectRatio( const Vector3& target, const Vector3& source );
534 * Scales an Actor, such that it fill its Parent's Size Keeping the aspect ratio.
535 * f(target, source) = Vector3( max( target.X / source.X, max( target.Y / source.Y, target.Z / source.Z ) )
536 * If any of the source dimensions is zero it will be ignored in the calculation
538 * @param [in] target size
539 * @param [in] source size
540 * @return target scaled inside source
542 DALI_IMPORT_API Vector3 FillKeepAspectRatio( const Vector3& target, const Vector3& source );
545 * Scales an Actor, such that it fill its Parent's Size in the X and Y coordinates Keeping the aspect ratio.
546 * f(target, source) = Vector3( max( target.X / sizeX, target.Y / sizeY ) )
547 * If any of the source dimensions is zero it will be ignored in the calculation
549 * @param [in] target size
550 * @param [in] source size
551 * @return target scaled inside source
553 DALI_IMPORT_API Vector3 FillXYKeepAspectRatio( const Vector3& target, const Vector3& source );
556 * Shrinks source size inside the target size maintaining aspect ratio of source
557 * If source is smaller than target it returns source
558 * @pre source width and height > 0
559 * @param [in] target size
560 * @param [in] source size
561 * @return target scaled inside source
563 Vector3 ShrinkInsideKeepAspectRatio( const Vector3& target, const Vector3& source );
571 #endif // __DALI_VECTOR_3_H__