godot::prelude

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.

pub fn try_to_rgb(self) -> Result<Color, String>

Fallible ColorHsv conversion into Color. See also: ColorHsv::to_rgb.

Trait Implementations§

§

impl ApproxEq for ColorHsv

§

fn approx_eq(&self, other: &ColorHsv) -> bool

Hue values are wrapped before approximate comparison.

§

impl Clone for ColorHsv

§

fn clone(&self) -> ColorHsv

Returns a copy of the value. Read more
1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
§

impl Debug for ColorHsv

§

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter. Read more
§

impl Default for ColorHsv

§

fn default() -> ColorHsv

Returns the “default value” for a type. Read more
§

impl PartialEq for ColorHsv

§

fn eq(&self, other: &ColorHsv) -> bool

Tests for self and other values to be equal, and is used by ==.
1.0.0 · Source§

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.
§

impl PartialOrd for ColorHsv

§

fn partial_cmp(&self, other: &ColorHsv) -> Option<Ordering>

This method returns an ordering between self and other values if one exists. Read more
1.0.0 · Source§

fn lt(&self, other: &Rhs) -> bool

Tests less than (for self and other) and is used by the < operator. Read more
1.0.0 · Source§

fn le(&self, other: &Rhs) -> bool

Tests less than or equal to (for self and other) and is used by the <= operator. Read more
1.0.0 · Source§

fn gt(&self, other: &Rhs) -> bool

Tests greater than (for self and other) and is used by the > operator. Read more
1.0.0 · Source§

fn ge(&self, other: &Rhs) -> bool

Tests greater than or equal to (for self and other) and is used by the >= operator. Read more
§

impl Copy for ColorHsv

§

impl StructuralPartialEq for ColorHsv

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = Infallible

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.