[.NET] Generate ReadOnlySpan<T> Overloads for GodotSharp APIs

[Delsin-Yu]

By adding ReadOnlySpan<T> API overloads, this PR aims to make the overall GodotSharp API more flexible by addressing the need for a dedicated data transaction T[] when making API calls.

Using the example from this proposal, the original RenderingServer.MultimeshSetBuffer

public static void MultimeshSetBuffer(Rid multimesh, float[] buffer)

will have an additional overload that takes ReadOnlySpan<float>:

public static void MultimeshSetBuffer(Rid multimesh, ReadOnlySpan<float> buffer)

Bugsquad edit:

• Closes Add Span<> overloads to Godot methods which accept arrays godot-proposals#10012.

[raulsntos]

This is a massive compatibility break, so it's not acceptable. We could do it as long as it's only adding span overloads while keeping the array overloads, but only for non-virtual methods and spans should never be returned either.

[dotlogix]

Does this also include to add overloads which take a buffer span instead of returning an Array?

Currently one of my biggest performance issues are tied to GetBufferData in the RenderingDevice.BufferGetData. Internally most of these methods act on a pinned array which is created every single time you call this method.

For RenderingDevice.BufferGetData the array is a byte[] which is incompatible with most of the other Apis so you have to allocate yet another array (float[]) and memory copy again. Doing this allows to use pooled arrays / instances and avoid allocations alltogether

[Delsin-Yu]

I have modified my PR to fit the compatibility requirements; now that span-related APIs are generated as overloads, no spans are returned by public APIs.

[Delsin-Yu]

@dotlogix In my original unmodified PR, yes, most arrays are directly replaced into Spans, including the return value. But for compatibility reasons, we can't do this, not on the main branch.

[dotlogix]

@dotlogix In my original unmodified PR, yes, most arrays are directly replaced into Spans, including the return value. But for compatibility reasons, we can't do this, not on the main branch.

Guess you forgot to revert:
GD.VarToBytes
Compat.*

I don't mean return a ReadOnlySpan instead of a T[] but instead of creating an array and return it, take a Span and write to that instead.

[Delsin-Yu]

Guess you forgot to revert: GD.VarToBytes

Good catch, thanks!

I don't mean return a ReadOnlySpan instead of a T[] but instead of creating an array and return it take a Span and write to that instead.

Oh, do you mean to return a Span for developers to write into, like a temporary buffer? As you mentioned, that would work by utilizing an array pool, but it would be challenging to manage the lifetime of the rented arrays. It sounds like a job for a custom struct-based, disposable array wrapper, but any of it is beyond the compatibility requirements. You can create a customized fork based on 34f85da if you wish.

[dotlogix]

Guess you forgot to revert: GD.VarToBytes

Good catch, thanks!

I don't mean return a ReadOnlySpan instead of a T[] but instead of creating an array and return it take a Span and write to that instead.

Oh, do you mean to return a Span for developers to write into, like a temporary buffer? As you mentioned, that would work by utilizing an array pool, but it would be challenging to manage the lifetime of the rented arrays. It sounds like a job for a custom struct-based, disposable array wrapper, but any of it is beyond the compatibility requirements. You can create a customized fork based on 34f85da if you wish.

No I mean in addition to this:

public byte[] BufferGetData(Rid buffer, uint offsetBytes = 0u, uint sizeBytes = 0u)

Have an overload like this:

public void BufferGetData(Rid buffer, Span<byte> target, uint offsetBytes = 0u, uint sizeBytes = 0u)

[Delsin-Yu]

No I mean in addition to this:

public byte[] BufferGetData(Rid buffer, uint offsetBytes = 0u, uint sizeBytes = 0u)

Have an overload like this:

public void BufferGetData(Rid buffer, Span<byte> target)

I don't think this is possible. The C# binding layer does not contain Godot logic; the binding generator creates the APIs you see.

[dotlogix]

No I mean in addition to this:

public byte[] BufferGetData(Rid buffer, uint offsetBytes = 0u, uint sizeBytes = 0u)

Have an overload like this:

public void BufferGetData(Rid buffer, Span<byte> target)

I don't think this is possible. The C# binding layer does not contain Godot logic; the binding generator creates the APIs you see.

Hm that's quite unfortunate. I would know how to implement that in C# pretty easily, but I just don't understand the binding generator (C++) so I can't just add it myself.

[Delsin-Yu]

Request removing breaks_compact & feature_proposal.

[Delsin-Yu]

I should probably generate ROS overloads for vararg methods as well.

Edit: Done, vararg methods now have overloads like:

public Error Rpc(StringName method, params Variant[] @args)
public Error Rpc(StringName method, ReadOnlySpan<Variant> @args)

public Variant New(params Variant[] @args)
public Variant New(ReadOnlySpan<Variant> @args)

public void CallGroupFlags(long flags, StringName group, StringName method, params Variant[] @args)
public void CallGroupFlags(long flags, StringName group, StringName method, ReadOnlySpan<Variant> @args)

[raulsntos]

Looks good to me, thanks.

I have compared the generated bindings with the ones we were generating before this PR, and the changes look good. It also doesn't look like it breaks compatibility, I double-checked with APICompat.

[Repiteo]

Thanks!