Struct Color128

#[repr(C)]
pub struct Color128 {
    pub r: f32,
    pub g: f32,
    pub b: f32,
    pub a: f32,
}

A color value stored as 4 floats with values that are generally between 0 and 1! Note that there’s also a Color32 structure, and that 4 floats is generally a lot more than you need. So, use this for calculating individual colors at quality, but maybe store them en-masse with Color32!

Also note that RGB is often a terrible color format for picking colors, but it’s how our displays work and we’re stuck with it. If you want to create a color via code, try out the static Color.HSV method instead!

A note on gamma space vs. linear space colors! Color is not inherently one or the other, but most color values we work with tend to be gamma space colors, so most functions in StereoKit are gamma space. There are occasional functions that will ask for linear space colors instead, primarily in performance critical places, or places where a color may not always be a color! However, performing math on gamma space colors is bad, and will result in incorrect colors. We do our best to indicate what color space a function uses, but it’s not enforced through syntax! https://stereokit.net/Pages/StereoKit/Color.html

see also Color32 named_colors

Examples

use stereokit_rust::{util::{Color128, named_colors}, maths::Vec3};

// Cyan from different sources:
let color_cyan1: Color128  = named_colors::CYAN.into();
let color_cyan2: Color128  = [0.0, 1.0, 1.0, 1.0].into();
let color_cyan3 = Color128 {r: 0.0, g: 1.0, b: 1.0, a: 1.0};
let color_cyan4 = Color128::new (0.0, 1.0, 1.0, 1.0);
let color_cyan5 = Color128::rgba(0.0, 1.0, 1.0, 1.0);
let color_cyan6 = Color128::rgb (0.0, 1.0, 1.0 );
let color_cyan7 = Color128::hsv (0.5, 1.0, 1.0, 1.0);
let color_cyan8 = Color128::hsv_vec3 (Vec3::new(0.5, 1.0, 1.0), 1.0);
let color_cyan9 = Color128::lab (0.911, -0.493, 0.042, 1.0);
let color_cyanA = Color128::lab_vec3 (Vec3::new(0.911, -0.493, 0.042), 1.0);
let color_cyanB = Color128::hex (0x00FFFFFF);

assert_eq!(color_cyan1, color_cyanB);

Fields

r: f32

g: f32

b: f32

a: f32

Implementations

impl Color128

pub const BLACK: Color128

Opaque black color

pub const BLACK_TRANSPARENT: Color128

Transparent black color

pub const WHITE: Color128

Opaque white color

pub const fn new(r: f32, g: f32, b: f32, a: f32) -> Self

Try hsv instead! But if you really need to create a color from RGB values, I suppose you’re in the right place. All parameter values are generally in the range of 0-1. https://stereokit.net/Pages/StereoKit/Color/Color.html

pub const fn rgba(r: f32, g: f32, b: f32, a: f32) -> Self

Try hsv instead! But if you really need to create a color from RGB values, I suppose you’re in the right place. All parameter values are generally in the range of 0-1. https://stereokit.net/Pages/StereoKit/Color/Color.html

pub const fn new_rgb(r: f32, g: f32, b: f32) -> Self

👎Deprecated: Use Color128::rgb instead

Try hsv instead! But if you really need to create a color from RGB values, I suppose you’re in the right place. All parameter values are generally in the range of 0-1. Alpha will be set to 1.0 https://stereokit.net/Pages/StereoKit/Color/Color.html

pub const fn rgb(r: f32, g: f32, b: f32) -> Self

Try hsv instead! But if you really need to create a color from RGB values, I suppose you’re in the right place. All parameter values are generally in the range of 0-1. Alpha will be set to 1.0 https://stereokit.net/Pages/StereoKit/Color/Color.html

pub fn hsv(hue: f32, saturation: f32, value: f32, transparency: f32) -> Color128

Creates a Red/Green/Blue gamma space color from Hue/Saturation/Value information. https://stereokit.net/Pages/StereoKit/Color/HSV.html

pub fn hsv_vec3(vec: impl Into<Vec3>, transparency: f32) -> Self

Creates a Red/Green/Blue gamma space color from Hue/Saturation/Value information. https://stereokit.net/Pages/StereoKit/Color/HSV.html

see also color_hsv

pub fn lab(l: f32, a: f32, b: f32, transparency: f32) -> Self

Creates a gamma space RGB color from a CIE-Lab color space. CIE-Lab is a color space that models human perception, and has significantly more accurate to perception lightness values, so this is an excellent color space for color operations that wish to preserve color brightness properly.

Traditionally, values are L [0,100], a,b [-200,+200] but here we normalize them all to the 0-1 range. If you hate it, let me know why! https://stereokit.net/Pages/StereoKit/Color/LAB.html

see also color_lab

pub fn lab_vec3(vec: Vec3, transparency: f32) -> Self

Creates a gamma space RGB color from a CIE-Lab color space. CIE-Lab is a color space that models human perception, and has significantly more accurate to perception lightness values, so this is an excellent color space for color operations that wish to preserve color brightness properly.

Traditionally, values are L [0,100], a,b [-200,+200] but here we normalize them all to the 0-1 range. If you hate it, let me know why! https://stereokit.net/Pages/StereoKit/Color/LAB.html

see also color_lab

pub fn hex(hex_value: u32) -> Self

Create a color from an integer based hex value! This can make it easier to copy over colors from the web. This isn’t a string function though, so you’ll need to fill it out the whole way. Ex: Color32::Hex(0x0000FFFF) would be RGBA(0,0,1,1). https://stereokit.net/Pages/StereoKit/Color/Hex.html

pub fn lerp(a: Color128, b: Color128, t: f32) -> Self

This will linearly blend between two different colors! Best done on linear colors, rather than gamma corrected colors, but will work either way. This will not clamp the percentage to the 0-1 range. https://stereokit.net/Pages/StereoKit/Color/Lerp.html

• a - The first color, this will be the result if t is 0.
• b - The second color, this will be the result if t is 1.
• t - A percentage representing the blend between a and b. This is not clamped to the 0-1 range, and will result in extrapolation outside this range.

see also crate::maths::lerp

Examples

use stereokit_rust::{util::{Color128, named_colors}};

let color_red: Color128  = named_colors::RED.into();
let color_blue: Color128  = named_colors::BLUE.into();
let color_mix = Color128::lerp(color_red, color_blue, 0.25);
assert_eq!(color_mix, Color128::rgb(0.75, 0.0, 0.25));

pub fn to_linear(&self) -> Self

Converts this from a gamma space color, into a linear space color! If this is not a gamma space color, this will just make your color wacky! https://stereokit.net/Pages/StereoKit/Color/ToLinear.html

see also color_to_linear

Examples

use stereokit_rust::{util::{Color128, named_colors}};

let color = Color128::rgb(0.75, 0.0, 0.25);
let color_linear = color.to_linear();
assert_eq!(color_linear, Color128 { r: 0.5310492, g: 0.0, b: 0.04736614, a: 1.0 });

pub fn to_gamma(&self) -> Self

Converts this from a linear space color, into a gamma space color! If this is not a linear space color, this will just make your color wacky! https://stereokit.net/Pages/StereoKit/Color/ToGamma.html

see also color_to_gamma

Examples

use stereokit_rust::{util::{Color128, named_colors}};

let color = Color128 { r: 0.5310492, g: 0.0, b: 0.04736614, a: 1.0 };
let color_gamma = color.to_gamma();
assert_eq!(color_gamma, Color128::rgb(0.75, 0.0, 0.25));

pub fn to_hsv(&self) -> Vec3

Converts the gamma space color to a Hue/Saturation/Value format! Does not consider transparency when calculating the result. https://stereokit.net/Pages/StereoKit/Color/ToHSV.html

Returns a Vec3 containing Hue, Saturation, and Value, stored in x, y, and z respectively. All values are between 0-1. see also color_to_hsv

Examples

use stereokit_rust::{util::{Color128, named_colors}, maths::Vec3};

let color = Color128::rgb(0.75, 0.0, 0.25);
let color_hsv = color.to_hsv();
assert_eq!(color_hsv, Vec3::new(0.9444444, 1.0, 0.75));

pub fn to_lab(&self) -> Vec3

Converts the gamma space RGB color to a CIE LAB color space value! Conversion back and forth from LAB space could be somewhat lossy. https://stereokit.net/Pages/StereoKit/Color/ToLAB.html

Returns a LAB Vec3 where x=L, y=A, z=B.
see also color_to_lab

Examples

use stereokit_rust::{util::{Color128, named_colors}, maths::Vec3};

let color = Color128::rgb(0.75, 0.0, 0.25);
let color_lab = color.to_lab();
assert_eq!(color_lab, Vec3{ x: 0.403711, y: 0.6654343, z: 0.55437124 });

Trait Implementations

impl Add for Color128

This will add a color component-wise with another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Addition.html

type Output = Color128

The resulting type after applying the + operator.

fn add(self, rhs: Self) -> Self

Performs the + operation.

impl AddAssign for Color128

This will add a color component-wise with another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Addition.html

fn add_assign(&mut self, rhs: Self)

Performs the += operation.

impl Clone for Color128

fn clone(&self) -> Color128

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for Color128

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

Formats the value using the given formatter.

impl Default for Color128

fn default() -> Color128

Returns the “default value” for a type.

impl Display for Color128

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

Mostly for debug purposes, this is a decent way to log or inspect the color in debug mode. Looks like “Color128 {r: 1.0, g: 1.0, b: 1.0, a: 1.0}” https://stereokit.net/Pages/StereoKit/Color/ToString.html

impl Div<Color128> for f32

This will divide a color linearly, including alpha. Best done on a color in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Division.html

type Output = Color128

The resulting type after applying the / operator.

fn div(self, rhs: Color128) -> Self::Output

Performs the / operation.

impl Div<f32> for Color128

This will divide a color linearly, including alpha. Best done on a color in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Division.html

type Output = Color128

The resulting type after applying the / operator.

fn div(self, rhs: f32) -> Self::Output

Performs the / operation.

impl Div for Color128

This will divide a color component-wise against another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Division.html

type Output = Color128

The resulting type after applying the / operator.

fn div(self, rhs: Self) -> Self::Output

Performs the / operation.

impl DivAssign<f32> for Color128

This will divide a color linearly, including alpha. Best done on a color in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Division.html

fn div_assign(&mut self, rhs: f32)

Performs the /= operation.

impl DivAssign for Color128

This will divide a color component-wise against another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Division.html

fn div_assign(&mut self, rhs: Self)

Performs the /= operation.

impl From<[f32; 4]> for Color128

fn from(s: [f32; 4]) -> Self

Converts to this type from the input type.

impl From<Color128> for Color32

fn from(a: Color128) -> Self

Converts to this type from the input type.

impl From<Color32> for Color128

fn from(a: Color32) -> Self

Converts to this type from the input type.

impl Mul<Color128> for f32

This will multiply a color linearly, including alpha. Best done on a color in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Multiply.html

type Output = Color128

The resulting type after applying the * operator.

fn mul(self, rhs: Color128) -> Self::Output

Performs the * operation.

impl Mul<f32> for Color128

This will multiply a color linearly, including alpha. Best done on a color in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Multiply.html

type Output = Color128

The resulting type after applying the * operator.

fn mul(self, rhs: f32) -> Self::Output

Performs the * operation.

impl Mul for Color128

This will multiply a color component-wise against another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Multiply.html

type Output = Color128

The resulting type after applying the * operator.

fn mul(self, rhs: Self) -> Self::Output

Performs the * operation.

impl MulAssign<f32> for Color128

This will multiply a color linearly, including alpha. Best done on a color in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Multiply.html

fn mul_assign(&mut self, rhs: f32)

Performs the *= operation.

impl MulAssign for Color128

This will multiply a color component-wise against another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Multiply.html

fn mul_assign(&mut self, rhs: Self)

Performs the *= operation.

impl PartialEq for Color128

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

Tests for self and other values to be equal, and is used by ==.

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 Sub for Color128

This will subtract color b component-wise from color a, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Subtraction.html

type Output = Color128

The resulting type after applying the - operator.

fn sub(self, rhs: Self) -> Self

Performs the - operation.

impl SubAssign for Color128

This will subtract a color component-wise from another color, including alpha. Best done on colors in linear space. No clamping is applied. https://stereokit.net/Pages/StereoKit/Color/op_Subtraction.html

fn sub_assign(&mut self, rhs: Self)

Performs the -= operation.

impl Copy for Color128