stride3d / stride3d/stride

Move to a more modern and consistent API using Spans

Open
#1,982 14 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
C#
Stars
7.8k
Forks
1.2k
Avg merge
2d 17h
Merged PRs (30d)
49

Description

Is your feature request related to a problem? Please describe.
When using the engine I found a bunch of places where we can benefit from using spans over the traditional array APIs.
A common pattern atm is passing an array+length or array+index+length which is exactly what a Span is as well.
Most of these usages copy the content of the Array to an internal Buffer so they absolutly don't care if we use a Span instead.

This would allow us to mark the array APIs as obsolete and move to more memory/cache friendly constructs around Span & Ref.
Spans can also be pinned to use them as Native memory where needed. We could even use NativeMemory or other Buffer constructs internally for high performance usages.

I guess it would also make it easier to work with Silk.net which heavily relies on Spans as well

Describe the solution you'd like
Instead of APIs like this:
void SetValue(T arg1)
void SetValue(T[] args)
void SetValue(int count, T[] args)

I would suggest using
void SetValue(T arg1) => SetValue(MemoryMarshal.CreateSpan(ref arg1, 1))
void SetValue(ReadOnlySpan args)

This makes it easier to maintain as we only need to implement a single method compared to 3 while preserving all of the abilities as previously.
It also allows you to use partial or stackallocated arrays (stackalloc int[] { 1, 2, 3 }), collection expressions (NET 8 [1,2,3] ), or fixed size buffers (NET 8) to be passed without any memory allocations.

Describe alternatives you've considered
Array Pooling could work but seems like a waste when passing only part's of an array.

Additional context
Collection expressions: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/operators/collection-expressions
Spans: https://learn.microsoft.com/en-us/archive/msdn-magazine/2018/january/csharp-all-about-span-exploring-a-new-net-mainstay

I would happily volunteer to do this migration :)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by inventorying the engine APIs that accept arrays, array-plus-length, or array-plus-index-and-length, as described in the issue. Determine the migration scope and compatibility requirements first; done means the selected APIs consistently accept spans while preserving existing capabilities and avoiding unnecessary allocations.

Written by the indexing model from the issue text.

Assessment

Tech stack
csharp
Domain
backend-api-design, game-dev, performance
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.