1 #ifndef __DALI_VECTOR_3_H__
2 #define __DALI_VECTOR_3_H__
5 * Copyright (c) 2014 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.
22 #include <dali/public-api/common/dali-common.h>
35 * @brief A three dimensional vector.
37 struct DALI_IMPORT_API Vector3
45 // (x width r), (y height g), (z depth b) must be consecutive in memory.
46 // No other data must be added before (x width r) member.
47 // No virtual methods must be added to this struct.
58 * @param [in] x (or width) component
59 * @param [in] y (or height) component
60 * @param [in] z (or depth) component
62 explicit Vector3(float x, float y, float z)
70 * @brief Conversion constructor from an array of three floats.
72 * @param [in] array of xyz
74 explicit Vector3(const float* array)
84 * @param [in] vec2 Vector2 to create this vector from
86 explicit Vector3( const Vector2& vec2 );
91 * @param [in] vec4 Vector4 to create this vector from
93 explicit Vector3( const Vector4& vec4 );
97 static const Vector3 ONE; ///< (1.0f,1.0f,1.0f)
98 static const Vector3 XAXIS; ///< Vector representing the X axis
99 static const Vector3 YAXIS; ///< Vector representing the Y axis
100 static const Vector3 ZAXIS; ///< Vector representing the Z axis
101 static const Vector3 NEGATIVE_XAXIS; ///< Vector representing the negative X axis
102 static const Vector3 NEGATIVE_YAXIS; ///< Vector representing the negative Y axis
103 static const Vector3 NEGATIVE_ZAXIS; ///< Vector representing the negative Z axis
104 static const Vector3 ZERO; ///< (0.0f, 0.0f, 0.0f)
109 * @brief Assignment operator.
111 * @param[in] array of floats
114 Vector3& operator=(const float* array)
124 * @brief Assignment operator.
126 * @param[in] rhs vector to assign.
129 Vector3& operator=(const Vector2& rhs);
132 * @brief Assignment operator.
134 * @param[in] rhs vector to assign.
137 Vector3& operator=(const Vector4& rhs);
140 * @brief Addition operator.
142 * @param[in] rhs vector to add.
143 * @return A vector containing the result of the addition
145 Vector3 operator+(const Vector3& rhs) const
153 * @brief Addition assignment operator.
155 * @param[in] rhs vector to add.
158 Vector3& operator+=(const Vector3& rhs)
168 * @brief Subtraction operator.
170 * @param[in] rhs the vector to subtract
171 * @return A vector containing the result of the subtraction
173 Vector3 operator-(const Vector3& rhs) const
181 * @brief Subtraction assignment operator.
183 * @param[in] rhs the vector to subtract
186 Vector3& operator-=(const Vector3& rhs)
196 * @brief Multiplication operator.
198 * @param[in] rhs the vector to multiply
199 * @return A vector containing the result of the multiplication
201 Vector3 operator*(const Vector3& rhs) const
209 * @brief Multiplication operator.
211 * @param[in] rhs the float value to scale the vector
212 * @return A vector containing the result of the scaling
214 Vector3 operator*(float rhs) const
216 return Vector3(x * rhs, y * rhs, z * rhs);
220 * @brief Multiplication assignment operator.
222 * @param[in] rhs the vector to multiply
225 Vector3& operator*=(const Vector3& rhs)
235 * @brief Multiplication assignment operator.
237 * @param[in] rhs the float value to scale the vector
240 Vector3& operator*=(float rhs)
250 * @brief Multiplication assignment operator.
252 * @param[in] rhs the Quaternion value to multiply the vector by
255 Vector3& operator*=(const Quaternion& rhs);
258 * @brief Division operator.
260 * @param[in] rhs the vector to divide
261 * @return A vector containing the result of the division
263 Vector3 operator/(const Vector3& rhs) const
271 * @brief Division operator.
273 * @param[in] rhs The float value to scale the vector by
274 * @return A vector containing the result of the scaling
276 Vector3 operator/(float rhs) const
278 return Vector3(x / rhs, y / rhs, z / rhs);
282 * @brief Division assignment operator.
284 * @param[in] rhs the vector to divide
287 Vector3& operator/=(const Vector3& rhs)
297 * @brief Division assignment operator.
299 * @param[in] rhs the float value to scale the vector by
302 Vector3& operator/=(float rhs)
304 float oneOverRhs = 1.0f / rhs;
313 * @brief Unary negation operator.
315 * @return A vector containg the negation
317 Vector3 operator-() const
319 Vector3 temp(-x, -y, -z);
325 * @brief Equality operator.
327 * utilises appropriate machine epsilon values;
329 * @param[in] rhs The vector to test against
330 * @return true if the vectors are equal
332 bool operator==(const Vector3& rhs) const;
335 * @brief Inequality operator.
337 * utilises appropriate machine epsilon values;
339 * @param[in] rhs The vector to test against
340 * @return true if the vectors are not equal
342 bool operator!=(const Vector3& rhs) const
344 return !(*this == rhs);
348 * @brief Const array subscript operator overload.
350 * Asserts if index is out of range. Should be 0, 1 or 2
351 * @param[in] index Subscript
352 * @return The float at the given index.
354 const float& operator[](const unsigned int index) const
356 DALI_ASSERT_ALWAYS( index < 3 && "Vector element index out of bounds" );
358 return AsFloat()[index];
362 * @brief Mutable array subscript operator overload.
364 * Asserts if index is out of range. Should be 0, 1 or 2
365 * @param[in] index Subscript index
366 * @return The float at the given index.
368 float& operator[](const unsigned int index)
370 DALI_ASSERT_ALWAYS( index < 3 && "Vector element index out of bounds" );
372 return AsFloat()[index];
376 * @brief Returns the dot product of this vector and another vector.
378 * The dot product is the length of one vector in the direction of another vector.
379 * This is great for lighting, threshold testing the angle between two unit vectors,
380 * calculating the distance between two points in a particular direction.
381 * @param [in] other the other vector
382 * @return the dot product
384 float Dot(const Vector3& other) const;
387 * @brief Returns the cross produce of this vector and another vector.
389 * The cross produce of two vectors is a vector which is perpendicular to the plane of the
390 * two vectors. This is great for calculating normals and making matrices orthogonal.
392 * @param [in] other the other vector
393 * @return the cross product
395 Vector3 Cross(const Vector3& other) const;
398 * @brief Returns the length of the vector.
400 * @return the length of the vector
402 float Length() const;
405 * @brief Returns the length of the vector squared.
407 * This is more efficient than Length() for threshold
408 * testing as it avoids the use of a square root.
409 * @return the length of the vector squared.
411 float LengthSquared() const;
414 * @brief Sets the vector to be unit length, whilst maintaining its direction.
420 * @brief Clamps the vector between minimum and maximum vectors.
422 * @param [in] min the minimum vector
423 * @param [in] max the maximum vector
425 void Clamp( const Vector3& min, const Vector3& max );
428 * @brief Returns the contents of the vector as an array of 3 floats.
430 * The order of the values in this array are as follows:
431 * 0: x (or width, or r)
432 * 1: y (or height, or g)
433 * 2: z (or depth, or b)
434 * @note inlined for performance reasons (generates less code than a function call)
435 * @return the vector contents as an array of 3 floats.
437 const float* AsFloat() const {return &x;}
440 * @brief Returns the contents of the vector as an array of 3 floats.
442 * The order of the values in this array are as follows:
443 * 0: x (or width, or r)
444 * 1: y (or height, or g)
445 * 2: z (or depth, or b)
446 * @note inlined for performance reasons (generates less code than a function call)
447 * @return the vector contents as an array of 3 floats.
449 float* AsFloat() {return &x;}
452 * @brief Returns the x & y components (or width & height, or r & g) as a Vector2.
454 * @note inlined for performance reasons (generates less code than a function call)
455 * @return the partial vector contents as Vector2 (x,y)
457 const Vector2& GetVectorXY() const {return reinterpret_cast<const Vector2&>(x);}
460 * @brief Returns the x & y components (or width & height, or r & g) as a Vector2.
462 * @note inlined for performance reasons (generates less code than a function call)
463 * @return the partial vector contents as Vector2 (x,y)
465 Vector2& GetVectorXY() {return reinterpret_cast<Vector2&>(x);}
468 * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2.
470 * @note inlined for performance reasons (generates less code than a function call)
471 * @return the partial vector contents as Vector2 (y,z)
473 const Vector2& GetVectorYZ() const {return reinterpret_cast<const Vector2&>(y);}
476 * @brief Returns the y & z components (or height & depth, or g & b) as a Vector2.
478 * @note inlined for performance reasons (generates less code than a function call)
479 * @return the partial vector contents as Vector2 (y,z)
481 Vector2& GetVectorYZ() {return reinterpret_cast<Vector2&>(y);}
486 // (x width r), (y height g), (z depth b) must be consecutive in memory.
487 // No other data must be added before (x width r) member.
488 // No virtual methods must be added to this struct.
491 float x; ///< x component
492 float width; ///< width component
493 float r; ///< red component
497 float y; ///< y component
498 float height; ///< height component
499 float g; ///< green component
503 float z; ///< z component
504 float depth; ///< depth component
505 float b; ///< blue component
510 * @brief Print a Vector3.
512 * @param [in] o The output stream operator.
513 * @param [in] vector The vector to print.
514 * @return The output stream operator.
516 DALI_IMPORT_API std::ostream& operator<< (std::ostream& o, const Vector3& vector);
519 * @brief Returns a vector with components set to the minimum of the corresponding component in a and b.
521 * If a=0,1,2 and b=2,1,0 returns a vector of 2,1,2.
522 * @param [in] a a vector
523 * @param [in] b a vector
524 * @return a vector containing the minimum of each component from a and b
526 inline Vector3 Min( const Vector3& a, const Vector3& b )
528 return Vector3( a.x < b.x ? a.x : b.x ,
529 a.y < b.y ? a.y : b.y,
530 a.z < b.z ? a.z : b.z );
534 * @brief Returns a vector with components set to the maximum of the corresponding component in a and b.
536 * If a=0,1 and b=1,0 returns a vector of 1,1
537 * @param [in] a a vector
538 * @param [in] b a vector
539 * @return a vector containing the maximum of each component from a and b
541 inline Vector3 Max( const Vector3& a, const Vector3& b )
543 return Vector3( a.x > b.x ? a.x : b.x,
544 a.y > b.y ? a.y : b.y,
545 a.z > b.z ? a.z : b.z );
549 * @brief Clamps each of vector v's components between minimum and maximum values.
551 * @param [in] v a vector
552 * @param [in] min the minimum value
553 * @param [in] max the maximum value
554 * @return a vector containing the clamped components of v
556 DALI_IMPORT_API Vector3 Clamp( const Vector3& v, const float& min, const float& max );
559 * @brief Scales an Actor, such that it fits within its Parent's Size Keeping the aspect ratio.
561 * f(target, source) = Vector3( min( target.X / source.X, min( target.Y / source.Y, target.Z / source.Z ) )
562 * If any of the source dimensions is zero it will be ignored in the calculation
564 * @param [in] target size
565 * @param [in] source size
566 * @return target scaled inside source
568 DALI_IMPORT_API Vector3 FitKeepAspectRatio( const Vector3& target, const Vector3& source );
571 * @brief Scales an Actor, such that it fill its Parent's Size Keeping the aspect ratio.
573 * f(target, source) = Vector3( max( target.X / source.X, max( target.Y / source.Y, target.Z / source.Z ) )
574 * If any of the source dimensions is zero it will be ignored in the calculation
576 * @param [in] target size
577 * @param [in] source size
578 * @return target scaled inside source
580 DALI_IMPORT_API Vector3 FillKeepAspectRatio( const Vector3& target, const Vector3& source );
583 * @brief Scales an Actor, such that it fill its Parent's Size in the X and Y coordinates Keeping the aspect ratio.
585 * f(target, source) = Vector3( max( target.X / sizeX, target.Y / sizeY ) )
586 * If any of the source dimensions is zero it will be ignored in the calculation
588 * @param [in] target size
589 * @param [in] source size
590 * @return target scaled inside source
592 DALI_IMPORT_API Vector3 FillXYKeepAspectRatio( const Vector3& target, const Vector3& source );
595 * @brief Shrinks source size inside the target size maintaining aspect ratio of source.
597 * If source is smaller than target it returns source
598 * @pre source width and height > 0
599 * @param [in] target size
600 * @param [in] source size
601 * @return target scaled inside source
603 DALI_IMPORT_API Vector3 ShrinkInsideKeepAspectRatio( const Vector3& target, const Vector3& source );
608 #endif // __DALI_VECTOR_3_H__