Sat Nov 30 01:13:49 AM UTC 2024

config.toml

@@ -22,6 +22,8 @@ taxonomies = [
 # Whether to do syntax highlighting
 # Theme can be customised by setting the `highlight_theme` variable to a theme supported by Zola
 highlight_code = true
+highlight_theme = "Everforest Dark"
+extra_syntaxes_and_themes = ["highlight_themes", "syntaxes"]
 
 # Whether external links are to be opened in a new tab
 # If this is true, a `rel="noopener"` will always automatically be added for security reasons

content/blog/blacklight-shader.md

@@ -0,0 +1,107 @@
++++
+title = "creating a blacklight shader"
+date = 2024-11-29
+draft = true
++++
+
+today i wanted to take a bit of time to write about a shader i implemented for my in-progress game project (more on that soon™)
+
+i wanted to create a "blacklight" effect, where specific lights could reveal part of the base texture. this shader works with **spot lights** only, but could be extended to work with point lights
+
+// TODO: image of finished shader
+
+i wrote this shader in wgsl for a [bevy engine](https://bevyengine.org) project, but it should translate easily to other shading languages
+
+the finished shader can be found as part of [this repo](https://github.com/exvacuum/bevy_blacklight_material)
+## shader inputs
+
+for this shader, i wanted the following features:
+- the number of lights should be dynamic
+- the revealed portion of the object should match the area illuminated by each light
+    - the falloff of the light over distance should match the fading of the object
+
+for this to work i need the following information about each light:
+- position (world space)
+- direction (world space)
+- range
+- inner and outer angle
+    - these will control the falloff of the light at its edges
+    - outer angle should be less than pi/2 radians 
+    - inner angle should be less than the outer angle
+
+i also need some info from the vertex shader:
+- position (**world space!**)
+- uv
+
+bevy's default pbr vertex shader provides this information, but as long as you can get this info into your fragment shader you should be good to go
+
+lastly i'll take a base color texture and a sampler
+
+with all of that, i can start off the shader by setting up the inputs and fragment entry point:
+
+```wgsl
+#import bevy_pbr::forward_io::VertexOutput;
+
+struct BlackLight {
+	position: vec3<f32>,
+	direction: vec3<f32>,
+	range: f32,
+	inner_angle: f32,
+	outer_angle: f32,
+}
+
+@group(2) @binding(0) var<storage> lights: array<BlackLight>;
+@group(2) @binding(1) var base_texture: texture_2d<f32>;
+@group(2) @binding(2) var base_sampler: sampler;
+
+@fragment
+fn fragment(
+	in: VertexOutput,
+) -> @location(0) vec4<f32> {
+}
+```
+(bevy uses group 2 for custom shader bindings)
+
+since the number of lights is dynamic, i use a [storage buffer](https://google.github.io/tour-of-wgsl/types/arrays/runtime-sized-arrays/) to store that information
+
+## shader calculations
+
+the first thing we'll need to know is how close to looking at the fragment the light source is
+
+we can get this information using some interesting math:
+
+```wgsl
+let light = lights[0];
+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));
+```
+
+the first step of this is taking the dot product of light direction and the direction from the light to the fragment
+
+since both direction vectors are normalized, the dot product will be between -1.0 and 1.0
+
+the dot product of two unit vectors is the cosine of the angle between them ([proof here](https://math.libretexts.org/Bookshelves/Calculus/Calculus_(OpenStax)/12%3A_Vectors_in_Space/12.03%3A_The_Dot_Product#Evaluating_a_Dot_Product))
+
+therefore, we take the arccosine of that dot product to get the angle between the light and the fragment
+
+once we have this angle we can plug it in to an inverse square falloff based on the angle properties of the light:
+
+```wgsl
+let angle_inner_factor = light.inner_angle/light.outer_angle;
+let angle_factor = inverse_falloff_radius(light_to_fragment_angle / light.outer_angle, angle_inner_factor)));
+```
+```wgsl
+fn inverse_falloff(factor: f32) -> f32 {
+	let squared = factor * factor;
+	return 1.0/squared;
+}
+
+fn inverse_falloff_radius(factor: f32, radius: f32) -> f32 {
+	if factor < radius {
+		return 1.0;
+	} else {
+		return inverse_falloff((factor - radius) / (1.0 - radius));
+	}
+}
+```
+

sass/style.scss

@@ -25,7 +25,7 @@
 
 body {
   color: everforest.$fg;
-  background-color: everforest.$bg0;
+  background-color: everforest.$bg1;
 }
 
 a {
@@ -37,6 +37,10 @@ img {
   max-height: 720px;
 }
 
+pre {
+  padding: 5px;
+}
+
 .wip-indicator {
   color: everforest.$yellow;
 }

syntaxes/wgsl.sublime-syntax

@@ -0,0 +1,215 @@
+%YAML 1.2
+---
+# http://www.sublimetext.com/docs/syntax.html
+name: WGSL
+file_extensions: [wgsl]
+scope: source.wgsl
+contexts:
+  main:
+    - include: line_comments
+    - include: block_comments
+    - include: constants
+    - include: keywords
+    - include: attributes
+    - include: functions
+    - include: function_calls
+    - include: types
+    - include: variables
+    - include: punctuation
+  attributes:
+    # attribute declaration
+    - match: '(@)([A-Za-z_]+)'
+      scope: meta.attribute.wgsl
+      captures:
+        1: keyword.operator.attribute.at
+        2: entity.name.attribute.wgsl
+  block_comments:
+    # empty block comments
+    - match: /\*\*/
+      scope: comment.block.wgsl
+    # block documentation comments
+    - match: /\*\*
+      push:
+        - meta_scope: comment.block.documentation.wgsl
+        - match: \*/
+          pop: true
+        - include: block_comments
+    # block comments
+    - match: /\*(?!\*)
+      push:
+        - meta_scope: comment.block.wgsl
+        - match: \*/
+          pop: true
+        - include: block_comments
+  constants:
+    # boolean constant
+    - match: \b(true|false)\b
+      scope: constant.language.boolean.wgsl
+    # decimal float literal
+    - match: '(\b(0|[1-9][0-9]*)[fh]\b|([0-9]*\.[0-9]+|[0-9]+\.[0-9]*)([eE][+-]?[0-9]+)?[fh]?|[0-9]+[eE][+-]?[0-9]+[fh]?)'
+      scope: constant.numeric.float.wgsl
+    # decimal int literal
+    - match: '\b(0|[1-9][0-9]*)[iu]?\b'
+      scope: constant.numeric.decimal.wgsl
+    # hexadecimal int literal
+    - match: '\b0[xX][0-9a-fA-F]+[iu]?\b'
+      scope: constant.numeric.decimal.wgsl
+  function_calls:
+    # function/method calls
+    - match: '([A-Za-z0-9_]+)(\()'
+      captures:
+        1: entity.name.function.wgsl
+        2: punctuation.brackets.round.wgsl
+      push:
+        - meta_scope: meta.function.call.wgsl
+        - match: \)
+          captures:
+            0: punctuation.brackets.round.wgsl
+          pop: true
+        - include: line_comments
+        - include: block_comments
+        - include: constants
+        - include: keywords
+        - include: attributes
+        - include: function_calls
+        - include: types
+        - include: variables
+        - include: punctuation
+  functions:
+    # function definition
+    - match: '\b(fn)\s+([A-Za-z0-9_]+)((\()|(<))'
+      captures:
+        1: keyword.other.fn.wgsl
+        2: entity.name.function.wgsl
+        4: punctuation.brackets.round.wgsl
+      push:
+        - meta_scope: meta.function.definition.wgsl
+        - match: '\{'
+          captures:
+            0: punctuation.brackets.curly.wgsl
+          pop: true
+        - include: line_comments
+        - include: block_comments
+        - include: constants
+        - include: keywords
+        - include: attributes
+        - include: function_calls
+        - include: types
+        - include: variables
+        - include: punctuation
+  keywords:
+    # other keywords
+    - match: \b(bitcast|block|break|case|continue|continuing|default|discard|else|elseif|enable|fallthrough|for|function|if|loop|override|private|read|read_write|return|storage|switch|uniform|while|workgroup|write)\b
+      scope: keyword.control.wgsl
+    # reserved keywords
+    - match: \b(asm|const|do|enum|handle|mat|premerge|regardless|typedef|unless|using|vec|void)\b
+      scope: keyword.control.wgsl
+    # storage keywords
+    - match: \b(let|var)\b
+      scope: keyword.other.wgsl storage.type.wgsl
+    # type keyword
+    - match: \b(type)\b
+      scope: keyword.declaration.type.wgsl storage.type.wgsl
+    # enum keyword
+    - match: \b(enum)\b
+      scope: keyword.declaration.enum.wgsl storage.type.wgsl
+    # struct keyword
+    - match: \b(struct)\b
+      scope: keyword.declaration.struct.wgsl storage.type.wgsl
+    # fn
+    - match: \bfn\b
+      scope: keyword.other.fn.wgsl
+    # logical operators
+    - match: (\^|\||\|\||&&|<<|>>|!)(?!=)
+      scope: keyword.operator.logical.wgsl
+    # logical AND, borrow references
+    - match: '&(?![&=])'
+      scope: keyword.operator.borrow.and.wgsl
+    # assignment operators
+    - match: (\+=|-=|\*=|/=|%=|\^=|&=|\|=|<<=|>>=)
+      scope: keyword.operator.assignment.wgsl
+    # single equal
+    - match: '(?<![<>])=(?!=|>)'
+      scope: keyword.operator.assignment.equal.wgsl
+    # comparison operators
+    - match: (=(=)?(?!>)|!=|<=|(?<!=)>=)
+      scope: keyword.operator.comparison.wgsl
+    # math operators
+    - match: '(([+%]|(\*(?!\w)))(?!=))|(-(?!>))|(/(?!/))'
+      scope: keyword.operator.math.wgsl
+    # dot access
+    - match: \.(?!\.)
+      scope: keyword.operator.access.dot.wgsl
+    # dashrocket, skinny arrow
+    - match: '->'
+      scope: keyword.operator.arrow.skinny.wgsl
+  line_comments:
+    # single line comment
+    - match: \s*//.*
+      scope: comment.line.double-slash.wgsl
+  punctuation:
+    # comma
+    - match: ','
+      scope: punctuation.comma.wgsl
+    # curly braces
+    - match: '[{}]'
+      scope: punctuation.brackets.curly.wgsl
+    # parentheses, round brackets
+    - match: '[()]'
+      scope: punctuation.brackets.round.wgsl
+    # semicolon
+    - match: ;
+      scope: punctuation.semi.wgsl
+    # square brackets
+    - match: '[\[\]]'
+      scope: punctuation.brackets.square.wgsl
+    # angle brackets
+    - match: '(?<![=-])[<>]'
+      scope: punctuation.brackets.angle.wgsl
+  types:
+    # scalar types
+    - match: \b(bool|i32|u32|f16|f32)\b
+      scope: storage.type.wgsl
+    # reserved scalar types
+    - match: \b(i64|u64|f64)\b
+      scope: storage.type.wgsl
+    # vector type aliasses
+    - match: \b(vec2i|vec3i|vec4i|vec2u|vec3u|vec4u|vec2f|vec3f|vec4f|vec2h|vec3h|vec4h)\b
+      scope: storage.type.wgsl
+    # matrix type aliasses
+    - match: \b(mat2x2f|mat2x3f|mat2x4f|mat3x2f|mat3x3f|mat3x4f|mat4x2f|mat4x3f|mat4x4f|mat2x2h|mat2x3h|mat2x4h|mat3x2h|mat3x3h|mat3x4h|mat4x2h|mat4x3h|mat4x4h)\b
+      scope: storage.type.wgsl
+    # vector/matrix types
+    - match: '\b(vec[2-4]|mat[2-4]x[2-4])\b'
+      scope: storage.type.wgsl
+    # atomic types
+    - match: \b(atomic)\b
+      scope: storage.type.wgsl
+    # array types
+    - match: \b(array)\b
+      scope: storage.type.wgsl
+    # sampled texture types
+    - match: \b(texture_1d|texture_2d|texture_2d_array|texture_3d|texture_cube|texture_cube_array)\b
+      scope: storage.type.wgsl
+    # multisampled texture types
+    - match: \b(texture_multisampled_2d|texture_depth_multisampled_2d)\b
+      scope: storage.type.wgsl
+    # external sampled texture types
+    - match: \b(texture_external)\b
+      scope: storage.type.wgsl
+    # storage texture types
+    - match: \b(texture_storage_1d|texture_storage_2d|texture_storage_2d_array|texture_storage_3d)\b
+      scope: storage.type.wgsl
+    # depth texture types
+    - match: \b(texture_depth_2d|texture_depth_2d_array|texture_depth_cube|texture_depth_cube_array)\b
+      scope: storage.type.wgsl
+    # sampler type
+    - match: \b(sampler|sampler_comparison)\b
+      scope: storage.type.wgsl
+    # custom type
+    - match: '\b([A-Z][A-Za-z0-9]*)\b'
+      scope: entity.name.type.wgsl
+  variables:
+    # variables
+    - match: '\b(?<!(?<!\.)\.)(?:r#(?!(crate|[Ss]elf|super)))?[a-z0-9_]+\b'
+      scope: variable.other.wgsl