Tracking: Collection of issues found when porting HLSL to rust-gpu

[hrydgard]

I and some others have been porting a body of HLSL code to rust-gpu. Here's some notes about unexpected differences, pitfalls, and hard-to-port things.

Fixable issues (doesn't mean they're easy!)

• [ ] For loops compile to a mess that spirv-cross can't quite handle, so we're sticking to while loops
• [x] .abs() and .sign() don't work (cause 64-bit int code gen). See https://github.com/EmbarkStudios/rust-gpu/issues/468
• [ ] .saturate doesn't behave like HLSL's saturate with regards to NaNs. (glam issue?)
• [ ] #derive(Debug) on a struct really weirds the compiler out, no way to see what you did wrong
• [x] Need to use #[rustfmt::skip] on shader entry points, since rustfmt eats long attributes! For example, this line gets mangled from:

    #[spirv(storage_buffer, descriptor_set = 0, binding = 1)] instance_constants_dyn: &[InstanceDynamicParameters],

into:

    instance_constants_dyn: &[InstanceDynamicParameters],

• [x] Nothing corresponding to HLSL's any() and all() ?
• [x] Bitwise operators missing from integer vector types
• [ ] Can't use named constants to control thread group size: https://github.com/EmbarkStudios/rust-gpu/issues/697
• [x] barriers are very difficult to use and need wrappers (https://github.com/EmbarkStudios/rust-gpu/issues/696)
• [ ] The builtin #[spirv(global_invocation_id)] id: UVec3 needs to be declared as an UVec3, and then truncated if you want a Vec2. In HLSL and GLSL it's common to declare it as a 2-vector instead (UVec2) if you only care about x and y. #885

Unintuitive behavior mismatches

• #895
• ~~const_mat3! is equivalent to the transpose of HLSL's float3x3. Same goes for the other matrix constructors, of course. Dangerous trap! But probably the right way around, really.~~ const_mat3! is no longer supported in latest glam.
• (macaw problem) step function is unintuitive: x.step(y) = step(y, x).

Inconveniences that may not be fixable

• The mix of uint3 for global_invocation_id and int2/int3 for texture fetches is a lot more painful in rust than in HLSL.
  • This currently seems to just work? ~@oisyn
• a.max(b) instead of max(a, b) is sometimes kinda laborious. though rust-style.
• Sometimes need to do a lot more parameter passing since inputs are not global. Not necessarily a bad thing though.

Documentation issues

• shared memory not properly documented, very hard to find the correct syntax. (https://github.com/EmbarkStudios/rust-gpu/issues/695)