.. _stdlib_color_utils: ============ Color module ============ This module provides utility functions for working with colors, including color conversion, color manipulation, and random color generation. It supports both float4 (linear, sRGB, and HSVA color spaces) and uint (0xAARRGGBB) color formats. To add this module to your project, add the following line to your project file:: require engine.math.color_utils // or require engine.core +++++++++ Constants +++++++++ .. _global-color_utils-BLACK_COLOR: .. das:attribute:: BLACK_COLOR = float4(0f,0f,0f,1f) Black color .. _global-color_utils-WHITE_COLOR: .. das:attribute:: WHITE_COLOR = float4(1f,1f,1f,1f) White color .. _global-color_utils-CLEAR_COLOR: .. das:attribute:: CLEAR_COLOR = float4(0f,0f,0f,0f) Clear color, alpha = 0 .. _global-color_utils-RED_COLOR: .. das:attribute:: RED_COLOR = float4(1f,0f,0f,1f) Red color .. _global-color_utils-GREEN_COLOR: .. das:attribute:: GREEN_COLOR = float4(0f,1f,0f,1f) Green color .. _global-color_utils-BLUE_COLOR: .. das:attribute:: BLUE_COLOR = float4(0f,0f,1f,1f) Blue color .. _global-color_utils-YELLOW_COLOR: .. das:attribute:: YELLOW_COLOR = float4(1f,0.92f,0.016f,1f) Yellow color .. _global-color_utils-CYAN_COLOR: .. das:attribute:: CYAN_COLOR = float4(0f,1f,1f,1f) Cyan color .. _global-color_utils-MAGENTA_COLOR: .. das:attribute:: MAGENTA_COLOR = float4(1f,0f,1f,1f) Magenta color .. _global-color_utils-GRAY_COLOR: .. das:attribute:: GRAY_COLOR = float4(0.5f,0.5f,0.5f,1f) Gray color .. _global-color_utils-LIGHT_GRAY_COLOR: .. das:attribute:: LIGHT_GRAY_COLOR = float4(0.75f,0.75f,0.75f,1f) Light gray color .. _global-color_utils-DARK_GRAY_COLOR: .. das:attribute:: DARK_GRAY_COLOR = float4(0.25f,0.25f,0.25f,1f) Dark gray color +++++++++ Functions +++++++++ * :ref:`float4_to_color32 (color: float4) : uint ` * :ref:`float4_to_color32 (r: float; g: float; b: float; a: float = 1f) : uint ` * :ref:`make_color32 (r: int; g: int; b: int; a: int) : uint ` * :ref:`color32_to_float4 (color: uint) : float4 ` * :ref:`lerp_color32 (a: uint; b: uint; t: float) : uint ` * :ref:`add_color32 (a: uint; b: uint) : uint ` * :ref:`sub_color32 (a: uint; b: uint) : uint ` * :ref:`mul_color32 (a: uint; b: uint) : uint ` * :ref:`mul_color32 (a: uint; b: float) : uint ` * :ref:`desaturate (color: float4; amount: float) : float4 ` * :ref:`desaturate (color: float4) : float4 ` * :ref:`desaturate (color: uint) : uint ` * :ref:`desaturate (color: uint; amount: float) : uint ` * :ref:`srgb_to_linear (color: float4) : float4 ` * :ref:`linear_to_srgb (color: float4) : float4 ` * :ref:`srgb_to_linear (color: uint) : uint ` * :ref:`linear_to_srgb (color: uint) : uint ` * :ref:`premultiply_alpha (color: float4) : float4 ` * :ref:`premultiply_alpha (color: uint) : uint ` * :ref:`rgb_to_hsv (rgb: float4) : float3 ` * :ref:`rgb_to_hsva (rgba: float4) : float4 ` * :ref:`rgb_to_hsva (rgba: uint) : float4 ` * :ref:`hsv_to_rgb (hsv: float3; alpha: float = 1f) : float4 ` * :ref:`hsv_to_rgb (h: float; s: float; v: float; alpha: float = 1f) : float4 ` * :ref:`hsv_to_rgb (hsva: float4) : float4 ` * :ref:`get_random_color (hsv_min: float3 = float3(0f,0.2f,0.35f); hsv_max: float3 = float3(1f,1f,1f)) : float4 ` * :ref:`get_random_color32 (hsv_min: float3 = float3(0f,0.2f,0.35f); hsv_max: float3 = float3(1f,1f,1f)) : uint ` .. _function-color_utils_float4_to_color32_float4: .. das:function:: float4_to_color32(color: float4) : uint Converts a float4 'color' to a uint color32. :Arguments: * **color** : float4 .. _function-color_utils_float4_to_color32_float_float_float_float: .. das:function:: float4_to_color32(r: float; g: float; b: float; a: float = 1f) : uint Converts a float4 'color' to a uint color32. :Arguments: * **r** : float * **g** : float * **b** : float * **a** : float .. _function-color_utils_make_color32_int_int_int_int: .. das:function:: make_color32(r: int; g: int; b: int; a: int) : uint Makes a color32 from the given arguments. :Arguments: * **r** : int * **g** : int * **b** : int * **a** : int .. _function-color_utils_color32_to_float4_uint: .. das:function:: color32_to_float4(color: uint) : float4 Converts a uint color32 to a float4. :Arguments: * **color** : uint .. _function-color_utils_lerp_color32_uint_uint_float: .. das:function:: lerp_color32(a: uint; b: uint; t: float) : uint Linearly interpolates between two color32 values. :Arguments: * **a** : uint * **b** : uint * **t** : float .. _function-color_utils_add_color32_uint_uint: .. das:function:: add_color32(a: uint; b: uint) : uint Adds two color32 values together. :Arguments: * **a** : uint * **b** : uint .. _function-color_utils_sub_color32_uint_uint: .. das:function:: sub_color32(a: uint; b: uint) : uint Subtracts one color32 value from another. :Arguments: * **a** : uint * **b** : uint .. _function-color_utils_mul_color32_uint_uint: .. das:function:: mul_color32(a: uint; b: uint) : uint Multiplies two color32 values together. :Arguments: * **a** : uint * **b** : uint .. _function-color_utils_mul_color32_uint_float: .. das:function:: mul_color32(a: uint; b: float) : uint Multiplies a color32 value by a scalar. :Arguments: * **a** : uint * **b** : float .. _function-color_utils_desaturate_float4_float: .. das:function:: desaturate(color: float4; amount: float) : float4 Desaturates a color by a given amount. :Arguments: * **color** : float4 * **amount** : float .. _function-color_utils_desaturate_float4: .. das:function:: desaturate(color: float4) : float4 Desaturates a color. :Arguments: * **color** : float4 .. _function-color_utils_desaturate_uint: .. das:function:: desaturate(color: uint) : uint Desaturates a color. :Arguments: * **color** : uint .. _function-color_utils_desaturate_uint_float: .. das:function:: desaturate(color: uint; amount: float) : uint Desaturates a color by a given amount. :Arguments: * **color** : uint * **amount** : float .. _function-color_utils_srgb_to_linear_float4: .. das:function:: srgb_to_linear(color: float4) : float4 Converts an sRGB color to linear color space. :Arguments: * **color** : float4 .. _function-color_utils_linear_to_srgb_float4: .. das:function:: linear_to_srgb(color: float4) : float4 Converts a linear color to sRGB color space. :Arguments: * **color** : float4 .. _function-color_utils_srgb_to_linear_uint: .. das:function:: srgb_to_linear(color: uint) : uint Converts an sRGB color to linear color space. :Arguments: * **color** : uint .. _function-color_utils_linear_to_srgb_uint: .. das:function:: linear_to_srgb(color: uint) : uint Converts a linear color to sRGB color space. :Arguments: * **color** : uint .. _function-color_utils_premultiply_alpha_float4: .. das:function:: premultiply_alpha(color: float4) : float4 Premultiplies the alpha channel of a color. :Arguments: * **color** : float4 .. _function-color_utils_premultiply_alpha_uint: .. das:function:: premultiply_alpha(color: uint) : uint Premultiplies the alpha channel of a color. :Arguments: * **color** : uint .. _function-color_utils_rgb_to_hsv_float4: .. das:function:: rgb_to_hsv(rgb: float4) : float3 Converts an RGB color to HSV color space. HSV stands for Hue, Saturation, Value. In the returned value, field `x` represents hue, or the position in the spectrum; y - saturation, the color saturation, z - value, the color brightness. :Arguments: * **rgb** : float4 .. _function-color_utils_rgb_to_hsva_float4: .. das:function:: rgb_to_hsva(rgba: float4) : float4 Converts an RGBA color to HSVA color space. Note that in the returned value field `w` represents the alpha channel. :Arguments: * **rgba** : float4 .. _function-color_utils_rgb_to_hsva_uint: .. das:function:: rgb_to_hsva(rgba: uint) : float4 Converts an RGBA color to HSVA color space. Note that in the returned value field `w` represents the alpha channel. :Arguments: * **rgba** : uint .. _function-color_utils_hsv_to_rgb_float3_float: .. das:function:: hsv_to_rgb(hsv: float3; alpha: float = 1f) : float4 Converts an HSV color to RGB color space. :Arguments: * **hsv** : float3 * **alpha** : float .. _function-color_utils_hsv_to_rgb_float_float_float_float: .. das:function:: hsv_to_rgb(h: float; s: float; v: float; alpha: float = 1f) : float4 Converts an HSV color to RGB color space. :Arguments: * **h** : float * **s** : float * **v** : float * **alpha** : float .. _function-color_utils_hsv_to_rgb_float4: .. das:function:: hsv_to_rgb(hsva: float4) : float4 Converts an HSVA color to RGBA color space. :Arguments: * **hsva** : float4 .. _function-color_utils_get_random_color_float3_float3: .. das:function:: get_random_color(hsv_min: float3 = float3(0f,0.2f,0.35f); hsv_max: float3 = float3(1f,1f,1f)) : float4 Returns a random color in the given HSV range. :Arguments: * **hsv_min** : float3 * **hsv_max** : float3 .. _function-color_utils_get_random_color32_float3_float3: .. das:function:: get_random_color32(hsv_min: float3 = float3(0f,0.2f,0.35f); hsv_max: float3 = float3(1f,1f,1f)) : uint Returns a random color. :Arguments: * **hsv_min** : float3 * **hsv_max** : float3