Reading and writing vectors to buffers

[petrihakkinen]

Hi! We're currently in the process of taking the (fairly) new buffer type into use. It's great but sometimes we'd like to read/write vectors to buffers with a single call. A typical case is vertex data with 2 to 4 floats per element. I'm wondering has it been considered to extend the api to support vectors? E.g.

buffer.readf32x2(buf, offset) -> vector
buffer.readf32x3(buf, offset) -> vector
buffer.readf32x4(buf, offset) -> vector

buffer.writef32x2(buf, offset, vectorvalue)
buffer.writef32x3(buf, offset, vectorvalue)
buffer.writef32x4(buf, offset, vectorvalue)

When reading vectors, extra/unused components would be filled with zero.
readf32x4 and writef32x4 would be only available when Luau is compiled with LUA_VEC_SIZE 4.

In addition to being convenient, I believe these would be significantly faster than separate calls and converting back & forth between scalars and vectors, although it would require benchmarking.

Thoughts?

[petrihakkinen]

For motivation I wrote a quick experiment which shows 40% improvement between these two versions:

-- 40% faster
poc_writef32x3(buffer, 0, vec)

-- scalar version
buffer.writef32(buffer, 0, vec.x)
buffer.writef32(buffer, 4, vec.y)
buffer.writef32(buffer, 8, vec.z)

poc_writef32x3 is implemented using the C API, so a proper implementation should be even faster with a fastcall built-in in the VM.

[vegorov-rbx]

Embedders are free to extend the available functions in the environment as they see fit.

Every potential combination of operations can be rewritten as a specific C library call (or even a fastcall) and will be faster just by nature of the VM having overhead.
That doesn't mean we should have all and each one of them as a built-in function.
It makes for weak motivating factor.

While developers on some Luau platforms are limited in what functions they get, other embedders can choose to provide what they need to achieve their performance goals.

So no, we are unlikely to add the operations you propose.

I would even say your suggestions don't even make sense to involve vectors.
If functions named f32 were to read or return multiple values, those would just accept or return multiple values (I think batch operations were discussed in RFC and rejected although that might have happened privately).

One operation that I do expect is maybe readvector/writevector that reads or writes the whole vector.
But it should be the full vector value as that's the type we have defined.
One of the problems is specifying that in a way that would work with different Luau configurations.

[vegorov-rbx]

There's a potential path readvector3/readvector4, the plan was to look at it more after the vector library RFC.

[petrihakkinen]

Thanks for the answer. I think I explained the rationale poorly.

The naming of the existing buffer API in general seems to specify the storage type (as opposed to source data type). E.g. buffer.writeu8 writes a 8-bit integer regardless of the internal numeric type. I believe vectors should be handled similarly:

1. This allows more variants to be added in the future (by embedders or Roblox). Say, buffer.writef64x3 for writing 3-component doubles.
2. It decouples the API from internal vector data type. Say, in the future Luau changes vector data type to 3 doubles, or introduces more than one vector data type. What should readvector/writevector do in that case?
3. It solves the issue with LUA_VEC_SIZE by specifying exactly how many components are read/written.

(Side note: buffer.readvector and buffer.writevector operating with different number of components depending on LUA_VEC_SIZE would be a recipe for disaster. Shared library code would behave very differently on different versions of the VM.)

buffer.writef32x2 is an extension to this idea and comes from our view of vectors as being analoguous to SIMD CPU registers. We use native vectors for 2D coordinates, 3D coordinates, homogeneuous coordinates, RGBA colors and even quaternions. This has allowed us to write high performance code that has minimal dispatching overhead (don't you also use native vector type for 2D vectors at Roblox?). I think this meshes well with dynamic languages in general -- fewer types means less overhead in the VM (doesn't Luau have only one scalar type for similar reasons?).

In this context, I think writef32x2 makes sense. A use case for this would be reading/writing 2D coordinates to memory from a vector. That said, this is not as critical to us as 3 and 4-component vector operations are.

I also considered an API with multiple values but it has major downsides so I discarded the idea:

1. Fastcalls especially with multiple return values can be tricky
2. Packing/unpacking scalars to vectors and back adds a significant overhead
3. It leaves a hole in the buffer API as vectors would still be left out

Ultimately the decision is of course yours, but hopefully this makes sense. I'm available for writing a RFC and/or implementing the feature if it seems likely we could find a compromise.

[petrihakkinen]

Oh one more point came to mind:
4. Being explicit is more clear to the user. writef32x3 writes 3 floats but writevector requires knowing what a vector is actually made of (floats opposed to doubles, and even the number of components is not that clear because of LUA_VEC_SIZE).

[vegorov-rbx]

1. This allows more variants to be added in the future. Say, buffer.writef64x3 for writing 3-component doubles.

This is an API combinatorial explosion and the goal is to NOT add more variants.

It decouples the API from internal vector data type. Say, in the future Luau changes vector data type to 3 doubles, or introduces more than one vector data type. What should readvector/writevector do in that case?

Internal vector type is not going to change.

It solves the issue with LUA_VEC_SIZE by specifying exactly how many components are read/written.

Can be solved by other means like the one I mentioned with readvector3/4.

our view of vectors as being analoguous to SIMD CPU registers.

I do not support such view.

I'm available for writing a RFC and/or implementing the feature if it seems likely we could find a compromise.

I don't think it's a valuable effort given what seems to be a fundamental disagreement on the design in this discussion.

[petrihakkinen]

Alright, thanks for your time.