Struct Device

pub struct Device { /* private fields */ }

The main struct which provides abstraction over the wgpu library.

Implementations

impl Device

pub fn new() -> Device

Creates a new Device. (request a device with power_preference: wgpu::PowerPreference::HighPerformance)

pub fn get_info(self) -> String

Get some info about the gpu chosen to run the code on.

pub fn create_buffer( &mut self, name: &str, data_type: BufferType, size: usize, usage: BufferUsage, is_output: bool, )

Creates a buffer.

Arguments :

• name : the name of the buffer that will be available in the shader
• data_types : the type of the buffer, can be eaiser : “i32”, “u32”, “f32”, or “bool”
• size : the element size of the buffer (if it is a buffer of 3 u32s, the size is 3)
• usage : a description of how the buffer will be used in the shader
• is_output : whether or not to retrieve the data in the buffer after execution

pub fn create_buffer_from<T: ToVecU8<T>>( &mut self, name: &str, content: &Vec<T>, usage: BufferUsage, is_output: bool, )

Creates a buffer from a vector.

Arguments :

• name : the name of the buffer that will be available in the shader
• content : a reference to the vector
• usage : a description of how the buffer will be used in the shader
• is_output : whether or not to retrieve the data in the buffer after execution

pub fn apply_buffer_usages( &mut self, buf_name: &str, usage: BufferUsages, is_output: bool, )

Change for given buffer the usage. Is mainly used to add manualy a wgpu::BufferUsages. If you also want to change the easy_gpgpu::BufferUsage, you can do : wgpu::BuferUsages::some_usage | easy_gpgpu::BufferUsage::some_other_usage.

pub fn apply_on_vector<T: ToVecU8<T> + Clone>( &mut self, vec: Vec<T>, code: &str, ) -> Vec<T>

Apply a change over all elements of a vector.

Arguments :

• vec: the vector to apply the change on
• code: what to do which each elements, a piece of wgsl shader in the shader, you have access to the element variable which represent an element in the vector that last line has to be the return value i.e : (more or less like in a rust function when we don’t use return)

let mut device = easy_gpgpu::Device::new();
let v1 = vec![1u32, 2, 3];
let v1 = device.apply_on_vector(v1, "element * 2u");
assert_eq!(v1, vec![2u32, 4, 6]);
 
// this code will do for each element :
// element = element * 2;

Important Note : There should be no variable/function/struct with a name containing the substring “element”;

This function is limited to vectors with a byte length <= 1_073_741_824 (268_435_456 i32s max)

Possible problems you could encounter :

If you want to use this function with a previously created buffer, be aware that the number of buffers per execution is limited to 8 (you can have more but it’s max 8 buffers used in the shader). This function creates automatically a certain number of buffers depending on the size (max size for a buffer is 134_217_728 bytes)

pub fn create_shader_module( &self, dispatch: Dispatch, code: &str, ) -> ShaderModule

Creates a shader module to execute it several time on the device If you don’t need to use to execute the shader several time, use execute_shader_code instead.

pub fn execute_shader_module( &mut self, shader_module: &ShaderModule, ) -> Vec<OutputVec>

Executes a shader module on the gpu which can be create with device.create_shader_module

Arguments :

• shader_module : a compiled shader

Return value (same as the execute_shader_code function):

The output is a vector of vector : a liste of all the buffers outputed, to get the raw values, call for example output[0].unwrap_i32()to get a Vec<i32>. (there is also unwrap_u32, unwrap_f32 and unwrap_bool) It is advised to turn this into an iterator using : output.into_iter() and get the outputed vectors with the next() method.

Panics :

• if there has not been any buffer created before the execution

Note that if you want to execute the shader only once you can do two steps at once with device.execute_shader_code.

pub fn execute_shader_code( &mut self, dispatch: Dispatch, code: &str, ) -> Vec<OutputVec>

The single most important method in this crate : it runs the wgsl shader code on the gpu and gets the output

Arguments :

• dispatch : most interesting use is Dispatch::Linear(n), it will add a variable in the shader, index which varies from 0 to n over all executions of the shader if Dispatch::Custom(x, y, z) is used, you will get the global_id variable with three fields : global_id.x, global_id.y and global_id.z
• code : the shader code to run on the gpu, the buffers created before on this device are available with the name provided

Output :

The output is a vector of vector : a liste of all the buffers outputed, to get the raw values, call for example output[0].unwrap_i32()to get a Vec<i32>. (there is also unwrap_u32, unwrap_f32 and unwrap_bool) It is advised to turn this into an iterator using : output.into_iter() and get the outputed vectors with the next() method.

Important note :

The first line of your shader should be exactly : “fn main() {”, the shader will not get preprocessed correctly otherwise.

pub fn execute_commands(&mut self, commands: Vec<Command<'_>>)

Execute a list of commands, there can be at most a single shader command.

pub fn get_buffer_data(&self, buffer_names: Vec<&str>) -> Vec<OutputVec>

Retrieves the data of buffers to vectors. It has to have been created with is_output: true.