quasilyte
commented
1 week ago I'll add some context since it's missing in the description:
Why is this needed?
To avoid a full-slice copy. When using DrawTriangles for batch drawing, the indices slice will be re-used on the caller side and it can be quite large (let's say maxUint16/10 elements or so for a particle system is not a rarity).
When these indices are passed to the DrawTriangles as uint16, Ebitengine internally creates a slice of uint32 of the same length and copies everything in there. We can hypothetically get rid of this step if the input argument type is []uint32. Then there would be no extra data copying/allocation in the DrawTriangles method.
I started to use DrawTriangles recently and it's very useful for several stuff, but my most favorite ones are:
- batch-drawing of the same image and different positions (great for particle systems)
- shader-oriented drawing when we don't need an input image, but want to draw using the shader itself
There is a way to enable this optimization without breaking the API and it involves Go build tags. I'm not recommending it, but it's just an idea.
- Document some build tag, like
ebiten_uint32 - Introduce build-tag protected files, we need two (one for uint32 and one for uint16)
- Use our new function in DrawTriangles
Here is how it could look like:
//go:build ebiten_uint32
package ebiten
type Indice = uint32
// This conversion is no-operation, it just returns the slice.
// No allocations, no data copying.
func convertIndices(indices []Indice) []Indice {
return indices
}//go:build !ebiten_uint32
package ebiten
type Indice = uint16
// This is how it behaves by default.
func convertIndices(indices []Indice) []Indice {
is := make([]uint32, len(indices))
for i := range is {
is[i] = uint32(indices[i])
}
return is
}And then in DrawTriangles:
- is := make([]uint32, len(indices))
- for i := range is {
- is[i] = uint32(indices[i])
- }
+ is := convertIndices(indices)The signature will change textually, but it will be 100% compatible with the current API.
- DrawTriangles(vertices []Vertex, indices []uint16, img *Image, options *DrawTrianglesOptions)
+ DrawTriangles(vertices []Vertex, indices []Indice img *Image, options *DrawTrianglesOptions)To use this new API, the user would need to add a tag to their go command. Here is an example:
# Running with []uint32
# The user must pass []uint32 for the code to compile
$ go run --tags ebiten_uint32 ./cmd/mygame# Running with []uint16
# The user must pass []uint16 for the code to compile
# No tags are specified (it's a default behavior)
$ go run ./cmd/mygame# It's possible to use it with go-build as well
$ go build --tags ebiten_uint32 -o ./bin/mygame ./cmd/mygameThere could be other ways, like adding a new transitional function that can be used before the older API is changed; but that would increase the public API surface which is bad (we would need something to do with these new functions later).
@Zyko0 may have something extra to add. I would also like to invite @tinne26 for the discussion.
tinne26
hajimehoshi
Zyko0
Operating System
What feature would you like to be added?
This is a related change to #2612. Now Ebitengine internal uses []uint32 for indices, we should be able to use []uint32 for indices as public APIs instead of []uint16.
As this is a breaking change, let's do it in v3.
Why is this needed?
No response