bgfx

Not sure into which category falls this blog entry, maybe review? I never did any 3D programming, so tutorial is out of question. Anyway I was fiddling with bgfx library and here are my experiences.
According to author, Branimir Karadzic, bgfx is cross-platform, graphics API agnostic, "Bring Your Own Engine/Framework" style rendering library. Since it works on Linux I was interested to take a look at it. Best way to get info on project is to visit https://github.com/bkaradzic/bgfx and read README.md. If you are curious to try it you will need also https://github.com/bkaradzic/bx to build it. Library uses custom tool GENie so that is reason why bx is needed, we will need it for projects as well. I have built it and attempted running examples. Some were working, some not. I was attempting to run them from directory where compiled assemblies are but they need runtime. So to run examples go to /examples/runtime and execute ../../.build/linux64_gcc/bin/example-00-helloworldDebug.
How to generate project make files or codeblocks or codelite projects. Since this is cross-platform tool Windows and Mac OS X targets are supported but I will focus on Linux only. Go to bgfx project root and run

../bx/tools/bin/linux/genie --help

To generate make files, do

../bx/tools/bin/linux/genie --gcc=linux-gcc --with-tools gmake

That will produce examples as targets plus tools, like shaderc. Now cd to .build/projects/gmake-linux and execute make help to see options. For 64 bit Linux we may build using this command:

make config=debug64 example-XY-name/nothing for all

If we are using IDE, we go to .build/projects/codeblocks or codelite, open generated project set target and build it. Now we are ready to start fiddling with provided examples.
For somebody who never did any 3D coding, like me, examples provided with bgfx are too complicated so I dumbed them down.

#include "common.h" #include <bgfx.h> int _main_(int /*_argc*/, char** /*_argv*/) { uint32_t width = 1280; uint32_t height = 720; uint32_t debug = BGFX_DEBUG_NONE; uint32_t reset = BGFX_RESET_VSYNC; bgfx::init(); bgfx::setDebug(debug); bgfx::setViewClear(0 , BGFX_CLEAR_COLOR|BGFX_CLEAR_DEPTH , 0x0000ffff , 1.0f , 0 ); while (!entry::processEvents(width, height, debug, reset) ) { bgfx::setViewRect(0, 0, 0, width, height); bgfx::submit(0); bgfx::frame(); } bgfx::shutdown(); return 0; }

This is example-00-helloworld reduced to creating and showing blue window. There is huge amount of plumbing code which makes those examples work in very few lines of code. For example entry::processEvents. In original shape example will print some text and place image on the screen.
Next to be slaughtered is cubes example. It draws now single triangle:

#include "common.h" #include "bgfx_utils.h" #include <stdlib.h> struct PosColorVertex { float m_x; float m_y; float m_z; uint32_t m_abgr; static void init() { ms_decl .begin() .add(bgfx::Attrib::Position, 3, bgfx::AttribType::Float) .add(bgfx::Attrib::Color0, 4, bgfx::AttribType::Uint8, true) .end(); }; static bgfx::VertexDecl ms_decl; }; bgfx::VertexDecl PosColorVertex::ms_decl; static PosColorVertex s_triangleVertices[3] = { { 0.0f, 1.0f, 0.0f, 0xff0000ff }, {-1.0f, -1.0f, 0.0f, 0xffff0000 }, { 1.0f, -1.0f, 0.0f, 0xffff00ff }, }; static const uint16_t s_triangleIndices[3] = { 0, 1, 2 }; float * view; float * proj; int _main_(int /*_argc*/, char** /*_argv*/) { uint32_t width = 1280; uint32_t height = 720; uint32_t debug = BGFX_DEBUG_TEXT; uint32_t reset = BGFX_RESET_VSYNC; bgfx::init(); bgfx::reset(width, height, reset); // Enable debug text. bgfx::setDebug(debug); // Set view 0 clear state. bgfx::setViewClear(0 , BGFX_CLEAR_COLOR|BGFX_CLEAR_DEPTH , 0x303030ff , 1.0f , 0 ); // Create vertex stream declaration. PosColorVertex::init(); // Create static vertex buffer. bgfx::VertexBufferHandle vbh = bgfx::createVertexBuffer( // Static data can be passed with bgfx::makeRef bgfx::makeRef(s_triangleVertices, sizeof(s_triangleVertices) ) , PosColorVertex::ms_decl ); // Create static index buffer. bgfx::IndexBufferHandle ibh = bgfx::createIndexBuffer( // Static data can be passed with bgfx::makeRef bgfx::makeRef(s_triangleIndices, sizeof(s_triangleIndices) ) ); // Create program from shaders. bgfx::ProgramHandle program = loadProgram("vs_cubes", "fs_cubes"); view = (float*)calloc(16,sizeof(float)); view[0] = view[5] = view[10] = view[15] = 1; proj = (float*)calloc(16,sizeof(float)); proj[0] = proj[5] = 0.9; proj[15] = 1; while (!entry::processEvents(width, height, debug, reset) ) { // Use debug font to print information about this example. bgfx::dbgTextClear(); bgfx::dbgTextPrintf(0, 1, 0x4f, "bgfx/examples/01-cube"); bgfx::dbgTextPrintf(0, 2, 0x6f, "Description: Rendering simple static mesh."); bgfx::setViewTransform(0, view, proj); const bgfx::HMD* hmd = bgfx::getHMD(); if (NULL != hmd) { bgfx::setViewRect(0, 0, 0, hmd->width, hmd->height); } else { bgfx::setViewRect(0, 0, 0, width, height); } // Set vertex and fragment shaders. bgfx::setProgram(program); // Set vertex and index buffer. bgfx::setVertexBuffer(vbh); bgfx::setIndexBuffer(ibh); // Set render states. bgfx::setState(BGFX_STATE_DEFAULT); // Submit primitive for rendering to view 0. bgfx::submit(0); // Advance to next frame. Rendering thread will be kicked to // process submitted rendering primitives. bgfx::frame(); } // Cleanup. bgfx::destroyIndexBuffer(ibh); bgfx::destroyVertexBuffer(vbh); bgfx::destroyProgram(program); free(proj); free(view); // Shutdown bgfx. bgfx::shutdown(); return 0; }

Naturally I didn't touch shaders. If we remove completely shaders from code, instances of program, triangle will become black, new achievements of hacking. I also did square, here is the relevant code:

static PosColorVertex s_triangleVertices[4] = { {-1.0f, 1.0f, 0.0f, 0xff0000ff }, {-1.0f, -1.0f, 0.0f, 0xffff0000 }, { 1.0f, -1.0f, 0.0f, 0xffff00ff }, { 1.0f, 1.0f, 0.0f, 0xffff00ff }, }; static const uint16_t s_triangleIndices[6] = { 0, 1, 2, 0, 2, 3 };

Everything else is the same as for triangle. I hope my experience helps somebody to get started. After I spent eternity in programming there are still areas completely unknown to me. If I didn't get friendly suggestion to use identity as view and orthogonal matrix as projection I would stay on Hello World/blue window.