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
impl ColorHsv
pub const fn from_hsv(h: f32, s: f32, v: f32) -> 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
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
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
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
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.
pub fn try_to_rgb(self) -> Result<Color, String>
pub fn try_to_rgb(self) -> Result<Color, String>
Fallible ColorHsv
conversion into Color
. See also: ColorHsv::to_rgb
.