Skip to main content

Geometric transformations

warning

Automatic WGSL docs generation publishable on this website is currently waiting on wgpu#6364. In the meantime, refer to the WGSL sources in the wgebra repository.

Most compute kernels for geometry, physics, robotics, games, etc. rely on some form of geometric transformations. While the WGSL specification gives access to raw transformation matrices through mat2x2, mat3x3, and mat4x4, these are both difficult to initialize and to use in practice is it is lacking utility functions to manipulate them.

WGebra defines strongly typed transformations for ergonomic and efficient handling of common transformations: rotations (as complex numbers or quaternions) and similarities.

note

There is no strongly typed isometries. Use similarities with a scaling factor of 1 instead.

Rotations​

Using a mat2x2 or mat3x3 for representing a 2D or 3D rotation is both wasteful in terms of memory usage, as well as inefficient when it comes to operations like inversion. The WgRot2 and WgQuat composable shaders expose reusable WGSL types and functions for representing and handling these rotations as a complex number (i.e. 2 floats) in 2D, or a quaternion (i.e. 4 floats) in 3D.

2D rotations example​

#[derive(Shader)]
#[shader(derive(WgRot2), src = "your_shader.wgsl")]
struct YourShader;

// Automatically generates a test to check with `cargo test` if `your_shader.wgsl` compiles.
wgcore::test_shader_compilation!(YourShader);

Quaternion example​

#[derive(Shader)]
#[shader(derive(WgQuat), src = "your_shader.wgsl")]
struct YourShader;

// Automatically generates a test to check with `cargo test` if `your_shader.wgsl` compiles.
wgcore::test_shader_compilation!(YourShader);

Similarities​

Similarities are transformations representing a uniform scaling factor, followed by a rotation, followed by a translation. They are a superset of isometries for which the scaling factor is always 1.

#[derive(Shader)]
#[shader(derive(WgSim3), src = "your_shader.wgsl")]
struct YourShader;

// Automatically generates a test to check with `cargo test` if `your_shader.wgsl` compiles.
wgcore::test_shader_compilation!(YourShader);