Library overview

The library aims to provide simple yet flexible framework to work with post-processing OpenGL shader effects in a LibGDX application. On top of it, there is a bunch of most common out-of-the-box effects included in the library. So it would be nice and simple to pick up the library and start using it straight away, as well as have these effects as a good reference to create your own ones.

Library module structure

1. gdx-vfx-core - Core classes.
2. gdx-vfx-effects - Collection of the out-of-the-box filters and effects. Read more about this module at Built-in Effects page.
3. gdx-vfx-gwt - Platform specific code for GWT backend.

General usage workflow

1. Create and configure required Effects and add them to a Manager.
2. Inside your render code this happens:
   1. The Manager starts capturing into an off-screen buffer.
   2. You render your scene.
   3. The Manager stops capturing into an off-screen buffer.
   4. The Manager applies Effect chain to the captured result.
   5. The Manager renders the result into the screen or another frame buffer (if you specify one).
   6. When no longer needed, the Manager and all the Effects should be disposed manually. Please read the notes about this stage here.

Library architecture

There are 3 core building blocks in the library's code that help to organize the structure.

1. VfxFilter aka Filter

Serves as a shader effect wrapper. Sort of an interface between GLSL code and Java. Main purpose is to create and manage shader's state, update uniforms, bind textures, expose getters/setters to the Effect classes, etc...

A Filter usually implements a singe-pass shader effect. It can be reused in composition with other Filters to create complicated Effects (e.g. BloomEffect mix three different Filters together).

2. VfxEffect aka Effect

Is a high level controller over the effect. Doesn't directly deal with shaders, but does this through Filter classes by managing their instances internally.

An Effect may have multiple Filters to compose them together to achieve complex result.

3. VfxManager aka Manager

The main class of the library. Does scene off-screen capture and applies Filters to it. A Manager maintains post-processing Filter queue, so all the required Filters should be added the Manager in order to be applied to the scene.

Implementation specifics

There is a collection of things that is important to know about before you start using the library code.

VFX frame buffer

The library impose you to use VfxFrameBuffer class over regular FrameBuffer whenever you need to deal with the off-screen rendering during capturing or applying effects chain stages. Please read about VfxFrameBuffer justification on this page.

Ping-pong rendering

As there is a chain of Filters (can be break down to a chain of Effects) to be applied to the scene one after another, we use ping-pong buffer render approach. Ping-pong buffer basically stands for two buffers where one is used as an input (aka src buffer) for the effect and the other one as the buffer where we will render to (aka dst buffer). Once any Filter is rendered, the ping-pong buffer should be swapped, so now the result will be held in the src buffer and ready to be used as an input for another filter.

Resource disposal

As we dealing with OpenGL related stuff, most of the library classes implement Disposable interface and shall be properly disposed when no longer needed.

The important to note, that although a Manager maintains a chain of Effects, it doesn't manage their life-cycle. Means you have to manually call VfxEffect#dispose() when you no longer need it (e.g. application termination).

You create Effect instances outside of the Manager, add/remove them to the Manager whenever you need them to participate in the effect chain, and you're responsible for disposing them yourself.

Custom OpenGL calls

The library relies on extended set of OpenGL functions, that are not yet available/implemented for the official LibGDX backends. Thus VfxGlExtension interface is introduced. Different implementations help to maintain cross-platform support. However the same implementation is shared among almost all the backends - DefaultVfxGlExtension, except for GWT backend we use GwtVfxGlExtension due to WebGL specifics.

At runtime currentVfxGlExtension instance is available through VfxGLUtils#glExtension.