Refactor docs to separate WebGL v1 and v2 content.

[tsnee]

Description

WebGLRenderingContext and WebGL2RenderingContext have overloaded versions of the bufferData and bufferSubData functions. Before, all were documented under files/en-us/web/api/webglrenderingcontext. After a discussion on a previous PR it was decided to split them up.

Motivation

As things stand today, webgl2renderingcontext/index.md contains broken links. This PR creates the files required to resolve those links.

Related issues and pull requests

Relates to #32598

[github-actions]

Preview URLs

• /en-US/docs/Web/API/WebGL2RenderingContext/bufferData
• /en-US/docs/Web/API/WebGL2RenderingContext/bufferSubData
• /en-US/docs/Web/API/WebGLRenderingContext/bufferData
• /en-US/docs/Web/API/WebGLRenderingContext/bufferSubData

(comment last updated: 2024-03-13 19:15:29)

[wbamberg]

Thank you @tsnee ! Like I say, I'm no expert on WebGL so I'd appreciate your checking my comments, which are just based on a read of the spec syntax.

[wbamberg]

As I read the specs we've got the following definitions:

undefined bufferData(GLenum target, GLsizeiptr size, GLenum usage);
undefined bufferData(GLenum target, AllowSharedBufferSource? srcData, GLenum usage);
undefined bufferData(GLenum target, [AllowShared] ArrayBufferView srcData, GLenum usage,
    unsigned long long srcOffset, optional GLuint length = 0);

So it looks to me as if:

• either size or srcData must be given but not both
• srcOffset is effectively optional but is only allowed if srcData is given
• length is optional but is only allowed if srcOffset is given

...which would give us the following syntax variations:

bufferData(target, size, usage)
bufferData(target, srcData, usage)
bufferData(target, srcData, usage, srcOffset)
bufferData(target, srcData, usage, srcOffset, length)

Do you think that is right?

[tsnee]

Yes

[wbamberg]

I can't leave a suggestion but "// WebGL1" above should be removed as well.

[tsnee]

OK

[wbamberg]

It looks to me like either size or srcData must be provided, so this version should be omitted.

[tsnee]

Yes

[wbamberg]

I can't comment below but maybe mark size and srcData optional and say one of them must be provided?

[tsnee]

I accepted your suggestion.

[wbamberg]

looks like this option is not valid, from the spec?

undefined bufferSubData(GLenum target, GLintptr offset, AllowSharedBufferSource data);

(also it's called data not srcData in the spec, not sure this is worth fixing.)

[tsnee]

Like I say, I'm no expert on WebGL so I'd appreciate your checking my comments, which are just based on a read of the spec syntax.

I am not either. Your comments look correct to me, but I don't know how to prove they are right. I am only just beginning to work with WebGL. I will see if I can write some sample code to find out what works and what does not. However I would feel a lot more confident if a subject matter expert could weigh in.

[davesmith00000]

Hi! @tsnee and I have been discussing some related work in the background for a ticket I raised (to do with WebGL2) on another repo, that has resulted in this valiant effort.
I wouldn't call myself a subject matter expert, and would happily bow to a higher authority if one showed up, but I have spent a good amount of time with the Kronos docs and translating them to usable interfaces.
All that said, @wbamberg's comments all look correct and reasonable to me, based on the Kronos docs links provided.
Hope that helps, great work all.

[wbamberg]

Thanks for the update @tsnee and for the review @davesmith00000 !

The only thing left here is to delete lines 17 and 18 from https://github.com/mdn/content/pull/32613/files#diff-f3fa71864e6aba88eba045c4a46156dcd01acefa12cdef0e0d1a547168ebc1c8

// WebGL1
bufferData(target, usage)

.per the comments at https://github.com/mdn/content/pull/32613/files#r1518443366 and https://github.com/mdn/content/pull/32613/files#r1518441714.

After that we should be good I think.

[tsnee]

Oops, I thought I had already done that. I'm glad you double checked.

[wbamberg]

🎉 thank you for your work on this!