v0.2.0 API changes and ndarray integration 🎉

New gpgpu release! This revision includes, among other things, improvements of the API and the new integration with the ndarray crate.

✨New features

🚩 integrate-ndarray feature for integration with ndarray crate

Integration with ndarray its been added with #3. I'm no expert using this crate so any comments are welcome!

• Upload ndarray arrays to the GPU using GpuArray objects. They save the dimensions of the array previous upload to the GPU.
• Take a look at the ndarray example. It has some comments about its usage and problems.

⚡ Major changes

👩‍💻 API changes

This changes are focused on improve the usability of gpgpu, making more clear the asynchronous intent. The most important changes are:

• Background polling: Polling functions cannot be used from gpgpu (can be used from wgpu). They are invoked every 10ms by default.
• Read functions: All read function of GpuBuffer and friends have both async and blocking methods:
  • read() and read_blocking(): Now it needs into an user provided buffer (#8).
  • read_vec() and read_vec_blocking(): Reads into a non-user allocated vector (ol' way).
• Write functions: All writes are instantly offloaded, this meaning that writes (updates to GPU) are non-blocking, but it progress cannot be checked.
• More clear interaction with wgpu: gpgpu GPU objects can now be created from wgpu ones using from_gpu_parts() and converted back using into_gpu_parts (#5).
• Kernel creation is simplified. It now has to be created from a Program which contains information about the shader, entry point and bindings (#4).
• Error handling it's been updated. Every GPU object has its own kind of error (#6).

🛠 General changes

• Added CI that checks code format, build status on some platforms and documentation errors. Right now it does not run any example or test (#7).
• Docs.rs documentation pulls examples into the usage of some of the functions.
• Selection of backend via environment variables is done using Framework::default().
• Updated wgpu to 0.12.

Full Changelog: v0.1.0...v0.2.0

v0.1.0 - gpgpu MVP 🎉

gpgpu is a GPGPU compute framework built on top of wgpu compute pipeline. It tries to be simple to use whilst being easy to integrate with wgpu.

✨ Features

🔖 GPU Compute made simple

gpgpu exposes some GPU objects with clearly defined methods for read and write data from / to the GPU. Some of these objects are:

• GpuBuffer: Homogeneous read-write (in shaders) buffer on the GPU.
• GpuUniformBuffer: Homogeneous read-only (in shaders) buffer on the GPU. Perfect for small, readonly data.
• GpuConstImage and GpuImage: 2D homogeneous image on the GPU. The former is read-only, while the latter is write-only (in shaders).

gpgpu also exposes DescriptorSet and Kernel objects to make easier the management and reuse of binding groups and executions of shaders.

🚩 integrate-image feature for integration with image crate

• Compile-time type conversion safety from/to image::ImageBuffer to/from gpgpu::GpuImage and gpgpu::GpuConsyImageobjects
  • Supported pixel types:
    • RGBA8 Uint
    • RGBA8 Uint Norm
    • RGBA8 Sint
    • RGBA8 Sint Norm
  • Bidirectional conversions between image::ImageBuffer and gpgpu::GpuImage or gpgpu::GpuConsyImage
    • Sync and async read
    • Sync and async writes

⛰ Enviroment backend selection

Using the env variable WGPU_BACKEND, the gpgpu-rs backend can be selected. Available options are:

• Vulkan: "vulkan" or "vk"
• DX12: "dx12" or "d3d12"
• DX11: "dx11" or "d3d11"
• Metal: "metal" or "mtl"
• OpenGL ES: "opengl", "gles" or "gl"
• WebGPU: "webgpu"
  Any comma separeted combiantion of any of the previous options is valid. ex. WGPU_BACKEND='vk,gl'

🆘 Help wanted

• For an efficient implementation of the conversion between image and gpgpu types, some unsafe code was required. A review of this fragment is very much appreciated 😄 (in src/features/integrate_image.rs 👀).
• I'm running out of ideas. The initial goal of this project was to allow me develop a GPU-based image processing library (imageproc_gpu). Since I think gpgpu is enough for that (but still very lacking), I'll continue with that project, adding whatever I need for GPGPU computing back at gpgpu. Any other idea is appreciated.

Full Changelog: v0.0.0-alpha.2...v0.1.0

v0.0.0-alpha.2: Image crate integration 🖼

This new release includes the capability to convert image::ImageBuffer from the image crate to gpgpu::GpuImage objects and vice versa.

✨ New features

🚩 integration-image feature flag

• Compile-time type conversion safety from/to image::ImageBuffer to/from gpgpu::GpuImage objects
  • Supported pixel types:
    • RGBA8 Uint
    • RGBA8 Uint Norm
    • RGBA8 Sint
    • RGBA8 Sint Norm
  • Bidirectional conversions between image::ImageBuffer and gpgpu::GpuImage
    • Sync and async read
    • Sync and async writes

⛰ Enviroment backend selection

Using the env variable WGPU_BACKEND, the gpgpu-rs backend can be selected. Available options are:

• Vulkan: "vulkan" or "vk"
• DX12: "dx12" or "d3d12"
• DX11: "dx11" or "d3d11"
• Metal: "metal" or "mtl"
• OpenGL ES: "opengl", "gles" or "gl"
• WebGPU: "webgpu"
  Any comma separeted combiantion of any of the previous options is valid. ex. WGPU_BACKEND='vk,gl'

📕 Vagrant box

For the development of gpgpu-rs a headless Vagrant box was created. It runs under Ubuntu 21.04. Only the OpenGL ES backend can be used.

For a complete list of the changes since the last release: v0.0.0-alpha.1...v0.0.0-alpha.2

🕹 Usage

Since this version still not published in Crates.io, add it to your Cargo.toml as follows:

[dependencies]
gpgpu = { git = "https://github.com/UpsettingBoy/gpgpu-rs", tag = "v0.0.0-alpha.2" }

🆘 Help wanted

• For an efficient implementation of the conversion between image and gpgpu-rs types, some unsafe code was required. A review of this fragment is very much appreciated 😄 (in src/features/integrate_image.rs 👀).
• I'm running out of ideas. The initial goal of this project was to allow me develop a GPU-based image processing library (imageproc_gpu). Since I think gpgpu-rs is enough for that (but still very lacking), I'll continue with that project, adding whatever I need for GPGPU computing back at gpgpu-rs. Any other idea is appreciated.

v0.0.0-alpha.1: First usable version 🚩

This is the first "real" release of gpgpu-rs, not an MVP yet but still usable.

Features

• Offloading of computations into the GPU 📈
  • Using gpgpu-rs primitives + compute shaders
  • Supports storage buffers, texture and storage textures on the shaders
  • Supports SPIR-V compute shader loading (works best with WGSL shaders from both source and SPIR-V)
  • Fairly primitive wgpu integration. Allows usage of gpgpu-rs primitives with wgpu pipelines (mainly graphic pipelines)
  • 2 simple examples, one for buffer compute and another one for image manipulation
• GpuBuffer primitive
  • Buffer of n T elements on the GPU. T must be bytemuck::Pod
  • Supports sync and async read and write operations
• GpuImage primivite
  • Handles a texture on the GPU. Only RGBA8 images yet 😢
  • Supports sync and async read and write operations

TODO

• Improve documentation and examples (new and more complex examples)
• Support of different texture formats on GpuImage
• Reuse of staging buffers (optional, typed as in the Vec allocator)
• New primitives for fine grained GPU usage (CpuAccessibleBuffer, ReadOnlyGpuImage, etc; better naming 😆)
• More to come...

All in all, I'm pretty happy with this release. I'm looking for comments on the API, if it is simple, easy to use, etc.