• Stars
    star
    1,592
  • Rank 29,380 (Top 0.6 %)
  • Language
    Rust
  • License
    MIT License
  • Created over 5 years ago
  • Updated almost 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

The write-once-run-anywhere GPGPU library for Rust

The old version of Emu (which used macros) is here.

Discord Chat crates.io docs.rs

Overview

Emu is a GPGPU library for Rust with a focus on portability, modularity, and performance.

It's a CUDA-esque compute-specific abstraction over WebGPU providing specific functionality to make WebGPU feel more like CUDA. Here's a quick run-down of highlight features...

  • Emu can run anywhere - Emu uses WebGPU to support DirectX, Metal, Vulkan (and also OpenGL and browser eventually) as compile targets. This allows Emu to run on pretty much any user interface including desktop, mobile, and browser. By moving heavy computations to the user's device, you can reduce system latency and improve privacy.

  • Emu makes compute easier - Emu makes WebGPU feel like CUDA. It does this by providing...

    • DeviceBox<T> as a wrapper for data that lives on the GPU (thereby ensuring type-safe data movement)
    • DevicePool as a no-config auto-managed pool of devices (similar to CUDA)
    • trait Cache - a no-setup-required LRU cache of JITed compute kernels.
  • Emu is transparent - Emu is a fully transparent abstraction. This means, at any point, you can decide to remove the abstraction and work directly with WebGPU constructs with zero overhead. For example, if you want to mix Emu with WebGPU-based graphics, you can do that with zero overhead. You can also swap out the JIT compiler artifact cache with your own cache, manage the device pool if you wish, and define your own compile-to-SPIR-V compiler that interops with Emu.

  • Emu is asynchronous - Emu is fully asynchronous. Most API calls will be non-blocking and can be synchronized by calls to DeviceBox::get when data is read back from device.

An example

Here's a quick example of Emu. You can find more in emu_core/examples and most recent documentation here.

First, we just import a bunch of stuff

use emu_glsl::*;
use emu_core::prelude::*;
use zerocopy::*;

We can define types of structures so that they can be safely serialized and deserialized to/from the GPU.

#[repr(C)]
#[derive(AsBytes, FromBytes, Copy, Clone, Default, Debug)]
struct Rectangle {
    x: u32,
    y: u32,
    w: i32,
    h: i32,
}

For this example, we make this entire function async but in reality you will only want small blocks of code to be async (like a bunch of asynchronous memory transfers and computation) and these blocks will be sent off to an executor to execute. You definitely don't want to do something like this where you are blocking (by doing an entire compilation step) in your async code.

fn main() -> Result<(), Box<dyn std::error::Error>> {
    futures::executor::block_on(assert_device_pool_initialized());

    // first, we move a bunch of rectangles to the GPU
    let mut x: DeviceBox<[Rectangle]> = vec![Default::default(); 128].as_device_boxed()?;
    
    // then we compile some GLSL code using the GlslCompile compiler and
    // the GlobalCache for caching compiler artifacts
    let c = compile::<String, GlslCompile, _, GlobalCache>(
        GlslBuilder::new()
            .set_entry_point_name("main")
            .add_param_mut()
            .set_code_with_glsl(
            r#"
#version 450
layout(local_size_x = 1) in; // our thread block size is 1, that is we only have 1 thread per block

struct Rectangle {
    uint x;
    uint y;
    int w;
    int h;
};

// make sure to use only a single set and keep all your n parameters in n storage buffers in bindings 0 to n-1
// you shouldn't use push constants or anything OTHER than storage buffers for passing stuff into the kernel
// just use buffers with one buffer per binding
layout(set = 0, binding = 0) buffer Rectangles {
    Rectangle[] rectangles;
}; // this is used as both input and output for convenience

Rectangle flip(Rectangle r) {
    r.x = r.x + r.w;
    r.y = r.y + r.h;
    r.w *= -1;
    r.h *= -1;
    return r;
}

// there should be only one entry point and it should be named "main"
// ultimately, Emu has to kind of restrict how you use GLSL because it is compute focused
void main() {
    uint index = gl_GlobalInvocationID.x; // this gives us the index in the x dimension of the thread space
    rectangles[index] = flip(rectangles[index]);
}
            "#,
        )
    )?.finish()?;
    
    // we spawn 128 threads (really 128 thread blocks)
    unsafe {
        spawn(128).launch(call!(c, &mut x));
    }

    // this is the Future we need to block on to get stuff to happen
    // everything else is non-blocking in the API (except stuff like compilation)
    println!("{:?}", futures::executor::block_on(x.get())?);

    Ok(())
}

And last but certainly not least, we use an executor to execute.

fn main() {
    futures::executor::block_on(do_some_stuff()).expect("failed to do stuff on GPU");
}

Built with Emu

Emu is relatively new but has already been used for GPU acceleration in a variety of projects.

  • Used in toil for GPU-accelerated linear algebra
  • Used in ipl3hasher for hash collision finding
  • Used in bigbang for simulating gravitational acceleration (used older version of Emu)

Getting started

The latest stable version is on Crates.io. To start using Emu, simply add the following line to your Cargo.toml.

[dependencies]
emu_core = "0.1.1"

To understand how to start using Emu, check out the docs. If you have any questions, please ask in the Discord.

Contributing

Feedback, discussion, PRs would all very much be appreciated. Some relatively high-priority, non-API-breaking things that have yet to be implemented are the following in rough order of priority.

  • Enusre that WebGPU polling is done correctly in `DeviceBox::get
  • Add support for WGLSL as input, use Naga for shader compilation
  • Add WASM support in Cargo.toml
  • Add benchmarks`
  • Reuse staging buffers between different DeviceBoxes
  • Maybe use uniforms for DeviceBox<T> when T is small (maybe)

If you are interested in any of these or anything else, please don't hesitate to open an issue on GitHub or discuss more on Discord.

More Repositories

1

pipelines

An experimental programming language for data flow
Nim
373
star
2

stdg

2D graphics in any programming language with just print statements
Rust
124
star
3

frequent

A utility for crawling websites and building frequency lists of words
Python
26
star
4

go-sm

A finite-state machine library for the Go programming language
Go
14
star
5

rep

enforce representation/class invariants in your Rust data structures
Rust
11
star
6

magic-square

A magic square data structure for the Python programming language
Python
8
star
7

go-fern

A small library for creating persistent L-systems in the Go programming language
Go
7
star
8

l

a very fast synthesizer of L-system grammars, solving a form of the "Inverse L-system" problem
Racket
6
star
9

margin

a Markov chain compiler for the DOT language
Python
5
star
10

digital-tower-defense-simulator

24-hour digital tower defense simulator/experiment made in p5
JavaScript
3
star
11

perceive

simple perceptron-based binary classification
Go
3
star
12

populate

tiny JS function for efficiently populating HTML lists - this was my first open-source-software-library-project thing!
JavaScript
3
star
13

fern

an automated synthesizer for programs that generate plant graphics
Racket
2
star
14

Artificial-Intelligence-And-Medicine

A website about AI and how it will shape the field of medicine.
HTML
2
star
15

wikipedia-traversal

A Python script for traversing Wikipedia pages
Python
2
star
16

lin

a higher-level DSL for linear programming
Racket
2
star
17

disjoint

A 40-line generic implementation of the disjoint set data structure in the Lua programming language
Lua
1
star
18

bag

A 40-line implementation of the bag data structure in the Lua programming language
Lua
1
star
19

quill

A high-level API for computing edit distance
Java
1
star
20

wayside

My submission for Ludum Dare 39 (A mobile-friendly platformer game made w. Phaser)
JavaScript
1
star