A lock-free CommandBuffer implementation designed for multi-threaded rendering applications. Useful to reduce state switches(i.e. materials, shaders), depth sorting(for transparency or hardware early-z rejection) and also for dispatching commands from multiple threads.
- lock-free, designed for high-congestion
- graphics API agnostic(see cb::RenderContext)
- fast and configurable allocation via a linear allocator
- optional material binder with multiple material passes support
- chainable/appendable commands
- configurable key type for sorting of commands(opaque, transparent, depth sorting)
- easy to use and configurable draw key via bitfields
- debug utilities, tag commands
- basic GL commands implementation(see GLCommands.h)
- lightweight, header only
The implementation is header only, except GL commands, requires at least C++11 support.
Creating a command:
struct DrawArrays {
static const cb::RenderContext::function_t kDispatchFunction;
GLuint vao;
uint32_t base;
uint32_t count;
GLenum primitive;
};
//in cpp
void drawArrays(const void* data, cb::RenderContext*) {
auto& cmd = *reinterpret_cast<const DrawGroundCommand*>(data);
glBindVertexArray(cmd.vao);
glDrawArrays(cmd.primitive, cmd.base, cmd.count);
}
const cb::RenderContext::function_t DrawArrays::kDispatchFunction = &drawArrays;Dispatching a command:
//create the command key first
cb::DrawKey key(0);
key.setViewLayer(cb::ViewLayerType::e3D, cb::TranslucencyType::eOpaque);
key.setDepth(depth);
key.setMaterial(materialId);
//then create command which will dispatch it
cmds::DrawArrays& cmd = *commandBuffer.addCommand<cmds::DrawArrays>(key);
cmd.vao = vaoId;
cmd.base = 0;
cmd.count = 4;
cmd.primitive = GL_TRIANGLE_STRIP;Tagging a command for debug purposes, use CB_DEBUG_TAG_COMMANDS in config.h to enable/disable tagging:
void testFunction() {
cb::DrawKey key = cb::DrawKey::makeDefault(viewportId, cb::ViewLayerType::e3D);
cmds::DrawArrays& cmd = *commandBuffer.addCommand<cmds::DrawArrays>(key);
...
// will name tag: 'testFunction : <cpp_line_number> : struct cmds::DrawArrays * __ptr64'
CB_DEBUG_COMMAND_TAG(cmd);
// will name tag: 'testFunction : <cpp_line_number> : struct cmds::DrawArrays * __ptr64 : draw quad'
CB_DEBUG_COMMAND_TAG_MSG(cmd, "draw quad");
// will name tag: 'draw quad'
CB_DEBUG_COMMAND_SET_MSG(cmd, "draw quad");
}NOTE. Can enable/disable logging of the commands via CB_DEBUG_COMMANDS_PRINT in config.h which is enabled by default.
Appending/chaining commands(useful to reduce overhead of redundant material bindings):
cb::DrawKey key = cb::DrawKey::makeDefault(viewportId, cb::ViewLayerType::e3D);
//setup key
cmds::DrawArrays* cmd = commandBuffer.addCommand<cmds::DrawArrays>(key);
//fill command data
CB_DEBUG_COMMAND_SET_MSG(cmd, "draw first quad");
//append multiple draw calls
for(int i = 1; i < 10; ++i) {
cmd = commandBuffer.appendCommand<cmds::DrawArrays>(cmd);
//fill command data
CB_DEBUG_COMMAND_SET_MSG(cmd, FORMAT_STR("draw quad %d", i));
...Sometimes you may want to share/reference a command so you don't copy it's data multiple times:
//create the first the shared command
CommandPacket* headerPacket = buffer.createCommandPacketData<cmds:SetMatrixCommand>(matrices);
//reference/share the command
key = cb::DrawKey::makeDefault(viewportId, cb::ViewLayerType::e3D);
CommandPacket* cmd = buffer.addCommandFrom(key, headerPacket);
//append a new command to the shared one
cmds::DrawArrays* draw = buffer.appendCommand<cmds::DrawArrays>(cmd);
//fill command data
//reference it again
key = cb::DrawKey::makeDefault(otherViewportId, cb::ViewLayerType::e3D);
cmd = buffer.addCommandFrom(key, headerPacket);
draw = buffer.appendCommand<cmds::DrawArrays>(cmd);
//fill command data
...NOTE. Since matrices are PODs you can use data copy commands which will automatically allocate auxiliary memory and copy it.
Check the example folder which shows how to use the CommandBuffer in a real use case scenario with more advanced usage, it was done by adapting NVIDIA's Gameworks GL Threading example to a deferred renderer.
The implementation is mainly based on Stefan Reinalter's blog post at Molecular Matters, about a 'Stateless, layered, multi-threaded rendering' which I highly recommend reading.
References:
- Stateless, layered, multi-threaded rendering by Stefan Reinalter
- Order your graphics draw calls around! by Christer Ericson
Bug reports and pull requests are welcome on GitHub at https://github.com/tuxalin/CommandBuffer.
The code is available as open source under the terms of the MIT License.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent