Introducing the Cobalt Renderer

The Cobalt Renderer is a generic, cross-platform graphics library. Cobalt aims to make using modern 3D graphics hardware simple. It does this by giving you a clean API to express what you want to draw (or compute), without getting bogged down in how to do that. Cobalt is designed to be an accessible, lightweight alternative to directly using low-level graphics APIs such as Vulkan, Direct3D and OpenGL. You can check out the project on GitHub, download the SDK, and read the docs.

Why not use a graphics API directly?

Any game or application that wants to be cross-platform cannot rely on a single graphics API. They must use multiple APIs, which each have their own pitfalls.

OpenGL is the most simple and universal API but is also the most problematic today. It is effectively deprecated and doesn’t support any new features modern graphics hardware introduces. Drivers are complicated and the API spec can be ambiguous, leading to bugs and performance challenges. It’s single-threaded, CPU-heavy and focused around a global state machine. OpenGL is not suitable for high-performance, modern applications and games.

No other API is universally adopted on all platforms. Direct3D is exclusive to Windows. Vulkan is close, but isn’t supported on macOS officially. macOS only supports Metal. Translation layers like MoltenVK are available but can introduce their own overhead and bugs.

Modern graphics APIs like Vulkan, Direct3D 12 and Metal are also extremely complicated. They expose many details about the underlying graphics hardware, allowing (and forcing) the programmer to deal with their nuances. As a result, the classic “Hello Triangle” is over 700 lines long for Vulkan.¹ This complexity is fine (even desirable) for game engine and library authors, but a hassle for game or application authors. It’s not productive to use these directly, unlike OpenGL and previous versions of Direct3D.

With this mess of low-level graphics APIs, it’s no wonder developers gravitate to using game engines, high-level drawing libraries or just OpenGL. Low-level graphics already has enough theory to learn and needing to learn a verbose API as well is a tough ask for beginners.

It’s a shame because computer graphics can be extremely rewarding. Few other areas in software provide direct visual feedback. Your code sculpts virtual worlds, shaders create mesmerising effects, and frame rates measure your efficiency. Graphics hardware is astoundingly powerful and using a low-level API lets you drive it to its fullest potential.

The Cobalt Renderer

Our goal with the Cobalt Renderer is to provide a straightforward, cross-platform solution to the low-level graphics API space. It’s focused entirely on rendering and makes an excellent, platform-independent layer to build games, applications, libraries and engines from. Cobalt is analogous to the OpenGL API in that it’s simple and productive. But unlike OpenGL, Cobalt is focused around what you want to draw instead of how. In OpenGL, you manipulate a global state machine and specify the commands and state changes to draw a scene. In Cobalt, you build a render tree that describes the frame to draw.

The Cobalt Renderer doesn’t hide basic graphics concepts, but unifies the commonalities across APIs. After all, graphics APIs all drive the same hardware and just expose the same concepts in different ways. Familiar primitives like shaders, vertex buffers, textures, frame buffers, draw calls, etc, are all represented in the Cobalt API. The renderer manages the more finicky details around memory types, allocators, descriptors, queues, barriers, transfers, etc. This makes Cobalt an approachable library for beginners to learn computer graphics and apply their gained knowledge to other low-level APIs.

Other major features include:

• Multithreading support. The render tree can be modified safely by multiple threads while the frame is being rendered. All rendering is orchestrated on a separate thread and only a brief global renderer lock is required at the start of each frame
• A common interface, backed by plugins for different underlying graphics APIs. These plugins can be dynamically loaded or statically linked
• Native C++ API, including a complete set of C bindings, allowing any language with C ABI support (e.g. Rust, C#, even Python) to use the renderer
• Support for multiple shader languages, such as HLSL, GLSL and SPIR-V. Shaders are cross-compiled under the hood as needed for different backend graphics APIs
• Cross-platform (Windows, Linux, macOS), backed by an extensive test suite we’ve verified on a range of hardware, new and old, from different vendors

Example: Creating a Texture

To give you a taste of the library, let’s compare creating a 2D texture and filling it with some image data with Cobalt and OpenGL. I won’t include Vulkan here because the snippet would be too long.

// Cobalt
ITextureBuffer2D::unique_ptr texture = renderer->CreateTextureBuffer2D();
texture->SetTextureDimensions(V2UInt32(2048, 2048));
texture->SetTextureFormat(
    ITextureBuffer::ImageFormat::RGBA, 
    ITextureBuffer::DataFormat::UNorm8
);
texture->SetUsageFlags(ITextureBuffer::UsageFlags::ShaderInput);
texture->SetPerformanceHints(
    ITextureBuffer::PerformanceHint::WriteRarely | 
    ITextureBuffer::PerformanceHint::ReadNever, 
    ITextureBuffer::PerformanceHint::WriteNever | 
    ITextureBuffer::PerformanceHint::ReadOften
);
assert(texture->SetInitialData(image.data(), image.size()));
assert(texture->AllocateMemory());

// OpenGL
unsigned int texture;
glGenTextures(1, &texture);
glBindTexture(GL_TEXTURE_2D, texture); 
glTexImage2D(
    GL_TEXTURE_2D, 
    0,
    GL_RGBA8, 
    2048,
    2048, 
    0,
    GL_RGBA, 
    GL_UNSIGNED_BYTE, 
    image.data()
);

OpenGL and Cobalt are clear and easy, but Cobalt has some significant advantages, even in this small example.

• We could indicate how we plan to use the texture, both on the CPU and GPU, so Cobalt can maximize performance for our use case
• Cobalt is multithreaded by design, and we could be actively rendering a frame and creating resources on other threads without issue

Development and Open Source Release

We started building the Cobalt Renderer at Maptek in 2018 and have been using it for commercial products for many years. My intern project was to write the initial Vulkan renderer backend, with subsequent years using Cobalt for a number of applications.

Many developers have contributed to making the Cobalt Renderer, but props must go to Roger Sanders for spearheading the project, designing the API and for much of the implementation. After many years of extensive use internally at Maptek, we’re thrilled to open source this work.

Future

As of the time of writing, the Cobalt Renderer is version 2.0.0 and we have ambitions for a number of projects, including:

• New features, such as mesh shaders and video frame capture (like H.264)
• A Metal API renderer plugin
• Official Rust bindings, hopefully coming very soon
• A tutorial series, in the same flavour as the brilliant Learn OpenGL

If the Cobalt Renderer sounds interesting to you, check out the project on GitHub, download the SDK and read the docs for more information. You can also find us on Discord if you’d like to chat or get support.

Happy programming!

Footnotes: