RixColorUtils.h

Go to the documentation of this file.

/*
# ------------------------------------------------------------------------------
#
# Copyright (c) 1986-2019 Pixar. All rights reserved.
#
# The information in this file (the "Software") is provided for the exclusive
# use of the software licensees of Pixar ("Licensees").  Licensees have the
# right to incorporate the Software into other products for use by other
# authorized software licensees of Pixar, without fee. Except as expressly
# permitted herein, the Software may not be disclosed to third parties, copied
# or duplicated in any form, in whole or in part, without the prior written
# permission of Pixar.
#
# The copyright notices in the Software and this entire statement, including the
# above license grant, this restriction and the following disclaimer, must be
# included in all copies of the Software, in whole or in part, and all permitted
# derivative works of the Software, unless such copies or derivative works are
# solely in the form of machine-executable object code generated by a source
# language processor.
#
# PIXAR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL PIXAR BE
# LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION
# OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN
# CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  IN NO CASE WILL
# PIXAR'S TOTAL LIABILITY FOR ALL DAMAGES ARISING OUT OF OR IN CONNECTION WITH
# THE USE OR PERFORMANCE OF THIS SOFTWARE EXCEED $50.
#
# Pixar
# 1200 Park Ave
# Emeryville CA 94608
#
# ------------------------------------------------------------------------------
*/


#ifndef RixColorUtils_h
#define RixColorUtils_h

#include "RixShadingUtils.h"            // for PRMAN_INLINE

#define F_LOGDOTFIVE    (-0.30102999566f)
#define F_INVLOGDOTFIVE (-3.32192809489f)

enum RixColorSpace
{
    k_sRGB = 0,
    k_Rec709,
    k_Rec2020,
    k_DCI_P3,
    k_Alexa_wide,
    k_ACEScg,
    k_CinemaGamut,
    k_NTSC,
    k_numColorSpaces
};

// NOTE: All matrices assume their default illuminant (usually D65)

// clang-format off
static float s_RGBtoXYZ[][9] = {
    // sRGB D65
    {   0.4124564f, 0.3575761f, 0.1804375f,
        0.2126729f, 0.7151522f, 0.0721750f,
        0.0193339f, 0.1191920f, 0.9503041f
    },
    // Rec.709
    {   0.4123866f, 0.3575915f, 0.1804505f,
        0.2126368f, 0.7151830f, 0.0721802f,
        0.0193306f, 0.1191972f, 0.9503726f
    },
    // Rec.2020
    {   0.6369535f, 0.1446192f, 0.1688559f,
        0.2626983f, 0.6780088f, 0.0592929f,
        0.0000000f, 0.0280731f, 1.0608272f
    },
    // DCI-P3
    {   4.45169816e-01f, 2.77134409e-01f, 1.72282670e-01f,
        2.09491678e-01f, 7.21595254e-01f, 6.89130679e-02f,
       -3.63410132e-17f, 4.70605601e-02f, 9.07355394e-01f
    },
    // Alexa Wide
    {   0.638008f,  0.214704f,  0.097744f,
        0.291954f,  0.823841f, -0.115795f,
        0.002798f, -0.067034f,  1.153294f
    },
    // ACES cg
    {   0.66245418f, 0.13400421f, 0.15618769f,
        0.27222872f, 0.67408177f, 0.05368952f,
       -0.00557465f, 0.00406073f, 1.0103391f
    },
    // Canon Cinema Gamut
    {
        0.71603649f,  0.12968185f,  0.10471021f,
        0.26125656f,  0.86963121f, -0.13088776f,
       -0.00967617f, -0.23647866f,  1.3350552f,
    },
    // old NTSC - for backward compatibility
    {    1.909851f,  -0.984623f,   0.058331f,
       -0.532414f,   1.999082f,  -0.118429f,
       -0.288187f,  -0.028307f,   0.897936f
    }
};
// clang-format on

// clang-format off
static float s_XYZtoRGB[][9] = {
    // sRGB D65
    {   3.2404542f, -1.5371385f, -0.4985314f,
       -0.9692660f,  1.8760108f,  0.0415560f,
        0.0556434f, -0.2040259f,  1.0572252f
    },
    // Rec.709 D65
    {   3.24100326f, -1.53739899f, -0.49861587f,
       -0.96922426f,  1.87592999f,  0.04155422f,
        0.05563942f, -0.2040112f,   1.05714897f
    },
    // Rec.2020 D65
    {   1.71666343f, -0.35567332f, -0.25336809f,
       -0.66667384f,  1.61645574f,  0.0157683f,
        0.01764248f, -0.04277698f,  0.94224328f
    },
    // DCI-P3
    {   2.72539403f, -1.01800301f, -0.4401632f,
       -0.79516803f,  1.68973205f,  0.02264719f,
        0.04124189f, -0.08763902f,  1.10092938f
    },
    // Alexa Wide
    {   1.78906454f, -0.48253382f, -0.20007503f,
       -0.63984874f,  1.3964001f,   0.19443223f,
       -0.04153097f,  0.08233496f,  0.87886816f
    },
    // ACES cg
    {   1.64102338f, -0.32480329f, -0.2364247f,
       -0.66366286f,  1.61533159f,  0.01675635f,
        0.01172189f, -0.00828444f,  0.98839486f
    },
    // Canon Cinema Gamut
    {
        1.48984566f, -0.2609007f,  -0.14242914f,
       -0.45817234f,  1.26164365f,  0.15962564f,
       -0.07035813f,  0.22158431f,  0.77627493f
    },
    // old NTSC - for backward compatibility
    {   0.606937f, 0.298939f, 0.0f,
        0.173509f, 0.586625f, 0.066099f,
        0.200263f, 0.114436f, 1.115749f
    }
};
// clang-format on

/*
 * RixHsvToRgb(hsv, rgb) converts a hue/saturation/value triple into an
 * RGB triple.
 * Based on the "hexcone" model.  See A.R.Smith, Color Gamut Transform Pairs,
 * Proc. Siggraph '78.
 */
#define IFLOOR(x) (((x) < 0.0f && (x) != (int)(x)) ? (int)x - 1 : (int)x)

PRMAN_INLINE void
RixHsvToRgb(RtColorRGB const& hsv, RtColorRGB& rgb)
{
    float h, f;
    float m, n, k;
    int i;

    h = hsv.r;
    h = h - static_cast<float>(static_cast<int>(h)) + (h < 0.0f ? 1.0f : 0.0f); /* h mod 1.0 */
    h = h * 6.0f;
    i = IFLOOR(h); /* integer part */
    f = h - static_cast<float>(i);     /* fractional part */
    m = hsv.b * (1.0f - hsv.g);
    n = hsv.b * (1.0f - (hsv.g * f));
    k = hsv.b * (1.0f - (hsv.g * (1.0f - f)));

    switch (i)
    { /* around the color wheel */
        case 0:
        default:
            rgb.r = hsv.b;
            rgb.g = k;
            rgb.b = m;
            break;
        case 1:
            rgb.r = n;
            rgb.g = hsv.b;
            rgb.b = m;
            break;
        case 2:
            rgb.r = m;
            rgb.g = hsv.b;
            rgb.b = k;
            break;
        case 3:
            rgb.r = m;
            rgb.g = n;
            rgb.b = hsv.b;
            break;
        case 4:
            rgb.r = k;
            rgb.g = m;
            rgb.b = hsv.b;
            break;
        case 5:
            rgb.r = hsv.b;
            rgb.g = m;
            rgb.b = n;
            break;
    }
}

PRMAN_INLINE void
RixRgbToHsv(RtColorRGB const& rgb, RtColorRGB& hsv)
{
    int spoke;     /* part of color wheel it's in */
    float h, s, v; /* hue, saturation & value components of HSV */
    float x;       /* smallest RGB component */

    /* set v to largest rgb component, x to smallest */
    if (rgb.r > rgb.g)
    {
        if (rgb.r > rgb.b)
        {
            v     = rgb.r;
            spoke = 0;
        }
        else
        {
            v     = rgb.b;
            spoke = 4;
        }
        if (rgb.g < rgb.b)
        {
            x = rgb.g;
            spoke++;
        }
        else
        {
            x = rgb.b;
        }
    }
    else
    {
        if (rgb.g > rgb.b)
        {
            v     = rgb.g;
            spoke = 2;
        }
        else
        {
            v     = rgb.b;
            spoke = 4;
        }
        if (rgb.r < rgb.b)
        {
            x = rgb.r;
        }
        else
        {
            x = rgb.b;
            spoke++;
        }
    }

    h = 0.0f;        /* default hue is red */
    s = 0.0f;        /* default saturation is unsaturated (gray) */
    if (v < 0.0001f) /* black */
        goto done;

    s = (v - x) / v; /* actual saturation */
    if (s < 0.0001f) /* gray */
        goto done;

    /* now compute actual hue */
    switch (spoke)
    {
        case 0: /* red largest, blue smallest */
            h = 1.0f - (v - rgb.g) / (v - x);
            break;

        case 1: /* red largest, green smallest */
            h = 5.0f + (v - rgb.b) / (v - x);
            break;

        case 2: /* green largest, red smallest */
            h = 3.0f - (v - rgb.b) / (v - x);
            break;

        case 3: /* green largest, blue smallest */
            h = 1.0f + (v - rgb.r) / (v - x);
            break;

        case 4: /* blue largest, red smallest */
            h = 3.0f + (v - rgb.g) / (v - x);
            break;

        case 5: /* blue largest, green smallest */
            h = 5.0f - (v - rgb.r) / (v - x);
            break;
    }
done:
    hsv.r = h * (1.0f / 6.0f);
    hsv.g = s;
    hsv.b = v;
}

/*
 * RixHslToRgb(hsl, rgb) converts a color in hue/saturation/lightness space into
 * an RGB triple.
 *
 * Based on the HLS color model.  See Foley and Van Dam, "Fundamentals of
 * Interactive Computer Graphics", 1982.
 *
 * RixHslToRgb assumes h is in the range [0,1) instead of [0,360) as defined
 * in Foley and Van Dam.
 */

// private function
PRMAN_INLINE float
rixValue(float n1, float n2, float hue)
{
    /* hue = hue mod 1.0 */
    hue = hue - (float)(int)hue + (hue < (float)0.0 ? (float)1.0 : (float)0.0);
    if (hue < (float)0.16666667)
        return (n1 + (n2 - n1) * hue * (float)6.0);
    if (hue < (float)0.5)
        return (n2);
    if (hue < (float)0.66666667)
        return (n1 + (n2 - n1) * ((float)4.0 - hue * (float)6.0));
    return (n1);
}

PRMAN_INLINE void
RixHslToRgb(RtColorRGB const& hsl, RtColorRGB& rgb)
{
    float h, s, l;
    float m1, m2;

    h = hsl.r;
    s = hsl.g;
    l = hsl.b;

    if (s == 0.0f)
    {
        rgb.r = rgb.g = rgb.b = l;
        return;
    }

    if (l <= 0.5f)
        m2 = l * (1.0f + s);
    else
        m2 = l + s - l * s;

    m1 = 2.0f * l - m2;

    rgb.r = rixValue(m1, m2, h + 0.33333333f);
    rgb.g = rixValue(m1, m2, h);
    rgb.b = rixValue(m1, m2, h - 0.33333333f);
}

PRMAN_INLINE void
RixRgbToHsl(RtColorRGB const& rgb, RtColorRGB& hsl)
{
    float maxi, mini, maxmin;
    float rc, gc, bc, hue, sat, light;

    if (rgb.r < rgb.g)
    {
        mini = (rgb.r < rgb.b) ? rgb.r : rgb.b;
        maxi = (rgb.g > rgb.b) ? rgb.g : rgb.b;
    }
    else
    {
        mini = (rgb.g < rgb.b) ? rgb.g : rgb.b;
        maxi = (rgb.r > rgb.b) ? rgb.r : rgb.b;
    }
    light = (maxi + mini) / 2.0f;

    if (maxi == mini)
        hsl.r = hsl.g = 0.0f;
    else
    {
        if (light < 0.5f)
            sat = (maxi - mini) / (maxi + mini);
        else
            sat = (maxi - mini) / (2.0f - maxi - mini);

        maxmin = 1.0f / (maxi - mini);
        rc     = (maxi - rgb.r) * maxmin;
        gc     = (maxi - rgb.g) * maxmin;
        bc     = (maxi - rgb.b) * maxmin;

        if (rgb.r == maxi)
            hue = bc - gc;
        else if (rgb.g == maxi)
            hue = 2.0f + rc - bc;
        else
            hue = 4.0f + gc - rc;

        hue /= 6.0f;
        if (hue < 0.0f)
            hue = hue + 1.0f;

        hsl.r = hue;
        hsl.g = sat;
    }
    hsl.b = light;
}

/*
 * RixXyzToRgb(xyz, rgb) converts a color in CIE xyz space into a RGB triple.
 * The functions default to sRGB but other pre-defined color spaces are
 * available.
 * See RixColorSpace for a full list.
 */

// clang-format off
PRMAN_INLINE void
RixXyzToRgb(RtColorRGB const& xyz, RtColorRGB& rgb, RixColorSpace cs = k_sRGB)
{
    if (cs < 0 || cs >= k_numColorSpaces)
        return;

    rgb.r = s_XYZtoRGB[cs][0] * xyz.r + s_XYZtoRGB[cs][1] * xyz.g + s_XYZtoRGB[cs][2] * xyz.b;
    rgb.g = s_XYZtoRGB[cs][3] * xyz.r + s_XYZtoRGB[cs][4] * xyz.g + s_XYZtoRGB[cs][5] * xyz.b;
    rgb.b = s_XYZtoRGB[cs][6] * xyz.r + s_XYZtoRGB[cs][7] * xyz.g + s_XYZtoRGB[cs][8] * xyz.b;
}

PRMAN_INLINE void
RixRgbToXyz(RtColorRGB const& rgb, RtColorRGB& xyz, RixColorSpace cs = k_sRGB)
{
    if (cs < 0 || cs >= k_numColorSpaces)
        return;

    xyz.r = s_RGBtoXYZ[cs][0] * rgb.r + s_RGBtoXYZ[cs][1] * rgb.g + s_RGBtoXYZ[cs][2] * rgb.b;
    xyz.g = s_RGBtoXYZ[cs][3] * rgb.r + s_RGBtoXYZ[cs][4] * rgb.g + s_RGBtoXYZ[cs][5] * rgb.b;
    xyz.b = s_RGBtoXYZ[cs][6] * rgb.r + s_RGBtoXYZ[cs][7] * rgb.g + s_RGBtoXYZ[cs][8] * rgb.b;
}

PRMAN_INLINE RtFloat
RixInputRange(const RtFloat& f, const RtFloat& min, const RtFloat& max)
{
    if (min == 0.f && max == 1.f)
        return f;
    if (min == max)
        return ((f < min)? 0.f : 1.f);
    return ((f - min) / (max - min));
}

PRMAN_INLINE RtColorRGB
RixInputRange(const RtColorRGB& rgb, const RtFloat& min, const RtFloat& max)
{
    RtColorRGB result;
    for (int i=0; i<3; i++)
        result[i] = RixInputRange(rgb[i], min, max);
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixInputRange(const RtColorRGB& rgb, const T& min, const T& max)
{
    RtColorRGB result;
    for (int i=0; i<3; i++)
        result[i] = RixInputRange(rgb[i], min[i], max[i]);
    return result;
}

PRMAN_INLINE RtFloat
RixOutputRange(const RtFloat& f, const RtFloat& min, const RtFloat& max)
{
    if (min == 0.f && max == 1.f)
        return f;
    return ((max - min) * f + min);
}

PRMAN_INLINE RtColorRGB
RixOutputRange(const RtColorRGB& rgb, const RtFloat& min, const RtFloat& max)
{
    RtColorRGB result;
    for (int i=0; i<3; i++)
        result[i] = RixOutputRange(rgb[i], min, max);
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixOutputRange(const RtColorRGB& rgb, const T& min, const T& max)
{
    RtColorRGB result;
    for (int i=0; i<3; i++)
        result[i] = RixOutputRange(rgb[i], min[i], max[i]);
    return result;
}

PRMAN_INLINE RtFloat
RixExposure(RtFloat const& f, RtFloat const& e)
{
    if (e != 0.0f)
        return (f * powf(2.f, e));
    return f;
}

PRMAN_INLINE RtColorRGB
RixExposure(const RtColorRGB& rgb, const RtFloat& e)
{
    RtColorRGB result = rgb;
    if (e != 0.0f)
    {
        RtFloat exposure = powf(2.f, e);
        result[0] *= exposure;
        result[1] *= exposure;
        result[2] *= exposure;
    }
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixExposure(const RtColorRGB& rgb, const T& e)
{
    RtColorRGB result;
    result.r = RixExposure(rgb[0], e[0]);
    result.g = RixExposure(rgb[1], e[1]);
    result.b = RixExposure(rgb[2], e[2]);
    return result;
}

PRMAN_INLINE RtFloat
RixGamma(const RtFloat& f, const RtFloat& g)
{
    if (g != 1.0f)
        return powf(RixMax(f, 0.f), 1.f / RixMax(g, 1e-5f));
    return f;
}

PRMAN_INLINE RtColorRGB
RixGamma(const RtColorRGB& rgb, const RtFloat& g)
{
    RtColorRGB result = rgb;
    if (g != 1.0f)
    {
        RtFloat safe_g = 1.f/RixMax(g, 1e-5f);
        result[0] = powf(rgb[0], safe_g);
        result[1] = powf(rgb[1], safe_g);
        result[2] = powf(rgb[2], safe_g);
    }
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixGamma(const RtColorRGB& rgb, const T& g)
{
    RtColorRGB result;
    result[0] = RixGamma(rgb[0], g[0]);
    result[1] = RixGamma(rgb[1], g[1]);
    result[2] = RixGamma(rgb[2], g[2]);
    return result;
}

PRMAN_INLINE RtFloat
RixContrast(RtFloat f, RtFloat contrast, RtFloat pivot)
{
    if (contrast == 0.f || f == pivot)
    {
        return f;
    }

    RtFloat result = f;
    RtFloat C = (RixClamp(contrast, -1.f, 1.f) * 0.5f) + 0.5f;
    C = RixMin( C, 0.999f );
    RtFloat power = logf(1.0f - C) / F_LOGDOTFIVE;
    if ( f < pivot )
    {
        result = f / pivot;
        result = powf(result, power);
        result *= pivot;
    }
    else
    {
        result = (f - pivot) / (1.0f - pivot);
        result = 1.0f - powf(1.0f - result, power);
        result *= (1.0f - pivot) + pivot;
    }
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixContrast(const RtColorRGB& rgb, const T& contrast, const T& pivot)
{
    RtColorRGB result;
    for (int i=0; i<3; i++)
        result[i] = RixContrast(rgb[i], contrast[i], pivot[i]);
    return result;
}

PRMAN_INLINE RtColorRGB
RixHsvCorrect(const RtColorRGB& rgb,
              const RtFloat& hue, const RtFloat& sat, const RtFloat& val)
{
    RtColorRGB tmp, result;
    RixRgbToHsv(rgb, tmp);
    tmp[0] = RixFractional(tmp[0] + hue);
    tmp[1] = RixClamp(tmp[1] * sat, 0.f, 1.f);
    tmp[2] = RixClamp(tmp[2] * val, 0.f, 1.f);
    RixHsvToRgb(tmp, result);
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixHsvCorrect(const RtColorRGB& rgb, const T& hsv)
{
    RtColorRGB tmp, result;
    RixRgbToHsv(rgb, tmp);
    tmp[0] = RixFractional(tmp[0] + hsv[0]);
    tmp[1] = RixClamp(tmp[1] * hsv[1], 0.f, 1.f);
    tmp[2] = RixClamp(tmp[2] * hsv[2], 0.f, 1.f);
    RixHsvToRgb(tmp, result);
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixHslCorrect(const RtColorRGB& rgb, const T& hsl)
{
    RtColorRGB tmp, result;
    RixRgbToHsl(rgb, tmp);
    tmp[0] = RixFractional(tmp[0] + hsl[0]);
    tmp[1] = RixClamp(tmp[1] * hsl[1], 0.f, 1.f);
    tmp[2] = RixClamp(tmp[2] * hsl[2], 0.f, 1.f);
    RixHslToRgb(tmp, result);
    return result;
}

template <typename T>
PRMAN_INLINE RtColorRGB
RixColorClamp(const RtColorRGB& rgb, const T& min, const T& max)
{
    RtColorRGB result;
    for (int i=0; i<3; i++)
        result[i] = RixClamp(rgb[i], min[i], max[i]);
    return result;
}

PRMAN_INLINE RtColorRGB
RixSaturation(const RtColorRGB& rgb, const float saturation)
{
    RtColorRGB result = rgb;
    if (saturation != 1.f)
    {
        float middleGrey = (1.f - RixMax(0.f, saturation)) * rgb.Luminance();
        result.r = RixMax(0.f, middleGrey + saturation * rgb.r);
        result.g = RixMax(0.f, middleGrey + saturation * rgb.g);
        result.b = RixMax(0.f, middleGrey + saturation * rgb.b);
    }
    return result;
}

PRMAN_INLINE void
RixSaturation(RtColorRGB& rgb, const float saturation)
{
    if (saturation != 1.f)
    {
        float middleGrey = (1.f - RixMax(0.f, saturation)) * rgb.Luminance();
        rgb.r = RixMax(0.f, middleGrey + saturation * rgb.r);
        rgb.g = RixMax(0.f, middleGrey + saturation * rgb.g);
        rgb.b = RixMax(0.f, middleGrey + saturation * rgb.b);
    }
}


// clang-format on

#endif // RixColorUtils_h