How context objects work

This page documents the inner working between the RenderCanvas and the context object.

Introduction

The process of rendering to a canvas can be separated in two parts: rendering and presenting. The role of the context is to facilitate the rendering, and to then present the result to the screen. For this, the canvas provides one or more present-methods. Each canvas backend must provide at least the ‘screen’ or ‘bitmap’ present-method.

Rendering                 Presenting

            ┌─────────┐               ┌────────┐
            │         │  ──screen──►  │        │
──render──► | Context │      or       │ Canvas │
            │         │  ──bitmap──►  │        │
            └─────────┘               └────────┘

If the context is a BitmapContext, and the canvas supports the bitmap present-method, things are easy. Similarly, if the context is a WgpuContext, and the canvas supports the screen present-method, the presenting is simply delegated to wgpu.

When there’s a mismatch, we use different context sub-classes that handle the conversion. With the WgpuContextToBitmap context, the rendered result is inside a texture on the GPU. This texture is then downloaded to a bitmap on the CPU that can be passed to the canvas.

            ┌─────────┐                     ┌────────┐
            │         │  ──tex─┐            │        │
──render──► | Context │        |            │ Canvas │
            │         │        └─bitmap──►  │        |
            └─────────┘                     └────────┘
                          download to CPU

With the BitmapContextToScreen context, the bitmap is uploaded to a GPU texture, which is then rendered to screen using the lower-level canvas-context from wgpu.

            ┌─────────┐                        ┌────────┐
            │         │           ┌─screen──►  │        │
──render──► | Context │           │            │ Canvas │
            │         │  ──bitmap─┘            │        |
            └─────────┘                        └────────┘
                           upload to GPU

This way, contexts can be made to work with all canvas backens.