Bug: WebGL tex(Sub)Image2D optionals

[nkemnitz]

TypeScript Version: 2.2.1 (and previous)

Code

window.onload = () => {
    const canvas: HTMLCanvasElement = document.createElement("canvas") as HTMLCanvasElement;
    const gl: WebGLRenderingContext = canvas.getContext("webgl", { antialias: false} ) as WebGLRenderingContext;
    const tex = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, tex);

/*A1*/ gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 32, 32, 0, gl.RGBA, gl.UNSIGNED_BYTE);
/*A2*/ gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 32, 32, 0, gl.RGBA, gl.UNSIGNED_BYTE, null);
/*A3*/ gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE);

/*B1*/ gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, 16, 16, gl.RGBA, gl.UNSIGNED_BYTE);
/*B2*/ gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, 16, 16, gl.RGBA, gl.UNSIGNED_BYTE, null);
/*B3*/ gl.texSubImage2D(gl.TEXTURE_2D, 0, 0, 0, gl.RGBA, gl.UNSIGNED_BYTE);
};

For cases A2 and B2, only:
{ "compilerOptions": { "strictNullChecks": true } }

Expected behavior:

A1 should fail and raise something like Valid arities are: [6, 9], but 8 arguments provided.
A2 should pass, in order to create an empty texture and modify the content later.
A3 should fail, because no source (ImageData | HTMLVideoElement | HTMLImageElement | HTMLCanvasElement) was provided.

B1 should fail and raise something like Valid arities are: [7, 9], but 8 arguments provided.
B2 should pass, eventually WebGL will return INVALID_VALUE for the missing pixels.
B3 should fail, because no source (ImageData | HTMLVideoElement | HTMLImageElement | HTMLCanvasElement) was provided.

Actual behavior:

A1 will pass tsc, but resulting code fails in browser (Tested with Chrome and Firefox, so far).
A2 will fail tsc, expecting ArrayBufferView | undefined.
A3 will pass tsc, but resulting code fails in browser (Tested with Chrome and Firefox, so far).

B1 will pass tsc, but resulting code fails in browser (Tested with Chrome and Firefox, so far).
B2 will fail tsc, expecting ArrayBufferView | undefined.
B3 will pass tsc, but resulting code fails in browser (Tested with Chrome and Firefox, so far).

[mhegazy]

The function has two overloads in the library:

    texImage2D(target: number, level: number, internalformat: number, width: number , height: number, border: number           , format: number, type: number, pixels?: ArrayBufferView): void;
    texImage2D(target: number, level: number, internalformat: number, format: number, type: number  , pixels?: ImageData | HTMLVideoElement | HTMLImageElement | HTMLCanvasElement): void;

Which from a cursory glance seem to match the description on https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/texImage2D.

Can you elaborate on why this is not correct?

[nkemnitz]

The WebGL specification for texImage2D says

If pixels is null, a buffer of sufficient size initialized to 0 is passed.
If pixels is non-null, the type of pixels must match the type of the data to be read.

In this case null is specifically indicating that you want an empty texture and not just accidentally forgot to set the last parameter. Which is bad because if you do forget to set pixels, tsc will show no errors -- but the function call will fail in Chrome and Firefox.

On the other hand, if you correctly set the parameter to null but have strictNullChecks activated, tsc will erroneously complain about it, expecting ArrayBufferView | undefined.

For comparison, texSubImage3D (MDN Link) has the following declaration:

[...] GLenum type, ArrayBufferView? srcData, optional GLuint srcOffset = 0);

In that case srcOffset?: number would be acceptable, but srcData?: ArrayBufferView still would not, I think.

Edit:
The second signature of texImage2D on MDN is definitely wrong. The spec lists source as non-optional parameter of type TexImageSource (ImageBitmap or ImageData or HTMLImageElement or HTMLCanvasElement or HTMLVideoElement)

[mhegazy]

Thanks for the explanation. looks like we need to split this declaration into two. A PR would be appreciated.
You can find more information about contributing lib.d.ts fixes at https://github.com/Microsoft/TypeScript/blob/master/CONTRIBUTING.md#contributing-libdts-fixes.

[mhegazy]

Oh i see the PR. thanks!