Sat Nov 30 03:01:27 AM EST 2024

2 files changed, 45 insertions, 7 deletions

diff --git a/assets/shaders/blacklight_material.wgsl b/assets/shaders/blacklight_material.wgsl
index 93e6969..d024755 100644
--- a/assets/shaders/blacklight_material.wgsl
+++ b/assets/shaders/blacklight_material.wgsl
@@ -20,13 +20,16 @@ fn fragment(
 	var final_color = vec4f(0.0, 0.0, 0.0, 0.0);
 	for (var i = u32(0); i < arrayLength(&lights); i = i+1) {
 		let light = lights[i];
-		let light_distance_squared = distance_squared(in.world_position.xyz, light.position);
+
 		let light_to_fragment_direction = normalize(in.world_position.xyz - light.position);
 		let light_to_fragment_angle = acos(dot(light.direction, light_to_fragment_direction));
-		let angle_inner_factor = light.inner_angle/light.outer_angle;
-		let angle_factor = falloff_radius(light_to_fragment_angle / light.outer_angle, angle_inner_factor);
-		let distance_factor = falloff_radius(saturate(light_distance_squared / (light.range * light.range)), 0.5);
-		final_color = saturate(final_color + base_color * (angle_factor * distance_factor));
+		let angle_inner_factor = light.inner_angle / light.outer_angle;
+		let angle_factor = linear_falloff_radius(light_to_fragment_angle / light.outer_angle, angle_inner_factor);
+
+		let light_distance_squared = distance_squared(in.world_position.xyz, light.position);
+		let distance_factor = inverse_falloff_radius(saturate(light_distance_squared / (light.range * light.range)), 0.5);
+
+		final_color = saturate(final_color + base_color * angle_factor * distance_factor);
 	}
 	return final_color;
 }
@@ -36,10 +39,22 @@ fn distance_squared(a: vec3f, b: vec3f) -> f32 {
 	return dot(vec, vec);
 }
 
-fn falloff_radius(factor: f32, radius: f32) -> f32 {
+fn linear_falloff_radius(factor: f32, radius: f32) -> f32 {
 	if factor < radius {
 		return 1.0;
 	} else {
 		return 1.0 - (factor - radius) / (1.0 - radius);
 	}
 }
+
+fn inverse_falloff(factor: f32) -> f32 {
+	return pow(1.0 - factor, 2.0);
+}
+
+fn inverse_falloff_radius(factor: f32, radius: f32) -> f32 {
+	if factor < radius {
+		return 1.0;
+	} else {
+		return inverse_falloff((factor - radius) / (1.0 - radius));
+	}
+}
diff --git a/src/lib.rs b/src/lib.rs
index 282c9b0..2ff9974 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -1,37 +1,60 @@
+#![warn(missing_docs)]
+
+//! A plugin for the bevy engine providing a simple [`BlacklightMaterial`], which reveals a base
+//! color based on light data from spot lights tagged with a [`Blacklight`] component.
+//! 
+//! Possible future features:
+//! - [`StandardMaterial`] extension for a "blacklight mapped" material.
+//! - Point light support.
+
 use bevy::{
     asset::embedded_asset,
     prelude::*,
     render::render_resource::{AsBindGroup, ShaderType},
 };
 
+/// Plugin which enables and updates blacklight shaders.
 pub struct BlacklightPlugin;
 
 impl Plugin for BlacklightPlugin {
     fn build(&self, app: &mut App) {
         embedded_asset!(app, "../assets/shaders/blacklight_material.wgsl");
-        app.add_plugins(MaterialPlugin::<BlacklightMaterial>::default()).add_systems(Update, update_shader_blacklight_data);
+        app.add_plugins(MaterialPlugin::<BlacklightMaterial>::default())
+            .add_systems(Update, update_shader_blacklight_data);
     }
 }
 
+/// Marker component for spot lights to use them as blacklights for [`BlacklightMaterial`].
 #[derive(Component, Debug)]
 pub struct Blacklight;
 
+/// Shader data representing a single blacklight point light.
 #[derive(Clone, Debug, ShaderType)]
 pub struct BlacklightData {
+    /// World-space position of this light.
     pub position: Vec3,
+    /// World-space direction of this light (must be normalized).
     pub direction: Vec3,
+    /// Range of this light (see [`SpotLight`]).
     pub range: f32,
+    /// Inner angle of this light (see [`SpotLight`]).
     pub inner_angle: f32,
+    /// Outer angle of this light (see [`SpotLight`]).
     pub outer_angle: f32,
 }
 
+/// Material which is invisible until exposed to light from a spot light tagged with the
+/// [`Blacklight`] component.
 #[derive(Asset, TypePath, AsBindGroup, Debug, Clone)]
 pub struct BlacklightMaterial {
+    /// List of light data processed by this shader
     #[storage(0, read_only)]
     pub lights: Vec<BlacklightData>,
+    /// Base color texture which is revealed by blacklight exposure.
     #[texture(1)]
     #[sampler(2)]
     pub base_texture: Option<Handle<Image>>,
+    /// Alpha mode for this material.
     pub alpha_mode: AlphaMode,
 }