feat: enhance gl-matrix types #6460

bigmistqke · 2025-09-25T13:16:45Z

Continuing from issue #6316 in which I proposed for MapLibre's gl-matrix types to reflect more their actual types. The original usecase for this type enhancement was a bug in an earlier version of chrome where a Float64Array from MapLibre that was typed as a Float32Array was passed to WebGL, which caused an error as earlier WebGL versions only accepted a Float32Array.

Introduction

Earlier versions of gl-matrix had as type Tuple | Float32Array.
MapLibre uses Float64Array in several spots, but these were cast to Float32Array to appease the squiggly typelords.
The most recent version of gl-matrix fixed this issue slightly by widening its types to Tuple | IndexedCollection<number> where IndexedCollection extends Iterable<number>.

This removed the need for casting to Float32Array, but there is still room for improvement:

gl-matrix does not make use of any generics, this means that all of its methods return vec3 and the like, widening the types of its input.
.create() and a handful of other methods create a default array-type which can be set with import {glMatrix} from 'gl-matrix'; glMatrix.ARRAY_TYPE = .... They also return vec3 and the like.
The types use Tuple | ... because it wants to communicate that only certain indices are valid and typescript has no alternative for a tuple for TypedArrays.

Changes

I patched gl-matrix in the following ways (see https://github.com/bigmistqke/gl-matrix/tree/feat-improve-typings):

Added a type-utility TypedArrayTuple to simulate tuple-like typings for TypedArrays and other Iterables, see ts playground
methods use generics and return Vec3Result<T> and the like, Vec3Result is
- Vec3Tuple if T is an array and
- TypedArrayTuple<Kind, Vec3Tuple['length']> if it's not
Have the default array type be overwritable via module augmentation:
- by default it is Float32Array (although this is not 100% correct as it falls back to Array if Float32Array is not available in the runtime the code is executed)
- but if you do declare module 'gl-matrix' { interface Overrides { arrayType: Float64Array; }} it is typed as Float64Array

This allowed me to remove a bunch of type-casts and highlight methods/properties that have multiple types throughout their lifetimes.

Conclusion

I am not completely sure of how I refactored the base types from

declare type vec3 = IndexedCollection | Vec3Tuple;

to

declare type vec3<T extends IndexedCollection | Vec3Tuple = IndexedCollection | Vec3Tuple> = T;

which isn't super useful as we do lose some type-information when doing position: vec3<Float64Array> = new Float64Array(3) as this just becomes Float64Array. I could either

narrow vec3<Float64Array> to TypedArrayTuple<Float64Array, 3>, but this would cause a bunch of type-errors in existing code and the only solution would be to cast as typescript natively does not capture its length
revert the base type refactor and don't wrap the property-types with vec3 and the like: position: Float64Array = new Float64Array(3)

Ideally I want to upstream this to gl-matrix, but I first wanted to get some feedback from you guys.

using patched version of gl-matrix see bigmistqke/gl-matrix@9267a9e

HarelM · 2025-09-25T17:28:51Z

src/geo/projection/globe_transform.ts

    }

-    private get currentTransform(): ITransform {
+    private get currentTransform(): VerticalPerspectiveTransform | MercatorTransform {


Why was this changed?

I will revert this. It's a more narrow type, but it's also a bit irrelevant to this PR.

HarelM · 2025-09-25T17:29:46Z

src/geo/projection/globe_transform.ts

+    public get inverseProjectionMatrix(): mat4<Float64Array> { return this.currentTransform.inverseProjectionMatrix; }

-    public get cameraPosition(): vec3 { return this.currentTransform.cameraPosition; }
+    public get cameraPosition(): vec3<Float64Array | Vec3Tuple>  { return this.currentTransform.cameraPosition; }


This seems like an odd typescript definition...

Yes, I agree, this looks bug prone. All the 'ugly' types are values that switch type during their lifetime, which the previous typings had hidden away from us.

HarelM · 2025-09-25T17:30:53Z

src/geo/projection/globe_transform.ts

    }

-    calculateFogMatrix(unwrappedTileID: UnwrappedTileID): mat4 {
+    calculateFogMatrix(unwrappedTileID: UnwrappedTileID): mat4<Float64Array> | mat4<Float32Array> {


This looks a bad return value... Is it really the case here?

HarelM · 2025-09-25T17:32:57Z

src/geo/projection/mercator_transform.ts

        return Frustum.fromInvProjectionMatrix(this._invViewProjMatrix, this.worldSize);
    }
-    getClippingPlane(): vec4 | null {
+    getClippingPlane(): null {


I'm guessing the return value here was meant for the interface implementation...?

I will revert this!

HarelM · 2025-09-25T17:36:27Z

Is be more interested to see the typescript charges in gl-matrix that solves all these issues.
It might be that simply adding some overloads will solve some of the issues here, wouldn't it?
I also find the word tuple confusing, coming from a c# backgrond where tuple is a pair with two items in it...

bigmistqke · 2025-09-25T18:50:18Z

Is be more interested to see the typescript charges in gl-matrix that solves all these issues.

The patch is generated from a build of the last commit of https://github.com/bigmistqke/gl-matrix/tree/feat-improve-typings

It might be that simply adding some overloads will solve some of the issues here, wouldn't it?

I am not completely following here.

I also find the word tuple confusing, coming from a c# backgrond where tuple is a pair with two items in it...

I agree, it's a horrible name, but sadly it is what typescript officially calls it: https://www.typescriptlang.org/docs/handbook/2/objects.html#tuple-types

HarelM · 2025-09-26T06:03:01Z

It might be that simply adding some overloads will solve some of the issues here, wouldn't it?

This is in regards to the possible solution of the gl-matrix types. Maybe allowing the matrix operators to receive more general types by adding an overload to the methods definition can solve some of the issues here.

birkskyum · 2025-09-27T20:04:37Z

I also find the word tuple confusing, coming from a c# backgrond where tuple is a pair with two items in it...

I think C# also can hold n-tuples - not just 2-tuples? https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/value-tuples

"You can define tuples with an arbitrary large number of elements:"

HarelM · 2025-09-28T18:30:22Z

True, but I think the original implementation was only item1 and item2 fields, but I might remember it wrong as it was a long time ago.
In any case, this is a bit besides the point...

feat: use enhanced types of gl-matrix

ab1e951

using patched version of gl-matrix see bigmistqke/gl-matrix@9267a9e

bigmistqke mentioned this pull request Sep 25, 2025

defaultProjectionData.fallbackMatrix and .mainMatrix do not reflect the correct types #6316

Open

HarelM reviewed Sep 25, 2025

View reviewed changes

bigmistqke added 2 commits October 2, 2025 15:08

feat: update enhanced types

a2a8a40

chore: update gl-matrix to bigmistqke/gl-matrix/tree/feat-improve-types

b347f25

bigmistqke mentioned this pull request Oct 8, 2025

Feat improve types toji/gl-matrix#495

Open

Uh oh!

feat: enhance gl-matrix types #6460

Are you sure you want to change the base?

feat: enhance gl-matrix types #6460

Uh oh!

Conversation

bigmistqke commented Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Introduction

Changes

Conclusion

Uh oh!

HarelM Sep 25, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bigmistqke Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

HarelM Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

bigmistqke Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

HarelM Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

HarelM Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

bigmistqke Sep 25, 2025

Choose a reason for hiding this comment

Uh oh!

HarelM commented Sep 25, 2025

Uh oh!

bigmistqke commented Sep 25, 2025

Uh oh!

HarelM commented Sep 26, 2025

Uh oh!

birkskyum commented Sep 27, 2025

Uh oh!

HarelM commented Sep 28, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bigmistqke commented Sep 25, 2025 •

edited

Loading

HarelM Sep 25, 2025 •

edited

Loading