Struct Gradient

pub struct Gradient(pub NonNull<_GradientT>);

A Gradient is a sparse collection of color keys that are used to represent a ramp of colors! This class is largely just storing colors and allowing you to sample between them.

Since the Gradient is just interpolating values, you can use whatever color space you want here, as long as it’s linear and not gamma! Gamma space RGB can’t math properly at all. It can be RGB(linear), HSV, LAB, just remember which one you have, and be sure to convert it appropriately later. Data is stored as float colors, so this’ll be a high accuracy blend! https://stereokit.net/Pages/StereoKit/Gradient.html

see also GradientKey crate::tex::Tex::gen_particle crate::tex::SHCubemap::gen_cubemap_gradient

Examples

use stereokit_rust::{maths::Vec3, system::AssetState, tex::{Tex, SHCubemap},
                     util::{named_colors, Gradient, GradientKey, Color128}};

let keys = [
    GradientKey::new(Color128::BLACK_TRANSPARENT, 0.0),
    GradientKey::new(named_colors::RED, 0.1),
    GradientKey::new(named_colors::CYAN, 0.4),
    GradientKey::new(named_colors::BLUE, 0.5),
    GradientKey::new(Color128::BLACK, 0.7)];

let sh_cubemap = SHCubemap::gen_cubemap_gradient(Gradient::new(Some(&keys)),
                                                 Vec3::UP, 128);
sh_cubemap.render_as_sky();

let mut gradient = Gradient::new(None);
gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(named_colors::LIGHT_BLUE, 0.4)
    .add(named_colors::BLUE, 0.5)
    .add(Color128::BLACK, 0.7);
let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

Tuple Fields

0: NonNull<_GradientT>

Implementations

impl Gradient

pub fn new(keys: Option<&[GradientKey]>) -> Self

Creates a new, completely empty gradient. https://stereokit.net/Pages/StereoKit/Gradient/Gradient.html

• keys - These can be in any order that you like, they’ll be sorted by their GradientKey.position value regardless!

see also gradient_create gradient_create_keys

Examples

use stereokit_rust::{maths::Vec3, tex::{Tex, SHCubemap},
                     util::{named_colors, Gradient, GradientKey, Color128}};

let keys = [
    GradientKey::new(Color128::BLACK_TRANSPARENT, 0.0),
    GradientKey::new(named_colors::RED, 0.5),
    GradientKey::new(Color128::BLACK, 0.7)];

let gradient1 = Gradient::new(Some(&keys));
assert_eq!(gradient1.get_count(), 3);
let sh_cubemap = SHCubemap::gen_cubemap_gradient(gradient1, Vec3::UP, 16);
sh_cubemap.render_as_sky();

let mut gradient2 = Gradient::new(Some(&keys));
gradient2.add(named_colors::CYAN, 0.4);
assert_eq!(gradient2.get_count(), 4);
let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient2));

pub fn add( &mut self, color_linear: impl Into<Color128>, position: f32, ) -> &mut Self

This adds a color key into the list. It’ll get inserted to the right slot based on its position. https://stereokit.net/Pages/StereoKit/Gradient/Add.html

• color_linear - Any linear space color you like!
• position - Typically a value between 0-1! This is the position of the color along the ‘x-axis’ of the gradient.

see also gradient_add

Examples

use stereokit_rust::{tex::Tex, util::{named_colors, Gradient, Color128}};

let mut gradient = Gradient::new(None);
gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(named_colors::LIGHT_BLUE, 0.4)
    .add(named_colors::BLUE, 0.5)
    .add(Color128::BLACK, 0.7);
assert_eq!(gradient.get_count(), 5);
let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

pub fn set( &mut self, index: i32, color_linear: impl Into<Color128>, position: f32, ) -> &mut Self

Updates the color key at the given index! This will NOT re-order color keys if they are moved past another key’s position, which could lead to strange behavior. https://stereokit.net/Pages/StereoKit/Gradient/Set.html

• index - Index of the color key to change.
• color_linear - Any linear space color you like!
• position - Typically a value between 0-1! This is the position of the color along the ‘x-axis’ of the gradient.

see also gradient_set

Examples

use stereokit_rust::{tex::Tex, util::{named_colors, Gradient,  Color128}};

let mut gradient = Gradient::new(None);
gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(named_colors::LIGHT_BLUE, 0.4)
    .add(named_colors::BLUE, 0.5)
    .add(Color128::BLACK, 0.7);
assert_eq!(gradient.get_count(), 5);
assert_eq!(gradient.get(0.3), Color128 { r: 0.7856209, g: 0.8980392, b: 0.6013072, a: 1.0 });

gradient.set(2, named_colors::RED, 0.3);
gradient.set(-20, named_colors::RED, -10.3); // out of bounds, should do nothing
assert_eq!(gradient.get_count(), 5);
assert_eq!(gradient.get(0.3), named_colors::RED.into());

let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

pub fn remove(&mut self, index: i32) -> &mut Self

Removes the color key at the given index! This won’t reindex the gradient so get_count will still return the same value. https://stereokit.net/Pages/StereoKit/Gradient/Remove.html

• index - The index of the color key to remove.

see also gradient_remove

Examples

use stereokit_rust::{tex::Tex, util::{named_colors, Gradient, Color128}};

let mut gradient = Gradient::new(None);
gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(named_colors::LIGHT_BLUE, 0.4)
    .add(named_colors::BLUE, 0.5)
    .add(Color128::BLACK, 0.7);
assert_eq!(gradient.get_count(), 5);
assert_eq!(gradient.get(0.4), named_colors::LIGHT_BLUE.into());

gradient.remove(2);
gradient.remove(19).remove(-189);
assert_eq!(gradient.get_count(), 5);
assert_eq!(gradient.get(0.4), Color128 { r: 0.25, g: 0.25, b: 0.75, a: 1.0 });

let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

pub fn get_count(&self) -> i32

The number of color keys present in this gradient. https://stereokit.net/Pages/StereoKit/Gradient/Count.html

see also gradient_count

Examples

use stereokit_rust::{tex::Tex, util::{named_colors, Gradient, Color128}};

let mut gradient = Gradient::new(None);
assert_eq!(gradient.get_count(), 0);

gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(Color128::BLACK, 0.7);
assert_eq!(gradient.get_count(), 3);

gradient.remove(1);
assert_eq!(gradient.get_count(), 3);

let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

pub fn get(&self, at: f32) -> Color128

Samples the gradient’s color at the given position! https://stereokit.net/Pages/StereoKit/Gradient/Get.html

• at - Typically a value between 0-1, but if you used larger or smaller values for your color key’s positions, it’ll be in that range!

Returns the interpolated color at the given position. If ‘at’ is smaller or larger than the gradient’s position range, then the color will be clamped to the color at the beginning or end of the gradient! see also gradient_get

Examples

use stereokit_rust::{tex::Tex, util::{named_colors, Gradient, Color128}};

let mut gradient = Gradient::new(None);
gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(named_colors::LIGHT_BLUE, 0.4)
    .add(named_colors::BLUE, 0.5)
    .add(Color128::BLACK, 0.7);

assert_eq!(gradient.get(0.3), Color128 { r: 0.7856209, g: 0.8980392, b: 0.6013072, a: 1.0 });
assert_eq!(gradient.get(0.4), named_colors::LIGHT_BLUE.into());
assert_eq!(gradient.get(0.5), named_colors::BLUE.into());

let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

pub fn get32(&self, at: f32) -> Color32

Samples the gradient’s color at the given position, and converts it to a 32 bit color. If your RGBA color values are outside of the 0-1 range, then you’ll get some issues as they’re converted to 0-255 range bytes! https://stereokit.net/Pages/StereoKit/Gradient/Remove.html

• at - Typically a value between 0-1, but if you used larger or smaller values for your color key’s positions, it’ll be in that range!

Returns the interpolated 32 bit color at the given position. If ‘at’ is smaller or larger than the gradient’s position range, then the color will be clamped to the color at the beginning or end of the gradient! see also gradient_get32

Examples

use stereokit_rust::{tex::Tex, util::{named_colors, Gradient, Color128, Color32}};

let mut gradient = Gradient::new(None);
gradient
    .add(Color128::BLACK_TRANSPARENT, 0.0)
    .add(named_colors::YELLOW, 0.1)
    .add(named_colors::LIGHT_BLUE, 0.4)
    .add(named_colors::BLUE, 0.5)
    .add(Color128::BLACK, 0.7);

assert_eq!(gradient.get32(0.3), Color32 { r: 200, g: 229, b: 153, a: 255 });
assert_eq!(gradient.get32(0.4), named_colors::LIGHT_BLUE);
assert_eq!(gradient.get32(0.5), named_colors::BLUE);

let tex_particule1 = Tex::gen_particle(128, 128, 0.2, Some(gradient));

Trait Implementations

impl AsRef<Gradient> for Gradient

fn as_ref(&self) -> &Gradient

Converts this type into a shared reference of the (usually inferred) input type.

impl Drop for Gradient

fn drop(&mut self)

Executes the destructor for this type.