Struct ColorHsv

pub struct ColorHsv {
    pub h: f32,
    pub s: f32,
    pub v: f32,
    pub a: f32,
}

Expand description

HSVA floating-number Color representation.

Godot’s Color built-in type supports mainly RGBA floating point-based notation. ColorHsv supports manipulating its HSVA representation by introducing conversion methods between itself and Color.

ColorHsv is not a GodotType. To use it in properties expecting Color, you need to convert it back to this type.

A Color created by ColorHsv::to_rgb() is equal to one created by Color::from_hsv(h, s, v), but the conversion time is approximately 4 times faster - partly because it avoids calls between Godot and Rust during conversion.

§Conversions

Both conversions (Color to ColorHsv and ColorHsv to Color) will panic if RGBA or HSVA values are not within range 0.0..=1.0. To ensure the values are in valid range, methods Color::normalized and ColorHsv::normalized_clamped_h or ColorHsv::normalized_wrapped_h can be used.

use godot::builtin::{Color, ColorHsv};

let rgb = Color::from_rgb(1.15, 0.0, 0.0);
let hsv = ColorHsv::from_hsv(1.15, 0.0, 0.0);

Such colors can’t be converted - below calls will panic, because at least one of the color values are not within 0.0..=1.0 range.

let hsv_from_rgb = rgb.to_hsv();

let rgb_from_hsv = hsv.to_rgb();

After normalization all values are within 0.0..=1.0 range, so the conversions are safe and won’t panic.

let hsv_from_rgb = rgb.normalized().to_hsv();
let rgb_from_hsv = hsv.normalized_wrapped_h().to_rgb();

§Precision warning

Conversions between f32-based RGB and HSV representations are not completely lossless. Try to avoid repeatable Color -> ColorHsv -> Color roundtrips. One way to minimalize possible distortions is to keep ColorHsv on the Rust side, apply all changes to this struct and convert it to Color before moving to the Godot side, instead of fetching Color from Godot side before every mutation, though changes should be minimal if color values are mutated either only on Color or ColorHsv side.

§Examples

use godot::builtin::{Color, ColorHsv};
use godot::builtin::math::assert_eq_approx;

// ColorHsv can be constructed from only Hue, Saturation and Value.  
let mut c_hsv = ColorHsv::from_hsv(0.74, 0.69, 0.18);

// Or with Alpha value also specified. If not specified, it is set at 1.0.
let mut c_hsv2 = ColorHsv::from_hsva(0.74, 0.69, 0.18, 1.0);

assert_eq!(c_hsv, c_hsv2);

// Two way conversion: Color -> ColorHsv -> Color is not entirely lossless. Such repeatable
// conversions should be avoided, as the data loss could build up to significant values if values
// are mutated both on `Color` and `ColorHsv`.
let color1 = Color::from_rgb(0.74, 0.69, 0.18);
let color2 = color1.to_hsv().to_rgb();

assert_ne!(color1, color2);
assert_eq_approx!(color1.r, color2.r);
assert_eq_approx!(color1.g, color2.g);
assert_eq_approx!(color1.b, color2.b);

§Reference

Smith, Alvy Ray. “Color gamut transform pairs.” ACM Siggraph Computer Graphics 12.3 (1978): 12-19.

Fields§

§h: f32§s: f32§v: f32§a: f32

Implementations§

§

impl ColorHsv

pub const fn from_hsv(h: f32, s: f32, v: f32) -> ColorHsv

Construct from Hue, Saturation and Value.

Alpha will be set at 1. by default. To construct with custom Alpha value, use ColorHsv::from_hsva constructor.

pub const fn from_hsva(h: f32, s: f32, v: f32, a: f32) -> ColorHsv

Construct from Hue, Saturation, Value and Alpha.

To construct with Alpha set as default 1., use ColorHsv::from_hsv constructor.

pub fn normalized_clamped_h(self) -> ColorHsv

Transforms the ColorHsv into one with values clamped to the range valid for transformation into Color.

To normalize with Hue value wrapped, not clamped (for continuity around the hue wheel), use ColorHsv::normalized_wrapped_h.

§Example

use godot::builtin::ColorHsv;
use godot::builtin::math::assert_eq_approx;

let hsv_c = ColorHsv::from_hsv(1.35, -0.60, 1.15);
let normalized = hsv_c.normalized_clamped_h();
assert_eq_approx!(normalized, ColorHsv::from_hsv(1.0, 0.0, 1.0));

pub fn normalized_wrapped_h(self) -> ColorHsv

Transforms the ColorHsv into one with Hue value wrapped and SVA clamped to the range valid for transformation into Color.

To normalize with Hue value clamped in the same way as SVA, use ColorHsv::normalized_clamped_h.

§Example

use godot::builtin::ColorHsv;
use godot::builtin::math::assert_eq_approx;

let hsv_c = ColorHsv::from_hsv(1.35, -0.60, 1.15);
let normalized = hsv_c.normalized_wrapped_h();
assert_eq_approx!(normalized, ColorHsv::from_hsv(0.35, 0.0, 1.0));

pub fn to_rgb(self) -> Color

⚠️ Convert ColorHsv into Color.

§Panics

Method will panic if the HSVA values are outside of the valid range 0.0..=1.0. You can use ColorHsv::normalized_clamped_h or ColorHsv::normalized_wrapped_h to ensure they are in range, or use ColorHsv::try_to_rgb implementation.