goldy 0.1.0

Python bindings for the Goldy GPU library

Goldy Python Bindings

Python bindings for the Goldy GPU library.

Installation

pip install goldy

Or build from source:

cd goldy-py
pip install maturin
maturin develop

Quick Start

import goldy
import numpy as np

# Create device
instance = goldy.Instance()
device = instance.create_device(goldy.DeviceType.DISCRETE_GPU)

# Create vertex buffer with a triangle
vertices = np.array([
    # x, y, r, g, b, a
     0.0, -0.5, 1.0, 0.0, 0.0, 1.0,  # red
    -0.5,  0.5, 0.0, 1.0, 0.0, 1.0,  # green
     0.5,  0.5, 0.0, 0.0, 1.0, 1.0,  # blue
], dtype=np.float32)
buffer = goldy.Buffer(device, vertices, goldy.BufferUsage.VERTEX)

# Create shader and pipeline
shader = goldy.ShaderModule.from_slang(device, goldy.Builtins.VERTEX_COLOR_2D)
pipeline = goldy.RenderPipeline(device, shader, shader, goldy.RenderPipelineDesc())

# Render
target = goldy.RenderTarget(device, 800, 600, goldy.TextureFormat.RGBA8_UNORM)
encoder = goldy.CommandEncoder()
with encoder.begin_render_pass() as rp:
    rp.clear(goldy.Color(0.1, 0.1, 0.2, 1.0))
    rp.set_pipeline(pipeline)
    rp.set_vertex_buffer(0, buffer)
    rp.draw(range(3))

target.render(encoder)
pixels = target.read_to_cpu()  # Returns numpy.ndarray with shape (600, 800, 4)

Examples

See the examples/ directory for complete examples:

• hello_triangle.py - Basic triangle rendering
• gradient.py - Custom shader with goldy_exp library
• adapter_info.py - Print GPU adapter information
• compute_demo.py - Compute shader placeholder

Run an example:

cd goldy-py
maturin develop
python examples/hello_triangle.py

Features

NumPy Integration

Buffers accept numpy arrays directly:

vertices = np.array([...], dtype=np.float32)
buffer = goldy.Buffer(device, vertices, goldy.BufferUsage.VERTEX)

Render targets return numpy arrays:

pixels = target.read_to_cpu()  # Shape: (height, width, 4), dtype: uint8

Context Managers

Pythonic API with with statements for render passes:

with encoder.begin_render_pass() as rp:
    rp.clear(goldy.Color.RED)
    rp.set_pipeline(pipeline)
    rp.draw(range(3))

Shader Libraries

Use the built-in goldy_exp library or register custom ones:

# Built-in library
shader = goldy.ShaderModule.from_slang(device, '''
    import goldy_exp;
    
    [shader("fragment")]
    float4 fs_main(FullscreenVarying input) : SV_Target {
        return float4(rainbow(input.uv.x), 1.0);
    }
''')

# Custom library
device.register_library('mylib', '''
    module mylib;
    public float3 my_color() { return float3(1.0, 0.5, 0.0); }
''')

API Reference

Core Classes

Class	Description
Instance	Entry point, enumerate adapters
Device	GPU device for creating resources
Buffer	GPU buffer for vertex/index/uniform data
ShaderModule	Compiled Slang shader
RenderPipeline	Complete render state
RenderTarget	Off-screen render target
CommandEncoder	Record render commands
RenderPass	Draw commands within a pass

Enums

Enum	Values
DeviceType	DISCRETE_GPU, INTEGRATED_GPU, CPU, OTHER
TextureFormat	RGBA8_UNORM, BGRA8_UNORM, RGBA16_FLOAT, ...
BufferUsage	VERTEX, INDEX, UNIFORM, STORAGE, ...
PrimitiveTopology	TRIANGLE_LIST, LINE_LIST, POINT_LIST, ...

Types

Type	Description
Color	RGBA color (float or byte)
VertexBufferLayout	Vertex format description
RenderPipelineDesc	Pipeline configuration
DepthStencilState	Depth testing configuration

Testing

cd goldy-py
maturin develop
pytest tests/ -v

Tests are organized into:

• test_types.py - Type wrapper tests (no GPU required)
• test_gpu.py - GPU integration tests (skipped if no GPU)

Requirements

• Python 3.9+
• NumPy 1.20+
• Vulkan 1.3+ compatible GPU

Publishing to PyPI

This package uses GitHub Actions with PyPI Trusted Publishers for automated releases.

Creating a release

1. Update version in pyproject.toml and python/goldy/__init__.py
2. Commit and push changes
3. Create a git tag matching the version:

   git tag v0.1.1dev0
   git push origin v0.1.1dev0
   

4. create a release: gh release create v0.1.1dev0 --title "v0.1.1dev0" --notes "..."
5. The publish workflow will automatically build wheels and upload to PyPI

Manual testing (TestPyPI)

For testing before a real release, you can configure a separate Trusted Publisher for TestPyPI at https://test.pypi.org/manage/account/publishing/ and modify the workflow to publish there first.

License

MIT License