Bazalt

Bazalt is a Python library for the Vulkan API. Use it to prototype GPU and shader work, and to build graphical applications. A C++23 core does the Vulkan work. The Python layer keeps the setup code short.

pip install bazalt

Bazalt supplies wheels for Windows, Linux and macOS, for CPython 3.10 to 3.14. You need a driver with Vulkan 1.2.

On macOS you must also install the Vulkan SDK. The system supplies no Vulkan loader, and the SDK gives you the loader and MoltenVK, which runs Vulkan on Metal. The macOS wheels are for Apple Silicon and need macOS 14 or later.

To build from source, you need a C++23 compiler (GCC 14+, or MSVC 19.36+ from Visual Studio 17.6) and the Vulkan SDK. On macOS, use the newest Xcode you have: bazalt uses C++23 features that Apple Clang received late.

A triangle

Three files: the program, a vertex shader and a fragment shader. Put them in one directory and run the program.

import bazalt as bz

window = bz.Window(1024, 720, "Bazalt - triangle")
ctx = bz.Context()
renderer = ctx.create_renderer(window)

# A pipeline is built against a render target, which supplies the formats.
# The window is one target. An offscreen image is another. Same call.
pipeline = (ctx.graphics_pipeline()
    .vertex_shader(ctx.compile_shader("triangle.vert", bz.ShaderStage.VERTEX))
    .fragment_shader(ctx.compile_shader("triangle.frag", bz.ShaderStage.FRAGMENT))
    .vertex_format([bz.VertexFormat.FLOAT3, bz.VertexFormat.FLOAT3])  # position + colour
    .build(renderer))

# Interleaved position (x, y, z) and colour (r, g, b). Vulkan clip space runs
# from -1 to 1, and y points down.
vbuf = ctx.create_buffer([
     0.0, -0.5, 0.0,   1.0, 0.0, 0.0,
    -0.5,  0.5, 0.0,   0.0, 1.0, 0.0,
     0.5,  0.5, 0.0,   0.0, 0.0, 1.0,
], bz.BufferType.VERTEX, bz.MemoryUsage.STATIC, bz.DataType.FLOAT)

# The triangle does not change, so record the commands one time and send the
# same recording every frame.
cmd = ctx.create_command_buffer()
cmd.begin()
with cmd.rendering(renderer, clear_color=[0.1, 0.2, 0.3, 1.0]) as c:
    c.bind_pipeline(pipeline).bind_vertex_buffer(vbuf).draw(3)

while window.is_open():
    bz.poll_events()
    ctx.begin_frame()          # opens one frame for every window on this Context
    if renderer.acquire():     # False when this window sits the frame out
        renderer.present(cmd)

// triangle.vert
#version 450
layout(location = 0) in vec3 inPosition;
layout(location = 1) in vec3 inColor;
layout(location = 0) out vec3 fragColor;

void main() {
    gl_Position = vec4(inPosition, 1.0);
    fragColor = inColor;
}

// triangle.frag
#version 450
layout(location = 0) in vec3 fragColor;
layout(location = 0) out vec4 outColor;

void main() {
    outColor = vec4(fragColor, 1.0);
}

Vulkan clip space, and the one line every 3D program writes

Vulkan puts the origin of a framebuffer in the top left corner, and +y in clip space points down. That agrees with the memory: row 0 of an image is the top row, texture coordinates start at the first texel, set_scissor and copy_image measure from the same corner, and a display scans the same way. OpenGL puts the origin at the bottom left, which is why OpenGL code flips images so often.

A projection matrix from GLM or pyrr therefore disagrees with Vulkan twice, because those build the OpenGL matrix. glm.perspective puts depth in -1 to 1, where Vulkan wants 0 to 1, and it points +y up. Correct both:

# perspectiveRH_ZO, not perspective: the ZO is the 0-to-1 depth range Vulkan uses.
proj = glm.perspectiveRH_ZO(glm.radians(60.0), width / height, 0.1, 100.0)
proj[1][1] *= -1        # GLM builds a y-up matrix; Vulkan clip space is y-down

Every example in examples/ does exactly this. Both lines belong to the matrix, not to bazalt: a projection written for Vulkan carries the range and the sign already, and needs neither.

That is why bazalt has no y_up switch. A flipped viewport reverses the triangle winding, so CullMode and FrontFace would mean opposite things depending on a keyword argument, and the rasterizer would point up while image.read(), copy_image and set_scissor still measure from the top left. If you want a flipped viewport anyway, nothing stops you: cmd.set_viewport(0, height, width, -height) inside the rendering scope overrides the one bazalt emits.

Compute writes an image, and you edit it while it runs

A compute shader fills an image texel by texel. A fullscreen triangle then samples that image. Two things happen here that you do not write:

• Bazalt sees that the dispatch writes the image and the draw reads it. It records the barrier and the layout change between them.
• hot_reload=True watches every file bazalt loaded. Edit pattern.comp with the window open and the picture changes. A typo logs a ShaderError and the last good version stays on screen.

import struct
import time

import bazalt as bz

W = H = 512

window = bz.Window(W, H, "Bazalt - compute")
ctx = bz.Context(hot_reload=True)
renderer = ctx.create_renderer(window)

# Compute: no vertices and no fragment shader. One dispatch per frame.
generate = (ctx.compute_pipeline()
    .shader(ctx.compile_shader("pattern.comp", bz.ShaderStage.COMPUTE))
    .storage_image(0)
    .push_constant(4)          # 4 bytes, one float: the time
    .build())                  # no target, because compute has no attachments

# Graphics: a fullscreen triangle that samples the result.
present = (ctx.graphics_pipeline()
    .vertex_shader(ctx.compile_shader("fullscreen.vert", bz.ShaderStage.VERTEX))
    .fragment_shader(ctx.compile_shader("present.frag", bz.ShaderStage.FRAGMENT))
    .texture(0, bz.ShaderStage.FRAGMENT)
    .build(renderer))

# One image, bound two ways: written as a storage image, read as a texture.
image = ctx.create_image(W, H, bz.Format.RGBA8)

pool = ctx.create_descriptor_pool()   # no sizes: it grows from the layouts it serves
write_set = pool.allocate_set(generate)
write_set.set_storage_image(0, image)
read_set = pool.allocate_set(present)
read_set.set_image(0, image)

cmd = ctx.create_command_buffer()
start = time.time()

while window.is_open():
    bz.poll_events()
    ctx.begin_frame()          # bazalt applies the file edits here
    if not renderer.acquire():
        continue

    cmd.begin()
    (cmd.bind_pipeline(generate)
        .bind_descriptor_set(write_set, generate)
        .push_constants(generate, 0, struct.pack("<f", time.time() - start))
        .dispatch((W + 7) // 8, (H + 7) // 8))
    with cmd.rendering(renderer) as c:
        c.bind_pipeline(present).bind_descriptor_set(read_set, present).draw(3)

    renderer.present(cmd)

// pattern.comp
#version 450
layout(local_size_x = 8, local_size_y = 8) in;
layout(set = 0, binding = 0, rgba8) uniform writeonly image2D img;
layout(push_constant) uniform Push { float time; } pc;

void main() {
    ivec2 p = ivec2(gl_GlobalInvocationID.xy);
    ivec2 sz = imageSize(img);
    if (p.x >= sz.x || p.y >= sz.y) return;

    vec2 uv = vec2(p) / vec2(sz);
    float v = 0.5 + 0.5 * sin(uv.x * 12.0 + pc.time) * cos(uv.y * 12.0 - pc.time * 0.7);
    imageStore(img, p, vec4(v, uv.x, uv.y, 1.0));
}

// fullscreen.vert — a triangle from gl_VertexIndex, with no vertex buffer
#version 450
layout(location = 0) out vec2 uv;

void main() {
    uv = vec2(gl_VertexIndex & 2, (gl_VertexIndex << 1) & 2);
    gl_Position = vec4(uv * 2.0 - 1.0, 0.0, 1.0);
}

// present.frag
#version 450
layout(location = 0) in vec2 uv;
layout(location = 0) out vec4 outColor;
layout(set = 0, binding = 0) uniform sampler2D tex;

void main() {
    outColor = texture(tex, uv);
}

The same code, with no window

A render target is an offscreen image with the same interface as the window. Both come from the Context, and everything else in this file works the same against either. Build the pipeline against it, submit, and read the pixels into NumPy. This runs in a test and in CI, where no display exists:

ctx = bz.Context()
target = ctx.create_render_target(800, 600, depth=bz.Format.D32F)

pipeline = ...   # the triangle pipeline above, built with .build(target)

cmd = ctx.create_command_buffer()
cmd.begin()
with cmd.rendering(target, clear_color=[0.1, 0.2, 0.3, 1.0]) as c:
    c.bind_pipeline(pipeline).bind_vertex_buffer(vbuf).draw(3)
ctx.submit(cmd)

pixels = target.color[0].read()      # numpy (600, 800, 4) uint8

In a notebook, and on a machine with no display

The code above is the whole notebook story: render offscreen, read the pixels, show them with the library you already use. A remote kernel on a university server works the same way, because bazalt starts the window system only when you ask for a Window.

Use with. Without it, a re-run cell leaves the previous Context's upload worker and hot-reload watcher running until the garbage collector reaches them, so a shared machine collects one set of threads per run:

import bazalt as bz
from PIL import Image

with bz.Context() as ctx:
    target = ctx.create_render_target(512, 512)
    # ...record and submit...
    pixels = target.color[0].read()

Image.fromarray(pixels)              # the cell shows it

Read the pixels inside the block. A Context that is closed starts no new work, and target.color[0].read() after the block raises StateError rather than a black image.

For anything interactive, build the Context once. A device costs tens of milliseconds, so a slider that calls the function above per event queues work faster than it finishes and the notebook stops responding. Build the Context, the pipeline and the target once, and let a redraw be a record, a submit and a read — a few milliseconds. That Context outlives the cell, which is what ctx.close() is for.

examples/33_notebook/notebook.ipynb shows both shapes, plus a compute cell that uses the GPU as a calculator.

What you get

• Vulkan, and not an engine. You keep the pipelines, the command buffers and the memory. Bazalt removes the setup code and the object lifetimes.
• Barriers on their own. Bazalt tracks the hazards while you record, then inserts the barriers and the layout changes. It reads the SPIR-V to find out which resources a shader writes, so a storage image written by a fragment shader is ordered for you. Context(auto_barriers=False) gives that job back to you through cmd.barrier().
• Compute beside graphics. One command buffer holds a dispatch and a draw. A dispatch writes the vertices and the draw reads them. Results come back as NumPy arrays.
• Images in every shape. 2D textures, texture arrays, cubemaps and 3D volumes come from one function: create_image(w, h, cube=True) or create_image(w, h, depth=n). A volume is a sampler3D in the shader — colour-grading LUTs, volumetric noise, raymarched clouds — and a NumPy array of the matching shape uploads straight into any of them.
• Every pipeline stage. Vertex, fragment and compute, plus tessellation for displacement and adaptive detail, and geometry for a primitive that becomes a different one. A dispatch or a draw can also read its own arguments from a buffer the GPU filled, so the count never travels back to the CPU.
• One rule for what blocks. Every write is asynchronous and every read blocks. A handle is its own future, so normal code waits nowhere. buf.read() blocks, because it has nothing to give you until the bytes arrive.
• Hot reload. Bazalt watches the shaders you loaded, their #include files and your images, then applies the edits in place. A mistake does not stop the application.
• Headless, and notebook-ready. Draw into an offscreen target and read the pixels as a NumPy array — no window and no display, so a Jupyter kernel on a remote server works. with bz.Context() as ctx: releases the device's worker threads when the block ends, instead of when the garbage collector notices.
• The window, and what arrives through it. Keys, the mouse and the scroll wheel, plus the characters the user typed through window.text_input(), files dropped on the window, the clipboard through bz.get_clipboard() and bz.set_clipboard(), an icon through window.set_icon(), and the pointer through window.set_cursor() and window.set_cursor_position(). A gamepad reports both the level and the edge. bz.list_monitors() says which displays exist, so a fullscreen window can name one. bz.poll_events() pumps a program that animates; bz.wait_events() sleeps until something happens, for one that does not.
• Tools for a picture that looks wrong. The validation layers report through a Python logger. Context(shader_printf=True) sends debugPrintfEXT() from a shader to that logger. Context(gpu_timing=True) and cmd.timer() measure a frame or one slice of a recording. cmd.label() makes a RenderDoc capture readable. A compiled shader also tells you what bazalt read out of it: shader.writes, shader.writes_unknown and shader.prints.
• Wide reach. Vulkan 1.2 is the baseline and bazalt uses 1.3 where the driver has it. You ask for a capability by what it does, never by a version or an extension name.
• No ceiling. cmd.barrier(), raw_extensions and the Vulkan handles stay open for the work bazalt does not cover.

Design rules

Four rules decide what goes into the API. DESIGN.md holds them with their reasons.

• One obvious way to do one thing. A resource that differs by one parameter is a keyword argument, not a new function.
• Never cap the ceiling. Each layer keeps an escape hatch to the Vulkan below it.
• It must run on more than 90% of machines.
• Prototyping comes first. A feature that makes pictures ranks before plumbing.

Examples

Every directory in examples/ runs on its own.

CHANGELOG.md lists what each release added. DESIGN.md gives the reasons behind the API.

License

MIT. See LICENSE.txt.