# RenderLifecycleMixin

Auto-generated from the @jbrowse/mobx-state-tree model in the source. See the [developer guide](https://jbrowse.org/jb2/docs/developer_guide/) for concepts. Built into JBrowse core. [View source](https://github.com/GMOD/jbrowse-components/blob/main/packages/render-core/src/RenderLifecycleMixin.ts).

Owns the GPU draw lifecycle for any display that paints to a canvas.

Plugins compose this mixin (directly or via `MultiRegionDisplayMixin` /
`GlobalFetchMixin`) and call
`self.attachRenderingBackend(backend, () => ({ upload, render }))` from their
own `startRenderingBackend(backend)` action. **The second argument is a thunk
because it runs exactly once**, on the first attach: `startRenderingBackend`
fires again on every context-loss recovery, and the autoruns keep the
callbacks they were given first. Anything the callbacks close over — an
upload sync's memo of what it last sent — is built inside it, so it lives as
long as the callbacks that read it rather than being allocated per recovery
and discarded. The mixin owns:

 - `canvasDrawn` — observable flag read by test-selector `data-testid` attributes to detect first paint.
 - `currentRenderingBackend` — the backend reference, updated on context-loss
   recovery. Autoruns read it each tick so they re-fire against the new
   one without being reinstalled.
 - `renderTick` — counter the render autorun observes; bumped by
   `renderNow()` after every upload that reached the backend, on
   tab-visibility restore, and when a circular ring backend starts. These
   are not a pan or zoom, so off screen a moved tick means new data.

The `upload` callback runs in one autorun, `render` in another. Inside
each, every observable read is auto-tracked by MobX — no getter-layer
indirection, no multi-entry config. `render` returns `true` when the
backend actually painted content (flips `canvasDrawn`), `false` to skip
this tick (e.g. `renderState` not yet computed or no regions loaded).

## Volatiles

| Member | Description |
| --- | --- |
| **canvasDrawn**<br><code>boolean</code> | flips true on first paint; read by test selectors to detect render |
| **paintCount**<br><code>number</code> | bumped after every frame the backend painted, so a consumer that reads this display's canvas — the circular view's ring, which copies the strip into a texture — knows when the pixels moved |
| **currentRenderingBackend**<br><code>unknown</code> | current backend reference, updated on context-loss recovery. Typed `unknown` rather than generic `B`: this mixin is composed by every display via a non-generic factory, so the per-display backend type `B` isn't known here — it's supplied at `attachRenderingBackend<B>` and narrowed with `as B` inside the autoruns. Don't "fix" the cast. |
| **renderTick**<br><code>number</code> | counter the render autorun observes; bumped to force a re-render |
| **renderError**<br><code>unknown</code> | the render-backend (GPU/Canvas2D init or context-loss) error, or undefined. Single source of truth for the render-error terminal state: `useRenderingBackend` writes it from the canvas-init mechanism so the model — not React-local hook state — owns every terminal state. Read by `displayPhase` (whose `renderError` term outranks `loading`, suppressing the scrim) and by `DisplayChrome` (shows the retry overlay). |
| **offScreen**<br><code>boolean</code> | the display's canvas has scrolled out of the page, so the render autorun skips pan and zoom redraws, still draws new data, and hands its GPU targets back after every tick. Written by `useRenderingBackend`, which watches the canvas element itself — false everywhere `IntersectionObserver` is absent, which is every unit test and every non-browser host.<br><br>A whole view that scrolls away is already unmounted (`useViewVisibility`) and a minimized track never mounts, so what this covers is the track below the fold of a view that is mounted: the display list is not windowed, and each of those tracks holds a full-height multisampled target. |

## Getters

| Member | Description |
| --- | --- |
| **canRender**<br><code>boolean</code> | Overridable precondition (default true): both lifecycle autoruns skip their callback entirely while this is false, so a display's `upload`/`render` need no readiness check.<br><br>The LGV mixins override it with `view.initialized`, because before the view is measured its geometry throws by design (`view.width`, and so `visibleRegions` / `trackWidthPx` with it) and a throw in either callback is routed to `renderError` — surfacing "not measured yet" as the GPU render-error banner. Because it's an observable read inside the autoruns, the pair re-fires the moment it flips. This is the *precondition* axis only: whether any data has arrived stays the render callback's gate (return `false` to skip a tick), which is why `renderState` getters can be plain resolved values. |
| **rendersCanvas**<br><code>boolean</code> | Overridable hook (default true): whether this display paints a canvas in its **current** configuration, as opposed to a deliberate static placeholder (LD with the triangle off, sequence past base resolution — both render a message where the `<canvas>` would go, so `canvasRef` is never called and `canvasDrawn` can never flip).<br><br>Lives here, beside `canvasDrawn`, because every consumer of "has this display painted" needs the pair. Both LGV fetch foundations fill it with `!fetchInert`, so a display there states its placeholder once, through that hook; the raw default reaches only a display composing this mixin outside them. See `painted` below for the reader that was missed while the two were separate overrides. |
| **paintInert**<br><code>boolean</code> | Overridable hook (default false): the display has reached a state it will not paint its way out of, so `painted` below should answer *finished* rather than *pending*. Both LGV fetch families fill it through `foundationPaintInert`: a failed fetch, a standing cancel, no content on screen, or the too-large banner in the canvas's place. The comparative side names it `fetchInert`.<br><br>A hook rather than a read of `error` here, for two reasons: this package is a leaf and `error` belongs to the fetch mixins, and declaring that name here would *collide* with `FetchMixin`'s volatile — `types.compose` gives the collision to its later argument, and the two families compose the two mixins in opposite orders. |
| **paintSuperseded**<br><code>boolean</code> | Overridable hook (default false): what is on the canvas was painted from data a later change has made wrong, so `painted` below should answer *pending* until the repaint lands even though `canvasDrawn` is still true. The per-region fetch foundation fills it with `staleSettingsDrawn` — held data drawn under settings that have since moved — which avoids resetting `canvasDrawn` on every settings change, because the reset would blank the display. A capture waiting on `data-display-drawn` then waits for the refetch rather than snapshotting the previous setting's pixels.<br><br>A hook and not a reset of the flag, because the flag is re-marked by any redraw — a pan between the settings change and the refetch would report the stale canvas drawn — and a derivation cannot be raced. |
| **painted**<br><code>boolean</code> | **The first-paint answer every consumer outside the display should read**, `canvasDrawn` being only the raw flag: a display that is deliberately not painting a canvas has finished, and reporting it unfinished leaves every waiter on it waiting forever.<br><br>The two `rendersCanvas: false` states each had three of their four consumers wired by hand — the loading scrim (`rendersCanvas` / `fetchInert`) and the SVG export (`fetchInert`) — while the fourth, `data-display-drawn`, went on publishing `"false"` forever off the raw flag. `PENDING_DISPLAYS` (`@jbrowse/browser-test-utils`) selects on that attribute, so a zoomed-out reference sequence track made every capture wait for the page run's full timeout, which then ended without reporting it. `fetchInert` on the comparative side has the same problem: the forgotten reader is the one outside the display, so the display has to publish one name for it.<br><br>`paintInert` is the third term and the same argument once more, for the state where a display *would* paint a canvas and never gets to — a fetch that failed before first paint. `paintSuperseded` is the fourth, and the one that subtracts: a canvas painted from data a settings change has made wrong is drawn and not finished. See both hooks. |

## Actions

| Member | Description |
| --- | --- |
| **markCanvasDrawn**<br><code>() =&gt; void</code> |  |
| **resetCanvasDrawn**<br><code>() =&gt; void</code> |  |
| **stopRenderingBackend**<br><code>() =&gt; void</code> |  |
| **renderNow**<br><code>() =&gt; void</code> |  |
| **setOffScreen**<br><code>(offScreen: boolean) =&gt; void</code> |  |
| **setRenderError**<br><code>(error: unknown) =&gt; void</code> | set/clear the render-backend error. Called by `useRenderingBackend`: with the error when the canvas factory rejects (or context-loss re-init fails), and with `undefined` on successful (re)init and on retry. |
| **attachRenderingBackend**<br><code>&lt;B&gt;(backend: B, setup: () =&gt; RenderingBackendCallbacks&lt;B&gt;) =&gt; void</code> | attach a GPU/Canvas2D backend and install the upload + render autorun pair. Idempotent: re-calling swaps the backend and does not run `setup` again, so the callbacks and everything they close over are the first call's. |

