Header-only effects and helper library for Bgfx to help you hit the ground running. Includes a bunch of post processing filters to complete common graphical tasks
An extension library for bgfx to help you hit the ground running by wrapping common tasks in simple header files. It also provides a number of Effects to provide an off-the-shelf solution to common rendering demands, such as post processing filters, shadow mapping and more.
Like bgfx, this is rendering library. Its not a game engine and does not aim to be. Rather it simply gives you the pieces to rapidly assemble a graphics pipeline in a cross platform, api agnostic manner. Bgfxh aims to bridge the gap between using a potentially large or bloated generalist graphics library or game engine for simple rendering jobs, and reinventing the wheel by creating an engine from scratch. By thinly relying on bgfx maintenance requirements are kept low.
Liam Twigger - @SnapperTheTwig
#include <bgfxh/loadTexture.h>
. Only want itinitSdlWindow()
loadTexture()
- supports what bimg supports (most of this is extracted from the bgfx examples and repackaged to be used here)loadShader()
debugDrawFramebuffer()
and debugDrawFramebufferMono()
for monochromatic framebuffers (such as depth buffers).Effects are basically C++ objects that wrap bgfx commands and resources do some graphical task. To use, simply:
#include <bgfxh/effects/bloom.h>
)bgfxh::bloomEffect mBloomEffect;
mBloomEffect.init();
- this generates the uniforms, samplers and framebuffers for the filter and loads the relevant shadersmBloomEffect.submit(framebufferToBloom);
- this will set up the viewsShaders ''can'' be embedded in the Effects. Use #define BGFXH_EMBED_EFFECT_SHADERS
to embed at compile time.
Each filter has detailed use instructions in the top of their respective header file.
Availiable Effects:
atmosphere.h
- Implementation of Sean O'Niel's atmospheric shader from Gpu Gems 2. Works at all altitudes, can shade the atmosphere and the ground, can work either in the vertex or the fragment shader. Includes a utitlity to generate sky dome/sphere meshescascadingShadowMap.h
- Cascading shadowmap generation (both regular and VSM, with frustum checking)bloom.h
- Bloom with a fixed gaussian kernal. Uses bilinear filtering for efficiencyguassianBlur.h
- Guassian blur with setable kernal. Also has a function to generate a suitable sigma for a given kernallum.h
- Time averaged luminance calculationtonemapping.h
- ACES Filmic Tonemapping + can combine the outputs of other EffectsSimply copy the shaders you want and merge the folders together. So to add bloom and luminance shaders to your application copy the contents of bgfxh/shaders/bloom/
and bgfx/shaders/lum/
to yourApp/<yourShaderPath>/
, and set bgfxh::shaderSearchPath
to "<yourShaderPath>/" + bgfxh::getShaderDirectoryFromRenderType() + "/"
to point the shader loader to the right shaders. For OpenGl this will be "<yourShaderPath>/glsl/"
, for dx11 this will be "<yourShaderPath>/dx11/"
, for Vulkan this will be "<yourShaderPath>/spriv/"
Note that bgfxh::shaderSearchPath
only effects the location of shaders loaded for bgfxh filters! Eg bgfxh::bloomEffect will load bloom_brightpass
by invoking bgfxh::loadShader(bgfxh::shaderSearchPath + "vs_bloom_brightpass.bin", bgfxh::shaderSearchPath + "fs_bloom_brightpass.bin")
loadShader will handle Windows or POSIX file paths (it internally invokes bgfxh::fixPath(path)
)
If you are lacking a build system for your own shaders you can use the one provided.
Shaders come already compiled + are embeddable, so you can use them right away!
More Render Jobs = more better! I do have plans to specifically make the following, but any input will be greatly appreciated
Be sure to create/edit the .lzz
files, not the generated .h
files. The tools + scripts to create the header files from the .lzz
sources are provided.
#include <SDL>
#include <bgfx>
#define BGFXH_IMPL
#include <bfgxh/bgfxh.h>
#include <bfgxh/sdlWindow.h>
int main (int argc, char *argv[]) {
SDL_Init(0);
SDL_Window * mWindow = SDL_CreateWindow("BGFXH Test", SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, 1200, 720, SDL_WINDOW_SHOWN | SDL_WINDOW_RESIZABLE);
bgfxh::initSdlWindowAndBgfx(mWindow); // Creates a bgfx context in an sdl window
// You now have a window + a bgfx context!
while (true) {
drawStuff();
bgfx::frame();
}
}
initSdlWindowAndBgfx()
internally calls bgfx::init()
with some default parameters. You can avoid this by calling initSdlWindow(mWindow);
, then call bgfx::init();
when you like;
#define BGFXH_IMPL
#include <bfgxh/loadTexture.h>
...
bgfx::TextureHandle foo = bgfxh::loadTexture ("filename.ext", BGFX_TEXTURE_FLAGS | BGFX_SAMPLER_FLAGS);
NOTE: that this file adds a linking dependency on libbimg_decode(Debug/release).a. This is from bimg and is built alongside bgfx
It is recommended that you use texturec (part of bgfx, see tools) to create a texture file (.dds/.kxt) as these are optimised for loading and can contain pre-computed mipmaps. On the fly mipmap generation is not supported (and is slow anyway).
#define BGFXH_IMPL
#include <bfgxh/bgfxh.h>
#include <bfgxh/sdlWindow.h> // If using SDL Windows!
...
initSdlWindowAndBgfx(mWindow);
bgfxh::init(backbufferWidth, backbufferHeight, "path/to/shaders"); //<-- shaders, uniforms and vertexDecl's for debug drawing are made here
.... OR ....
bgfx::Init mInit;
// Set mInit's parameters here
initSdlWindowAndBgfx(mWindow, mInit);
bgfxh::init(backbufferWidth, backbufferHeight, "path/to/shaders"); //<-- shaders, uniforms and vertexDecl's for debug drawing are made here
.... OR ....
initSdlWindow(mWindow); // Don't call bgfx::init() internally. Infact if you're not using SDL you can omit this line altogether
bgfx::init();
bgfxh::init(backbufferWidth, backbufferHeight, "path/to/shaders");
#define BGFXH_IMPL
#include <bfgxh/bgfxh.h>
...
bgfx::init();
bgfxh::init(backbufferWidth, backbufferHeight, "path/to/shaders"); //<-- shaders, uniforms and vertexDecl's for debug drawing are made here
...
// Initialises a 2D view, with tag, size, no framebuffer attachement (render to backbuffer), doesn't clear, and is not a unit ortho matrix
bgfxh::initView2D (VIEW_ID_OUTPUT_PASS, "output pass", backbufferWidth, backbufferHeight, BGFX_INVALID_HANDLE, false, false);
// Viewing a texture
// ViewId, thingToInspect, xPos, yPos, xSize, ySize, (backbufferWidth), (backbufferHeight)
// (backbufferWidth), (backbufferHeight) are only used for pixel-perfect dx9 rendering and can be ommitted if you don't care about that
bgfxh::debugDrawTexture (VIEW_ID_OUTPUT_PASS, textureHandleToView, 10, 10, 120, 120, backbufferWidth, backbufferHeight);
// Viewing a framebuffer
bgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, framebufferToInspect, 10+130, 10, 120, 120, backbufferWidth, backbufferHeight);
// Viewing the output of a bgfxh::effect
bgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, mBgfxhLumEffect.getOutputFramebuffer(), 10+130*2, 10, 120, 120, backbufferWidth, backbufferHeight);
// Inspecting a cascading shadow map (eg, cascadingShadowMapEffect.h)
for (unsigned int i = 0; i < mBgfxhCsmEffect.nShadowLevels; ++i)
bgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, mBgfxhCsmEffect.getOutputFramebuffer(i), 10 + 130*i, 130, 120, 120, backbufferWidth, backbufferHeight);
#define BGFXH_IMPL
#include <bfgxh/bgfxh.h>
// Optionally #define BGFXH_EMBED_EFFECT_SHADERS if you want shaders embedded at compile time
#include <bfgxh/effects/bloom.h>
#include <bfgxh/effects/lum.h>
class GfxPipeline {
public:
// Effect objects
bgfxh::bloomEffect mBloomEffect; // Each "job" or is a class!
bgfxh::lumEffect mLumEffect;
bgfxh::tonemappingEffect mTonemappingEffect;
// Your resources
bgfx::ProgramHandle m_myProgram;
bgfx::FrameBufferHandle m_myFramebuffer;
GfxPipeline () {}
~GfxPipeline() {} // Each "job" will clean up its resources on destruction
void init () {
// Set parameters
mBloomEffect.setSize (600, 360);
mBloomEffect.nBloomBlurPasses = 2;
mBloomEffect.init(); // Resources are created here!
mLumEffect.init();
mTonemappingEffect.setSize (1200, 720);
mTonemappingEffect.maxAdditonalSamplerSlots = 1; // Configure the tonemapping filter to accept a blended attachement
mTonemappingEffect.init ();
// Your stuff
m_myProgram = bgfxh::loadProgram("path/vs_forwardRenderer.bin", "fs_forwardRenderer.bin");
m_myFramebuffer = ... ; // Gbuffer? Or just a colour/depth buffer for forward rendering!
}
void submitScene (YourScene) {
mLumEffect.viewId = 1; // A lum filter will take up 5 views
mBloomEffect.viewId = 1 + mLumEffect.getViewIncrement(); // A bloom filter will take a number of views depending on how many blur passes you are doing
mTonemappingEffect.viewId = mBloomEffect.viewId + mBloomEffect.getViewIncrement();
...
// Render your scene to a framebuffer (m_myFramebuffer)
// You still have to implement your own forward or gbuffer here
//bgfx::submit(0, m_myProgram)
...
// Apply Post Processing using the filters!
mLumEffect.submit (bgfx::getTexture(m_myFramebuffer, 0));
// Get the output of a effect as a texture that you can use in another effect!
mBloomEffect.submit (mLumEffect.getOutputTexture(), bgfx::getTexture(m_myFramebuffer, 0));
// Configure the tonemapping filter to additively blend the bloom
mBgfxhTonemappingEffect.setExtraComponent (0, mBgfxhBloomEffect.getOutputTexture(), 1.0f, 0.f);
// Does the tonemapping. Renders to backbuffer by default
mTonemappingEffect.submit (bgfx::getTexture(m_myFramebuffer, 0), mLumEffect.getOutputTexture());
// Debug render the lum filter's output to see if it is calculating sensible lum values
const int OUTPUT_PASS_ID = 200;
bgfxh::initView2D (VIEW_ID_OUTPUT_PASS, "output pass", backbufferWidth, backbufferHeight, BGFX_INVALID_HANDLE, false, false);
bgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, mLumEffect.getOutputFramebuffer(), 10, 10, 120, 120, backbufferWidth, backbufferHeight);
}
}
//Wrapper.h
#include <bfgxh/bgfxh.h>
#include <bfgxh/...>
#include <bfgxh/...> //etc
//Wrapper.cpp
#define BGFXH_IMPL
#include <bfgxh/bgfxh.h>
#include <bfgxh/...>
#include <bfgxh/...> //etc
#define BGFXH_IMPL
#include <bfgxh/bgfxh.h>
...
bgfxh::frustum mFrustum;
mFrustum.setFromViewAndProjMatrix (viewMtx, projMtx);
for (each object in scene) {
if (mFrustum.frustumCheck (object.positionVec3, object.radius)) continue; // Where radius is the radius of some bounding sphere for the object
... Alternatively ....
if (mFrustum.frustumCheck (object.bgfxModelMtx, object.radius)) continue;
// Set uniforms, transform matricies, etc
bgfx::setTransform (object.bgfxModelMtx);
bgfx::submit();
}
Submit using one of:
bgfxh::m_programUntexturedPassthrough
- Renders geometry without any texture or any fancy stuff. Handy for wireframe rendering
bgfxh::m_programTexturePassthrough
- Renders a texture. Handy for GUI stuff
bgfxh::m_programTexturePassthroughMonochromatic
- Renders a texture in greyscale. Handy for inspecting a framebuffer
Thanks To Branimir Karadzic and all others who have contributed to Bgfx!
Public Domain Various code snippets have been adapted from bgfx and are thus under the BSD license.