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

Issue automatically imported from old repo: https://github.com/EmbarkStudios/rust-gpu/issues/744
Old labels: a: documentation,t: tracking issue
Originally creatd by hrydgard on 2021-09-02T11:14:16Z

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 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
• 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: https://github.com/EmbarkStudios/rust-gpu/issues/697
• 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)

Start by reviewing the unchecked items in this tracking issue and the linked issues #468, #697, #696, #885, and #695. Confirm the current status of each HLSL-to-rust-gpu mismatch and document a specific remaining issue with a clear reproduction or documentation target.