Skip to main content

ferrochart_render_wgpu/
lib.rs

1//! wgpu rendering backend for FerroChart: the primary backend for desktop and
2//! the web (Vulkan, Metal, DX12, WebGPU; WebGL2 with the `webgl` feature).
3//!
4//! - **Series data lives on the GPU** in chunks of 4096 elements with frozen
5//!   f64 reference prices. Only chunks that are drawn are uploaded; data
6//!   changes are pulled with `changes_since` and only dirty ranges rewritten.
7//!   Panning and zooming update a few uniforms and issue one instanced draw per
8//!   visible chunk.
9//! - **Shaders mirror `transform_helpers`** operation by operation
10//!   (`src/shaders/series.wgsl`), so this backend matches the CPU backend's
11//!   golden images.
12//! - **Layer cache**: background and main layers are rendered into an
13//!   offscreen texture that is reused while their revisions do not change;
14//!   crosshair-only frames redraw just the overlay on top of it.
15//! - Vertex buffers are bound at the first visible element of each chunk and
16//!   instances always start at 0 (no `first_instance`, so WebGL2 works the
17//!   same way); no storage buffers are used.
18//!
19//! # Examples
20//!
21//! Offscreen rendering with read-back (the same mode tests use):
22//!
23//! ```no_run
24//! use ferrochart_core::chart::{SeriesData, SeriesOptions};
25//! use ferrochart_core::frame::SeriesKind;
26//! use ferrochart_core::geom::SizeCss;
27//! use ferrochart_core::render::Renderer;
28//! use ferrochart_core::testing::random_walk;
29//! use ferrochart_core::{Chart, ChartOptions};
30//! use ferrochart_render_wgpu::{GpuContext, WgpuRenderer};
31//!
32//! let ctx = GpuContext::headless()?;
33//! let mut renderer = WgpuRenderer::offscreen(&ctx);
34//! let mut chart = Chart::new(ChartOptions::default());
35//! chart.resize(SizeCss { w: 800.0, h: 450.0 }, 1.0);
36//! let id = chart.add_series(chart.main_pane(), SeriesKind::Candlestick, SeriesOptions::default())?;
37//! chart.set_data(id, SeriesData::Ohlc(random_walk(1, 1000, 0, 60_000)?))?;
38//! chart.build_frame(0.0, &renderer.measurer());
39//! renderer.render(chart.frame(), &chart.data_view())?;
40//! let rgba = renderer.read_pixels()?;
41//! assert_eq!(rgba.len(), 800 * 450 * 4);
42//! # Ok::<(), Box<dyn std::error::Error>>(())
43//! ```
44//!
45#![forbid(unsafe_code)]
46
47mod atlas;
48mod native;
49mod pipelines;
50mod series;
51
52pub use native::{GpuSeries, GpuSeriesCtx};
53
54use std::collections::HashMap;
55use std::sync::{Arc, Mutex};
56
57use ferrochart_core::chart::ChartDataView;
58use ferrochart_core::data::OhlcLevelView;
59use ferrochart_core::frame::{
60    CustomDraw, DrawCmd, FontStyleRef, Frame, Layer, LineDash, LineInst, PriceMapping, SeriesDraw,
61    SeriesKind, SeriesStyle, TextAlign, TextRun,
62};
63use ferrochart_core::geom::{PointPx, RectPx, Rgba, SizePx};
64use ferrochart_core::render::{RenderError, Renderer};
65use ferrochart_core::text::TextMeasurer;
66use ferrochart_core::transform_helpers::{
67    CHUNK_LEN, bar_metrics, chunk_of, chunk_start, x_shift, y_bias, y_of_price,
68};
69use ferrochart_text::TextEngine;
70
71use crate::atlas::Atlas;
72use crate::pipelines::{
73    DrawUniform, GlyphInstance, IconInstance, LineInstance, Pipelines, RectInstance,
74    TriangleInstance,
75};
76use crate::series::{COLOR_BYTES, Scratch, SeriesGpu, ohlc_offset, value_offset};
77
78/// Polls a future to completion on the current thread. wgpu's native futures
79/// are ready immediately; this avoids an executor dependency.
80#[cfg(not(target_arch = "wasm32"))]
81fn block_on<F: std::future::Future>(future: F) -> F::Output {
82    use std::task::{Context, Poll, Waker};
83    let mut future = std::pin::pin!(future);
84    let mut cx = Context::from_waker(Waker::noop());
85    loop {
86        if let Poll::Ready(v) = future.as_mut().poll(&mut cx) {
87            return v;
88        }
89        std::thread::yield_now();
90    }
91}
92
93/// A wgpu instance, adapter, device and queue.
94#[derive(Debug)]
95pub struct GpuContext {
96    /// The instance.
97    pub instance: wgpu::Instance,
98    /// The adapter.
99    pub adapter: wgpu::Adapter,
100    /// The device.
101    pub device: wgpu::Device,
102    /// The queue.
103    pub queue: wgpu::Queue,
104}
105
106impl GpuContext {
107    /// A context without a window, for offscreen rendering. Blocks until the
108    /// adapter and device are ready (native only; use [`request`](Self::request)
109    /// on the web).
110    ///
111    /// # Errors
112    ///
113    /// [`RenderError::Backend`] if no adapter or device is available.
114    #[cfg(not(target_arch = "wasm32"))]
115    pub fn headless() -> Result<Self, RenderError> {
116        let instance = wgpu::Instance::new(wgpu::InstanceDescriptor::new_without_display_handle());
117        Self::with_instance(instance, None)
118    }
119
120    /// Blocking [`request`](Self::request) (native only: on the web the
121    /// adapter and device are JS promises that only resolve after returning
122    /// to the event loop).
123    ///
124    /// # Errors
125    ///
126    /// [`RenderError::Backend`] if no adapter or device is available.
127    #[cfg(not(target_arch = "wasm32"))]
128    pub fn with_instance(
129        instance: wgpu::Instance,
130        surface: Option<&wgpu::Surface<'_>>,
131    ) -> Result<Self, RenderError> {
132        block_on(Self::request(instance, surface))
133    }
134
135    /// A context on `instance` whose adapter can present to `surface` (if
136    /// given).
137    ///
138    /// # Errors
139    ///
140    /// [`RenderError::Backend`] if no adapter or device is available.
141    pub async fn request(
142        instance: wgpu::Instance,
143        surface: Option<&wgpu::Surface<'_>>,
144    ) -> Result<Self, RenderError> {
145        let adapter = instance
146            .request_adapter(&wgpu::RequestAdapterOptions {
147                power_preference: wgpu::PowerPreference::default(),
148                force_fallback_adapter: false,
149                compatible_surface: surface,
150                ..wgpu::RequestAdapterOptions::default()
151            })
152            .await
153            .map_err(|_| RenderError::Backend("no suitable GPU adapter"))?;
154        Self::from_adapter(instance, adapter).await
155    }
156
157    /// A context on an adapter obtained from `instance`.
158    ///
159    /// Device limits, with the adapter's texture sizes: the downlevel
160    /// defaults (storage buffers, compute shaders) when the adapter supports
161    /// compute shaders, otherwise the WebGL2 downlevel defaults. The built-in
162    /// pipelines only use WebGL2-level features either way; the higher
163    /// limits are for native plugins such as the order flow heatmap.
164    ///
165    /// # Errors
166    ///
167    /// [`RenderError::Backend`] if the device cannot be created.
168    pub async fn from_adapter(
169        instance: wgpu::Instance,
170        adapter: wgpu::Adapter,
171    ) -> Result<Self, RenderError> {
172        let allowed = adapter.limits();
173        let compute = wgpu::Limits::downlevel_defaults().using_resolution(allowed.clone());
174        let limits = if adapter
175            .get_downlevel_capabilities()
176            .flags
177            .contains(wgpu::DownlevelFlags::COMPUTE_SHADERS)
178            && compute.check_limits(&allowed)
179        {
180            compute
181        } else {
182            wgpu::Limits::downlevel_webgl2_defaults().using_resolution(allowed)
183        };
184        let (device, queue) = adapter
185            .request_device(&wgpu::DeviceDescriptor {
186                label: Some("ferrochart"),
187                required_limits: limits,
188                ..wgpu::DeviceDescriptor::default()
189            })
190            .await
191            .map_err(|_| RenderError::Backend("cannot create GPU device"))?;
192        Ok(Self {
193            instance,
194            adapter,
195            device,
196            queue,
197        })
198    }
199}
200
201/// Adapts a [`TextEngine`] to the core's [`TextMeasurer`].
202#[derive(Clone, Copy, Debug)]
203pub struct EngineMeasurer<'a>(pub &'a TextEngine);
204
205impl TextMeasurer for EngineMeasurer<'_> {
206    fn ascii_advances(&self, style: FontStyleRef) -> &[f32; 128] {
207        self.0.ascii_advances(style.font.0)
208    }
209
210    fn subscript_advances(&self, style: FontStyleRef) -> Option<&[f32; 10]> {
211        Some(self.0.subscript_advances(style.font.0))
212    }
213
214    fn measure(&self, text: &str, style: FontStyleRef) -> SizePx {
215        SizePx {
216            w: self.0.width(style.font.0, text, style.size),
217            h: self.line_height(style),
218        }
219    }
220
221    fn line_height(&self, style: FontStyleRef) -> f32 {
222        self.0.line_metrics(style.font.0, style.size).height()
223    }
224}
225
226/// Integer pixel box `[x0, x1) × [y0, y1)`, rounded like the CPU backend.
227#[derive(Clone, Copy, Debug, PartialEq, Eq)]
228struct IBox {
229    x0: i32,
230    y0: i32,
231    x1: i32,
232    y1: i32,
233}
234
235impl IBox {
236    fn of_rect(r: RectPx) -> Self {
237        Self {
238            x0: r.x.round() as i32,
239            y0: r.y.round() as i32,
240            x1: (r.x + r.w).round() as i32,
241            y1: (r.y + r.h).round() as i32,
242        }
243    }
244
245    fn intersect(self, o: Self) -> Self {
246        Self {
247            x0: self.x0.max(o.x0),
248            y0: self.y0.max(o.y0),
249            x1: self.x1.min(o.x1),
250            y1: self.y1.min(o.y1),
251        }
252    }
253
254    fn is_empty(self) -> bool {
255        self.x1 <= self.x0 || self.y1 <= self.y0
256    }
257}
258
259fn rgba(c: Rgba) -> [u8; 4] {
260    [c.r, c.g, c.b, c.a]
261}
262
263fn rgba_f(c: Rgba) -> [f32; 4] {
264    [c.r, c.g, c.b, c.a].map(|v| f32::from(v) / 255.0)
265}
266
267/// Series pipelines.
268#[derive(Clone, Copy, Debug, PartialEq, Eq)]
269enum SeriesPipe {
270    /// Candlestick and Heikin-Ashi.
271    Candles,
272    OhlcBars,
273    /// Volume, colored by the source bar's direction.
274    Histogram,
275    /// Histogram of a value series, with optional per-point colors.
276    ValueHistogram,
277    /// The line of line, area and baseline series.
278    Line,
279    /// The fill of area and baseline series.
280    Fill,
281    /// The dots of points series.
282    Points,
283}
284
285impl SeriesPipe {
286    /// Pipelines that draw `kind`, in order (fills under lines, as in the CPU
287    /// backend).
288    fn passes(kind: SeriesKind) -> &'static [Self] {
289        match kind {
290            SeriesKind::Candlestick | SeriesKind::HeikinAshi => &[Self::Candles],
291            SeriesKind::OhlcBar => &[Self::OhlcBars],
292            SeriesKind::Volume => &[Self::Histogram],
293            SeriesKind::Histogram => &[Self::ValueHistogram],
294            SeriesKind::Line => &[Self::Line],
295            SeriesKind::Area | SeriesKind::Baseline => &[Self::Fill, Self::Line],
296            SeriesKind::Points => &[Self::Points],
297            // Bands have their own pipeline (`Op::Band`). Custom series
298            // arrive as primitives or `DrawCmd::Custom`, Kagi and Point &
299            // Figure as primitives.
300            SeriesKind::Band | SeriesKind::Custom | SeriesKind::Kagi | SeriesKind::PointFigure => {
301                &[]
302            }
303        }
304    }
305}
306
307/// One recorded draw operation; replayed into a render pass.
308#[derive(Clone, Copy, Debug)]
309enum Op {
310    Scissor(IBox),
311    Rects {
312        start: u32,
313        count: u32,
314    },
315    Lines {
316        start: u32,
317        count: u32,
318    },
319    Glyphs {
320        start: u32,
321        count: u32,
322    },
323    Icons {
324        start: u32,
325        count: u32,
326    },
327    Triangles {
328        start: u32,
329        count: u32,
330    },
331    Series {
332        pipe: SeriesPipe,
333        series: u32,
334        level: u8,
335        chunk: i64,
336        /// Element offset within the chunk.
337        elem: i64,
338        count: u32,
339        uniform: u32,
340        log: bool,
341    },
342    /// A band between series `upper` and `lower` (same level and chunk).
343    Band {
344        upper: u32,
345        lower: u32,
346        level: u8,
347        chunk: i64,
348        /// Element offset within the chunk.
349        elem: i64,
350        count: u32,
351        uniform: u32,
352        log: bool,
353    },
354    /// `gpu_series[plugin]` draws `custom_draws[draw]`.
355    Custom {
356        plugin: u32,
357        draw: u32,
358    },
359}
360
361/// Where frames go.
362enum Target {
363    /// Not yet sized.
364    None,
365    Offscreen {
366        texture: wgpu::Texture,
367        view: wgpu::TextureView,
368        size: (u32, u32),
369    },
370    Surface {
371        surface: wgpu::Surface<'static>,
372        config: wgpu::SurfaceConfiguration,
373        view_format: wgpu::TextureFormat,
374    },
375}
376
377/// The cached background + main layers.
378struct LayerCache {
379    view: wgpu::TextureView,
380    bind: wgpu::BindGroup,
381    size: (u32, u32),
382    /// Revisions of the background and main layers it holds.
383    revisions: Option<(u64, u64)>,
384}
385
386/// A growable GPU buffer.
387struct GrowBuffer {
388    buffer: wgpu::Buffer,
389    capacity: u64,
390    usage: wgpu::BufferUsages,
391    label: &'static str,
392}
393
394impl GrowBuffer {
395    fn new(device: &wgpu::Device, label: &'static str, usage: wgpu::BufferUsages) -> Self {
396        let capacity = 4096;
397        Self {
398            buffer: Self::make(device, label, usage, capacity),
399            capacity,
400            usage,
401            label,
402        }
403    }
404
405    fn make(
406        device: &wgpu::Device,
407        label: &'static str,
408        usage: wgpu::BufferUsages,
409        size: u64,
410    ) -> wgpu::Buffer {
411        device.create_buffer(&wgpu::BufferDescriptor {
412            label: Some(label),
413            size,
414            usage: usage | wgpu::BufferUsages::COPY_DST,
415            mapped_at_creation: false,
416        })
417    }
418
419    /// Writes `bytes`, growing first if needed. Returns whether the buffer was
420    /// replaced (bind groups must be recreated).
421    fn write(&mut self, device: &wgpu::Device, queue: &wgpu::Queue, bytes: &[u8]) -> bool {
422        let need = bytes.len() as u64;
423        let mut grown = false;
424        if need > self.capacity {
425            self.capacity = need.next_power_of_two();
426            self.buffer = Self::make(device, self.label, self.usage, self.capacity);
427            grown = true;
428        }
429        if !bytes.is_empty() {
430            queue.write_buffer(&self.buffer, 0, bytes);
431        }
432        grown
433    }
434}
435
436/// The wgpu renderer.
437pub struct WgpuRenderer {
438    device: wgpu::Device,
439    queue: wgpu::Queue,
440    format: wgpu::TextureFormat,
441    target: Target,
442    pipelines: Pipelines,
443    atlas: Atlas,
444    atlas_bind: wgpu::BindGroup,
445    text: TextEngine,
446    series: HashMap<u32, SeriesGpu>,
447    scratch: Scratch,
448    /// Bound as the color buffer of value histograms without per-point
449    /// colors (all zero: series color).
450    zero_colors: wgpu::Buffer,
451    uniform_align: usize,
452    uniform_buf: GrowBuffer,
453    uniform_bind: wgpu::BindGroup,
454    rect_buf: GrowBuffer,
455    line_buf: GrowBuffer,
456    icon_buf: GrowBuffer,
457    tri_buf: GrowBuffer,
458    glyph_buf: GrowBuffer,
459    cache: Option<LayerCache>,
460    // Per-frame scratch, reused.
461    uniforms: Vec<u8>,
462    rects: Vec<RectInstance>,
463    lines: Vec<LineInstance>,
464    icons: Vec<IconInstance>,
465    tris: Vec<TriangleInstance>,
466    glyphs: Vec<GlyphInstance>,
467    main_ops: Vec<Op>,
468    overlay_ops: Vec<Op>,
469    clips: Vec<IBox>,
470    gpu_error: Arc<Mutex<Option<String>>>,
471    /// Native custom series and their kinds, in the same order.
472    gpu_series: Vec<Box<dyn GpuSeries>>,
473    native_kinds: Vec<&'static str>,
474    /// The `DrawCmd::Custom`s of this frame (scratch).
475    custom_draws: Vec<CustomDraw>,
476}
477
478impl std::fmt::Debug for WgpuRenderer {
479    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
480        f.debug_struct("WgpuRenderer")
481            .field("format", &self.format)
482            .field("series", &self.series.len())
483            .finish_non_exhaustive()
484    }
485}
486
487const OFFSCREEN_FORMAT: wgpu::TextureFormat = wgpu::TextureFormat::Rgba8Unorm;
488const MAX_SIZE: f32 = 16_384.0;
489
490impl WgpuRenderer {
491    fn with_format(ctx: &GpuContext, format: wgpu::TextureFormat, target: Target) -> Self {
492        let device = ctx.device.clone();
493        // wgpu's default handler panics; keep the error and fail the next
494        // `render` instead (public API must not panic).
495        let gpu_error = Arc::new(Mutex::new(None::<String>));
496        let sink = Arc::clone(&gpu_error);
497        device.on_uncaptured_error(Arc::new(move |e: wgpu::Error| {
498            if let Ok(mut slot) = sink.lock() {
499                slot.get_or_insert_with(|| e.to_string());
500            }
501        }));
502        let pipelines = Pipelines::new(&device, format);
503        let atlas = Atlas::new(&device);
504        let atlas_bind = Self::texture_bind(&device, &pipelines, &atlas.view);
505        let uniform_buf =
506            GrowBuffer::new(&device, "ferrochart uniforms", wgpu::BufferUsages::UNIFORM);
507        let uniform_bind = Self::uniform_bind(&device, &pipelines, &uniform_buf.buffer);
508        let align = device.limits().min_uniform_buffer_offset_alignment.max(256) as usize;
509        Self {
510            rect_buf: GrowBuffer::new(&device, "ferrochart rects", wgpu::BufferUsages::VERTEX),
511            line_buf: GrowBuffer::new(&device, "ferrochart lines", wgpu::BufferUsages::VERTEX),
512            icon_buf: GrowBuffer::new(&device, "ferrochart icons", wgpu::BufferUsages::VERTEX),
513            tri_buf: GrowBuffer::new(&device, "ferrochart triangles", wgpu::BufferUsages::VERTEX),
514            glyph_buf: GrowBuffer::new(&device, "ferrochart glyphs", wgpu::BufferUsages::VERTEX),
515            queue: ctx.queue.clone(),
516            format,
517            target,
518            pipelines,
519            atlas,
520            atlas_bind,
521            text: TextEngine::new(),
522            series: HashMap::new(),
523            scratch: Scratch::default(),
524            zero_colors: device.create_buffer(&wgpu::BufferDescriptor {
525                label: Some("ferrochart zero colors"),
526                size: COLOR_BYTES,
527                usage: wgpu::BufferUsages::VERTEX,
528                mapped_at_creation: false,
529            }),
530            uniform_align: align,
531            uniform_buf,
532            uniform_bind,
533            cache: None,
534            uniforms: Vec::new(),
535            rects: Vec::new(),
536            lines: Vec::new(),
537            icons: Vec::new(),
538            tris: Vec::new(),
539            glyphs: Vec::new(),
540            main_ops: Vec::new(),
541            overlay_ops: Vec::new(),
542            clips: Vec::new(),
543            gpu_error,
544            gpu_series: Vec::new(),
545            native_kinds: Vec::new(),
546            custom_draws: Vec::new(),
547            device,
548        }
549    }
550
551    /// A renderer that draws into its own texture; read it back with
552    /// [`read_pixels`](Self::read_pixels). The texture is sized by each frame.
553    pub fn offscreen(ctx: &GpuContext) -> Self {
554        Self::with_format(ctx, OFFSCREEN_FORMAT, Target::None)
555    }
556
557    /// A renderer that presents to `surface` (created from `ctx.instance`).
558    ///
559    /// # Errors
560    ///
561    /// [`RenderError::Backend`] if the surface is not supported by the adapter,
562    /// [`RenderError::InvalidSize`] for a zero or too large size.
563    pub fn with_surface(
564        ctx: &GpuContext,
565        surface: wgpu::Surface<'static>,
566        size: SizePx,
567    ) -> Result<Self, RenderError> {
568        let (w, h) = target_size(size)?;
569        let caps = surface.get_capabilities(&ctx.adapter);
570        let format = caps
571            .formats
572            .iter()
573            .copied()
574            .find(|f| !f.is_srgb())
575            .or_else(|| caps.formats.first().copied())
576            .ok_or(RenderError::Backend("surface not supported by the adapter"))?;
577        // Colors are blended in sRGB-encoded space like the CPU backend, so
578        // render through a non-sRGB view.
579        let view_format = format.remove_srgb_suffix();
580        let mut config = surface
581            .get_default_config(&ctx.adapter, w, h)
582            .ok_or(RenderError::Backend("surface not supported by the adapter"))?;
583        config.format = format;
584        config.present_mode = wgpu::PresentMode::AutoVsync;
585        if view_format != format {
586            config.view_formats = vec![view_format];
587        }
588        surface.configure(&ctx.device, &config);
589        Ok(Self::with_format(
590            ctx,
591            view_format,
592            Target::Surface {
593                surface,
594                config,
595                view_format,
596            },
597        ))
598    }
599
600    /// The first GPU error (validation, out of memory) reported since the
601    /// last call, with wgpu's message. A frame during which such an error
602    /// occurred makes [`Renderer::render`] return [`RenderError::Backend`].
603    ///
604    /// The renderer installs the device's uncaptured-error handler; with
605    /// several renderers on one device, the last one created receives them.
606    pub fn take_gpu_error(&mut self) -> Option<String> {
607        self.gpu_error.lock().ok().and_then(|mut e| e.take())
608    }
609
610    fn has_gpu_error(&self) -> bool {
611        self.gpu_error.lock().is_ok_and(|e| e.is_some())
612    }
613
614    /// Registers the native implementation of a custom series kind,
615    /// replacing an earlier one of the same kind. The kind is then in
616    /// [`Renderer::native_kinds`]; pass those to `Chart::set_native_kinds`
617    /// (the host helpers do it before every frame). Do not register an
618    /// implementation that needs compute shaders on WebGL2.
619    pub fn register_series(&mut self, series: Box<dyn GpuSeries>) {
620        let kind = series.kind();
621        if let Some(n) = self.native_kinds.iter().position(|&k| k == kind) {
622            self.gpu_series[n] = series;
623        } else {
624            self.native_kinds.push(kind);
625            self.gpu_series.push(series);
626        }
627    }
628
629    /// The text measurer to pass to `Chart::build_frame`.
630    pub fn measurer(&self) -> EngineMeasurer<'_> {
631        EngineMeasurer(&self.text)
632    }
633
634    /// The text engine (to add fonts).
635    pub fn text_engine_mut(&mut self) -> &mut TextEngine {
636        &mut self.text
637    }
638
639    /// Bytes of GPU vertex buffers held for series data.
640    pub fn series_chunks(&self) -> usize {
641        self.series.values().map(SeriesGpu::chunk_count).sum()
642    }
643
644    fn uniform_bind(
645        device: &wgpu::Device,
646        p: &Pipelines,
647        buffer: &wgpu::Buffer,
648    ) -> wgpu::BindGroup {
649        device.create_bind_group(&wgpu::BindGroupDescriptor {
650            label: Some("ferrochart uniforms"),
651            layout: &p.uniform_layout,
652            entries: &[wgpu::BindGroupEntry {
653                binding: 0,
654                resource: wgpu::BindingResource::Buffer(wgpu::BufferBinding {
655                    buffer,
656                    offset: 0,
657                    size: wgpu::BufferSize::new(core::mem::size_of::<DrawUniform>() as u64),
658                }),
659            }],
660        })
661    }
662
663    fn texture_bind(
664        device: &wgpu::Device,
665        p: &Pipelines,
666        view: &wgpu::TextureView,
667    ) -> wgpu::BindGroup {
668        device.create_bind_group(&wgpu::BindGroupDescriptor {
669            label: Some("ferrochart texture"),
670            layout: &p.texture_layout,
671            entries: &[wgpu::BindGroupEntry {
672                binding: 0,
673                resource: wgpu::BindingResource::TextureView(view),
674            }],
675        })
676    }
677
678    fn color_texture(
679        &self,
680        label: &str,
681        size: (u32, u32),
682        usage: wgpu::TextureUsages,
683    ) -> wgpu::Texture {
684        self.device.create_texture(&wgpu::TextureDescriptor {
685            label: Some(label),
686            size: wgpu::Extent3d {
687                width: size.0,
688                height: size.1,
689                depth_or_array_layers: 1,
690            },
691            mip_level_count: 1,
692            sample_count: 1,
693            dimension: wgpu::TextureDimension::D2,
694            format: self.format,
695            usage,
696            view_formats: &[],
697        })
698    }
699
700    fn ensure_cache(&mut self, size: (u32, u32)) {
701        if self.cache.as_ref().is_some_and(|c| c.size == size) {
702            return;
703        }
704        let texture = self.color_texture(
705            "ferrochart layer cache",
706            size,
707            wgpu::TextureUsages::RENDER_ATTACHMENT | wgpu::TextureUsages::TEXTURE_BINDING,
708        );
709        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
710        let bind = Self::texture_bind(&self.device, &self.pipelines, &view);
711        self.cache = Some(LayerCache {
712            view,
713            bind,
714            size,
715            revisions: None,
716        });
717    }
718
719    fn ensure_offscreen(&mut self, size: (u32, u32)) {
720        if matches!(self.target, Target::Offscreen { size: s, .. } if s == size) {
721            return;
722        }
723        if matches!(self.target, Target::Surface { .. }) {
724            return;
725        }
726        let texture = self.color_texture(
727            "ferrochart offscreen target",
728            size,
729            // Sampled by hosts that compose the chart themselves (egui).
730            wgpu::TextureUsages::RENDER_ATTACHMENT
731                | wgpu::TextureUsages::COPY_SRC
732                | wgpu::TextureUsages::TEXTURE_BINDING,
733        );
734        let view = texture.create_view(&wgpu::TextureViewDescriptor::default());
735        self.target = Target::Offscreen {
736            texture,
737            view,
738            size,
739        };
740    }
741
742    fn reconfigure(&mut self, size: (u32, u32)) {
743        if let Target::Surface {
744            surface, config, ..
745        } = &mut self.target
746            && (config.width, config.height) != size
747        {
748            config.width = size.0;
749            config.height = size.1;
750            surface.configure(&self.device, config);
751        }
752    }
753
754    /// The texture an offscreen renderer drew the last frame into, for hosts
755    /// that compose the chart into their own rendering (a UI toolkit's paint
756    /// callback, a game engine). `None` for a renderer created with
757    /// [`with_surface`](Self::with_surface) and before the first frame.
758    ///
759    /// The format is `Rgba8Unorm` holding sRGB-encoded colors (the CPU
760    /// backend's pixels): sample it as is and write the values to a
761    /// non-sRGB target, or convert them to linear before writing to an sRGB
762    /// one. The usages are `RENDER_ATTACHMENT | COPY_SRC | TEXTURE_BINDING`.
763    /// The texture is replaced when the frame size changes, so look it up
764    /// after each [`Renderer::render`] rather than keeping it.
765    ///
766    /// ```no_run
767    /// use ferrochart_core::geom::SizeCss;
768    /// use ferrochart_core::render::Renderer;
769    /// use ferrochart_core::{Chart, ChartOptions};
770    /// use ferrochart_render_wgpu::{GpuContext, WgpuRenderer};
771    ///
772    /// let ctx = GpuContext::headless()?;
773    /// let mut renderer = WgpuRenderer::offscreen(&ctx);
774    /// let mut chart = Chart::new(ChartOptions::default());
775    /// chart.resize(SizeCss { w: 800.0, h: 450.0 }, 2.0);
776    /// chart.build_frame(0.0, &renderer.measurer());
777    /// renderer.render(chart.frame(), &chart.data_view())?;
778    /// let texture = renderer.offscreen_texture().ok_or("no frame yet")?;
779    /// assert_eq!((texture.width(), texture.height()), (1600, 900));
780    /// // Bind `renderer.offscreen_view()` in the host's own pipeline.
781    /// # Ok::<(), Box<dyn std::error::Error>>(())
782    /// ```
783    pub fn offscreen_texture(&self) -> Option<&wgpu::Texture> {
784        match &self.target {
785            Target::Offscreen { texture, .. } => Some(texture),
786            _ => None,
787        }
788    }
789
790    /// A view of the whole [`offscreen_texture`](Self::offscreen_texture)
791    /// (same lifetime and conditions), ready to bind for sampling.
792    pub fn offscreen_view(&self) -> Option<&wgpu::TextureView> {
793        match &self.target {
794            Target::Offscreen { view, .. } => Some(view),
795            _ => None,
796        }
797    }
798
799    /// Reads the offscreen target back as tightly packed RGBA8 rows.
800    ///
801    /// # Errors
802    ///
803    /// [`RenderError::InvalidSize`] if this is not an offscreen renderer or
804    /// nothing was rendered, [`RenderError::Backend`] if mapping fails.
805    #[cfg(not(target_arch = "wasm32"))]
806    pub fn read_pixels(&self) -> Result<Vec<u8>, RenderError> {
807        let Target::Offscreen {
808            texture,
809            size: (w, h),
810            ..
811        } = &self.target
812        else {
813            return Err(RenderError::InvalidSize);
814        };
815        let (w, h) = (*w, *h);
816        let row = w * 4;
817        let padded =
818            row.div_ceil(wgpu::COPY_BYTES_PER_ROW_ALIGNMENT) * wgpu::COPY_BYTES_PER_ROW_ALIGNMENT;
819        let buffer = self.device.create_buffer(&wgpu::BufferDescriptor {
820            label: Some("ferrochart read-back"),
821            size: u64::from(padded) * u64::from(h),
822            usage: wgpu::BufferUsages::COPY_DST | wgpu::BufferUsages::MAP_READ,
823            mapped_at_creation: false,
824        });
825        let mut encoder = self
826            .device
827            .create_command_encoder(&wgpu::CommandEncoderDescriptor::default());
828        encoder.copy_texture_to_buffer(
829            wgpu::TexelCopyTextureInfo {
830                texture,
831                mip_level: 0,
832                origin: wgpu::Origin3d::ZERO,
833                aspect: wgpu::TextureAspect::All,
834            },
835            wgpu::TexelCopyBufferInfo {
836                buffer: &buffer,
837                layout: wgpu::TexelCopyBufferLayout {
838                    offset: 0,
839                    bytes_per_row: Some(padded),
840                    rows_per_image: Some(h),
841                },
842            },
843            wgpu::Extent3d {
844                width: w,
845                height: h,
846                depth_or_array_layers: 1,
847            },
848        );
849        self.queue.submit([encoder.finish()]);
850        let (tx, rx) = std::sync::mpsc::channel();
851        buffer.map_async(wgpu::MapMode::Read, .., move |r| {
852            let _ = tx.send(r);
853        });
854        self.device
855            .poll(wgpu::PollType::wait_indefinitely())
856            .map_err(|_| RenderError::Backend("GPU poll failed"))?;
857        rx.recv()
858            .ok()
859            .and_then(Result::ok)
860            .ok_or(RenderError::Backend("buffer mapping failed"))?;
861        let mapped = buffer
862            .get_mapped_range(..)
863            .map_err(|_| RenderError::Backend("buffer mapping failed"))?;
864        let mut out = Vec::with_capacity((row * h) as usize);
865        for y in 0..h as usize {
866            let start = y * padded as usize;
867            out.extend_from_slice(mapped.get(start..start + row as usize).unwrap_or(&[]));
868        }
869        Ok(out)
870    }
871
872    // ---- frame recording -------------------------------------------------
873
874    fn push_uniform(&mut self, u: &DrawUniform) -> u32 {
875        let offset = self.uniforms.len();
876        self.uniforms.extend_from_slice(bytemuck::bytes_of(u));
877        self.uniforms.resize(offset + self.uniform_align, 0);
878        u32::try_from(offset).unwrap_or(0)
879    }
880
881    fn push_op(ops: &mut Vec<Op>, op: Op) {
882        // Extend the previous run of the same primitive when contiguous.
883        if let Some(last) = ops.last_mut() {
884            match (last, op) {
885                (Op::Rects { start, count }, Op::Rects { start: s, count: n })
886                | (Op::Lines { start, count }, Op::Lines { start: s, count: n })
887                | (Op::Glyphs { start, count }, Op::Glyphs { start: s, count: n })
888                | (Op::Icons { start, count }, Op::Icons { start: s, count: n })
889                | (Op::Triangles { start, count }, Op::Triangles { start: s, count: n })
890                    if *start + *count == s =>
891                {
892                    *count += n;
893                    return;
894                }
895                _ => {}
896            }
897        }
898        ops.push(op);
899    }
900
901    fn rect(&mut self, ops: &mut Vec<Op>, r: RectPx, color: Rgba) {
902        let b = IBox::of_rect(r);
903        if b.is_empty() || color.a == 0 {
904            return;
905        }
906        let start = u32::try_from(self.rects.len()).unwrap_or(u32::MAX);
907        self.rects.push(RectInstance {
908            rect: [
909                b.x0 as f32,
910                b.y0 as f32,
911                (b.x1 - b.x0) as f32,
912                (b.y1 - b.y0) as f32,
913            ],
914            color: rgba(color),
915        });
916        Self::push_op(ops, Op::Rects { start, count: 1 });
917    }
918
919    /// A filled polygon as a triangle fan around its first vertex: exact for
920    /// convex polygons (all built-in drawings), like the CPU backend's
921    /// non-anti-aliased fill.
922    fn polygon(&mut self, ops: &mut Vec<Op>, pts: &[PointPx], fill: Rgba) {
923        let [first, rest @ ..] = pts else {
924            return;
925        };
926        if fill.a == 0 || rest.len() < 2 {
927            return;
928        }
929        let start = u32::try_from(self.tris.len()).unwrap_or(u32::MAX);
930        let color = rgba(fill);
931        for w in rest.windows(2) {
932            self.tris.push(TriangleInstance {
933                ab: [first.x, first.y, w[0].x, w[0].y],
934                c: [w[1].x, w[1].y],
935                color,
936            });
937        }
938        let count = u32::try_from(rest.len() - 1).unwrap_or(0);
939        Self::push_op(ops, Op::Triangles { start, count });
940    }
941
942    /// Mirrors the CPU backend: axis-aligned solid lines become pixel rects,
943    /// everything else is an anti-aliased line.
944    fn line(&mut self, ops: &mut Vec<Op>, l: LineInst) {
945        let width = l.stroke.width.0.max(1.0).round();
946        let vertical = (l.from.x - l.to.x).abs() < 1e-3;
947        let horizontal = (l.from.y - l.to.y).abs() < 1e-3;
948        if l.stroke.dash == LineDash::Solid && (vertical || horizontal) {
949            let half = width * 0.5;
950            let r = if vertical {
951                RectPx {
952                    x: l.from.x - half,
953                    y: l.from.y.min(l.to.y),
954                    w: width,
955                    h: (l.to.y - l.from.y).abs().max(1.0),
956                }
957            } else {
958                RectPx {
959                    x: l.from.x.min(l.to.x),
960                    y: l.from.y - half,
961                    w: (l.to.x - l.from.x).abs().max(1.0),
962                    h: width,
963                }
964            };
965            self.rect(ops, r, l.stroke.color);
966            return;
967        }
968        let start = u32::try_from(self.lines.len()).unwrap_or(u32::MAX);
969        self.lines.push(LineInstance {
970            ends: [l.from.x, l.from.y, l.to.x, l.to.y],
971            width,
972            dash: match l.stroke.dash {
973                LineDash::Solid => 0,
974                LineDash::Dashed => 1,
975                LineDash::Dotted => 2,
976            },
977            color: rgba(l.stroke.color),
978        });
979        Self::push_op(ops, Op::Lines { start, count: 1 });
980    }
981
982    /// Mirrors `CpuRenderer::draw_text`: same alignment, baseline and pen
983    /// rounding, same glyph bitmaps.
984    fn text_run(&mut self, ops: &mut Vec<Op>, run: &TextRun, text: &str) {
985        let font = run.style.font.0;
986        let size = run.style.size;
987        let width = self.text.width(font, text, size);
988        let m = self.text.line_metrics(font, size);
989        let x0 = match run.align {
990            TextAlign::Left => run.pos.x,
991            TextAlign::Center => run.pos.x - width * 0.5,
992            TextAlign::Right => run.pos.x - width,
993        }
994        .round();
995        let baseline = (run.pos.y + (m.ascent - m.descent) * 0.5).round();
996        if let Some(bg) = run.bg {
997            let pad = bg.padding.0;
998            self.rect(
999                ops,
1000                RectPx {
1001                    x: x0 - pad,
1002                    y: baseline - m.ascent - pad,
1003                    w: width + 2.0 * pad,
1004                    h: m.ascent + m.descent + 2.0 * pad,
1005                },
1006                bg.color,
1007            );
1008        }
1009        let mut pen = 0.0_f32;
1010        for ch in text.chars() {
1011            let gx = (x0 + pen).round() as i32;
1012            pen += self.text.advance(font, ch, size);
1013            let Some(slot) = self.atlas.get(&self.queue, &self.text, font, ch, size) else {
1014                continue;
1015            };
1016            let start = u32::try_from(self.glyphs.len()).unwrap_or(u32::MAX);
1017            self.glyphs.push(GlyphInstance {
1018                dst: [
1019                    (gx + slot.left) as f32,
1020                    (baseline as i32 + slot.top) as f32,
1021                    slot.w as f32,
1022                    slot.h as f32,
1023                ],
1024                src: [slot.x as f32, slot.y as f32],
1025                color: rgba(run.color),
1026            });
1027            Self::push_op(ops, Op::Glyphs { start, count: 1 });
1028        }
1029    }
1030
1031    fn series_draw(
1032        &mut self,
1033        ops: &mut Vec<Op>,
1034        frame: &Frame,
1035        data: ChartDataView<'_>,
1036        s: &SeriesDraw,
1037        viewport: [f32; 2],
1038    ) {
1039        if s.kind == SeriesKind::Band {
1040            self.band_draw(ops, frame, data, s, viewport);
1041            return;
1042        }
1043        let passes = SeriesPipe::passes(s.kind);
1044        let Some(view) = data.ohlc(s.series, s.lod_level) else {
1045            return;
1046        };
1047        if s.kind == SeriesKind::Volume && view.volume.is_none() {
1048            return;
1049        }
1050        let Some(style) = frame.styles.get(s.style.0 as usize).copied() else {
1051            return;
1052        };
1053        let span = s.index_range;
1054        if span.is_empty() {
1055            return;
1056        }
1057        let top = self.clips.last().copied().unwrap_or(IBox {
1058            x0: 0,
1059            y0: 0,
1060            x1: 0,
1061            y1: 0,
1062        });
1063        let clip = top.intersect(IBox::of_rect(s.clip));
1064        ops.push(Op::Scissor(clip));
1065        let yt = s.y_transform;
1066        // Volumes are drawn from their own buffer; the OHLC buffer only gives
1067        // the direction, which the linear values decide.
1068        let log = s.kind != SeriesKind::Volume && yt.mapping == PriceMapping::Log;
1069        let m = bar_metrics(s.x_transform.step);
1070        let dash = match style.line_dash {
1071            LineDash::Solid => 0,
1072            LineDash::Dashed => 1,
1073            LineDash::Dotted => 2,
1074        };
1075        let flags = u32::from(m.show_body)
1076            | (u32::from(m.show_border) << 1)
1077            | (u32::from(style.step) << 2)
1078            | (u32::from(s.kind == SeriesKind::Baseline) << 3)
1079            | (u32::from(s.kind == SeriesKind::Area) << 4)
1080            | (dash << 5);
1081        let level = view.level;
1082        let colors = (s.kind == SeriesKind::Histogram && level == 0)
1083            .then(|| data.point_colors(s.series))
1084            .flatten();
1085        let line_base = y_of_price(&yt, style.base_value);
1086        let clip_y = [s.clip.y, s.clip.y + s.clip.h];
1087        let id = s.series.0;
1088        for &pipe in passes {
1089            for c in chunk_of(level, span.start)..=chunk_of(level, span.end - 1) {
1090                let cs = chunk_start(level, c);
1091                let e0 = span.start.max(cs);
1092                let e1 = span.end.min(cs + CHUNK_LEN);
1093                if e0 >= e1 {
1094                    continue;
1095                }
1096                let gpu = self.series.entry(id).or_default();
1097                let Some(chunk) = gpu.prepare(
1098                    &self.device,
1099                    &self.queue,
1100                    &mut self.scratch,
1101                    &view,
1102                    colors,
1103                    c,
1104                    log,
1105                ) else {
1106                    continue;
1107                };
1108                let (bias, base_y) = match pipe {
1109                    SeriesPipe::Candles | SeriesPipe::OhlcBars => {
1110                        (y_bias(&yt, chunk.reference), 0.0)
1111                    }
1112                    SeriesPipe::Histogram => (y_bias(&yt, 0.0), y_of_price(&yt, 0.0)),
1113                    SeriesPipe::Fill if s.kind == SeriesKind::Area => {
1114                        (y_bias(&yt, chunk.reference), clip_y[1])
1115                    }
1116                    SeriesPipe::ValueHistogram
1117                    | SeriesPipe::Line
1118                    | SeriesPipe::Fill
1119                    | SeriesPipe::Points => (y_bias(&yt, chunk.reference), line_base),
1120                };
1121                let SeriesStyle {
1122                    up,
1123                    down,
1124                    up_wick,
1125                    down_wick,
1126                    up_border,
1127                    down_border,
1128                    fill_top,
1129                    fill_bottom,
1130                    line_width,
1131                    ..
1132                } = style;
1133                let (body, colors) = match pipe {
1134                    SeriesPipe::Line | SeriesPipe::Fill => (
1135                        line_width.0 * 0.5,
1136                        [up, down, fill_top, fill_bottom, up_border, down_border],
1137                    ),
1138                    // The dot's diameter.
1139                    SeriesPipe::Points => (
1140                        line_width.0,
1141                        [up, down, fill_top, fill_bottom, up_border, down_border],
1142                    ),
1143                    _ => (
1144                        m.body,
1145                        [up, down, up_wick, down_wick, up_border, down_border],
1146                    ),
1147                };
1148                let uniform = self.push_uniform(&DrawUniform {
1149                    viewport,
1150                    x_step: s.x_transform.step,
1151                    x_shift: x_shift(&s.x_transform),
1152                    a: yt.a,
1153                    bias,
1154                    index_offset: i32::try_from(e0 - s.x_transform.base).unwrap_or(0),
1155                    body,
1156                    flags,
1157                    base_y,
1158                    clip_y,
1159                    colors: colors.map(rgba_f),
1160                });
1161                ops.push(Op::Series {
1162                    pipe,
1163                    series: id,
1164                    level,
1165                    chunk: c,
1166                    elem: e0 - cs,
1167                    count: u32::try_from(e1 - e0).unwrap_or(0),
1168                    uniform,
1169                    log,
1170                });
1171            }
1172        }
1173        let top = self.clips.last().copied().unwrap_or(clip);
1174        ops.push(Op::Scissor(top));
1175    }
1176
1177    /// A band: the upper and lower series' chunks drawn together,
1178    /// each with its own reference price (`bias` and `base_y` of the uniform).
1179    fn band_draw(
1180        &mut self,
1181        ops: &mut Vec<Op>,
1182        frame: &Frame,
1183        data: ChartDataView<'_>,
1184        s: &SeriesDraw,
1185        viewport: [f32; 2],
1186    ) {
1187        let Some(pair) = s.pair else { return };
1188        let (Some(upper), Some(lower)) = (
1189            data.ohlc(s.series, s.lod_level),
1190            data.ohlc(pair, s.lod_level),
1191        ) else {
1192            return;
1193        };
1194        let Some(style) = frame.styles.get(s.style.0 as usize).copied() else {
1195            return;
1196        };
1197        let span = s.index_range;
1198        if span.is_empty() {
1199            return;
1200        }
1201        let top = self.clips.last().copied().unwrap_or(IBox {
1202            x0: 0,
1203            y0: 0,
1204            x1: 0,
1205            y1: 0,
1206        });
1207        let clip = top.intersect(IBox::of_rect(s.clip));
1208        ops.push(Op::Scissor(clip));
1209        let yt = s.y_transform;
1210        let log = yt.mapping == PriceMapping::Log;
1211        let level = upper.level;
1212        let clip_y = [s.clip.y, s.clip.y + s.clip.h];
1213        let (id, pair) = (s.series.0, pair.0);
1214        for c in chunk_of(level, span.start)..=chunk_of(level, span.end - 1) {
1215            let cs = chunk_start(level, c);
1216            let e0 = span.start.max(cs);
1217            let e1 = span.end.min(cs + CHUNK_LEN);
1218            if e0 >= e1 {
1219                continue;
1220            }
1221            let mut reference = |series: u32, view: &OhlcLevelView<'_>| {
1222                self.series
1223                    .entry(series)
1224                    .or_default()
1225                    .prepare(
1226                        &self.device,
1227                        &self.queue,
1228                        &mut self.scratch,
1229                        view,
1230                        None,
1231                        c,
1232                        log,
1233                    )
1234                    .map(|chunk| chunk.reference)
1235            };
1236            let (Some(ru), Some(rl)) = (reference(id, &upper), reference(pair, &lower)) else {
1237                continue;
1238            };
1239            let st = style;
1240            let colors = [
1241                st.up,
1242                st.down,
1243                st.fill_top,
1244                st.fill_bottom,
1245                st.up_border,
1246                st.down_border,
1247            ];
1248            let uniform = self.push_uniform(&DrawUniform {
1249                viewport,
1250                x_step: s.x_transform.step,
1251                x_shift: x_shift(&s.x_transform),
1252                a: yt.a,
1253                bias: y_bias(&yt, ru),
1254                index_offset: i32::try_from(e0 - s.x_transform.base).unwrap_or(0),
1255                body: 0.0,
1256                flags: 0,
1257                // The lower series' bias (`y_lower` in the shader).
1258                base_y: y_bias(&yt, rl),
1259                clip_y,
1260                colors: colors.map(rgba_f),
1261            });
1262            ops.push(Op::Band {
1263                upper: id,
1264                lower: pair,
1265                level,
1266                chunk: c,
1267                elem: e0 - cs,
1268                count: u32::try_from(e1 - e0).unwrap_or(0),
1269                uniform,
1270                log,
1271            });
1272        }
1273        let top = self.clips.last().copied().unwrap_or(clip);
1274        ops.push(Op::Scissor(top));
1275    }
1276
1277    fn record_layer(
1278        &mut self,
1279        ops: &mut Vec<Op>,
1280        frame: &Frame,
1281        layer: &Layer,
1282        data: ChartDataView<'_>,
1283        full: IBox,
1284        viewport: [f32; 2],
1285    ) {
1286        self.clips.clear();
1287        self.clips.push(full);
1288        ops.push(Op::Scissor(full));
1289        let pools = &frame.pools;
1290        for cmd in &layer.cmds {
1291            match *cmd {
1292                DrawCmd::PushClip(r) => {
1293                    let top = self.clips.last().copied().unwrap_or(full);
1294                    let b = top.intersect(IBox::of_rect(r));
1295                    self.clips.push(b);
1296                    ops.push(Op::Scissor(b));
1297                }
1298                DrawCmd::PopClip if self.clips.len() > 1 => {
1299                    self.clips.pop();
1300                    ops.push(Op::Scissor(self.clips.last().copied().unwrap_or(full)));
1301                }
1302                DrawCmd::Rects(span) => {
1303                    for r in pools.rects.get(span.range()).unwrap_or(&[]) {
1304                        self.rect(ops, r.rect, r.color);
1305                    }
1306                }
1307                DrawCmd::Lines(span) => {
1308                    for l in pools.lines.get(span.range()).unwrap_or(&[]) {
1309                        self.line(ops, *l);
1310                    }
1311                }
1312                DrawCmd::Polyline { points, style } => {
1313                    let pts = pools.points.get(points.range()).unwrap_or(&[]);
1314                    for w in pts.windows(2) {
1315                        self.line(
1316                            ops,
1317                            LineInst {
1318                                from: w[0],
1319                                to: w[1],
1320                                stroke: style,
1321                            },
1322                        );
1323                    }
1324                }
1325                DrawCmd::Text(span) => {
1326                    for run in pools.text_runs.get(span.range()).unwrap_or(&[]) {
1327                        let text = pools.text.get(run.text.range()).unwrap_or("");
1328                        self.text_run(ops, run, text);
1329                    }
1330                }
1331                DrawCmd::Series(s) => self.series_draw(ops, frame, data, &s, viewport),
1332                DrawCmd::Icon(span) => {
1333                    for icon in pools.icons.get(span.range()).unwrap_or(&[]) {
1334                        if icon.color.a == 0 || icon.size.0 <= 0.0 {
1335                            continue;
1336                        }
1337                        let start = u32::try_from(self.icons.len()).unwrap_or(u32::MAX);
1338                        self.icons.push(IconInstance {
1339                            pos: [icon.pos.x, icon.pos.y],
1340                            size: icon.size.0,
1341                            icon: u32::from(icon.icon),
1342                            color: rgba(icon.color),
1343                        });
1344                        Self::push_op(ops, Op::Icons { start, count: 1 });
1345                    }
1346                }
1347                DrawCmd::Polygon { points, fill } => {
1348                    let pts = pools.points.get(points.range()).unwrap_or(&[]);
1349                    self.polygon(ops, pts, fill);
1350                }
1351                DrawCmd::Custom(c) => {
1352                    let Some(n) = self.native_kinds.iter().position(|&k| k == c.kind) else {
1353                        continue;
1354                    };
1355                    let ctx = GpuSeriesCtx {
1356                        device: &self.device,
1357                        queue: &self.queue,
1358                        format: self.format,
1359                        viewport,
1360                        frame,
1361                    };
1362                    self.gpu_series[n].prepare(&ctx, &c, &data);
1363                    let draw = u32::try_from(self.custom_draws.len()).unwrap_or(u32::MAX);
1364                    self.custom_draws.push(c);
1365                    ops.push(Op::Custom {
1366                        plugin: u32::try_from(n).unwrap_or(u32::MAX),
1367                        draw,
1368                    });
1369                }
1370                // Unbalanced pops are ignored.
1371                DrawCmd::PopClip => {}
1372            }
1373        }
1374    }
1375
1376    fn replay(&self, pass: &mut wgpu::RenderPass<'_>, ops: &[Op], size: (u32, u32)) {
1377        let mut skip = false;
1378        for op in ops {
1379            match *op {
1380                Op::Scissor(b) => {
1381                    let b = b.intersect(IBox {
1382                        x0: 0,
1383                        y0: 0,
1384                        x1: size.0 as i32,
1385                        y1: size.1 as i32,
1386                    });
1387                    skip = b.is_empty();
1388                    if !skip {
1389                        pass.set_scissor_rect(
1390                            b.x0 as u32,
1391                            b.y0 as u32,
1392                            (b.x1 - b.x0) as u32,
1393                            (b.y1 - b.y0) as u32,
1394                        );
1395                    }
1396                }
1397                _ if skip => {}
1398                Op::Custom { plugin, draw } => {
1399                    if let (Some(p), Some(d)) = (
1400                        self.gpu_series.get(plugin as usize),
1401                        self.custom_draws.get(draw as usize),
1402                    ) {
1403                        p.draw(pass, d);
1404                    }
1405                }
1406                Op::Rects { start, count } => {
1407                    pass.set_pipeline(&self.pipelines.rects);
1408                    pass.set_bind_group(0, &self.uniform_bind, &[0]);
1409                    let stride = core::mem::size_of::<RectInstance>() as u64;
1410                    pass.set_vertex_buffer(
1411                        0,
1412                        self.rect_buf.buffer.slice(u64::from(start) * stride..),
1413                    );
1414                    pass.draw(0..6, 0..count);
1415                }
1416                Op::Lines { start, count } => {
1417                    pass.set_pipeline(&self.pipelines.lines);
1418                    pass.set_bind_group(0, &self.uniform_bind, &[0]);
1419                    let stride = core::mem::size_of::<LineInstance>() as u64;
1420                    pass.set_vertex_buffer(
1421                        0,
1422                        self.line_buf.buffer.slice(u64::from(start) * stride..),
1423                    );
1424                    pass.draw(0..6, 0..count);
1425                }
1426                Op::Icons { start, count } => {
1427                    pass.set_pipeline(&self.pipelines.icons);
1428                    pass.set_bind_group(0, &self.uniform_bind, &[0]);
1429                    let stride = core::mem::size_of::<IconInstance>() as u64;
1430                    pass.set_vertex_buffer(
1431                        0,
1432                        self.icon_buf.buffer.slice(u64::from(start) * stride..),
1433                    );
1434                    pass.draw(0..6, 0..count);
1435                }
1436                Op::Triangles { start, count } => {
1437                    pass.set_pipeline(&self.pipelines.triangles);
1438                    pass.set_bind_group(0, &self.uniform_bind, &[0]);
1439                    let stride = core::mem::size_of::<TriangleInstance>() as u64;
1440                    pass.set_vertex_buffer(
1441                        0,
1442                        self.tri_buf.buffer.slice(u64::from(start) * stride..),
1443                    );
1444                    pass.draw(0..3, 0..count);
1445                }
1446                Op::Glyphs { start, count } => {
1447                    pass.set_pipeline(&self.pipelines.glyphs);
1448                    pass.set_bind_group(0, &self.uniform_bind, &[0]);
1449                    pass.set_bind_group(1, &self.atlas_bind, &[]);
1450                    let stride = core::mem::size_of::<GlyphInstance>() as u64;
1451                    pass.set_vertex_buffer(
1452                        0,
1453                        self.glyph_buf.buffer.slice(u64::from(start) * stride..),
1454                    );
1455                    pass.draw(0..6, 0..count);
1456                }
1457                Op::Band {
1458                    upper,
1459                    lower,
1460                    level,
1461                    chunk,
1462                    elem,
1463                    count,
1464                    uniform,
1465                    log,
1466                } => {
1467                    let buffers = |series: u32| {
1468                        let c = self.series.get(&series)?.chunk(level, chunk)?;
1469                        if log { c.ln.as_ref() } else { Some(&c.ohlc) }
1470                    };
1471                    let (Some(u), Some(l)) = (buffers(upper), buffers(lower)) else {
1472                        continue;
1473                    };
1474                    pass.set_bind_group(0, &self.uniform_bind, &[uniform]);
1475                    pass.set_pipeline(&self.pipelines.band);
1476                    // Elements j and j + 1 of both series.
1477                    pass.set_vertex_buffer(0, u.slice(ohlc_offset(0, elem)..));
1478                    pass.set_vertex_buffer(1, u.slice(ohlc_offset(0, elem + 1)..));
1479                    pass.set_vertex_buffer(2, l.slice(ohlc_offset(0, elem)..));
1480                    pass.set_vertex_buffer(3, l.slice(ohlc_offset(0, elem + 1)..));
1481                    pass.draw(0..6, 0..count);
1482                }
1483                Op::Series {
1484                    pipe,
1485                    series,
1486                    level,
1487                    chunk,
1488                    elem,
1489                    count,
1490                    uniform,
1491                    log,
1492                } => {
1493                    let Some(c) = self.series.get(&series).and_then(|s| s.chunk(level, chunk))
1494                    else {
1495                        continue;
1496                    };
1497                    let prices = if log { c.ln.as_ref() } else { Some(&c.ohlc) };
1498                    let Some(prices) = prices else {
1499                        continue;
1500                    };
1501                    pass.set_bind_group(0, &self.uniform_bind, &[uniform]);
1502                    pass.set_vertex_buffer(0, prices.slice(ohlc_offset(0, elem)..));
1503                    match pipe {
1504                        SeriesPipe::Candles => {
1505                            pass.set_pipeline(&self.pipelines.candles);
1506                            pass.draw(0..12, 0..count);
1507                        }
1508                        SeriesPipe::OhlcBars => {
1509                            pass.set_pipeline(&self.pipelines.ohlc_bars);
1510                            pass.draw(0..18, 0..count);
1511                        }
1512                        SeriesPipe::ValueHistogram => {
1513                            let colors = c.colors.as_ref().unwrap_or(&self.zero_colors);
1514                            pass.set_pipeline(&self.pipelines.value_histogram);
1515                            pass.set_vertex_buffer(1, colors.slice(value_offset(0, elem)..));
1516                            pass.draw(0..6, 0..count);
1517                        }
1518                        SeriesPipe::Points => {
1519                            pass.set_pipeline(&self.pipelines.points);
1520                            pass.draw(0..6, 0..count);
1521                        }
1522                        SeriesPipe::Line | SeriesPipe::Fill => {
1523                            // Element j + 1 (the junction element for the last).
1524                            pass.set_vertex_buffer(1, prices.slice(ohlc_offset(0, elem + 1)..));
1525                            if pipe == SeriesPipe::Line {
1526                                pass.set_pipeline(&self.pipelines.line_series);
1527                                pass.draw(0..18, 0..count);
1528                            } else {
1529                                pass.set_pipeline(&self.pipelines.fill_series);
1530                                pass.draw(0..6, 0..count);
1531                            }
1532                        }
1533                        SeriesPipe::Histogram => {
1534                            let Some(vol) = &c.volume else {
1535                                continue;
1536                            };
1537                            pass.set_pipeline(&self.pipelines.histogram);
1538                            pass.set_vertex_buffer(1, vol.slice(value_offset(0, elem)..));
1539                            pass.draw(0..6, 0..count);
1540                        }
1541                    }
1542                }
1543            }
1544        }
1545    }
1546
1547    /// Draws `frame` into `target`.
1548    fn render_into(
1549        &mut self,
1550        frame: &Frame,
1551        data: ChartDataView<'_>,
1552        target: &wgpu::TextureView,
1553        size: (u32, u32),
1554    ) {
1555        // Pull data changes for every series drawn in this frame.
1556        for layer in &frame.layers {
1557            for cmd in &layer.cmds {
1558                if let DrawCmd::Series(s) = cmd {
1559                    for id in core::iter::once(s.series).chain(s.pair) {
1560                        self.series.entry(id.0).or_default().sync(data, id);
1561                    }
1562                }
1563            }
1564        }
1565        self.ensure_cache(size);
1566        let revisions = (frame.layers[0].revision, frame.layers[1].revision);
1567        let cache_valid = self
1568            .cache
1569            .as_ref()
1570            .is_some_and(|c| c.revisions == Some(revisions));
1571
1572        self.uniforms.clear();
1573        self.custom_draws.clear();
1574        self.rects.clear();
1575        self.lines.clear();
1576        self.icons.clear();
1577        self.tris.clear();
1578        self.glyphs.clear();
1579        let viewport = [size.0 as f32, size.1 as f32];
1580        self.push_uniform(&DrawUniform {
1581            viewport,
1582            ..DrawUniform::default()
1583        });
1584        let full = IBox {
1585            x0: 0,
1586            y0: 0,
1587            x1: size.0 as i32,
1588            y1: size.1 as i32,
1589        };
1590        let mut main_ops = std::mem::take(&mut self.main_ops);
1591        let mut overlay_ops = std::mem::take(&mut self.overlay_ops);
1592        main_ops.clear();
1593        overlay_ops.clear();
1594        if !cache_valid {
1595            for layer in &frame.layers[..2] {
1596                self.record_layer(&mut main_ops, frame, layer, data, full, viewport);
1597            }
1598        }
1599        self.record_layer(
1600            &mut overlay_ops,
1601            frame,
1602            &frame.layers[2],
1603            data,
1604            full,
1605            viewport,
1606        );
1607
1608        if self
1609            .uniform_buf
1610            .write(&self.device, &self.queue, &self.uniforms)
1611        {
1612            self.uniform_bind =
1613                Self::uniform_bind(&self.device, &self.pipelines, &self.uniform_buf.buffer);
1614        }
1615        self.rect_buf
1616            .write(&self.device, &self.queue, bytemuck::cast_slice(&self.rects));
1617        self.line_buf
1618            .write(&self.device, &self.queue, bytemuck::cast_slice(&self.lines));
1619        self.icon_buf
1620            .write(&self.device, &self.queue, bytemuck::cast_slice(&self.icons));
1621        self.tri_buf
1622            .write(&self.device, &self.queue, bytemuck::cast_slice(&self.tris));
1623        self.glyph_buf.write(
1624            &self.device,
1625            &self.queue,
1626            bytemuck::cast_slice(&self.glyphs),
1627        );
1628
1629        let mut encoder = self
1630            .device
1631            .create_command_encoder(&wgpu::CommandEncoderDescriptor {
1632                label: Some("ferrochart frame"),
1633            });
1634        if let Some(cache) = &self.cache {
1635            if !cache_valid {
1636                let c = frame.clear_color;
1637                let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1638                    label: Some("ferrochart main layers"),
1639                    color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1640                        view: &cache.view,
1641                        depth_slice: None,
1642                        resolve_target: None,
1643                        ops: wgpu::Operations {
1644                            load: wgpu::LoadOp::Clear(wgpu::Color {
1645                                r: f64::from(c.r) / 255.0,
1646                                g: f64::from(c.g) / 255.0,
1647                                b: f64::from(c.b) / 255.0,
1648                                a: f64::from(c.a) / 255.0,
1649                            }),
1650                            store: wgpu::StoreOp::Store,
1651                        },
1652                    })],
1653                    depth_stencil_attachment: None,
1654                    timestamp_writes: None,
1655                    occlusion_query_set: None,
1656                    multiview_mask: None,
1657                });
1658                self.replay(&mut pass, &main_ops, size);
1659            }
1660            let mut pass = encoder.begin_render_pass(&wgpu::RenderPassDescriptor {
1661                label: Some("ferrochart composite + overlay"),
1662                color_attachments: &[Some(wgpu::RenderPassColorAttachment {
1663                    view: target,
1664                    depth_slice: None,
1665                    resolve_target: None,
1666                    ops: wgpu::Operations {
1667                        load: wgpu::LoadOp::Clear(wgpu::Color::BLACK),
1668                        store: wgpu::StoreOp::Store,
1669                    },
1670                })],
1671                depth_stencil_attachment: None,
1672                timestamp_writes: None,
1673                occlusion_query_set: None,
1674                multiview_mask: None,
1675            });
1676            pass.set_pipeline(&self.pipelines.composite);
1677            pass.set_bind_group(0, &self.uniform_bind, &[0]);
1678            pass.set_bind_group(1, &cache.bind, &[]);
1679            pass.draw(0..3, 0..1);
1680            self.replay(&mut pass, &overlay_ops, size);
1681        }
1682        self.queue.submit([encoder.finish()]);
1683        if let Some(cache) = &mut self.cache {
1684            cache.revisions = Some(revisions);
1685        }
1686        self.main_ops = main_ops;
1687        self.overlay_ops = overlay_ops;
1688    }
1689}
1690
1691impl WgpuRenderer {
1692    fn result(&self) -> Result<(), RenderError> {
1693        if self.has_gpu_error() {
1694            return Err(RenderError::Backend("GPU error (see take_gpu_error)"));
1695        }
1696        Ok(())
1697    }
1698}
1699
1700fn target_size(size: SizePx) -> Result<(u32, u32), RenderError> {
1701    let (w, h) = (size.w.round(), size.h.round());
1702    if !(w >= 1.0 && h >= 1.0 && w <= MAX_SIZE && h <= MAX_SIZE) {
1703        return Err(RenderError::InvalidSize);
1704    }
1705    Ok((w as u32, h as u32))
1706}
1707
1708impl Renderer for WgpuRenderer {
1709    fn render(&mut self, frame: &Frame, data: &ChartDataView<'_>) -> Result<(), RenderError> {
1710        let size = target_size(frame.size_px)?;
1711        if let Target::Surface { .. } = self.target {
1712            self.reconfigure(size);
1713            let Target::Surface {
1714                surface,
1715                view_format,
1716                ..
1717            } = &self.target
1718            else {
1719                return Err(RenderError::InvalidSize);
1720            };
1721            let texture = match surface.get_current_texture() {
1722                wgpu::CurrentSurfaceTexture::Success(t)
1723                | wgpu::CurrentSurfaceTexture::Suboptimal(t) => t,
1724                wgpu::CurrentSurfaceTexture::Outdated | wgpu::CurrentSurfaceTexture::Lost => {
1725                    if let Target::Surface {
1726                        surface, config, ..
1727                    } = &self.target
1728                    {
1729                        surface.configure(&self.device, config);
1730                    }
1731                    return Err(RenderError::Backend("surface outdated; reconfigured"));
1732                }
1733                wgpu::CurrentSurfaceTexture::Timeout | wgpu::CurrentSurfaceTexture::Occluded => {
1734                    return Err(RenderError::Backend("surface not available"));
1735                }
1736                wgpu::CurrentSurfaceTexture::Validation => {
1737                    return Err(RenderError::Backend("surface validation error"));
1738                }
1739            };
1740            let view = texture.texture.create_view(&wgpu::TextureViewDescriptor {
1741                format: Some(*view_format),
1742                ..wgpu::TextureViewDescriptor::default()
1743            });
1744            self.render_into(frame, *data, &view, size);
1745            self.queue.present(texture);
1746            return self.result();
1747        }
1748        self.ensure_offscreen(size);
1749        let Target::Offscreen { view, .. } = &self.target else {
1750            return Err(RenderError::InvalidSize);
1751        };
1752        let view = view.clone();
1753        self.render_into(frame, *data, &view, size);
1754        self.result()
1755    }
1756
1757    fn resize(&mut self, size: SizePx) {
1758        if let Ok(size) = target_size(size) {
1759            match self.target {
1760                Target::Surface { .. } => self.reconfigure(size),
1761                _ => self.ensure_offscreen(size),
1762            }
1763        }
1764    }
1765
1766    fn native_kinds(&self) -> &[&'static str] {
1767        &self.native_kinds
1768    }
1769}