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
• .abs() and .sign() don't work (cause 64-bit int code gen). See .abs() and .signum() cause 64-bit integer instruction generation #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
• 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],

• Nothing corresponding to HLSL's any() and all() ?
• Bitwise operators missing from integer vector types
• Can't use named constants to control thread group size: Pass constants into #[spirv(compute(threads(...)))] ? #697
• barriers are very difficult to use and need wrappers (Memory barrier documentation, and wrappers for common usage #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. Be more lenient on the vector type used for global_invocation_id #885

Unintuitive behavior mismatches

• need to assign the result of texture fetches to an explicitly Vec4 variable, before actually using it as something smaller #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. (Properly document support for shared memory (aka groupshared) (was: implement too) #695)