Custom track and display types

TL;DR: a new way to visualize data in an existing view is a display type; a track type is a new conceptual category of track.

A track owns the high-level identity (an ID, a name, a default set of displays); a display shows that track inside a particular view and owns the drawing.

Track  ─owns→  Display(s)  ─draw→  canvas

Tracks are deliberately thin. Every in-tree registration, with the view each display renders in — SyntenyTrack and VariantTrack are the two that reach past LinearGenomeView:

Add a track type only when you need a new conceptual track category, a custom config schema for that category, or behavior shared across multiple displays. Register it with pluginManager.addTrackType(...), reusing the base track config schema.

When to add a custom display type#

• Drawing chrome over the rendered content (e.g. the Y-scale axis in wiggle tracks, soft-clip indicators in alignments)
• Adding track-menu items that toggle display-only state (e.g. "Show soft clipping", "Modifications")
• Wiring a custom widget into feature clicks (e.g. VariantFeatureWidget)
• Bundling a specific adapter with drawing code tuned for it, so users get the right combination by default. The generic pairing a plugin skips here is FeatureTrack with LinearBasicDisplay.

The display owns view-specific state, menu items, overlays, and the drawing itself. A rendering backend is built, never registered: the plugin ABI has no rendering-backend element type, so the display calls createRenderingBackend, which walks the WebGPU → WebGL2 → Canvas2D ladder, or createCanvas2DBackend when it ships no shader path.

Display foundations#

LGV displays compose one foundation mixin on BaseDisplay, all sharing baseLinearDisplayConfigSchema. The foundation answers how the display fetches; how it renders is a separate axis on top.

Both walkthroughs use MultiRegionDisplayMixin, the common case. The architecture spec goes further into why fetch and render are split.

If your display holds onto what the pointer is over, read the hover rules first: a zoom, a side-scroll, an internal scroll and the region-too-large banner all move content under a stationary cursor without firing a pointer event, so a stored hit goes on naming what used to be there.

Cross-cutting mixins#

Orthogonal to the foundation — compose any of them on top of whichever one you picked. Each is one mixin with one overridable hook, and composing it is the opt-in: a display that never overrides the hook gets the default and pays nothing. Reach for one before writing the behavior yourself; Composed by is read off the types.compose(...) calls, so it also answers "does anything else already do this?"

Order matters in one place: types.compose gives a collision to the later argument, so composing HeightModeMixin() before TrackHeightMixin() silently leaves grow mode inert. The mixin reports that at attach.

Walkthroughs#

Two end-to-end guides build the same display, differing only in the renderer. Start with the first:

• Plotting features in a custom display - fetch in a worker, draw with Canvas2D. Right for gene-scale tracks.
• GPU displays - the same display with a .slang shader behind it, for roughly ≳100K features per frame.

Both are build-step plugins; Writing a plugin covers the scaffold and build setup they assume.

For a worked in-tree display, read plugins/wiggle/src/LinearWiggleDisplay for an overlay drawn over rendered content, or plugins/alignments/src/LinearAlignmentsDisplay for many toggleable menu items and a custom feature widget.

See also#

• Data fetching pipeline
• SVG export