Struct SphericalHarmonics

#[repr(C)]
pub struct SphericalHarmonics {
    pub coefficients: [Vec3; 9],
}

Spherical Harmonics are kinda like Fourier, but on a sphere. That doesn’t mean terribly much to me, and could be wrong, but check out here for more details about how Spherical Harmonics work in this context!

However, the more prctical thing is, SH can be a function that describes a value over the surface of a sphere! This is particularly useful for lighting, since you can basically store the lighting information for a space in this value! This is often used for lightmap data, or a light probe grid, but StereoKit just uses a single SH for the entire scene. It’s a gross oversimplification, but looks quite good, and is really fast! That’s extremely great when you’re trying to hit 60fps, or even 144fps. https://stereokit.net/Pages/StereoKit/SphericalHarmonics.html

see also: crate::tex::SHCubemap

Examples

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

let light0 = SHLight::new([1.0, 0.0, 0.0], named_colors::RED);
let light1 = SHLight::new([0.0, 1.0, 0.0], named_colors::GREEN);
let light2 = SHLight::new([0.0, 0.0, 1.0], named_colors::BLUE);

let mut sh = SphericalHarmonics::from_lights(&[light0, light1, light2]);
sh.brightness(1.0)
  .add(Vec3::NEG_Y, named_colors::GREEN)
  .add(Vec3::NEG_Z, named_colors::BLUE)
  .add(Vec3::NEG_X, named_colors::RED);

assert_eq!(sh.get_sample(Vec3::UP), Color128 { r: 0.5813507, g: 0.8046322, b: 0.5813487, a: 1.0 });
assert_eq!(sh.get_dominent_light_direction(), Vec3 { x: 0.27644092, y: 0.2728996, z: 0.9214696 });

Fields

coefficients: [Vec3; 9]

Implementations

impl SphericalHarmonics

pub fn from_lights(lights: &[SHLight]) -> Self

Creates a SphericalHarmonics approximation of the irradiance given from a set of directional lights! https://stereokit.net/Pages/StereoKit/SphericalHarmonics/FromLights.html

• lights - A list of directional lights!

Returns a SphericalHarmonics approximation of the irradiance given from a set of directional lights! see also SHLight

Examples

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

let light0 = SHLight::new([1.0, 1.0, 1.0], named_colors::RED);
let light1 = SHLight::new([0.5, 0.5, 0.5], named_colors::RED);
let light2 = SHLight::new([0.25, 0.25, 0.25], named_colors::RED);

let sh = SphericalHarmonics::from_lights(&[light0, light1, light2]);

assert_eq!(sh.get_sample(Vec3::UP), Color128 { r: 2.2098913, g: 0.0, b: 0.0, a: 1.0 });
assert_eq!(sh.get_dominent_light_direction(), -Vec3::ONE.get_normalized());

pub fn new(coefficients: [Vec3; 9]) -> Self

Creates a SphericalHarmonic from an array of coefficients. Useful for loading stored data! https://stereokit.net/Pages/StereoKit/SphericalHarmonics/SphericalHarmonics.html

• coefficients - Must be an array with a length of 9!

see also sh_create

Examples

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

let mut sh0 = SphericalHarmonics::default();
sh0.add([1.0, 0.0, 1.0], named_colors::RED);
let coefficient = sh0.coefficients;

let sh = SphericalHarmonics::new(coefficient);

assert_eq!(sh.get_sample([1.0, 0.0, 1.0]), Color128 { r: 11.453729, g: 0.0, b: 0.0, a: 1.0 });
assert_eq!(sh.get_dominent_light_direction(), Vec3::new(-1.0, 0.0, -1.0).get_normalized());

pub fn add( &mut self, light_dir: impl Into<Vec3>, light_color: impl Into<Color128>, ) -> &mut Self

Adds a ‘directional light’ to the lighting approximation. This can be used to bake a multiple light setup, or accumulate light from a field of points. https://stereokit.net/Pages/StereoKit/SphericalHarmonics/Add.html

• light_dir - The direction of the light source.
• light_color - Color of the light, in linear color space.

see also sh_add

Examples

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

let mut sh = SphericalHarmonics::default();
sh.add([1.0, 0.0, 1.0], named_colors::RED)
  .add([0.0, 1.0, 0.0], named_colors::GREEN)
  .add([0.0, 0.0, 1.0], named_colors::BLUE);

assert_eq!(sh.get_sample([1.0, 0.0, 1.0]), Color128 { r: 11.453729, g: -0.2956792, b: 4.4505944, a: 1.0 });
assert_eq!(sh.get_dominent_light_direction(), Vec3 { x: -0.21951628, y: -0.21670417, z: -0.95123714 });

pub fn brightness(&mut self, scale: f32) -> &mut Self

Scales all the SphericalHarmonic’s coefficients! This behaves as if you’re modifying the brightness of the lighting this object represents. https://stereokit.net/Pages/StereoKit/SphericalHarmonics/Brightness.html

• scale - A multiplier for the coefficients! A value of 1 will leave everything the same, 0.5 will cut the brightness in half, and a 2 will double the brightness.

see also sh_brightness

Examples

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

let mut sh = SphericalHarmonics::default();
sh.add([1.0, 0.0, 1.0], named_colors::RED)
  .brightness(0.5);

assert_eq!(sh.get_sample([1.0, 0.0, 1.0]), Color128 { r: 5.726864, g: 0.0, b: 0.0, a: 1.0 });
assert_eq!(sh.get_dominent_light_direction(), Vec3::new(-1.0, 0.0, -1.0).get_normalized());

sh.brightness(2.0);
assert_eq!(sh.get_sample([1.0, 0.0, 1.0]), Color128 { r: 11.453729, g: 0.0, b: 0.0, a: 1.0 });
assert_eq!(sh.get_dominent_light_direction(), Vec3::new(-1.0, 0.0, -1.0).get_normalized());


sh.brightness(0.0);
assert_eq!(sh.get_sample([1.0, 0.0, 1.0]), Color128::BLACK);
assert_eq!(sh.get_dominent_light_direction().x.is_nan(), true);

pub fn get_sample(&self, normal: impl Into<Vec3>) -> Color128

Look up the color information in a particular direction! https://stereokit.net/Pages/StereoKit/SphericalHarmonics/Sample.html

• normal - The direction to look in. Should be normalized.

Returns the color represented by the SH in the given direction. see also sh_brightness

pub fn get_dominent_light_direction(&self) -> Vec3

Returns the dominant direction of the light represented by this spherical harmonics data. The direction value is normalized. You can get the color of the light in this direction by using the struct’s Sample method: light.get_sample(-light.get_dominent_light_direction()). https://stereokit.net/Pages/StereoKit/SphericalHarmonics/DominantLightDirection.html

see also sh_brightness

Examples

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

let mut sh = SphericalHarmonics::default();
sh.add([1.0, 0.0, 1.0], named_colors::RED)
  .add([1.0, 1.0, 0.0], named_colors::GREEN)
  .add([0.0, 1.0, 1.0], named_colors::BLUE);

assert_eq!(sh.get_dominent_light_direction(), Vec3 { x: -0.3088678, y: -0.6715365, z: -0.6735276 });

pub fn to_array(&self) -> [Vec3; 9]

Converts the SphericalHarmonic into a vector of coefficients 9 long. Useful for storing calculated data! https://stereokit.net/Pages/StereoKit/SphericalHarmonics/ToArray.html

Returns an array of coefficients 9 long. see also sh_brightness

Trait Implementations

impl Clone for SphericalHarmonics

fn clone(&self) -> SphericalHarmonics

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for SphericalHarmonics

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

Formats the value using the given formatter.

impl Default for SphericalHarmonics

fn default() -> SphericalHarmonics

Returns the “default value” for a type.

impl PartialEq for SphericalHarmonics

fn eq(&self, other: &SphericalHarmonics) -> 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 Copy for SphericalHarmonics

impl StructuralPartialEq for SphericalHarmonics