Cross platform Zig OpenGL backend. RenderKit is an API abstraction (very similar to and inspired by Sokol) that wraps calls to OpenGL. It has its own GL function loader so no external loader is required though you can optionally pass in your own GL loader function (SDL_GL_GetProcAddress or glfwGetProcAddress for example).
RenderKit is just a pure OpenGL API abstraction layer. In order to get something on screen, it requires an OS window and a graphics context. The companion GameKit repository provides all of that and more. It has all the high-level abstractions needed to make fast, efficient 2D games. GameKit can be used as a standalone framework or as inspiration for using RenderKit in your own projects.
RenderKit has just one external dependency: SDL. You can install SDL with the package manager of your choice.
- clone the repository:
git clone https://github.com/prime31/zig-renderkit - in your projects build.zig, pass your
LibExeObjSteptoaddRenderKitToArtifactinRenderKit's build.zig
The RenderKit API uses descriptor structs for creating backend objects much like the Metal API or Sokol. Backend objects are passed back as handles to avoid any pointer management being exposed to game code.
General backend setup and management of graphics state.
pub fn setup(desc: RendererDesc, allocator: Allocator) void
pub fn shutdown() void
pub fn setRenderState(state: RenderState) void
pub fn viewport(x: c_int, y: c_int, width: c_int, height: c_int) void
pub fn scissor(x: c_int, y: c_int, width: c_int, height: c_int) void
Loading and updating of GPU textures.
pub fn createImage(desc: ImageDesc) Image
pub fn destroyImage(image: Image) void
pub fn updateImage(comptime T: type, image: Image, content: []const T) void
Offscreen passes (commonly refered to as render targets or framebuffers).
pub fn createPass(desc: PassDesc) Pass
pub fn destroyPass(pass: Pass) void
These are the methods you will use in your main render loop. beginPass renders to an offscreen pass and all offscreen rendering should be done first. Once all offscreen rendering is done drawing to the backbuffer is handled via beginDefaultPass. Each call to beginPass/beginDefaultPass should be followed by a matching call to endPass. Finally, when all rendering for the frame is done calling commitFrame flushes all the graphics commands.
pub fn beginDefaultPass(action: ClearCommand, width: c_int, height: c_int) void
pub fn beginPass(pass: Pass, action: ClearCommand) void
pub fn endPass() void
pub fn commitFrame() void
Creating and management of buffers (vertex and index).
pub fn createBuffer(comptime T: type, desc: BufferDesc(T)) Buffer
pub fn destroyBuffer(buffer: Buffer) void
pub fn updateBuffer(comptime T: type, buffer: Buffer, verts: []const T) void
pub fn appendBuffer(comptime T: type, buffer: Buffer, verts: []const T) u32
The only short lived player in the API. BufferBindings envelop what you want to render including an index buffer, 1 - 4 vertex buffers and the textures to bind.
pub fn applyBindings(bindings: BufferBindings) void
pub fn draw(base_element: c_int, element_count: c_int, instance_count: c_int) void
An important aspect to understand about RenderKit shaders is how the manage uniforms. When you create a shader you have to tell RenderKit what your vertex and fragment uniforms are.
pub fn createShaderProgram(comptime VertUniformT: type, comptime FragUniformT: type, desc: ShaderDesc) ShaderProgram
pub fn destroyShaderProgram(shader: ShaderProgram) void
pub fn useShaderProgram(shader: ShaderProgram) void
pub fn setShaderProgramUniformBlock(comptime UniformT: type, shader: ShaderProgram, stage: ShaderStage, value: *UniformT) void
It is recommended to use the ShaderCompileStep (docs here) and let RenderKit handle cross-compiling your shaders and generating your uniform structs. Note that only float uniforms are supported due to issues with ints between the different backends (future considerations). The shader compiler will handle getting alignment and paddings correct automatically. The shader compiler leverages Sokol Shader Compiler and takes GLSL in spitting out GLSL/SPIR-V/Metal shaders and a zig file with your uniform structs. A commented example of a struct generated by the ShaderCompileStep is below.
There are a few key points to understand with regard to the comptime metadata field. While you can handwrite these if you prefer, the compiler can also handle them for you. The metadata field contains a required uniforms field, that contains the uniforms for your shader. The shader compiler will pack all your uniforms into a single array of float4. This lets you update all of them in one single call.
The images field (currently only supports fragment shaders) specifies the names of all the images in your shader. RenderKit will automatically find the declarations and bind the correct slots for you.
pub const DissolveParams = extern struct {
// the comptime metadata used when creating a shader program to initialize the backend details
pub const metadata = .{
// an array of the images that should be setup
.images = .{ "main_tex", "dissolve_tex" },
// definition of each uniform along with its type/size. The shader compiler will always pack all data into
// a single array of float4. Only handwritten shaders would need multiple uniforms (one per struct field).
.uniforms = .{ .DissolveParams = .{ .type = .float4, .array_count = 2 } },
};
// the runtime fields, generated from the uniforms defined in the shader. Note that the `threshold_color` field
// is automatically aligned for you by the shader compiler.
progress: f32 = 0,
threshold: f32 = 0,
threshold_color: [4]f32 align(16) = [_]f32{0} ** 4,
};
Uses zgl for loading OpenGL functions