color.h

Go to the documentation of this file.

/***************************************************************************************************
 * Copyright 2025 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:
    using Pod_type        = Color_struct;    
    using storage_type    = Color_struct;    
    using value_type      = Float32;         
    using size_type       = Size;            
    using difference_type = Difference;      
    using pointer         = Float32 *;       
    using const_pointer   = const Float32*;  
    using reference       = Float32 &;       
    using const_reference = const Float32&;  
 
    static constexpr Size SIZE      = 4;     
 
    static constexpr inline Size size()     { return SIZE; }
 
    static constexpr 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.
        using Traits = mi::base::numeric_traits<Float32>;
        Float32 v = (Traits::has_signaling_NaN)
            ? Traits::signaling_NaN() : Traits::max MI_PREVENT_MACRO_EXPAND ();
        r = v;
        g = v;
        b = v;
        a = v;
#endif
    }
 
    Color( const Color& c) = default;
 
#if (__cplusplus >= 201402L)
    constexpr
#endif
    inline Color( const Color_struct& c) : Color_struct{c.r,c.g,c.b,c.a}
    {
    }
 
#if (__cplusplus >= 201402L)
    constexpr
#endif
    inline explicit Color( const Float32 s) : Color_struct{s,s,s,s}
    {
    }
 
#if (__cplusplus >= 201402L)
    constexpr
#endif
    inline Color( Float32 nr, Float32 ng, Float32 nb, Float32 na = 1.0f) : Color_struct{nr,ng,nb,na}
    {
    }
 
    template <typename T>
#if (__cplusplus >= 201402L)
    constexpr
#endif
    inline explicit Color( T array[4]) : Color_struct{array[0],array[1],array[2],array[3]}
    {
    }
 
#if (__cplusplus >= 201402L)
    constexpr
#endif
    inline explicit Color( const Vector<Float32,4>& v) : Color_struct{v.x,v.y,v.z,v.w}
    {
    }
 
#if (__cplusplus >= 201402L)
    constexpr
#endif
    inline explicit Color( const Spectrum_struct& s) : Color_struct{s.c[0],s.c[1],s.c[2],1.0f}
    {
    }
 
    inline Color& operator=( const Color& c) = default;
 
    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 { 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 { 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 { 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 { lhs.r / rhs.r, lhs.g / rhs.g, lhs.b / rhs.b, lhs.a / rhs.a};
}
 
inline Color operator-( const Color& c)
{
    return { -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 { c.r * s, c.g * s, c.b * s, c.a * s};
}
 
inline Color operator*( Float32 s, const Color& c)
{
    return { 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 { c.r * f, c.g * f, c.b * f, c.a * f};
}
 
 
//------ Function Overloads for Color Algorithms ------------------------------
 
 
inline Color abs( const Color& c)
{
    return { abs( c.r), abs( c.g), abs( c.b), abs( c.a)};
}
 
inline Color acos( const Color& c)
{
    return { 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 { asin( c.r), asin( c.g), asin( c.b), asin( c.a)};
}
 
inline Color atan( const Color& c)
{
    return { atan( c.r), atan( c.g), atan( c.b), atan( c.a)};
}
 
inline Color atan2( const Color& c, const Color& d)
{
    return { 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 { 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 { 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 { 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 { 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 { 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 { cos( c.r), cos( c.g), cos( c.b), cos( c.a)};
}
 
inline Color degrees( const Color& c)
{
    return { degrees( c.r), degrees( c.g), degrees( c.b), degrees( c.a)};
}
 
inline Color elementwise_max( const Color& lhs, const Color& rhs)
{
    return { 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 { 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 { exp( c.r), exp( c.g), exp( c.b), exp( c.a)};
}
 
inline Color exp2( const Color& c)
{
    return { exp2( c.r), exp2( c.g), exp2( c.b), exp2( c.a)};
}
 
inline Color floor( const Color& c)
{
    return { floor( c.r), floor( c.g), floor( c.b), floor( c.a)};
}
 
inline Color fmod( const Color& a, const Color& b)
{
    return { 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 { fmod( a.r, b), fmod( a.g, b), fmod( a.b, b), fmod( a.a, b)};
}
 
inline Color frac( const Color& c)
{
    return { 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 { 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 { 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 { 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 { log( c.r), log( c.g), log( c.b), log( c.a)};
}
 
inline Color log2 MI_PREVENT_MACRO_EXPAND ( const Color& c)
{
    return { 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 { log10( c.r), log10( c.g), log10( c.b), log10( c.a)};
}
 
inline Color modf( const Color& c, Color& i)
{
    return { 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 { 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 { pow( a.r, b), pow( a.g, b), pow( a.b, b), pow( a.a, b)};
}
 
inline Color radians( const Color& c)
{
    return { radians( c.r), radians( c.g), radians( c.b), radians( c.a)};
}
 
inline Color round( const Color& c)
{
    return { round( c.r), round( c.g), round( c.b), round( c.a)};
}
 
inline Color rsqrt( const Color& c)
{
    return { rsqrt( c.r), rsqrt( c.g), rsqrt( c.b), rsqrt( c.a)};
}
 
inline Color saturate( const Color& c)
{
    return { saturate( c.r), saturate( c.g), saturate( c.b), saturate( c.a)};
}
 
inline Color sign( const Color& c)
{
    return { sign( c.r), sign( c.g), sign( c.b), sign( c.a)};
}
 
inline Color sin( const Color& c)
{
    return { 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 { 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 { 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 { sqrt( c.r), sqrt( c.g), sqrt( c.b), sqrt( c.a)};
}
 
inline Color step( const Color& a, const Color& c)
{
    return { 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 { 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 { 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 { 0, 0, 0, a};
    if( axis > maxval) // too bright: all white, exit.
        return { 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 { 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