color.h File Reference

‎/***************************************************************************************************
 * Copyright 2024 NVIDIA Corporation. All rights reserved.
 **************************************************************************************************/

#ifndef MI_MATH_COLOR_H
#define MI_MATH_COLOR_H

#include <mi/base/types.h>
#include <mi/math/assert.h>
#include <mi/math/function.h>
#include <mi/math/vector.h>

namespace mi {

namespace math {

// Color and Spectrum can be converted into each other. To avoid cyclic dependencies among the
// headers, the Spectrum_struct class is already defined here.

//------- POD struct that provides storage for spectrum elements --------

struct Spectrum_struct
{
    Float32 
               c[3];
};

//------ Color Class ---------------------------------------------------------

enum Clip_mode {
    CLIP_RGB,   
    CLIP_ALPHA, 
    CLIP_RAW    
};

class Color : public Color_struct //-V690 PVS
{
public:
    typedef Color_struct      
               Pod_type;         
    typedef Color_struct      
               storage_type;     
    typedef Float32           
               value_type;       
    typedef Size              
               size_type;        
    typedef Difference        
               difference_type;  
    typedef Float32 *         pointer;          
    typedef const Float32 *   const_pointer;    
    typedef Float32 &         reference;        
    typedef const Float32 &   const_reference;  

    static const Size 
               SIZE      = 4;            

    static inline Size 
               size()     { return SIZE; }

    static inline Size 
               max_size() { return SIZE; }

    inline Float32*        begin()       { return &r; }

    inline const Float32*  begin() const { return &r; }

    inline Float32*        end()         { return begin() + SIZE; }

    inline const Float32*  end() const   { return begin() + SIZE; }

    inline Color()
    {
#ifndef NDEBUG
        // In debug mode, default-constructed colors are initialized with signaling NaNs or, if not
        // applicable, with a maximum value to increase the chances of diagnosing incorrect use of
        // an uninitialized color.
        typedef mi::base::numeric_traits< Float32> Traits;
        Float32 v = (Traits::has_signaling_NaN)
            ? Traits::signaling_NaN() : Traits::max MI_PREVENT_MACRO_EXPAND ();
        r = v;
        g = v;
        b = v;
        a = v;
#endif
    }

#if (__cplusplus >= 201103L)
    Color( const Color& c) = default;
#endif

    inline Color( const Color_struct& c)
    {
        r = c.r;
        g = c.g;
        b = c.b;
        a = c.a;
    }

    inline explicit Color( const Float32 s)
    {
        r = s;
        g = s;
        b = s;
        a = s;
    }

    inline Color( Float32 nr, Float32 ng, Float32 nb, Float32 na = 1.0)
    {
        r = nr;
        g = ng;
        b = nb;
        a = na;
    }

    template <typename T>
    inline explicit Color( T array[4])
    {
        r = array[0];
        g = array[1];
        b = array[2];
        a = array[3];
    }

    inline explicit Color( const Vector< Float32, 4>& v)
    {
        r = v.x;
        g = v.y;
        b = v.z;
        a = v.w;
    }

    inline explicit Color( const Spectrum_struct& s)
    {
        r = s.c[0];
        g = s.c[1];
        b = s.c[2];
        a = 1.0f;
    }

    inline Color& operator=( const Color& c)
    {
        Color_struct::operator=( c);
        return *this;
    }

    inline Color& operator=( const Vector< Float32, 4>& v)
    {
        r = v.x;
        g = v.y;
        b = v.z;
        a = v.w;
        return *this;
    }

    inline const Float32& operator[]( Size i) const
    {
        mi_math_assert_msg( i < 4, "precondition");
        return (&r)[i];
    }

    inline Float32& operator[]( Size i)
    {
        mi_math_assert_msg( i < 4, "precondition");
        return (&r)[i];
    }


    inline Float32 get( Size i) const
    {
        mi_math_assert_msg( i < 4, "precondition");
        return (&r)[i];
    }

    inline void set( Size i, Float32 value)
    {
        mi_math_assert_msg( i < 4, "precondition");
       (&r)[i] = value;
    }

    inline bool is_black() const
    {
        return (r == 0.0f) && (g == 0.0f) && (b == 0.0f);
    }

    inline Float32 
               linear_intensity() const
    {
        return (r + g + b) * Float32(1.0 / 3.0);
    }

    inline Float32 
               ntsc_intensity() const
    {
        return r * 0.299f + g * 0.587f + b * 0.114f;
    }

    inline Float32 
               cie_intensity() const
    {
        return r * 0.212671f + g * 0.715160f + b * 0.072169f;
    }

    inline Color 
               clip( Clip_mode mode = CLIP_RGB, bool desaturate = false) const;


    inline Color 
               desaturate( Float32 maxval = 1.0f) const;
};

//------ Free comparison operators ==, !=, <, <=, >, >= for colors  ------------

inline bool  operator==( const Color& lhs, const Color& rhs)
{
    return is_equal( lhs, rhs);
}

inline bool  operator!=( const Color& lhs, const Color& rhs)
{
    return is_not_equal( lhs, rhs);
}

inline bool operator< ( const Color& lhs, const Color& rhs)
{
    return lexicographically_less( lhs, rhs);
}

inline bool operator< =( const Color& lhs, const Color& rhs)
{
    return lexicographically_less_or_equal( lhs, rhs);
}

inline bool operator>( const Color& lhs, const Color& rhs)
{
    return lexicographically_greater( lhs, rhs);
}

inline bool operator>=( const Color& lhs, const Color& rhs)
{
    return lexicographically_greater_or_equal( lhs, rhs);
}



//------ Free operators +=, -=, *=, /=, +, -, *, and / for colors --------------

inline Color& operator+=( Color& lhs, const Color& rhs)
{
    lhs.r += rhs.r;
    lhs.g += rhs.g;
    lhs.b += rhs.b;
    lhs.a += rhs.a;
    return lhs;
}

inline Color& operator-=( Color& lhs, const Color& rhs)
{
    lhs.r -= rhs.r;
    lhs.g -= rhs.g;
    lhs.b -= rhs.b;
    lhs.a -= rhs.a;
    return lhs;
}

inline Color& operator*=( Color& lhs, const Color& rhs)
{
    lhs.r *= rhs.r;
    lhs.g *= rhs.g;
    lhs.b *= rhs.b;
    lhs.a *= rhs.a;
    return lhs;
}

inline Color& operator/=( Color& lhs, const Color& rhs)
{
    lhs.r /= rhs.r;
    lhs.g /= rhs.g;
    lhs.b /= rhs.b;
    lhs.a /= rhs.a;
    return lhs;
}

inline Color 
               operator+( const Color& lhs, const Color& rhs)
{
    return Color( lhs.r + rhs.r, lhs.g + rhs.g, lhs.b + rhs.b, lhs.a + rhs.a);
}

inline Color 
               operator-( const Color& lhs, const Color& rhs)
{
    return Color( lhs.r - rhs.r, lhs.g - rhs.g, lhs.b - rhs.b, lhs.a - rhs.a);
}

inline Color 
               operator*( const Color& lhs, const Color& rhs)
{
    return Color( lhs.r * rhs.r, lhs.g * rhs.g, lhs.b * rhs.b, lhs.a * rhs.a);
}

inline Color 
               operator/( const Color& lhs, const Color& rhs)
{
    return Color( lhs.r / rhs.r, lhs.g / rhs.g, lhs.b / rhs.b, lhs.a / rhs.a);
}

inline Color 
               operator-( const Color& c)
{
    return Color( -c.r, -c.g, -c.b, -c.a);
}



//------ Free operator *=, /=, *, and / definitions for scalars ---------------

inline Color& operator*=( Color& c, Float32 s)
{
    c.r *= s;
    c.g *= s;
    c.b *= s;
    c.a *= s;
    return c;
}

inline Color& operator/=( Color& c, Float32 s)
{
    const Float32 f = 1.0f / s;
    c.r *= f;
    c.g *= f;
    c.b *= f;
    c.a *= f;
    return c;
}

inline Color 
               operator*( const Color& c, Float32 s)
{
    return Color( c.r * s, c.g * s, c.b * s, c.a * s);
}

inline Color 
               operator*( Float32 s, const Color& c)
{
    return Color( s * c.r, s * c.g, s* c.b, s * c.a);
}

inline Color 
               operator/( const Color& c, Float32 s)
{
    const Float32 f = 1.0f / s;
    return Color( c.r * f, c.g * f, c.b * f, c.a * f);
}


//------ Function Overloads for Color Algorithms ------------------------------


inline Color 
               abs( const Color& c)
{
    return Color( abs( c.r), abs( c.g), abs( c.b), abs( c.a));
}

inline Color 
               acos( const Color& c)
{
    return Color( acos( c.r), acos( c.g), acos( c.b), acos( c.a));
}

inline bool all( const Color& c)
{
    return (c.r != 0.0f) && (c.g != 0.0f) && (c.b != 0.0f) && (c.a != 0.0f);
}

inline bool any( const Color& c)
{
    return (c.r != 0.0f) || (c.g != 0.0f) || (c.b != 0.0f) || (c.a != 0.0f);
}

inline Color 
               asin( const Color& c)
{
    return Color( asin( c.r), asin( c.g), asin( c.b), asin( c.a));
}

inline Color 
               atan( const Color& c)
{
    return Color( atan( c.r), atan( c.g), atan( c.b), atan( c.a));
}

inline Color 
               atan2( const Color& c, const Color& d)
{
    return Color( atan2( c.r, d.r), atan2( c.g, d.g), atan2( c.b, d.b), atan2( c.a, d.a));
}

inline Color 
               ceil( const Color& c)
{
    return Color( ceil( c.r), ceil( c.g), ceil( c.b), ceil( c.a));
}

inline Color 
               clamp( const Color& c, const Color& low, const Color& high)
{
    return Color( clamp( c.r, low.r, high.r),
                  clamp( c.g, low.g, high.g),
                  clamp( c.b, low.b, high.b),
                  clamp( c.a, low.a, high.a));
}

inline Color 
               clamp( const Color& c, const Color& low, Float32 high)
{
    return Color( clamp( c.r, low.r, high),
                  clamp( c.g, low.g, high),
                  clamp( c.b, low.b, high),
                  clamp( c.a, low.a, high));
}

inline Color 
               clamp( const Color& c, Float32 low, const Color& high)
{
    return Color( clamp( c.r, low, high.r),
                  clamp( c.g, low, high.g),
                  clamp( c.b, low, high.b),
                  clamp( c.a, low, high.a));
}

inline Color 
               clamp( const Color& c, Float32 low, Float32 high)
{
    return Color( clamp( c.r, low, high),
                  clamp( c.g, low, high),
                  clamp( c.b, low, high),
                  clamp( c.a, low, high));
}

inline Color 
               cos( const Color& c)
{
    return Color( cos( c.r), cos( c.g), cos( c.b), cos( c.a));
}

inline Color 
               degrees( const Color& c)
{
    return Color( degrees( c.r), degrees( c.g), degrees( c.b), degrees( c.a));
}

inline Color 
               elementwise_max( const Color& lhs, const Color& rhs)
{
    return Color( base::max MI_PREVENT_MACRO_EXPAND ( lhs.r, rhs.r),
                  base::max MI_PREVENT_MACRO_EXPAND ( lhs.g, rhs.g),
                  base::max MI_PREVENT_MACRO_EXPAND ( lhs.b, rhs.b),
                  base::max MI_PREVENT_MACRO_EXPAND ( lhs.a, rhs.a));
}

inline Color 
               elementwise_min( const Color& lhs, const Color& rhs)
{
    return Color( base::min MI_PREVENT_MACRO_EXPAND ( lhs.r, rhs.r),
                  base::min MI_PREVENT_MACRO_EXPAND ( lhs.g, rhs.g),
                  base::min MI_PREVENT_MACRO_EXPAND ( lhs.b, rhs.b),
                  base::min MI_PREVENT_MACRO_EXPAND ( lhs.a, rhs.a));
}

inline Color 
               exp( const Color& c)
{
    return Color( exp( c.r), exp( c.g), exp( c.b), exp( c.a));
}

inline Color 
               exp2( const Color& c)
{
    return Color( exp2( c.r), exp2( c.g), exp2( c.b), exp2( c.a));
}

inline Color 
               floor( const Color& c)
{
    return Color( floor( c.r), floor( c.g), floor( c.b), floor( c.a));
}

inline Color 
               fmod( const Color& a, const Color& b)
{
    return Color( fmod( a.r, b.r), fmod( a.g, b.g), fmod( a.b, b.b), fmod( a.a, b.a));
}

inline Color 
               fmod( const Color& a, Float32 b)
{
    return Color( fmod( a.r, b), fmod( a.g, b), fmod( a.b, b), fmod( a.a, b));
}

inline Color 
               frac( const Color& c)
{
    return Color( frac( c.r), frac( c.g), frac( c.b), frac( c.a));
}

inline Color 
               gamma_correction(
    const Color& color,     
    Float32 gamma_factor)   
{
    mi_math_assert( gamma_factor > 0);
    const Float32 f = Float32(1.0) / gamma_factor;
    return Color( fast_pow( color.r, f),
                  fast_pow( color.g, f),
                  fast_pow( color.b, f),
                  fast_pow( color.a, f));
}

inline bool is_approx_equal(
    const Color& lhs,
    const Color& rhs,
    Float32      e)
{
    return is_approx_equal( lhs.r, rhs.r, e)
        && is_approx_equal( lhs.g, rhs.g, e)
        && is_approx_equal( lhs.b, rhs.b, e)
        && is_approx_equal( lhs.a, rhs.a, e);
}

inline Color 
               lerp(
    const Color& c1,  
    const Color& c2,  
    const Color& t)   
{
    return Color( lerp( c1.r, c2.r, t.r),
                  lerp( c1.g, c2.g, t.g),
                  lerp( c1.b, c2.b, t.b),
                  lerp( c1.a, c2.a, t.a));
}

inline Color 
               lerp(
    const Color& c1,  
    const Color& c2,  
    Float32      t)   
{
    // equivalent to: return c1 * (Float32(1)-t) + c2 * t;
    return Color( lerp( c1.r, c2.r, t),
                  lerp( c1.g, c2.g, t),
                  lerp( c1.b, c2.b, t),
                  lerp( c1.a, c2.a, t));
}

inline Color 
               log( const Color& c)
{
    return Color( log( c.r), log( c.g), log( c.b), log( c.a));
}

inline Color 
               log2 
               MI_PREVENT_MACRO_EXPAND ( const Color& c)
{
    return Color( log2 
               MI_PREVENT_MACRO_EXPAND (c.r),
                  log2 
               MI_PREVENT_MACRO_EXPAND (c.g),
                  log2 
               MI_PREVENT_MACRO_EXPAND (c.b),
                  log2 
               MI_PREVENT_MACRO_EXPAND (c.a));
}

inline Color 
               log10( const Color& c)
{
    return Color( log10( c.r), log10( c.g), log10( c.b), log10( c.a));
}

inline Color 
               modf( const Color& c, Color& i)
{
    return Color( modf( c.r, i.r), modf( c.g, i.g), modf( c.b, i.b), modf( c.a, i.a));
}

inline Color 
               pow( const Color& a,  const Color& b)
{
    return Color( pow( a.r, b.r), pow( a.g, b.g), pow( a.b, b.b), pow( a.a, b.a));
}

inline Color 
               pow( const Color& a,  Float32 b)
{
    return Color( pow( a.r, b), pow( a.g, b), pow( a.b, b), pow( a.a, b));
}

inline Color 
               radians( const Color& c)
{
    return Color( radians( c.r), radians( c.g), radians( c.b), radians( c.a));
}

inline Color 
               round( const Color& c)
{
    return Color( round( c.r), round( c.g), round( c.b), round( c.a));
}

inline Color 
               rsqrt( const Color& c)
{
    return Color( rsqrt( c.r), rsqrt( c.g), rsqrt( c.b), rsqrt( c.a));
}

inline Color 
               saturate( const Color& c)
{
    return Color( saturate( c.r), saturate( c.g), saturate( c.b), saturate( c.a));
}

inline Color 
               sign( const Color& c)
{
    return Color( sign( c.r), sign( c.g), sign( c.b), sign( c.a));
}

inline Color 
               sin( const Color& c)
{
    return Color( sin( c.r), sin( c.g), sin( c.b), sin( c.a));
}

inline void sincos( const Color& a, Color& s, Color& c)
{
    sincos( a.r, s.r, c.r);
    sincos( a.g, s.g, c.g);
    sincos( a.b, s.b, c.b);
    sincos( a.a, s.a, c.a);
}

inline Color 
               smoothstep( const Color& a, const Color& b, const Color& c)
{
    return Color( smoothstep( a.r, b.r, c.r),
                  smoothstep( a.g, b.g, c.g),
                  smoothstep( a.b, b.b, c.b),
                  smoothstep( a.a, b.a, c.a));
}

inline Color 
               smoothstep( const Color& a, const Color& b, Float32 x)
{
    return Color( smoothstep( a.r, b.r, x),
                  smoothstep( a.g, b.g, x),
                  smoothstep( a.b, b.b, x),
                  smoothstep( a.a, b.a, x));
}

inline Color 
               sqrt( const Color& c)
{
    return Color( sqrt( c.r), sqrt( c.g), sqrt( c.b), sqrt( c.a));
}

inline Color 
               step( const Color& a, const Color& c)
{
    return Color( step( a.r, c.r), step( a.g, c.g), step( a.g, c.b), step( a.a, c.a));
}

inline Color 
               tan( const Color& c)
{
    return Color( tan( c.r), tan( c.g), tan( c.b), tan( c.a));
}

inline bool isfinite 
               MI_PREVENT_MACRO_EXPAND (const Color& c)
{
    return isfinite 
               MI_PREVENT_MACRO_EXPAND (c.r)
        && isfinite 
               MI_PREVENT_MACRO_EXPAND (c.g)
        && isfinite 
               MI_PREVENT_MACRO_EXPAND (c.b)
        && isfinite 
               MI_PREVENT_MACRO_EXPAND (c.a);
}

inline bool isinfinite 
               MI_PREVENT_MACRO_EXPAND (const Color& c)
{
    return isinfinite 
               MI_PREVENT_MACRO_EXPAND (c.r)
        || isinfinite 
               MI_PREVENT_MACRO_EXPAND (c.g)
        || isinfinite 
               MI_PREVENT_MACRO_EXPAND (c.b)
        || isinfinite 
               MI_PREVENT_MACRO_EXPAND (c.a);
}

inline bool isnan 
               MI_PREVENT_MACRO_EXPAND (const Color& c)
{
    return isnan 
               MI_PREVENT_MACRO_EXPAND (c.r)
        || isnan 
               MI_PREVENT_MACRO_EXPAND (c.g)
        || isnan 
               MI_PREVENT_MACRO_EXPAND (c.b)
        || isnan 
               MI_PREVENT_MACRO_EXPAND (c.a);
}

MI_HOST_DEVICE_INLINE void to_rgbe( const Color& color, Uint32& rgbe)
{
    to_rgbe( &color.r, rgbe);
}

MI_HOST_DEVICE_INLINE void to_rgbe( const Color& color, Uint8 rgbe[4])
{
    to_rgbe( &color.r, rgbe);
}

MI_HOST_DEVICE_INLINE void from_rgbe( const Uint8 rgbe[4], Color& color)
{
    from_rgbe( rgbe, &color.r);
    color.a = 1.0f;
}

MI_HOST_DEVICE_INLINE void from_rgbe( const Uint32 rgbe, Color& color)
{
    from_rgbe( rgbe, &color.r);
    color.a = 1.0f;
}

//------ Definitions of member functions --------------------------------------

#ifndef MI_FOR_DOXYGEN_ONLY

inline Color 
               Color::clip(
    Clip_mode  mode,
    bool       desaturate) const
{
    Float32 max_val = 1.0f;
    Color col = *this;
    if( col.a < 0.0f)
        col.a = 0.0f;
    if( mode == CLIP_RGB) {
        if( col.a < col.r)  col.a = col.r;
        if( col.a < col.g)  col.a = col.g;
        if( col.a < col.b)  col.a = col.b;
    }
    if( col.a > 1.0f)
        col.a = 1.0f;
    if( mode == CLIP_ALPHA)
        max_val = col.a;
    if( desaturate)
        return col.desaturate(max_val);
    return Color( math::clamp( col.r, 0.0f, max_val),
                  math::clamp( col.g, 0.0f, max_val),
                  math::clamp( col.b, 0.0f, max_val),
                  col.a);
}

inline Color 
               Color::desaturate( Float32 maxval) const
{
    // We compute a new color based on s with the vector formula c(s) = (N + s(I-N)) c0 where N is
    // the 3 by 3 matrix with the [1,3] vector b with the NTSC values as its rows, and c0 is the
    // original color. All c(s) have the same brightness, b*c0, as the original color. It can be
    // algebraically shown that the hue of the c(s) is the same as for c0. Hue can be expressed with
    // the formula h(c) = (I-A)c, where A is a 3 by 3 matrix with all 1/3 values. Essentially,
    // h(c(s)) == h(c0), since A*N == N

    Float32 t; // temp for saturation calc

    Float32 axis = ntsc_intensity();
    if( axis < 0) // negative: black, exit.
        return Color( 0, 0, 0, a);
    if( axis > maxval) // too bright: all white, exit.
        return Color( maxval, maxval, maxval, a);

    Float32 drds = r - axis;                // calculate color axis and
    Float32 dgds = g - axis;                // dcol/dsat. sat==1 at the
    Float32 dbds = b - axis;                // outset.

    Float32 sat = 1.0f;                     // initial saturation
    bool  clip = false;                     // outside range, desaturate

    if( r > maxval) {                       // red > maxval?
        clip = true;
        t = (maxval - axis) / drds;
        if( t < sat) sat = t;
    } else if( r < 0) {                     // red < 0?
        clip = true;
        t = -axis / drds;
        if( t < sat) sat = t;
    }
    if( g > maxval) {                       // green > maxval?
        clip = true;
        t = (maxval - axis) / dgds;
        if( t < sat) sat = t;
    } else if( g < 0) {                     // green < 0?
        clip = true;
        t = -axis / dgds;
        if( t < sat) sat = t;
    }
    if( b > maxval) {                       // blue > maxval?
        clip = true;
        t = (maxval - axis) / dbds;
        if( t < sat) sat = t;
    } else if( b < 0) {                     // blue < 0?
        clip = true;
        t = -axis / dbds;
        if( t < sat) sat = t;
    }
    if( clip) {
        // negative solutions should not be possible
        mi_math_assert( sat >= 0);
        // clamp to avoid numerical imprecision
        return Color( math::clamp( axis + drds * sat, 0.0f, maxval),
                      math::clamp( axis + dgds * sat, 0.0f, maxval),
                      math::clamp( axis + dbds * sat, 0.0f, maxval),
                      a);
    }
    mi_math_assert( r >= 0 && r <= maxval);
    mi_math_assert( g >= 0 && g <= maxval);
    mi_math_assert( b >= 0 && b <= maxval);
    return *this;
}

#endif // MI_FOR_DOXYGEN_ONLY
 // end group mi_math_color

} // namespace math

} // namespace mi

#endif // MI_MATH_COLOR_H