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)

# You describe a frame as passes on a graph. A pass with a render target draws
# into it. The triangle does not change, so build the graph one time and send
# the same graph every frame.
g = ctx.graph()
with g.add_pass(renderer, clear_color=[0.1, 0.2, 0.3, 1.0]) as p:
    p.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(g)

// 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: p.set_viewport(0, height, width, -height) inside a render pass 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. That is two passes, and two things happen here that you do not write:

• Bazalt compares what each pass reads with what the earlier passes wrote. It sees that the compute pass writes the image and the render pass reads it, so it puts the barrier and the layout change between them. It does this for the whole frame at one time, so an image that two passes use in a row keeps the right layout instead of changing back and forth.
• 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)

g = ctx.graph()
start = time.time()

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

    # The push constant changes every frame, so build the graph again. Use
    # reset() rather than a new graph: it keeps the GPU objects.
    g.reset()
    (g.add_pass(name="pattern")
        .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 g.add_pass(renderer, name="present") as p:
        p.bind_pipeline(present).bind_descriptor_set(read_set, present).draw(3)

    renderer.present(g)

// 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)

g = ctx.graph()
with g.add_pass(target, clear_color=[0.1, 0.2, 0.3, 1.0]) as p:
    p.bind_pipeline(pipeline).bind_vertex_buffer(vbuf).draw(3)
ctx.submit(g)

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)
    # ...build a graph and submit it...
    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. You describe a frame as passes on a graph. Bazalt compares what each pass reads with what the earlier passes wrote, then puts the barriers and the layout changes between them — for the whole frame at one time. 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. add_pass(auto_barriers=False) gives that job back to you through p.barrier(), for that pass alone.
• A pass is a handle, so a frame is editable. p.enabled = False drops one pass out of the frame and graph.remove(p) takes it out for good. Bazalt works out the barriers again for the passes that remain, so switching an effect off never leaves a stale barrier behind, and nothing is recorded a second time. This is what an effect chain you are still tuning wants, and it used to mean rebuilding the frame around an if.
• Compute beside graphics. One graph holds a compute pass and a render pass. A dispatch writes the vertices and the draw reads them. Results come back as NumPy arrays. Each pass names the queue it runs on: queue=bz.Queue.COMPUTE puts a pass on the compute queue, where it runs beside the graphics work. Bazalt puts the waits between the two queues for you, and it does that for the passes of one graph and for a graph you send again. Between two different graphs you say it with submit(after=...). The graphics queue stays the default, and the choice stays yours.
• 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.
• Data larger than a binding. A descriptor sees at most ctx.limits.max_storage_buffer of a buffer, which is 4 GB on most desktop drivers. buffer.address goes around it: the shader reads a pointer from a push constant, so the size the device can allocate becomes the only limit. ctx.limits reports the numbers behind decisions like this one, and a large upload is staged in pieces, so it costs GPU memory and not that much RAM as well.
• 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. Every submit hands back a Serial, so ctx.submit(g, wait=False, after=earlier) orders one submit behind another on the GPU while the CPU carries on.
• 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 p.timer() measure a frame or one part of a pass. p.label() and the pass name make 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. A manual pass with p.barrier(), submit(after=...) to order whole submits by hand, 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.