Add new halo support to !flare filter

Complements the starburst lines with a soft halo.

Author: jonathanhogg

docs/shaders.md

@@ -436,9 +436,9 @@ be controlled with the `downsample` attribute.
 ### `!flare`
 
 A `!flare` filter attempts to emulate the tendency of optical lenses to produce
-artefacts in the image, including "starbursts" and "ghosts". The filter requires
-a high dynamic range input (such as output by `!canvas3d`). The filter accepts
-the following attributes:
+artefacts in the image, including "starbursts", "halos" and "ghosts". The filter
+requires a high dynamic range input (such as output by `!canvas3d`). The filter
+accepts the following attributes:
 
 `threshold=` *L*
 : A luminosity threshold over which a pixel is deemed to be "bright". Default is
@@ -452,12 +452,23 @@ means one-quarter the luminosity. Default is `2`.
 `upright_length=` *LENGTH*
 : The length of the vertical/horizontal starburst lines, expressed as a
 multiple of the shorter of the filter width or height. Larger values are more
-expensive to compute. Default is `0.25`.
+expensive to compute. Default is `0.25`. Setting this to `0` disables the
+horizontal/vertical starburst lines.
 
 `diagonal_length=` *LENGTH*
 : The length of the diagonal starburst lines, expressed as a multiple of the
 shorter of the filter width or height. Larger values are more expensive to
-compute. Default is `0.125`.
+compute. Default is `0.125`. Setting this to `0` disables the diagonal starburst
+lines.
+
+`halo_radius=` *RADIUS*
+: The radius of the halo added on bright spots, expressed as a multiple of the
+shorter of the filter width or height. Larger values are more expensive to
+compute. Default is `0.0625`. Setting this to `0` disables the halo.
+
+`halo_attenuation=` *ATTENUATION*
+: An additional attenuation to apply to the halo, expressed as a power-of-2.
+Default is `3`.
 
 `ghosts=` *N*
 : The number of lens ghosts to add, between `0` and `6`. The size, location and
@@ -478,6 +489,13 @@ be controlled with the `downsample` attribute. As this filter is very expensive
 to compute, setting `downsample=3` or `downsample=4` can make a significant
 difference to GPU load – particularly if the filter `size` is large.
 
+:::{note}
+Generally, you will want to combine this filter with a [`!bloom`](#bloom) as the
+thresholding and attenuation makes flares localised to the brightest spots. The
+order in which these filters are applied will result in subtly different
+outputs.
+:::
+
 ### `!edges`
 
 The `!edges` node applies a simple edge-detection filter by blurring the input

examples/textures.png

@@ -97,3 +97,19 @@ vec3 filter_lens_flare(sampler2D tex, vec2 coord, vec2 size, float upright_lengt
     }
     return max(upright_color, diagonal_color) * pow(0.5, attenuation);
 }
+
+vec3 filter_lens_halo(sampler2D tex, vec2 coord, vec2 size, float radius, float threshold, float attenuation) {
+    const float Tau = 6.283185307179586231995926937088370323181152343750;
+    float l = min(size.x, size.y) * 0.5;
+    vec3 color = vec3(0.0);
+    float r = radius * l;
+    float n = Tau * r;
+    vec2 s = r / size;
+    if (n > 0.0) {
+        for (float i = 0.0; i < n; i += 1.0) {
+            vec3 col = texture(tex, coord + s * vec2(cos(i / n * Tau), sin(i / n * Tau))).rgb;
+            color = max(color, col * smoothstep(0.0, 1.0, srgb_luminance(col) - threshold));
+        }
+    }
+    return color * pow(0.5, attenuation);
+}

src/flitter/render/window/glsl/filter_functions.glsl

@@ -8,6 +8,8 @@ uniform int pass;
 uniform int ghosts;
 uniform float upright_length;
 uniform float diagonal_length;
+uniform float halo_radius;
+uniform float halo_attenuation;
 uniform float threshold;
 uniform float attenuation;
 uniform float aberration;
@@ -60,6 +62,7 @@ void main() {
 % if ghosts > 5:
             col += filter_lens_ghost(${'last' if passes == 5 else 'texture0'}, coord, size, 1.0, -0.75, threshold, attenuation + 1.0, aberration);
 % endif
+            col += filter_lens_halo(${'last' if passes == 5 else 'texture0'}, coord, size, halo_radius, threshold, attenuation + halo_attenuation);
             color = vec4(col, 1.0);
             break;
         }

src/flitter/render/window/glsl/flare.frag

@@ -129,7 +129,8 @@ def render(self, node, references, **kwargs):
             passes = 1
             downsample_passes = ()
         super().render(node, references, passes=passes, downsample_passes=downsample_passes,
-                       upright_length=0.25, diagonal_length=0.125, ghosts=6, threshold=1, attenuation=2, aberration=1, **kwargs)
+                       upright_length=1/4, diagonal_length=1/8, ghosts=6, threshold=1, attenuation=2, aberration=1,
+                       halo_radius=1/16, halo_attenuation=3, **kwargs)
 
 
 class Noise(Shader):