UT_FixedArrayMath.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * NAME:        UT_FixedArrayMath.h (UT Library, C++)
 *
 * COMMENTS:    Define common math operations on fixed array-like types,
 *              which can be used to implement classes such as 
 *              UT_Vector2.h, UT_Vector3.h, UT_Vector4.h, UT_FixedVector.h and more.
 *
 */

#pragma once

#ifndef __UT_FixedArrayMath__
#define __UT_FixedArrayMath__

#include "UT_FixedArray.h"
#include <SYS/SYS_StaticAssert.h>
#include <SYS/SYS_TypeTraits.h>
#include <SYS/SYS_Math.h>
#include <SYS/SYS_Inline.h>
#include <utility>

// namespace UT::FA
namespace UT { namespace FA {

//
// Each function object below implements a math operation that involves
// one or more fixed array-like types.
// Having each operation as a function object instead of
// a free-standing function facilitates (partial) specialization and avoids 
// the overloading issues that free-standing functions have.
// Each function object is parametrized by the element type and tuple size
// of the fixed array-like type it works with.
// The element type is not are not restricted to a scalar type,
// but may itself be a vector-like type.
//
// None of the below function objects use any type traits to
// decide which numeric types and numeric thresholds to use.
// Instead, it's up to client code to provide such types and thresholds.
//

// Assign each element of as to the corresponding element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] = as[ i ];
template< typename T, exint SIZE >
struct Set
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const TS& as ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] = as[ i ];
        }
    } 
};

// Convert each element of as to the corresponding element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] = as[ i ];
template< typename T, exint SIZE, typename A >
struct Convert
{
    template< typename TS, typename AS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const AS& as ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< AS, A, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] = as[ i ];
        }
    } 
};

// Add each element of as to the corresponding element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] += as[ i ];
template< typename T, exint SIZE >
struct Add
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const TS& as ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] += as[ i ];
        }
    } 
};

// Subtract each element of as from the corresponding element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] -= as[ i ];
template< typename T, exint SIZE >
struct Subtract
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const TS& as ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] -= as[ i ];
        }
    } 
};

// Multiply each element of 'ts' by 'a':
// For each i in [ 0, SIZE ) do ts[ i ] *= a;
template< typename T, exint SIZE, typename S = T >
struct Scale
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const S& a ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] *= a;
        }
    } 
};

// Divide each element of 'ts' by 'a':
// For each i in [ 0, SIZE ) do ts[ i ] /= a;
template< typename T, exint SIZE, typename S = T >
struct Divide
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const S& a ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] /= a;
        }
    } 
};

template< typename T, typename S, typename = void >
struct HasAddScaledFunction : SYS_FalseType {};

template< typename T, typename S >
struct HasAddScaledFunction< T, S, SYS_Void_t< decltype( addScaled( std::declval< T& >(), std::declval< S >(), std::declval< T >() ) ) > > : SYS_TrueType {};

template< typename T, typename S >
constexpr bool HasAddScaledFunction_v = HasAddScaledFunction< T, S >::value;

//
// To 'ts' add 'a' times 'bs'.
// This is done by performing an addScaled operation on each of the
// elements, if a suitable "addScaled" function exists.
// Otherwise, the addScaled for the elements is implemented
// in terms of the "+=" and "*" operators.
//
template< typename T, exint SIZE, typename S = T >
struct AddScaled
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const S& a, const TS& bs ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );
        
        if constexpr( HasAddScaledFunction_v< T, S > )
        {
            for ( exint i = 0; i != SIZE; ++i )
            {
                addScaled( ts[ i ], a, bs[ i ] );
            }
        }
        else // constexpr
        {
            for ( exint i = 0; i != SIZE; ++i )
            {
                ts[ i ] += a * bs[ i ];
            }
        }
    }
};

// From each element of 'ts', subtract 'a' times the corresponding element of 'bs'.
// For each i in [ 0, SIZE ) do ts[ i ] -= a * bs[ i ];
template< typename T, exint SIZE, typename S = T >
struct SubtractScaled
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const S& a, const TS& bs ) const noexcept
    {        
        AddScaled< T, SIZE, S >{}( ts, -a, bs );
    } 
};

// Negate each element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] = -ts[ i ];
template< typename T, exint SIZE >
struct Negate
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] = -ts[ i ];
        }
    } 
};

// Assign 'a' to each element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] = a
template< typename T, exint SIZE >
struct SetUniform
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const T& a ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] = a;
        }
    } 
};

// Add 'a' to each element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] += a
template< typename T, exint SIZE >
struct AddUniform
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const T& a ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] += a;
        }
    } 
};

// Subtract 'a' from each element of ts:
// For each i in [ 0, SIZE ) do ts[ i ] -= a
template< typename T, exint SIZE >
struct SubtractUniform
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const T& a ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] -= a;
        }
    } 
};

// Multiply each element of ts with the corresponding element of as:
// For each i in [ 0, SIZE ) do ts[ i ] *= as[ i ];
template< typename T, exint SIZE >
struct ScaleComponentwise
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const TS& as ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] *= as[ i ];
        }
    } 
};

// Divide each element of ts by the corresponding element of as:
// For each i in [ 0, SIZE ) do ts[ i ] /= as[ i ];
template< typename T, exint SIZE >
struct DivideComponentwise
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE void operator()( TS& ts, const TS& as ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for( exint i = 0; i != SIZE; ++i )
        {
            ts[ i ] /= as[ i ];
        }
    } 
};

template< typename T, typename = void >
struct HasDotFunction : SYS_FalseType {};

template< typename T >
struct HasDotFunction< T, SYS_Void_t< decltype( dot( std::declval< T >(), std::declval< T >() ) ) > > : SYS_TrueType {};

template< typename T >
constexpr bool HasDotFunction_v = HasDotFunction< T >::value;

//
// Dot returns the dot product of as and bs.
// If there exists a "dot" function for the element type T of as and bs,
// then the sum of the per-element dot products is returned.
// Otherwise the sum of the per-element products obtained from
// using the binary "*" operation is returned.
//
// To make Dot work correctly over a complex number type T,
// provide a function "dot" that returns the product of as[ i ]
// and the complex conjugate of bs[ i ].
//
template< typename T, exint SIZE >
struct Dot
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE auto operator()( const TS& as, const TS& bs ) const noexcept
    {        
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        if constexpr( HasDotFunction_v< T > )
        {
            auto r{ dot( as[ 0 ], bs[ 0 ] ) };

            for ( exint i = 1; i != SIZE; ++i )
            {
                r += dot( as[ i ], bs[ i ] );
            }

            return r;
        }
        else // constexpr
        {
            const auto a_0{ as[ 0 ] };
            const auto b_0{ bs[ 0 ] };
            auto r{ a_0 * b_0 };

            for ( exint i = 1; i != SIZE; ++i )
            {
                const auto a_i{ as[ i ] };
                const auto b_i{ bs[ i ] };
                r += a_i * b_i;
            }

            return r;
        }
    }     
};

template< typename T, exint SIZE >
struct Length2
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE auto operator()( const TS& as ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        return Dot< T, SIZE >{}( as, as );
    }
};

template< typename T, exint SIZE >
struct Distance2
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE auto operator()( const TS& as, const TS& bs ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        TS ds{};
        for ( exint i = 0; i != SIZE; ++i )
        {
            ds[ i ]  = bs[ i ];
            ds[ i ] -= as[ i ];
        }

        return Length2< T, SIZE >{}( ds );
    }
};

//TODO: This uses three floating-point types: T, U, and MF. Can this be simplified?
template< typename T, exint SIZE, typename MF = T, typename U = T >
struct Normalize
{
    template< typename TS >
    SYS_FORCE_INLINE MF operator()( TS& ts, const MF l2_min ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        const U l2{ Length2< T, SIZE >{}( ts ) };

        if ( l2 <= l2_min )
        {
            return MF{ 0 };
        }

        if ( l2 == U{ 1 } )
        {
            return MF{ 1 };
        }

        const MF l{ SYSsqrt( MF( l2 ) ) };

        // Check if the square root is equal 1.  sqrt(1+dx) ~ 1+dx/2,
        // so it may get rounded to 1 when it wasn't 1 before.
        if ( l != MF{ 1 } )
        {
            //TODO: Is this reciprocal pre-compute still worth it?
            const MF il{ MF{ 1 } / l };

            for ( exint i = 0; i != SIZE; ++i )
            {
                ts[ i ] *= il;
            }
        }

        return l;
    }
};

// Return whether p is true for all the elements (each one)
template< typename T, exint SIZE >
struct AllOf
{
    template< typename TS, typename UNARY_PREDICATE >
    constexpr SYS_FORCE_INLINE bool operator()( const TS& as, const UNARY_PREDICATE p ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if( ! p( as[ i ] ) )
            {
                return false;
            }
        }
        
        return true;
    }
};

// Return whether p is true for any elements (at least one)
template< typename T, exint SIZE >
struct AnyOf
{
    template< typename TS, typename UNARY_PREDICATE >
    constexpr SYS_FORCE_INLINE bool operator()( const TS& as, const UNARY_PREDICATE p ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if( p( as[ i ] ) )
            {
                return true;
            }
        }
        
        return false;
    }
};

// Return whether as[ i ] == 0, for each component i in [ 0, SIZE )
// This relies only on operator== for the underlying type T.
template< typename T, exint SIZE >
struct IsUniformZero
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE bool operator()( const TS& as ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if( ! ( as[ i ] == T{ 0 } ) )
            {
                return false;
            }
        }
        
        return true;
    }
};

// Return whether as[ i ] == bs[ i ], for each component i in [ 0, SIZE )
// This relies only on operator== for the underlying type T.
template< typename T, exint SIZE >
struct AreEqual
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE bool operator()( const TS& as, const TS& bs ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if( ! ( as[ i ] == bs[ i ] ) )
            {
                return false;
            }
        }
        
        return true;
    }
};

// Return whether the maximum norm of 'as' is less than or equal to 'e'.
// This returns true if and only if each element of 'as' has absolute value
// less than or equal to 'e'
// This relies only on operator< for the underlying type T.
template< typename T, exint SIZE >
struct MaxNormIsLEQ
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE bool operator()( const TS& as, const T e ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if ( ( as[ i ] < -e ) || (  e < as[ i ] ) )
            {
                return false;
            }
        }

        return true;
    }
};

// Return whether the maximum metric of 'as' and 'bs' is less than or equal to 'e'.
// This returns true if and only if each componentwise difference has absolute value
// less than or equal to 'e'
// This relies only on operator< for the underlying type T.
template< typename T, exint SIZE >
struct MaxMetricIsLEQ
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE bool operator()( const TS& as, const TS& bs, const T e ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if ( ( as[ i ] < bs[ i ] - e ) || ( bs[ i ] + e < as[ i ] ) )
            {
                return false;
            }
        }

        return true;
    }
};

// Return the maximum component
// This relies only on operator< for the underlying type T.
template< typename T, exint SIZE >
struct Max
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE T operator()( const TS& as ) const noexcept
    {
        T t{ as[ 0 ] };
        
        for ( exint i = 1; i != SIZE; ++i )
        {
            t = ( t < as[ i ] ) ? as[ i ] : t;
        }
        
        return t;
    }
};

// Return the minimum component
// This relies only on operator< for the underlying type T.
template< typename T, exint SIZE >
struct Min
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE T operator()( const TS& as ) const noexcept
    {
        T t{ as[ 0 ] };

        for ( exint i = 1; i != SIZE; ++i )
        {
            t = ( as[ i ] < t ) ? as[ i ] : t;
        }

        return t;
    }
};
    
// Return the sum of the components
// This relies only on operator+= for the underlying type T.
template< typename T, exint SIZE >
struct Sum
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE T operator()( const TS& as ) const noexcept
    {
        T t{ as[ 0 ] };

        for ( exint i = 1; i != SIZE; ++i )
        {
            t += as[ i ];
        }
        
        return t;
    }
};

// Based on lexicographical order, return
// -1, if as < bs 
//  1, if bs < as
//  0, otherwise.
// This relies only on operator< for the underlying type T.
template< typename T, exint SIZE >
struct TernaryOrder
{
    template< typename TS >
    constexpr SYS_FORCE_INLINE int operator()( const TS& as, const TS& bs ) const noexcept
    {
        SYS_STATIC_ASSERT( SYS_IsFixedArrayOf_v< TS, T, SIZE > );

        for ( exint i = 0; i != SIZE; ++i )
        {
            if( as[ i ] < bs[ i ] )
            {
                return -1;
            }

            if( bs[ i ] < as[ i ] )
            {
                return  1;
            }
        }
        
        return 0;
    }
};

} }
// end of namespace UT::FA

#endif