diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d41469c
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# Hill Noise
+
+This is a lua library implementation of 1D, 2D, and 3D [Hill Noise](http://blog.bruce-hill.com/hill-noise/).
+This random noise function generates continuous approximately uniformly distributed pseudorandom noise
+values in the range (0-1) with configurable resolution, level of detail, and shape characteristics.
+
+## Usage
+
+```lua
+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)
+```
+
+## Parameters
+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)
+
+### Runtime
+The noise and noise gradient functions all run in O(resolution), and more resolution
+may be needed for higher dimensional noise and additional detail.
+
+## LÖVE
+
+This library also include 1D, 2D, and 3D noise shaders for use with the [LÖVE game engine](https://love2d.org/).
+The shader versions are much faster for producing many noise values, as they run in parallel on the GPU.
+
+```lua
+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:
+* for 1D: `sigmoid(2*dn/dx)`, `sigmoid(2*dn/dx)`, `sigmoid(2*dn/dx)`
+* for 2D: `sigmoid(1.5*dn/dx)`, `sigmoid(1.5*dn/dy)`, `0`
+* for 3D: `sigmoid(4*dn/dx)`, `sigmoid(4*dn/dy)`, `sigmoid(4*dn/dz)`
+
+(coefficients were arbitrarily chosen to best squash typical gradients for the default
+parameters evenly into (0,1))
+
+Additionally, the 1D noise shader has an extra variable `draw_outline` that, if set to
+`true`, makes the 1D shader render output as white or black if the y-coordinate is
+above/below the  noise value for a given x-coordinate.
diff --git a/demo/main.lua b/demo/main.lua
index 4650c02..e918a3b 100644
--- a/demo/main.lua
+++ b/demo/main.lua
@@ -11,9 +11,7 @@ local decay = function(x) return .15^x end
 local n1,g1 = Noise.make1d{resolution=5, distribution=decay, seed=1}
 local n2,g2 = Noise.make2d{resolution=7, distribution=decay, seed=1}
 local n3,g3 = Noise.make3d{resolution=9, distribution=decay, seed=1}
-local s1,s1g = Noise.make1dShader{resolution=10, distribution=decay, seed=1}
-s1:send("draw_outline",true)
-s1g:send("draw_outline",true)
+local s1,s1g = Noise.make1dShader{resolution=10, distribution=decay, seed=1, draw_outline=true}
 local s2,s2g = Noise.make2dShader{resolution=15, distribution=decay, seed=1}
 local s3,s3g = Noise.make3dShader{resolution=20, distribution=decay, seed=1}
 
diff --git a/hill_noise.lua b/hill_noise.lua
index 44fdd0d..a12ffb7 100644
--- a/hill_noise.lua
+++ b/hill_noise.lua
@@ -5,6 +5,11 @@
 -- with approximately uniform distribution on the interval (0,1) and customizable resolution,
 -- levels of detail, and shape characteristics.
 --
+-- Functions: make1d([opts]), make2d([opts]), make3d([opts])
+--   each of these returns a noise function, and a gradient function of the noise function
+-- Shader functions: make1dShader([opts]), make2dShader([opts]), make3dShader([opts])
+--   each of these returns a noise shader, and a gradient shader of the noise function
+--
 -- Usage:
 --     local Noise = require 'hill_noise'
 --     local noise,noise_gradient = Noise.make3d{resolution=9}
@@ -44,7 +49,7 @@
 --   * for 3D: sigmoid(4*dn/dx), sigmoid(4*dn/dy), sigmoid(4*dn/dz)
 -- (coefficients were arbitrarily chosen to best squash typical gradients for the default
 --  parameters evenly into (0,1))
--- Additionally, the 1D noise shader has an extra variable "draw_outline" that, if set to
+-- Additionally, the 1D noise shader has an extra option "draw_outline" that, if set to
 -- true, makes the 1D shader render output as white or black if the y-coordinate is
 -- above/below the  noise value for a given x-coordinate.
 -- 
@@ -343,6 +348,9 @@ if love and love.graphics then
             shader:send("amplitudes",unpack(amplitudes))
             shader:send("range_min", 0)
             shader:send("range_max", 0)
+            if opts and opts.draw_outline then
+                shader:send("draw_outline", true)
+            end
         end
         return noiseShader,gradShader
     end