Update WebGL architecture doc with edits #6791
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
Update: added class diagram via Mermaid. Turns out GitHub can render those in readmes! |
|
@davepagurek You can merge this when you are ready |
nickmcintyre
reviewed
Mar 1, 2024
There was a problem hiding this comment.
@davepagurek looks great! Had a few minor formatting notes.
Also, in "Goals of WebGL" mode, you may be able to get by without extra boldness. For example:
Features should be beginner-friendly: It should provide a beginner-friendly introduction to WebGL and the features it offers.
The leading sentence already emphasizes the point.
| Currently, WebGL mode is functional for a variety of tasks, but many users and library makers want to extend it in new directions. We aim to create a set of building blocks for users and library makers from which they can craft extensions. A block can be considered "done" when it has an extensible API we can confidently commit to supporting. A major milestone for WebGL mode will be when we have a sufficient set of such blocks for an ecosystem of libraries. The main areas currently lacking in extension support are geometry and materials. | ||
|
|
||
| - **Extend p5.Geometry to support richer content.** One can create geometry, but many tasks a user might want to accomplish are not yet supported with a stable API. One might want to efficiently update geometry, which is necessary to support animated gltf models. One might want to group multiple materials in one object, if they are present in an imported model. One might want to add custom vertex attributes for a shader to work with. These tasks are currently unsupported. | ||
| ```mermaid |
| WebGL "1" *-- "*" Framebuffer | ||
| ``` | ||
|
|
||
| The entry point to most WebGL code is through **p5.RendererGL**. Top-level p5.js functions are passed to the current renderer. Both 2D and WebGL modes have renderer classes that conform to a common `p5.Renderer` interface. Immediate mode and retained mode functions are split up into **p5.RendererGL.Immediate.js** and **p5.RendererGL.Retained.js**. |
There was a problem hiding this comment.
Syntax highlighting: p5.RendererGL should probably be p5.RendererGL
|
|
||
| The entry point to most WebGL code is through **p5.RendererGL**. Top-level p5.js functions are passed to the current renderer. Both 2D and WebGL modes have renderer classes that conform to a common `p5.Renderer` interface. Immediate mode and retained mode functions are split up into **p5.RendererGL.Immediate.js** and **p5.RendererGL.Retained.js**. | ||
|
|
||
| Within the renderer, references to models are stored in the **retainedMode.geometry** map. Each value is an object storing the buffers of a **p5.Geometry**. When calling `model(yourGeometry)` for the first time, the renderer adds an entry in the map. It then stores references to the geometry's GPU resources there. If you draw a `p5.Geometry` to the main canvas and also to a WebGL `p5.Graphics`, it will have entries in two renderers. |
There was a problem hiding this comment.
Syntax highlighting: retainedMode.geometry should probably be retainedMode.geometry and p5.Geometry should be p5.Geometry
|
|
||
| Within the renderer, references to models are stored in the **retainedMode.geometry** map. Each value is an object storing the buffers of a **p5.Geometry**. When calling `model(yourGeometry)` for the first time, the renderer adds an entry in the map. It then stores references to the geometry's GPU resources there. If you draw a `p5.Geometry` to the main canvas and also to a WebGL `p5.Graphics`, it will have entries in two renderers. | ||
|
|
||
| Each material is represented by a **p5.Shader.** You set the current shader in the renderer via the `shader(yourShader)` function. This class handles compiling shader source code and setting shader uniforms. |
There was a problem hiding this comment.
Syntax highlighting: p5.Shader should probably be p5.Shader
|
|
||
| When setting a shader uniform, if the uniform type is an image, then the renderer creates a `p5.Texture` for it. Each `p5.Image`, `p5.Graphics`, `p5.MediaElement`, or `p5.Framebuffer` asset will get one. It is what keeps track of the image data's representation on the GPU. Before using the asset in a shader, p5.js will send new data to the GPU if necessary. For images, this happens when a user has manually updated the pixels of an image. This happens every frame for assets with data that may have changed each frame, such as a video or a `p5.Graphics`. | ||
|
|
||
| Textures corresponding to **p5.Framebuffer** objects are unique. Framebuffers are like graphics: they represent surfaces that can be drawn to. Unlike `p5.Graphics`, `p5.Framebuffer`s live entirely on the GPU. If one uses a `p5.Graphics` as a texture in a shader, the data needs to be transferred to and from the CPU. This can often be a performance bottleneck. In contrast, when drawing to a `p5.Framebuffer`, you draw directly to its GPU texture. Because of this, no extra data transfer is necessary. WebGL mode tries to use `p5.Framebuffer`s over `p5.Graphics` where possible for this reason. |
There was a problem hiding this comment.
Syntax highlighting: p5.Framebuffer should probably be p5.Framebuffer
Consistency: p5.Framebuffers are like graphics: ...
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This converts the edits from @limzykenneth and @nickmcintyre from Google Docs to the .md file here on Github.