add vec2, vec3, vec4 types to the language #32032

Migrated from https://github.com/ziglang/zig/issues/7295

These are not to be confused with @Vector which is for SIMD.

These types are primarily intended for use when targeting SPIR-V but will of course work on all targets.

They should support swizzling, just like glsl. All the math builtins will support these types. Generally, there should be a bijection between glsl code and zig code with respect to 2d, 3d, and 4d vectors.

Related:

• add matrix to the language
• rename SIMD vectors

Will this also include the ivec, uvec, bvec and dvec types (or equivalents)? Linking the Khronos wiki for reference: https://wikis.khronos.org/opengl/Data_Type_(GLSL)

(Really happy for a language construct with swizzling support - for the use cases where it’s helpful it’s really helpful).

There’s also the extension which adds lower precision types: https://github.com/KhronosGroup/GLSL/blob/main/extensions/ext/GL_EXT_shader_16bit_storage.txt

What will be the differences between vec2 and @Vector(2, f32)? Will it be just the swizzling? Wouldn't it be easier to add swizzling to @Vector?

@LucasSantos91 @Vector is for SIMD, i.e. batching operations on larger amounts of data. What exactly a @Vector is, is up to the backend, but the semantics and use case stay the same.
In other words @Vector is an optimisation primitive for when the compiler doesn't do a good enough job on its own.

Usually, @Vectors of the sizes common to shaders/games are too small and hurt performance, they don't exist for the convenience many mistakenly use them for!

These vec types are primarily to improve using zig as a shader language, these exist for the convenience you want. Unlike @Vector, they will have a defined layout so you can safely share them between program and shader code.

Perhaps @Vector could be renamed to be more descriptive like @Simd or similar.

it will be https://github.com/ziglang/zig/issues/7305

Considering the number of types that can be supported by shaders - I wonder if having a new set of intrinsics would make sense?

@Vec2(Type), @Vec3(Type), @Vec4(Type) - helps future proof the concept and avoids the need to add a bunch of new keywords to the language.

Perhaps @Vector could be renamed to be more descriptive like @Simd or similar.

it will be https://github.com/ziglang/zig/issues/7305

I anticipate that changing @Vector to @Simd might have positive implications for introducing Matrix types as well, as discussed in https://github.com/ziglang/zig/issues/4960. Specifically, it improves the case for implementing operations between vectors and matrices, since @Vector and@Matrix are both defined in the context of linear algebra and not simd. Plus this could extent to tensors, which is cool.

Generally, I'm a big fan of this, as decoupling @Vector from @Simd opens a lot of possible options for better linear algebra and game engine UX.

While I welcome the acceptance of this proposal, there are several unresolved questions (mostly from the original proposal):

1. Which vector types will be available? Will they be limited to floats? If so, what precision will they have: f32 or f64?
2. Will vectors support GLSL-like constructors [1]?
3. What is the status of @dot(), @cross(), @normalized() and @length() builtins? Are they accepted as part of this proposal?
4. Will it be possible to construct the planned Matrix type from vectors, similar to GLSL [1]?
5. Which swizzle masks will be supported? Will we have xyzw, rgba, and stpq like in GLSL [2]? Is support for numeric indices planned?

[1] - Topic "5.4.2. Vector and Matrix Constructors" from GLSL language specification.
[2] - Topic "5.5. Vector and Scalar Components and Length" from GLSL language specification.

How would @Vector (@Simd ?) of vecs be laid out?

I think it would make most sense to have, e.g, @Vector(4, vec3) have an equivalent layout to struct { x: @Vector(4, f32), y: @Vector(4, f32), z: @Vector(4, f32) } .

This would provide the most efficient storage, and straight forward, most performant runtime execution of operations on vec types.

Additionally, hypothetical @dot, @cross etc would be able to accept @Vector(N, Vecm) types and vectorize the operations efficiently.

This would also encourage users to write more efficient vectorized code operating on many blocks of data rather than trying to acheive good performance using a simd register for individual vec3s, which is often a losing strategy.

Related: SPIR-V Specification

Really happy that this is coming to zig.

Are vecs planned to be data-only types?
Can it, for example, have methods?

consta:vec2(f32)=.{3.0,2.0};constb:vec2(f32)=.{2.0,1.0};constc=a.sum(b);// vec2(f32).sum(a, b)

This could behave similar to infix operators, and allows for readable chaining, imitating something like this on a language level:

pubfnvec2(T:type)type{returnstruct{x:T,y:T,pubfnsum(self:@This(),other:@This())@This(){return.{self.x+other.x,self.y+other.y};}};// ... mul(), dot() goes here}pubfnmain()!void{// ... a, b, c initialization goes here_=a.sum(b).mul(c).dot();}

On a related note, proposed @Matrix can be similarly lifted to mat(rows, cols, T) or mat{rows}x{cols}(T), and builtin matrix operations can operate on @Simd.

// a is 2x3 matrix and b is 3x4 matrixconsta:@Simd(2*3,T)=.{...};constb:@Simd(3*4,T)=.{...};constc=@matMul(a,2,3,b,3,4);

This might be undesirable because of number of arguments (although it can make comptime layout manipulation trivial), but rows and cols can easily be encoded into mat type (similar to {array}.len), imitating something like this on a language level

pubfnmat(comptime_rows:usize,comptime_cols:usize,_T:type)type{returnstruct{constrows=_rows;constcols=_cols;constT=_T;m:@Simd(_rows*_cols,T),fnMultRetType(Self:type,Other:type)type{// asserts both are matrices, asserts Self.T == Other.T, etc}pubfnmul(self:@This(),other:anytype)@This().MulRetType(@TypeOf(self),@TypeOf(other)){// ...}};}

Methods can be helpful here too, turning

_=matmul(a,matmul(b,matmul(c,d)));

into

_=a.mul(b).mul(c).mul(d);

Maybe this kind of approach even allows to decide if internal representation of vec and mat is @Simd or just plain fields with build options.

they won't need .add/.mul because they'll support +/-/*// etc

@nektro wrote in #32032 (comment):

they won't need .add/.mul because they'll support +/-/*// etc

Many common operations on vectors cannot be expressed with these, .normalized(), .magnitude(), .dot()/.cross(), this way is more explicit.

I understand that this approach might be more suited for a library, but language-level vector/matrix types with good support for common operations might drastically reduce (essentially boilerplate) duplicate code for most graphical applications and potentially increase interop between libraries.

it's likely those will be new builtins or added to std.math

@nektro wrote in #32032 (comment):

it's likely those will be new builtins or added to std.math

That would be good enough for standard library, but functions in std.math would lose infix/chaining property, would risk polluting namespace,

Plus, operations between different types would require precise naming.

.scale method on a vec versus std.math.vecScale.

@andrewrk wrote in #32032 (comment):

Generally, there should be a bijection between glsl code and zig code with respect to 2d, 3d, and 4d vectors.

And in respect to this requirement, this approach would limit combinatorics per target somewhat.

@absurdistcode wrote in #32032 (comment):

How would @Vector (@Simd ?) of vecs be laid out?

I think it would make most sense to have, e.g, @Vector(4, vec3) have an equivalent layout to struct { x: @Vector(4, f32), y: @Vector(4, f32), z: @Vector(4, f32) } .

The layout of @Vector/@Simd is defined by the backend, this makes sense since it is an optimisation primitive, the backend can define it in whatever way is easier or allows more optimisations etc. Which are things that depend on how the backend is structures as well as the target.

Beware of glsl semantic when it comes to storage: vec3 are often aligned as v4 on the GPU. I am therefore not convinced they should be used for storage, unless people expect this kind of alignement on the CPU side.
I am otherwise very happy to see gamedev / graphics dev taken seriously by the zig team. I'd add that compatibility between libraries is another benefit of this proposal, no need for glue code as in C++ for example.

Perhaps @Vector could be renamed to @Lanes

It's more in line with how the programmer should think about it.
It still avoids the strict hardware presupposition (@Simd proposal) that any backend will always emit SIMD (per spec, up to the target),
while importantly separating what is an optimization primitive from the mathematical 'vector' namespace.

.. I think it improves clarity on both fronts.

// Preview: @Lanes/// Scale a slice of data by a scalar factor using the optimal hardware size.pubfnscaleData(data:[]f32,factor:f32)void{constlane_count=std.simd.suggestLaneCount(f32)orelse1;// prev suggestVectorLengthvari:usize=0;if(lane_count>1){constlanes_factor:@Lanes(lane_count,f32)=@splat(factor);while(i+lane_count<=data.len):(i+=lane_count){constlanes_input:@Lanes(lane_count,f32)=data[i..][0..lane_count].*;constlanes_output=lanes_input*lanes_factor;data[i..][0..lane_count].*=lanes_output;}}// Remainder loopwhile(i<data.len):(i+=1){data[i]*=factor;}}

I've written up a suggestion for how to implement this proposal here.

closing as duplicate of #35376