Skip to content

Commit

Permalink
Document three sets of GPU built-in functions (#92)
Browse files Browse the repository at this point in the history
  • Loading branch information
@dfellis
dfellis authored Jan 20, 2025
1 parent c069b16 commit a1165a5
Showing 1 changed file with 55 additions and 3 deletions.
58 changes: 55 additions & 3 deletions docs/built_ins.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -1061,15 +1061,67 @@ For clarity, the table of functions will be broken up into broad categories, and

### GPU-related functions

TODO
| Name | Type | Description |
| :--------------- | :------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mapReadBuffer` | `() -> BufferUsages` | Returns the buffer usages needed for a GPU -> CPU read buffer |
| `mapWriteBuffer` | `() -> BufferUsages` | Returns the buffer usages needed for a CPU -> GPU write buffer |
| `storageBuffer` | `() -> BufferUsages` | Returns the buffer usages needed for a GPU-only read/write storage buffer |
| `GBuffer{T}` | `(BufferUsages, T[]) -> GBuffer` | Constructs a buffer on the GPU using the provided array as data |
| `GBuffer{T}` | `(BufferUsages, i64) -> GBuffer` | Constructs an empty buffer on the GPU using the `i64` as the size in bytes |
| `GBuffer{T}` | `T[] -> GBuffer` | Constructs a storage buffer using the provided array as data |
| `GBuffer{T}` | `i64 -> GBuffer` | Constructs an empty storage buffer on the GPU using the `i64` as the size in bytes |
| `cpulen` | `GBuffer -> i64` | Returns the size in bytes of the buffer. CPU-only, not GPGPU |
| `id` | `GBuffer -> string` | Returns a unique ID string for the buffer |
| `GPGPU` | `(string, Array{Array{GBuffer}}, i64[3]) -> GPGPU` | Constructs a representation of `GPGPU` work to be done. The `string` is the WGSL shader code working on the provided buffers executing with the number of X, Y, and Z workgroups specified in the `i64[3]` |
| `GPGPU` | `(string, GBuffer) -> GPGPU` | Constructs a representation of `GPGPU` work to be done. The `string` is the WGSL shader code using the singular buffer. The set of workgroups is automatically derived from the buffer size |
| `run` | `Mut{GPGPU} -> ()` | Runs the representation of `GPGPU` work. Mutates the underlying buffers (by design) and compiles the shader code, if necessary, and caches it |
| `run` | `Mut{GPGPU[]} -> ()` | Runs the array of `GPGPU` work sequentially on the GPU. Mutates the underlying buffers (by design) and compiles the shader code, if necessary, and caches it |
| `shader` | `GPGPU -> string` | Extracts the shader code from the `GPGPU` value |
| `read{T}` | `GBuffer -> T[]` | Reads the data stored in the GPU buffer as an array of `T` values |
| `replace{T}` | `(GBuffer, T[]) -> ()!` | Replaces the data stored in the GPU buffer with the array of `T` values. Returns an `Error` if unsuccessful |

### Ergonomic GPGPU functions

TODO
| Name | Type | Description | Explicit |
| :------------ | :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------: |
| `WgpuType{N}` | `(N, string, Dict{string, string}, Set{GBuffer}) -> WgpuType{N}` | Manually construct a WGSL value for any type of data. `N` must be a compile-time `String` representing the WGSL type, the `string` is the name of the value, `Dict{string, string}` is the set of value-definition pairs needed to create the value, and `Set{GBuffer}` is the set of GPU buffers needed to create it. You probably won't use this directly | ❌ |
| `build{N}` | `N -> GPGPU` | Builds a representation of `GPGPU` work to be done. The `N` type must be derived from the `WgpuType{N}` for it to work. The dictionary of value definitions is used to construct a compute shader to generate the value represented by the `string`, and the set of GPU buffers is turned into an array of GPU buffers for the shader to use | ✅ |
| `build{N}` | `N[] -> GPGPU` | Builds a representation of `GPGPU` work to be done. The `N` type must be derived from the `WgpuType{N}` for it to work. This variant allows for multiple values to be calculated within a single shader (generally assignments to the GPU buffers to cause side-effects since they cannot by definition explicitly depend on each other ) | ✅ |

### GPGPU Primitive Type functions

TODO
| Name | Type | Description | Explicit |
| :------------------------ | :------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------- | :------: |
| `gu32` | `(string, Dict{string, string}, Set{GBuffer}) -> gu32` | Manually construct a GPU `u32` value. You probably won't use this directly | ❌ |
| `gi32` | `(string, Dict{string, string}, Set{GBuffer}) -> gi32` | Manually construct a GPU `i32` value. You probably won't use this directly | ❌ |
| `gf32` | `(string, Dict{string, string}, Set{GBuffer}) -> gf32` | Manually construct a GPU `f32` value. You probably won't use this directly | ❌ |
| `gbool` | `(string, Dict{string, string}, Set{GBuffer}) -> gbool` | Manually construct a GPU `bool` value. You probably won't use this directly | ❌ |
| `gPrimitiveConvert{I, O}` | `I -> O` | Manually construct a GPU type cast from the input type to the output type. You probably won't use this directly | ✅ |
| `gu32` | `u32 -> gu32` | Converts a `u32` into a GPU `u32` | ✅ |
| `gu32` | `gu32 -> gu32` | Returns the original value back | ✅ |
| `gu32` | `gi32 -> gu32` | Converts a `gi32` to a `gu32` | ✅ |
| `gu32` | `gf32 -> gu32` | Converts a `gf32` to a `gu32` | ✅ |
| `gu32` | `gbool -> gu32` | Converts a `gbool` to a `gu32` | ✅ |
| `gu32{T}` | `T -> gu32` | Converts the input type into a `u32` and then converts that into a `gu32` | ✅ |
| `gi32` | `i32 -> gi32` | Converts a `i32` into a GPU `i32` | ✅ |
| `gi32` | `gu32 -> gi32` | Converts a `gu32` to a `gi32` | ✅ |
| `gi32` | `gi32 -> gi32` | Returns the original value back | ✅ |
| `gi32` | `gf32 -> gi32` | Converts a `gf32` to a `gi32` | ✅ |
| `gi32` | `gbool -> gi32` | Converts a `gbool` to a `gi32` | ✅ |
| `gi32{T}` | `T -> gi32` | Converts the input type into a `i32` and then converts that into a `gi32` | ✅ |
| `gf32` | `f32 -> gf32` | Converts a `f32` into a GPU `f32` | ✅ |
| `gf32` | `gu32 -> gf32` | Converts a `gu32` to a `gf32` | ✅ |
| `gf32` | `gi32 -> gf32` | Converts a `gi32` to a `gf32` | ✅ |
| `gf32` | `gf32 -> gf32` | Returns the original value back | ✅ |
| `gf32` | `gbool -> gf32` | Converts a `gbool` to a `gf32` | ✅ |
| `gf32{T}` | `T -> gf32` | Converts the input type into a `f32` and then converts that into a `gf32` | ✅ |
| `gbool` | `bool -> gbool` | Converts a `bool` into a GPU `bool` | ✅ |
| `gbool` | `gu32 -> gbool` | Converts a `gu32` to a `gbool` | ✅ |
| `gbool` | `gi32 -> gbool` | Converts a `gi32` to a `gbool` | ✅ |
| `gbool` | `gf32 -> gbool` | Converts a `gf32` to a `gbool` | ✅ |
| `gbool` | `gbool -> gbool` | Returns the original value back | ✅ |
| `gbool{T}` | `T -> gbool` | Converts the input type into a `bool` and then converts that into a `gbool` | ✅ |
| `len` | `GBuffer -> gu32` | Returns the length of the specified GPU buffer as a `gu32` to use in GPGPU computation | ✅ |

### GPGPU Vector functions

Expand Down

0 comments on commit a1165a5

Please sign in to comment.