moonshine

Chainable post-processing shaders for LÖVE.

Overview

• Getting started
• General usage
• List of effects
• Writing effects
• License

Getting started

Clone this repository into your game folder:

git clone https://github.com/vrld/moonshine.git

This will create the folder moonshine.

In your main.lua, or wherever you load your libraries, add the following:

local moonshine = require 'moonshine'

Create and parametrize the post-processing effect in love.load(), for example:

function love.load()
  effect = moonshine(moonshine.effects.filmgrain)
                    .chain(moonshine.effects.vignette)
  effect.filmgrain.size = 2
end

Lastly, wrap the things you want to be drawn with the effect inside a function:

function love.draw()
    effect(function()
      love.graphics.rectangle("fill", 300,200, 200,200)
    end)
end

When you package your game for release, you might want consider deleting the (hidden) .git folder in the moonshine directory.

General usage

The main concept behind moonshine are chains. A chain consists of one or more effects. Effects that come later in the chain will be applied to the result of the effects that come before. In the example above, the vignette is drawn on top of the filmgrain.

Chains

Chains are created using the moonshine.chain function:

chain = moonshine.chain(effect)

For convenience, moonshine(effect) is an alias to moonshine.chain(effect). You can add new effects to a chain using

chain = chain.chain(another_effect)

or using chain.next(), which is an alias to chain.chain(). As the function returns the chain, you can specify your whole chain in one go, as shown in the example above.

Effects and effect parameters

The effects that come bundled with moonshine (see List of effects) are accessed by chain.effects.<effect-name>, e.g.,

moonshine.effects.glow

Most effects are parametrized to change how they look. In the example above, the size of the grains was set to 2 pixels (the default is 1 pixel). Effect parameters are set by first specifying the name of the effect and then the name of the parameter:

chain.<effect>.<parameter> = <value>

For example, if chain contained the glow and crt effects, you can set the glow strength parameter and crt distortionFactor parameter as such:

chain.glow.strength = 10
chain.crt.distortionFactor = {1.06, 1.065}

Because you likely initialize a bunch of parameters at once, you can set all parameters with the special key parameters (or params or settings). This is equivalent to the above:

chain.parameters = {
  glow = {strength = 10},
  crt = {distortionFactor = {1.06, 1.065}},
}

Note that this will only set the parameters specified in the table. The crt parameter feather, for example, will be left untouched.

Drawing effects

Creating effects and setting parameters is fine, but not very useful on its own. You also need to apply it to something. This is done using chain.draw():

chain.draw(func, ...)

This will apply the effect to everything that is drawn inside func(...). Everything that is drawn outside of func(...) will not be affected. For example,

love.graphics.draw(img1, 0,0)
chain.draw(function()
  love.graphics.draw(img2, 200,0)
end)
love.graphics.draw(img3, 400,0)

will apply the effect to img2, but not to img1 and img3. Note that some effects (like filmgrain) draw on the whole screen. So if in this example chain would consist of a gaussianblur and filmgrain effect, img1 will be covered with grain, but will not be blurred, img2 will get both effects, and img3 will be left untouched.

Similar to chain creation, chain(func, ...) is an alias to the more verbose chain.draw(func, ...).

Temporarily disabling effects

You can disable effects in a chain by using chain.disable(names...) and chain.enable(names...). For example,

effect = moonshine(moonshine.effects.boxblur)
                  .chain(moonshine.effects.filmgrain)
                  .chain(moonshine.effects.vignette)
effect.disable("boxblur", "filmgrain")
effect.enable("filmgrain")

would first disable the boxblur and filmgrain effect, and then enable the filmgrain again. Note that the effects are still in the chain, they are only not drawn.

Canvas size

You can change the size of the internal canvas, for example when the window was resized, by calling chain.resize(width, height). Do this anytime you want, but best not during chain.draw().

You can also specify the initial canvas size by starting the chain like this:

effect = moonshine(400,300, moonshine.effects.vignette)

That is, you specify the width and height before the first effect in the chain.

Is this efficient?

Of course, using moonshine is not as efficient as writing your own shader that does all the effects you want in the least amount of passes, but moonshine tries to minimize the overhead.

On the other hand, you don't waste time writing the same shader over and over again when using moonshine: You're trading a small amount of computation time for a large amount of development time.

List of effects

Currently, moonshine contains the following effects (in alphabetical order):

• boxblur: simple blurring
• chromasep: cheap/fake chromatic aberration
• colorgradesimple: weighting of color channels
• crt: crt/barrel distortion
• desaturate: desaturation and tinting
• dmg: Gameboy and other four color palettes
• fastgaussianblur: faster Gaussian blurring
• filmgrain: image noise
• gaussianblur: Gaussian blurring
• glow: aka (light bloom
• godsray: aka light scattering
• pixelate: sub-sampling (for that indie look)
• posterize: restrict number of colors
• scanlines: horizontal lines
• sketch: simulate pencil drawings
• vignette: shadow in the corners

boxblur

moonshine.effects.boxblur

Parameters:

chromasep

moonshine.effects.chromasep

Parameters:

colorgradesimple

moonshine.effects.colorgradesimple

Parameters:

crt

moonshine.effects.crt

Parameters:

desaturate

moonshine.effects.desaturate

Parameters:

dmg

moonshine.effects.dmg

DMG ships with 7 palettes:

1. default
2. dark_yellow
3. light_yellow
4. green
5. greyscale
6. stark_bw
7. pocket

Custom palettes must be in the format {{R,G,B}, {R,G,B}, {R,G,B}, {R,G,B}}, where R, G, and B are numbers between 0 and 255.

fastgaussianblur

moonshine.effects.fastgaussianblur

Parameters:

filmgrain

moonshine.effects.filmgrain

Parameters:

gaussianblur

moonshine.effects.gaussianblur

Parameters:

glow

moonshine.effects.glow

Parameters:

godsray

moonshine.effects.godsray

Parameters:

pixelate

moonshine.effects.pixelate

Parameters:

posterize

moonshine.effects.posterize

Parameters:

scanlines

moonshine.effects.scanlines

Parameters:

sketch

moonshine.effects.sketch

Parameters:

vignette

moonshine.effects.vignette

Parameters:

fog

moonshine.effects.fog

Parameters:

Writing effects

An effect is essentially a function that returns a moonshine.Effect{}, which must specify at least a name and a shader or a draw function.

It may also specify a setters table that contains functions that set the effect parameters and a defaults table with the corresponding default values. The default values will be set when the effect is instantiated.

A good starting point to see how to write effects is the colorgradesimple effect, which uses the shader, setters and defaults fields.

Moonshine uses double buffering to draw the effects. A function to swap and access the buffers is provided to the draw(buffer) function of your effect:

front, back = buffer() -- swaps front and back buffer and returns both

You don't have to care about canvases or restoring defaults, moonshine handles all that for you.

If you only need a custom draw function because your effect needs multiple shader passes, moonshine provides the draw_shader(buffer, shader) function. As you might have guessed, this function uses shader to draw the front buffer to the back buffer. The boxblur effect gives a simple example how to use this function.

If for some reason you need more than two buffer, you are more or less on your own. You can do everything, but make sure that the blend mode and the order of back and front buffer is the same before and after your custom draw function. The glow effect gives an example of a more complicated draw function.

License

See here for a list of contributors.

The main library can freely be used under the following conditions:

The MIT License (MIT)

Copyright (c) 2017 Matthias Richter

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.

Most of the effects are public domain (see comments inside the files):

• boxblur.lua
• chromasep.lua
• colorgradesimple.lua
• crt.lua
• desaturate.lua
• filmgrain.lua
• gaussianblur.lua
• glow.lua
• pixelate.lua
• posterize.lua
• scanlines.lua
• vignette.lua

These effects are MIT-licensed with multiple authors:

• dmg.lua: Joseph Patoprsty, Matthias Richter
• fastgaussianblur.lua: Tim Moore, Matthias Richter
• godsray.lua: Joseph Patoprsty, Matthias Richter. Based on work by ioxu, Fabien Sanglard, Kenny Mitchell and Jason Mitchell.
• sketch.lua: Martin Felis, Matthias Richter
• fog.lua: Brandon Blanker Lim-it. Based on work by Gonkee.