gaussian_blur_generator 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 4c08daccf74b7ab85e80ee4ade6521684f0ffbe2276b7a8b465578be3aad3703
+  data.tar.gz: 783e49eb582aa2bdffc954bda03ffcc4a888e290b14f89614dfdc0b216518d96
+SHA512:
+  metadata.gz: a84070cf8fcc524d4da0be924258e278e444280edfb63bf45c9efcfae1efea02d12a5e7302042305ba9368ac95b80b60ab9f0a28f00c8d9592b87a9bd245ad32
+  data.tar.gz: ded31a9a5b06cb81647411e31cdbf1a393abddd0b6892466e87c6b982891950595a51c9a095cb94524d46f30f26d78e4c848786fde21120677a96fe8e5a9884a

data/README.md

@@ -0,0 +1,72 @@
+## Gaussian Blur Generator
+
+Generates fragment shaders that apply a Gaussian blur in an efficient manner
+based on
+[this article](http://rastergrid.com/blog/2010/09/efficient-gaussian-blur-with-linear-sampling/).
+
+### Overview
+
+Normally, a blur shader would require N^2 texture reads for a kernel of size N.
+By splitting the shader in two (horizontal, then vertical) and applying a linear
+sampling technique, we can reduce the number of texture reads to approximately
+N, vastly improving the performance of a Gaussian blur. This can be reduced even
+further by ignoring values at the edges of kernels that virtually no difference
+to the output image.
+
+### What is this gem?
+
+This gem applies the technique from the article but generates many different
+shaders with different kernel sizes. It writes these shaders to files in the
+output directory, for example:
+
+- [output/blur/x/17.frag](output/blur/x/17.frag)
+- [output/blue/y/17.frag](output/blue/y/17.frag)
+
+You can run `./bin/generate` yourself by cloning the repository or use one of
+the pre-generated shaders in the [`output/blur`](output/blur) directory. These
+have generated with an epsilon value of 0.05 which roughly corresponds to the
+article, but you can set this yourself if you'd like:
+
+```sh
+$ ./bin/generate 0.07
+```
+
+This would set the threshold a little higher than the default 0.05.
+
+### How do I use it?
+
+1. Copy the x and y fragment shaders into your project for the kernel size you want.
+2. Compile a shader program for each of the fragment shaders
+3. Set `u_texture` to the input texture you want to blur
+4. Set `u_dimensions` to the pixel size of the output: `[width, height, 1/width, 1/height]`
+5. Draw your scene to a framebuffer/texture instead of directly to the screen
+6. Apply the first shader program, then draw to the screen with the second
+
+You can apply the shader to regions of the texture if you'd wish, but the
+simplest approach is to apply it to a full-screen quad. In which case, a simple
+vertex shader like this one will suffice:
+
+```glsl
+attribute vec4 a_position;
+
+void main() {
+  gl_Position = a_position;
+}
+```
+
+You may need to edit the [`glsl.rb` file](lib/gaussian_blur_generator/glsl.rb)
+to produce shader code that's more appropriate for your project.
+
+### Multiple passes?
+
+You may find it's more efficient to apply multiple passes of a smaller blur
+shader than a single pass of a larger one. This depends on a number of factors
+including GPU memory, fill rate, etc. In general, two blurs of size N is
+equivalent to a single blur of size `sqrt(2) * N`.
+
+Also, since Gaussian blur is a low-pass filter, it works very well with
+downsampling. See the article above for more information.
+
+### License
+
+MIT

data/bin/generate

@@ -0,0 +1,28 @@
+#!/usr/bin/env ruby
+
+LIB = File.expand_path(File.join(__dir__, "..", "lib"))
+$LOAD_PATH.unshift(LIB)
+
+EPSILON = Float(ARGV[0] || 0.05)
+
+require "gaussian_blur_generator"
+require "fileutils"
+
+FileUtils.mkdir_p("output/blur/x")
+FileUtils.mkdir_p("output/blur/y")
+
+GaussianBlurGenerator.generate(EPSILON) do |values|
+  ["x", "y"].each do |axis|
+    glsl = GaussianBlurGenerator.glsl(values, axis)
+    path = "output/blur/#{axis}/#{values.texture_reads}.frag"
+
+    File.write(path, glsl)
+  end
+
+  puts "Written output/blur/{x,y}/#{values.texture_reads}.frag"
+  puts "  discarded values < #{EPSILON} of peak"
+  puts "  number of texture reads = #{values.texture_reads}"
+  puts "  effective kernel size = #{values.effective_size}"
+  puts "  pascal's triangle row = #{values.row_number}"
+  puts
+end

data/lib/gaussian_blur_generator.rb

@@ -0,0 +1,4 @@
+require "bigdecimal/util"
+
+require "gaussian_blur_generator/base"
+require "gaussian_blur_generator/glsl"

data/lib/gaussian_blur_generator/base.rb

@@ -0,0 +1,51 @@
+class GaussianBlurGenerator
+  Values = Struct.new(:offsets_d, :weights_d, :offsets_l, :weights_l, :texture_reads, :effective_size, :row_number)
+
+  def self.generate(epsilon)
+    row_number = 0
+    last_size = 0
+
+    loop do
+      row_number += 2
+
+      row = pascal(row_number)
+      sum = row.sum
+      peak = row[row.size / 2].to_d / sum
+
+      # Remove weights that make negligible difference to the output image.
+      row = row.reject { |n| n.to_d / sum < peak * epsilon }
+      sum = row.sum
+
+      # If we've already seen a row of this size, skip those that are more truncated.
+      next if row.size == last_size
+      last_size = row.size
+
+      midpoint = row.size / 2
+      next if midpoint.odd?
+
+      weights_d = row.map { |n| n.to_d / sum }[midpoint..]
+      offsets_d = (0..midpoint).map(&:to_d)
+
+      break if weights_d[0] == 0 # Precision limit reached
+
+      weights_l = weights_d[1..].each_slice(2).map(&:sum)
+      offsets_l = offsets_d[1..].each_slice(2).map do |t1, t2|
+        numerator = offsets_d[t1] * weights_d[t1] + offsets_d[t2] * weights_d[t2]
+        denominator = weights_d[t1] + weights_d[t2]
+
+        numerator / denominator
+      end
+
+      weights_l.unshift(weights_d.first)
+      offsets_l.unshift(0.0)
+      texture_reads = offsets_l.size * 2 - 1
+
+      yield Values.new(offsets_d, weights_d, offsets_l, weights_l, texture_reads, row.size, row_number)
+    end
+  end
+
+  def self.pascal(n)
+    @cache ||= {}
+    @cache[n] ||= (n == 0 ? [1] : [1, *pascal(n - 1).each_cons(2).map(&:sum), 1])
+  end
+end

data/lib/gaussian_blur_generator/glsl.rb

@@ -0,0 +1,47 @@
+class GaussianBlurGenerator
+  def self.glsl(values, axis)
+    offsets = values.offsets_l[1..].map.with_index do |offset, index|
+      "float offset#{index + 1} = one_pixel * #{offset.to_f};"
+    end
+
+    if axis == "x"
+      template = "coords.x + offset@, coords.y"
+    else
+      template = "coords.x, coords.y + offset@"
+    end
+
+    positives = values.weights_l[1..].map.with_index do |weight, index|
+      "#{weight.to_f} * texture2D(u_texture, vec2(#{template.sub("@", (index + 1).to_s)}))"
+    end
+
+    negatives = positives.map { |s| s.sub("+", "-") }
+
+    summation = negatives.reverse + [
+      "#{values.weights_l[0].to_f} * texture2D(u_texture, coords)"
+    ] + positives
+
+    <<~GLSL
+      #ifdef GL_FRAGMENT_PRECISION_HIGH
+        precision highp float;
+      #else
+        precision mediump float;
+      #endif
+
+      uniform sampler2D u_texture;
+      uniform vec4 u_dimensions;
+
+      // Generated by https://github.com/tuzz/gaussian_blur_generator
+
+      void main() {
+        vec2 coords = gl_FragCoord.xy / u_dimensions.xy;
+
+        float one_pixel = u_dimensions.#{axis == "x" ? "z" : "w"};
+        #{offsets.join("\n  ")}
+
+        gl_FragColor = (
+          #{summation.join(" +\n    ")}
+        );
+      }
+    GLSL
+  end
+end

metadata

@@ -0,0 +1,48 @@
+--- !ruby/object:Gem::Specification
+name: gaussian_blur_generator
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Chris Patuzzo
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-05-03 00:00:00.000000000 Z
+dependencies: []
+description: Generates fragment shaders that apply a Gaussian blur in an efficient
+  manner.
+email: chris@patuzzo.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- bin/generate
+- lib/gaussian_blur_generator.rb
+- lib/gaussian_blur_generator/base.rb
+- lib/gaussian_blur_generator/glsl.rb
+homepage: https://github.com/tuzz/gaussian_blur_generator
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.2
+signing_key: 
+specification_version: 4
+summary: Gaussian Blur Generator
+test_files: []