yanchith / webglutenfree Goto Github PK

{Device,Framebuffer}.target() is already very similar to begin_render_pass from WebGPU - it binds a render target and prepares for recording rendering commands.

Add documentation for everything

We currently rely on TS to remove a whole class of invalid input values. We would like to have better support for JS consumers via having more complete input assertions with good error messages.

The downside is increased maintenance burden associated with keeping the asserts (and their tests) in sync with types, but there already need to be some run-time assertions for cases we can't check with types.

Currently rollup does not attempt to prune class methods due to the dynamic nature of the language, and it seems that even if it did, it would have to be really conservative about it (rollup/rollup#349). This means that our current API does not tree-shake well: Device is a class with a lot of methods that utilize imports from the rest of the library.

This is what the API could look like with plain functions:

import * as gf from "webglutenfree"

const dev = gf.createDevice(); // or gf.createDevice(canvas) or gf.createDevice(gl)
const cmd = gf.createCommand(dev, vertexShader, fragmentShader, options);
const attrs = gf.createAttributes(dev, primitive, attributeData);
gf.target(dev, (rt) => {
    gf.draw(rt, cmd, attrs);
});

We could potentially keep methods that don't make use of imports, or move everything into functions for more consistency.

WebGLRenderbuffers are the only way to support multisampling and postprocessing at the same time. The implementation should mirror Texture where possible. Examples could also be updated to use Renderbuffer where appropriate.

To prevent conflating @types dependencies between scripts and the library itself, split off scripts to its own subproject (with own package.json).

Currently, we can only pass in one buffer per attribute, but it is often desired to have multiple data sources in a single buffer, e.g. by interleaving values [position, color, position, color, ...].

WebGL let's the user control this via stride and offset parameters to gl.vertexAttribPointer(). Since we already expose other parameters to gl.vertexAttribPointer(), we can expose these two as well.

Also note that currently it is possible to pass a number[] as buffer in AttributePointerConfig. This must be disallowed since it would silently upload the same vertex buffer multiple times. This is no longer possible to do, so we should be good.

tslint:latest includes more, newer lints. We should upgrade and fix or whitelist violations.

Hi.

I'm trying to incorporate webglutenfree into a big three.js-based app. Both libs need to share the same GL context.
Three.js can reset its internal state, but I see no way to do so in webglutenfree.
In three.js I can do:

threeInstance.state.reset();

And that will cause three.js to bind programs, uniforms etc. again.
There needs to be something like that on webglutenfree side as well.

After 0.1.0 there should be significantly less API churn, but we need to implement more features before stabilizing anything - to find out what the "final" API looks like. Apart from features and API changes, we need better test coverage and documentation.

We need at least:

• Cubemaps (#19)
• Renderbuffers (#18)
• Decent test coverage (#26)
• Document all public APIs (#24)
• Add tutorial examples
• Improve showcase examples
• Document all examples (#25)
• Website with API docs (#39, #40)
• API cleanup
  • After implementing Cubemap and Renderbuffer decide, whether uniforms and textures should really be separate
    • Nope, the implementation can tell them apart, no need to separate them in the API. This also plays well with the new uniform types introduced in the Cubemap branch
  • Replace Command.locate() with AttributeLocation (#36)
  • Decide the "enum hierarchy".
    • Enums are per use-case and there is no hierarchy as a result of #17
  • Investigate making the library tree-shaking friendly (#53)
    • Won't be happening for 0.1.0, but may revisit later

Allow caching queried attribute locations with AttributeLocation:

const cmd = ...;
const aPosition = dev.queryAttributeLocation(cmd, "a_position");
const aColor = dev.queryAttributeLocation(cmd, "a_color");

// .index property allows for getting the location
const positionLocation = a_position.index;

// toString() allows for use in computed properties
const attrs = dev.createAttributes(Primitive.TRIANGLES, {
  [aPosition]: [
        [-0.3, -0.5],
        [0.3, -0.5],
        [0, 0.5],
    ],
  [aColor]: [
        [1, 0, 0, 1],
        [0, 1, 0, 1],
        [0, 0, 1, 1],
    ],
});

After implementing we can remove Command.locate() and migrate all examples to use this.

There could theoretically be support for WebGL1 with some required extensions (VAOs).

• How would this change the API?
• Can we support all features, or would some capabilities need to be disabled for WebGL 1 mode?
• Can #version 300 es be supported?

This can only be considered a win when the user doesn't need to know, whether he is using WebGL 1 or 2 under the hood. Also, need for this will disappear with time.

Currently examples have many top level constants for the viewers to play with. We could do a gui instead. https://github.com/flyover/imgui-js looks promising

To support plain javascript, we are not using const enums, increasing our code size footprint. With --preserveConstEnums, we could allow typescript users to optimize bundle size.

The enum objects would still be present in our dists for javascript projects, but typescript projects would inline enum values from d.ts, making the imported enum objects eligible for DCE during bundling.

Needs investigation whether typescript actually performs the inlining from d.ts as it may classify as type directed emit, which they don't do.

TextureArrays enable binding multiple textures at once, lessening the need for texture atlases.

As a preparation for adding docs to the website we should add some build tooling around the current gallery (currently completely static and residing in the docs dir) so it can start to slowly evolve towards a general website.

It should bundle webglutenfree and monaco as standard dependencies and only load the actual examples dynamically. Bundling monaco might require webpack 🙁

Cubemaps enable skyboxes and environment mapping. Implementation-wise, Cubemap should probably be a separate object from Texture, because it supports a slightly different operations, but also mirror its implementation. Would be nice to also add an example, while we are at it.

All non WebGL functionality should have unit tests. WebGL could be tested by mocking the context.

We would like to support applications that try to avoid memory pressure, therefore we should not make unneeded allocations and buffer copies all over the place.

There are probably two classes of allocations happening right now:

• const foo = bar || {}
• buffer conversions, e.g. new Uint8Array([1, 2, 3])

Spawning new empty objects theoretically could be fine, as long as the particular vm has a generational gc, these objects should be very cheap to create and destroy (needs verifying). In any case, we can live without some js conveniences if it provides better experience overall.

Buffer conversions are more tricky. WebGL always requires data in a typed array format. Currently we try to not do needless conversions, but there are a few [] to typed array conversions which do copy data. We should probably remove buffer copying from those that are expected to be called often or in the rendering loop, e.g. VertexBuffer.store(). It also may make sense to create a separate higher-level API and make the current API strictly low-overhead.