Updating API and documentation.

main.lua

@@ -1,26 +1,21 @@
-lg = love.graphics
+local Histogram = require 'histogram'
-W,H = lg.getDimensions()
-Histogram = require 'histogram'
 local Noise = require "noise"
 local DRAW_RES = love.window.toPixels(4)
 local SCALE = 100
-local font = lg.newFont(love.window.toPixels(24))
 
 local decay = function(x) return .15^x end
-local function rng()
+local n1,g1 = Noise.make1d{resolution=5, distribution=decay, seed=1}
-    local r = love.math.newRandomGenerator(1)
+local n2,g2 = Noise.make2d{resolution=7, distribution=decay, seed=1}
-    return function() return r:random() end
+local n3,g3 = Noise.make3d{resolution=9, distribution=decay, seed=1}
-end
+local s1,s1g = Noise.make1dShader{resolution=10, distribution=decay, seed=1}
-local makeAmps = Noise.makeAmplitudes
+local s2,s2g = Noise.make2dShader{resolution=15, distribution=decay, seed=1}
-local n1,g1 = Noise.make1d(makeAmps(8, decay), rng())
+local s3,s3g = Noise.make3dShader{resolution=20, distribution=decay, seed=1}
-local n2,g2 = Noise.make2d(makeAmps(9, decay), rng())
-local n3,g3 = Noise.make3d(makeAmps(11, decay), rng())
-local s1,s1g = Noise.make1dShader(makeAmps(9, decay), rng())
-local s2,s2g = Noise.make2dShader(makeAmps(15, decay), rng())
-local s3,s3g = Noise.make3dShader(makeAmps(19, decay), rng())
 
+lg = love.graphics
+W,H = lg.getDimensions()
 local cw,ch = W/2,H/3
 local canv = lg.newCanvas(cw,ch)
+local font = lg.newFont(love.window.toPixels(24))
 
 function love.load()
     xOffset = 0

noise.lua

@@ -1,3 +1,64 @@
+-- Hill Noise library
+-- Copyright 2017 Bruce Hill
+--
+-- This library provides functions for continuous pseudorandom 1D, 2D, and 3D noise functions
+-- with approximately uniform distribution on the interval (0,1) and customizable resolution,
+-- levels of detail, and shape characteristics.
+--
+-- Usage:
+--     local Noise = require 'hill_noise'
+--     local noise,noise_gradient = Noise.make3d{resolution=9}
+--     local x,y,z = 1,2,3
+--     local n = noise(x,y,z)
+--     local dndx,dndy,dndz = noise_gradient(x,y,z)
+--
+-- The noise construction functions all take the following options:
+--     * random: a random number function (default: math.random)
+--     * seed: if "random" is not provided, and the love.math module is loaded, a new
+--       pseudorandom number generator will be used with the specified seed
+--     * amplitudes: a list of sine wave amplitudes to use
+--     * resolution: if "amplitudes" is not provided, the number of sine waves to use
+--       (default: 5,7,9 for 1d,2d,3d functions, and 10,15,20 for 1d,2d,3d shaders)
+--     * distribution: if "amplitudes" is not provided, a function to evenly sample
+--       amplitudes from on the interval (0,1) (default: 0.1^x)
+--
+-- The noise and noise gradient functions all run in O(resolution), and more resolution
+-- may be needed for higher dimensional noise and additional detail.
+--
+-- For the LOVE game engine, there are versions that produce 1D, 2D, and 3D noise shaders
+-- as well, which are much faster and run on the GPU.
+--     local noise_shader, noise_gradient_shader = Noise.make3dShader{resolution=11}
+--     local canvas = love.graphics.newCanvas()
+--     -- At each location on the texture, the noise function is sampled at a linear
+--     --   interpolation between range_min and range_max, using the texture coordinates.
+--     --   For 3D noise, the "z" value is passed as a parameter.
+--     noise_shader:send("range_min", {0,20})
+--     noise_shader:send("range_max", {0,20})
+--     noise_shader:send('z', love.timer.getTime())
+--     love.graphics.setShader(noise_shader)
+--     love.graphics.draw(canvas)
+--     love.graphics.setShader()
+-- The noise gradient shaders populate the RGB channels with dn/dx, dn/dy, dn/dz partial
+-- derivatives, where [-1,0,1] is remapped to [0,0.5,1]. 
+-- 
+-- Permission is hereby granted, free of charge, to any person obtaining a copy of
+-- this software and associated documentation files (the "Software"), to deal in
+-- the Software without restriction, including without limitation the rights to
+-- use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+-- of the Software, and to permit persons to whom the Software is furnished to do
+-- so, subject to the following conditions:
+-- 
+-- The above copyright notice and this permission notice shall be included in all
+-- copies or substantial portions of the Software.
+-- 
+-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+-- IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+-- FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+-- AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+-- LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+-- OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+-- SOFTWARE.
+
 local noise = {}
 local exp,sin,cos,floor,log,acos,sqrt,abs = math.exp,math.sin,math.cos,math.floor,math.log,math.acos,math.sqrt,math.abs
 local GR, PI, TAU, SQRT5, LOG_GR = (sqrt(5)+1)/2, math.pi, 2*math.pi, sqrt(5), log((sqrt(5)+1)/2)
@@ -10,12 +71,28 @@ local function cdf_prime(x, dx)
     return (0.31831 * exp(-2/PI * x*x) * abs(x)*dx)/sqrt(1-exp(-2/PI*x*x))
 end
 
-local function _defaultArgs(amplitudes,random)
+local default_resolutions = {["1d"]=5, ["2d"]=7, ["3d"]=9, ["1dShader"]=10, ["2dShader"]=15, ["3dShader"]=20}
-    if amplitudes == nil then amplitudes = 5 end
+local function _defaultArgs(opts, kind)
-    if type(amplitudes) == 'number' then
+    opts = opts or {}
-        amplitudes = noise.makeAmplitudes(amplitudes, function(x) return .1^x end)
+    local amplitudes, random = opts.amplitudes, opts.random
+    if random then
+        assert(type(random) == 'function', "Random number function must be a function.")
+    elseif not random then
+        if opts.seed and love and love.math then
+            local rng = love.math.newRandomGenerator(opts.seed)
+            random = function(...) return rng:random(...) end
+        else
+            random = math.random
+        end
+    end
+    if not amplitudes then
+        local resolution = opts.resolution or default_resolutions[kind]
+        local distribution = opts.distribution or (function(x) return .1^x end)
+        amplitudes = {}
+        for i=1,resolution do
+            amplitudes[i] = distribution((i-.5)/resolution)
+        end
     end
-    if not random then random = math.random end
     return amplitudes, random
 end
 
@@ -35,17 +112,8 @@ local function makeOffsets(count, random)
     return offsets
 end
 
-noise.makeAmplitudes = function(count, fn)
+noise.make1d = function(opts)
-    local amplitudes = {}
+    local amplitudes, random = _defaultArgs(opts, "1d")
-    for i=1,count do
-        amplitudes[i] = fn((i-.5)/count)
-    end
-    return amplitudes
-end
-
-noise.make1d = function(amplitudes,random)
-    amplitudes, random = _defaultArgs(amplitudes, random)
-    local resolution = #amplitudes
     local sigma = calculateSigma(amplitudes)
     local offsets = makeOffsets(#amplitudes, random)
     local function noise(x)
@@ -70,9 +138,8 @@ noise.make1d = function(amplitudes,random)
     return noise, gradient
 end
 
-noise.make2d = function(amplitudes, random)
+noise.make2d = function(opts)
-    amplitudes, random = _defaultArgs(amplitudes, random)
+    local amplitudes, random = _defaultArgs(opts, "2d")
-    local resolution = #amplitudes
     local sigma = calculateSigma(amplitudes)
     local offsets = makeOffsets(2*#amplitudes, random)
     sigma = sigma/sqrt(2)
@@ -109,8 +176,8 @@ noise.make2d = function(amplitudes, random)
     return noise, gradient
 end
 
-noise.make3d = function(amplitudes, random)
+noise.make3d = function(opts)
-    amplitudes, random = _defaultArgs(amplitudes, random)
+    local amplitudes, random = _defaultArgs(opts, "3d")
     local resolution = #amplitudes
     local sigma = calculateSigma(amplitudes)
     local offsets = makeOffsets(3*#amplitudes, random)
@@ -203,6 +270,7 @@ noise.make3d = function(amplitudes, random)
     return noise, gradient
 end
 
+if love and love.graphics then
     local shader1d = [[
     #define TAU 6.283185307179586476925286766559005768394338798750211641949
     #define MAX_RESOLUTION 64
@@ -239,14 +307,14 @@ vec4 effect(vec4 color, Image texture, vec2 texture_coords, vec2 pixel_coords)
     }
     ]]
 
-noise.make1dShader = function(amplitudes, random)
+    noise.make1dShader = function(opts)
-    amplitudes, random = _defaultArgs(amplitudes, random)
+        local amplitudes, random = _defaultArgs(opts, "1dShader")
         local resolution = #amplitudes
         local sigma = calculateSigma(amplitudes)
         local offsets = makeOffsets(#amplitudes, random)
         local shaderCode = "#define RESOLUTION "..tostring(resolution).."\n"..shader1d
-    local noiseShader = lg.newShader(shaderCode)
+        local noiseShader = love.graphics.newShader(shaderCode)
-    local gradShader = lg.newShader("#define GRADIENT\n"..shaderCode)
+        local gradShader = love.graphics.newShader("#define GRADIENT\n"..shaderCode)
         do -- Dumb hack to work around a bug in Love 0.10.2 not sending the last value
             table.insert(amplitudes, 1.)
             table.insert(offsets, 1.)
@@ -309,14 +377,14 @@ vec4 effect(vec4 color, Image texture, vec2 texture_coords, vec2 pixel_coords)
     }
     ]]
 
-noise.make2dShader = function(amplitudes, random)
+    noise.make2dShader = function(opts)
-    amplitudes, random = _defaultArgs(amplitudes, random)
+        local amplitudes, random = _defaultArgs(opts, "2dShader")
         local resolution = #amplitudes
         local sigma = calculateSigma(amplitudes)
         local offsets = makeOffsets(2*#amplitudes, random)
         local shaderCode = "#define RESOLUTION "..tostring(resolution).."\n"..shader2d
-    local noiseShader = lg.newShader(shaderCode)
+        local noiseShader = love.graphics.newShader(shaderCode)
-    local gradShader = lg.newShader("#define GRADIENT\n"..shaderCode)
+        local gradShader = love.graphics.newShader("#define GRADIENT\n"..shaderCode)
         sigma = sigma/sqrt(2)
         local offsets2 = {}
         for i=1,#offsets-1,2 do
@@ -414,14 +482,14 @@ vec4 effect(vec4 color, Image texture, vec2 texture_coords, vec2 pixel_coords)
     }
     ]]
 
-noise.make3dShader = function(amplitudes, random)
+    noise.make3dShader = function(opts)
-    amplitudes, random = _defaultArgs(amplitudes, random)
+        local amplitudes, random = _defaultArgs(opts, "3dShader")
         local resolution = #amplitudes
         local sigma = calculateSigma(amplitudes)
         local offsets = makeOffsets(3*#amplitudes, random)
         local shaderCode = "#define RESOLUTION "..tostring(resolution).."\n"..shader3d
-    local noiseShader = lg.newShader(shaderCode)
+        local noiseShader = love.graphics.newShader(shaderCode)
-    local gradShader = lg.newShader("#define GRADIENT\n"..shaderCode)
+        local gradShader = love.graphics.newShader("#define GRADIENT\n"..shaderCode)
         sigma = sigma/sqrt(3)
         local offsets2 = {}
         for i=1,#offsets-1,3 do
@@ -440,5 +508,6 @@ noise.make3dShader = function(amplitudes, random)
         end
         return noiseShader, gradShader
     end
+end
 
 return noise