{"id":13731678,"url":"https://github.com/SnapperTT/bgfx-header-extension-library","last_synced_at":"2025-05-08T05:30:33.525Z","repository":{"id":45665613,"uuid":"189520964","full_name":"SnapperTT/bgfx-header-extension-library","owner":"SnapperTT","description":"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","archived":false,"fork":false,"pushed_at":"2025-04-01T10:42:26.000Z","size":1566,"stargazers_count":43,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-01T11:32:26.860Z","etag":null,"topics":["bgfx","directx","graphics","linux","macos","metal","opengl","vulkan","windows"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/SnapperTT.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-05-31T03:24:25.000Z","updated_at":"2025-04-01T10:42:31.000Z","dependencies_parsed_at":"2024-01-31T02:09:36.495Z","dependency_job_id":"49e39234-393d-4666-870f-c84d6ca8c5c9","html_url":"https://github.com/SnapperTT/bgfx-header-extension-library","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SnapperTT%2Fbgfx-header-extension-library","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SnapperTT%2Fbgfx-header-extension-library/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SnapperTT%2Fbgfx-header-extension-library/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/SnapperTT%2Fbgfx-header-extension-library/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/SnapperTT","download_url":"https://codeload.github.com/SnapperTT/bgfx-header-extension-library/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253008345,"owners_count":21839631,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bgfx","directx","graphics","linux","macos","metal","opengl","vulkan","windows"],"created_at":"2024-08-03T02:01:35.655Z","updated_at":"2025-05-08T05:30:33.508Z","avatar_url":"https://github.com/SnapperTT.png","language":"C","funding_links":[],"categories":["Graphics"],"sub_categories":[],"readme":"Bgfx Header Utils And Effects Library\n===================================\nAn extension library for [bgfx](https://github.com/bkaradzic/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.\n\nLike 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. \n\n## Contact:\nLiam Twigger - @SnapperTheTwig\n\n## Features:\n* Header only library, inspired by [stb](https://github.com/nothings/stb), requires no changes to your build system. Simply use #define BGFXH_IMPL before #include to generate an implementation\n* Only pay for what you use. Don't want texture loading? Then don't `#include \u003cbgfxh/loadTexture.h\u003e`. Only want it\n* SDL Window management with `initSdlWindow()`\n* Texture Loading with `loadTexture()` - supports what [bimg](https://github.com/bkaradzic/bimg) supports (most of this is extracted from the bgfx examples and repackaged to be used here)\n* Shader Loading with `loadShader()`\n* Inspect textures/framebuffers with `debugDrawFramebuffer()` and `debugDrawFramebufferMono()` for monochromatic framebuffers (such as depth buffers). \n* Frustum culling utility\n* A variety of Effects, see below for more info\n* Thin layer ontop of bgfxh. Rather than hiding the underlying framework under a complex layer of abstraction, bgfxh just provides free functions that do some job. Effects are c++ classes, are optional\n* Few dependencies - only on bgfx/bimg/bx and some standard c/c++ libraries\n* Permissive license\n\n## Effects:\nEffects are basically C++ objects that wrap bgfx commands and resources do some graphical task. To use, simply:\n* Include the relevant file (eg `#include \u003cbgfxh/effects/bloom.h\u003e`)\n* Create an object `bgfxh::bloomEffect mBloomEffect;`\n* Choose your settings for the filter, then call `mBloomEffect.init();` - this generates the uniforms, samplers and framebuffers for the filter and loads the relevant shaders\n* In your rendering loop, call `mBloomEffect.submit(framebufferToBloom);` - this will set up the views\n* On object destruction all resources created will be freed.\n\nShaders ''can'' be embedded in the Effects. Use `#define BGFXH_EMBED_EFFECT_SHADERS` to embed at compile time.\n\nEach filter has detailed use instructions in the top of their respective header file.\n\nAvailiable Effects:\n* `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 meshes\n* `cascadingShadowMap.h` - Cascading shadowmap generation (both regular and VSM, with frustum checking)\n* `bloom.h` - Bloom with a fixed gaussian kernal. Uses bilinear filtering for efficiency\n* `guassianBlur.h` - Guassian blur with setable kernal. Also has a function to generate a suitable sigma for a given kernal\n* `lum.h` - Time averaged luminance calculation\n* `tonemapping.h` - ACES Filmic Tonemapping + can combine the outputs of other Effects\n\n## Shaders:\nSimply 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/\u003cyourShaderPath\u003e/`, and set `bgfxh::shaderSearchPath` to `\"\u003cyourShaderPath\u003e/\" + bgfxh::getShaderDirectoryFromRenderType() + \"/\"` to point the shader loader to the right shaders. For OpenGl this will be `\"\u003cyourShaderPath\u003e/glsl/\"`, for dx11 this will be `\"\u003cyourShaderPath\u003e/dx11/\"`, for Vulkan this will be `\"\u003cyourShaderPath\u003e/spriv/\"`\n\nNote 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\")`\n\nloadShader will handle Windows or POSIX file paths (it internally invokes `bgfxh::fixPath(path)`)\n\nIf you are lacking a build system for your own shaders you can use the one provided.\n\nShaders come already compiled + are embeddable, so you can use them right away!\n\n## Contributing:\nMore Render Jobs = more better! I do have plans to specifically make the following, but any input will be greatly appreciated\n* A light sprite/tile engine (sprites should use the transient buffer, tiles should use a vertex buffer).\n* Screenspace reflection\n* A simple forward renderer\n\nBe 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.\n\nHow Do I?\n=========\n  * [Create a SDL Window?](#create-a-sdl-window-)\n  * [Load a Texture? (.dds/.ktx) Or an Image as a Texture (.jpg, .png, .tga, etc).](#load-a-texture---dds-ktx--or-an-image-as-a-texture--jpg--png--tga--etc-)\n  * [Initialise BGFX and BGFXH?](#initialise-bgfx-and-bgfxh-)\n  * [View the Contents of a Framebuffer?](#view-the-contents-of-a-framebuffer-)\n  * [Create a Rendering Pipeline With The Provided Effects and My Stuff?](#create-a-rendering-pipeline-with-the-provided-effects-and-my-stuff-)\n  * [Speed Up Compile Times By Making A Seperate Compilation Unit?](#speed-up-compile-times-by-making-a-seperate-compilation-unit-)\n  * [Frustum Cull?](#frustum-cull-)\n  * [Use the Built-In Shaders?](#use-the-built-in-shaders-)\n  \n## Create a SDL Window?\n```c++\n#include \u003cSDL\u003e\n#include \u003cbgfx\u003e\n\n#define BGFXH_IMPL\n#include \u003cbfgxh/bgfxh.h\u003e\n#include \u003cbfgxh/sdlWindow.h\u003e\n\nint main (int argc, char *argv[]) {\n\tSDL_Init(0);\n\tSDL_Window * mWindow = SDL_CreateWindow(\"BGFXH Test\", SDL_WINDOWPOS_UNDEFINED, SDL_WINDOWPOS_UNDEFINED, 1200, 720, SDL_WINDOW_SHOWN | SDL_WINDOW_RESIZABLE);\n\tbgfxh::initSdlWindowAndBgfx(mWindow); // Creates a bgfx context in an sdl window\n\t\n\t// You now have a window + a bgfx context!\n\twhile (true) {\n\t\tdrawStuff();\n\t\tbgfx::frame();\n\t\t}\n\t}\n```\n\n`initSdlWindowAndBgfx()` internally calls `bgfx::init()` with some default parameters. You can avoid this by calling `initSdlWindow(mWindow);`, then call `bgfx::init();` when you like;\n\n## Load a Texture? (.dds/.ktx) Or an Image as a Texture (.jpg, .png, .tga, etc).\n```c++\n#define BGFXH_IMPL\n#include \u003cbfgxh/loadTexture.h\u003e\n\n...\n\nbgfx::TextureHandle foo = bgfxh::loadTexture (\"filename.ext\", BGFX_TEXTURE_FLAGS | BGFX_SAMPLER_FLAGS);\n\n```\n\n**NOTE:** that this file adds a linking dependency on libbimg_decode(Debug/release).a. This is from bimg and is built alongside bgfx\n\nIt 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).\n\n## Initialise BGFX and BGFXH?\n```c++\n#define BGFXH_IMPL\n#include \u003cbfgxh/bgfxh.h\u003e\n#include \u003cbfgxh/sdlWindow.h\u003e // If using SDL Windows!\n\n...\n\ninitSdlWindowAndBgfx(mWindow);\nbgfxh::init(backbufferWidth, backbufferHeight, \"path/to/shaders\"); //\u003c-- shaders, uniforms and vertexDecl's for debug drawing are made here\n\n.... OR ....\n\nbgfx::Init mInit;\n// Set mInit's parameters here\ninitSdlWindowAndBgfx(mWindow, mInit);\nbgfxh::init(backbufferWidth, backbufferHeight, \"path/to/shaders\"); //\u003c-- shaders, uniforms and vertexDecl's for debug drawing are made here\n\n.... OR ....\n\ninitSdlWindow(mWindow); // Don't call bgfx::init() internally. Infact if you're not using SDL you can omit this line altogether\nbgfx::init();\nbgfxh::init(backbufferWidth, backbufferHeight, \"path/to/shaders\");\n```\n\n## View the Contents of a Framebuffer?\n```c++\n#define BGFXH_IMPL\n#include \u003cbfgxh/bgfxh.h\u003e\n\n...\n\nbgfx::init();\nbgfxh::init(backbufferWidth, backbufferHeight, \"path/to/shaders\"); //\u003c-- shaders, uniforms and vertexDecl's for debug drawing are made here\n\n...\n\n// Initialises a 2D view, with tag, size, no framebuffer attachement (render to backbuffer), doesn't clear, and is not a unit ortho matrix \nbgfxh::initView2D (VIEW_ID_OUTPUT_PASS, \"output pass\", backbufferWidth, backbufferHeight, BGFX_INVALID_HANDLE, false, false);\n// Viewing a texture\n// ViewId, thingToInspect, xPos, yPos, xSize, ySize, (backbufferWidth), (backbufferHeight)\n// (backbufferWidth), (backbufferHeight) are only used for pixel-perfect dx9 rendering and can be ommitted if you don't care about that\nbgfxh::debugDrawTexture (VIEW_ID_OUTPUT_PASS, textureHandleToView, 10, 10, 120, 120, backbufferWidth, backbufferHeight); \n\n// Viewing a framebuffer\nbgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, framebufferToInspect, 10+130, 10, 120, 120, backbufferWidth, backbufferHeight);\n\n// Viewing the output of a bgfxh::effect\nbgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, mBgfxhLumEffect.getOutputFramebuffer(), 10+130*2, 10, 120, 120, backbufferWidth, backbufferHeight);\n\n// Inspecting a cascading shadow map (eg, cascadingShadowMapEffect.h)\nfor (unsigned int i = 0; i \u003c mBgfxhCsmEffect.nShadowLevels; ++i)\n\tbgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, mBgfxhCsmEffect.getOutputFramebuffer(i), 10 + 130*i, 130, 120, 120, backbufferWidth, backbufferHeight);\n\t\t\n```\n\n## Create a Rendering Pipeline With The Provided Effects and My Stuff?\n```c++\n#define BGFXH_IMPL\n#include \u003cbfgxh/bgfxh.h\u003e\n// Optionally #define BGFXH_EMBED_EFFECT_SHADERS if you want shaders embedded at compile time\n#include \u003cbfgxh/effects/bloom.h\u003e\n#include \u003cbfgxh/effects/lum.h\u003e\n\nclass GfxPipeline {\npublic:\n\t// Effect objects\n\tbgfxh::bloomEffect mBloomEffect; // Each \"job\" or is a class! \n\tbgfxh::lumEffect mLumEffect;\n\tbgfxh::tonemappingEffect mTonemappingEffect;\n\t// Your resources\n\tbgfx::ProgramHandle m_myProgram;\n\tbgfx::FrameBufferHandle m_myFramebuffer;\n\n\tGfxPipeline () {}\n\t~GfxPipeline() {} // Each \"job\" will clean up its resources on destruction\n\n\tvoid init () {\n\t\t// Set parameters\n\t\tmBloomEffect.setSize (600, 360);\n\t\tmBloomEffect.nBloomBlurPasses = 2;\n\t\tmBloomEffect.init(); // Resources are created here!\n\t\tmLumEffect.init();\n\t\t\n\t\tmTonemappingEffect.setSize (1200, 720);\n\t\tmTonemappingEffect.maxAdditonalSamplerSlots = 1; // Configure the tonemapping filter to accept a blended attachement\n\t\tmTonemappingEffect.init ();\n\t\t\n\t\t// Your stuff\n\t\tm_myProgram = bgfxh::loadProgram(\"path/vs_forwardRenderer.bin\", \"fs_forwardRenderer.bin\");\n\t\tm_myFramebuffer = ... ; // Gbuffer? Or just a colour/depth buffer for forward rendering!\n\t\t\n\t\t}\n\t\t\n\tvoid submitScene (YourScene) {\n\t\tmLumEffect.viewId = 1; // A lum filter will take up 5 views\n\t\tmBloomEffect.viewId = 1 + mLumEffect.getViewIncrement();  // A bloom filter will take a number of views depending on how many blur passes you are doing\n\t\tmTonemappingEffect.viewId = mBloomEffect.viewId + mBloomEffect.getViewIncrement();\n\t\t\n\t\t...\n\t\t// Render your scene to a framebuffer (m_myFramebuffer)\n\t\t// You still have to implement your own forward or gbuffer here\n\t\t//bgfx::submit(0, m_myProgram)\n\t\t\n\t\t...\n\t\t// Apply Post Processing using the filters!\n\t\tmLumEffect.submit (bgfx::getTexture(m_myFramebuffer, 0));\n\t\t// Get the output of a effect as a texture that you can use in another effect!\n\t\tmBloomEffect.submit (mLumEffect.getOutputTexture(), bgfx::getTexture(m_myFramebuffer, 0)); \n\t\t// Configure the tonemapping filter to additively blend the bloom\n\t\tmBgfxhTonemappingEffect.setExtraComponent (0, mBgfxhBloomEffect.getOutputTexture(), 1.0f, 0.f);\n\t\t// Does the tonemapping. Renders to backbuffer by default\n\t\tmTonemappingEffect.submit (bgfx::getTexture(m_myFramebuffer, 0), mLumEffect.getOutputTexture()); \n\t\t\n\t\t// Debug render the lum filter's output to see if it is calculating sensible lum values\n\t\tconst int OUTPUT_PASS_ID = 200;\n\t\tbgfxh::initView2D (VIEW_ID_OUTPUT_PASS, \"output pass\", backbufferWidth, backbufferHeight, BGFX_INVALID_HANDLE, false, false);\n\t\tbgfxh::debugDrawFramebuffer (VIEW_ID_OUTPUT_PASS, mLumEffect.getOutputFramebuffer(), 10, 10, 120, 120, backbufferWidth, backbufferHeight);\n\t\t}\n\t\t\n\t\t\n\t}\n\n```\n\n## Speed Up Compile Times By Making A Seperate Compilation Unit?\n```c++\n//Wrapper.h\n#include \u003cbfgxh/bgfxh.h\u003e\n#include \u003cbfgxh/...\u003e\n#include \u003cbfgxh/...\u003e //etc\n```\n```c++\n//Wrapper.cpp\n#define BGFXH_IMPL\n#include \u003cbfgxh/bgfxh.h\u003e\n#include \u003cbfgxh/...\u003e\n#include \u003cbfgxh/...\u003e //etc\n```\n\n## Frustum Cull?\n```c++\n#define BGFXH_IMPL\n#include \u003cbfgxh/bgfxh.h\u003e\n\n...\n\nbgfxh::frustum mFrustum;\nmFrustum.setFromViewAndProjMatrix (viewMtx, projMtx);\n\nfor (each object in scene) {\n\tif (mFrustum.frustumCheck (object.positionVec3, object.radius)) continue; // Where radius is the radius of some bounding sphere for the object\n\t... Alternatively ....\n\tif (mFrustum.frustumCheck (object.bgfxModelMtx, object.radius)) continue;\n\t// Set uniforms, transform matricies, etc\n\tbgfx::setTransform (object.bgfxModelMtx);\n\tbgfx::submit();\n\t}\n\n\n```\n\n## Use the Built-In Shaders?\nSubmit using one of:\n`bgfxh::m_programUntexturedPassthrough` - Renders geometry without any texture or any fancy stuff. Handy for wireframe rendering\n`bgfxh::m_programTexturePassthrough` - Renders a texture. Handy for GUI stuff\n`bgfxh::m_programTexturePassthroughMonochromatic` - Renders a texture in greyscale. Handy for inspecting a framebuffer\n\t\n\nThanks\n======\nThanks To Branimir Karadzic and all others who have contributed to Bgfx!\n\nLicense\n=======\nPublic Domain\nVarious code snippets have been adapted from bgfx and are thus under the BSD license.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSnapperTT%2Fbgfx-header-extension-library","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSnapperTT%2Fbgfx-header-extension-library","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSnapperTT%2Fbgfx-header-extension-library/lists"}