plotter/include/plot/plot/trace.hpp

// SPDX-License-Identifier: MIT
// SPDX-FileCopyrightText: 2026 Martino Ferrari

#pragma once
#include <plot/core/color.hpp>
#include <plot/core/types.hpp>
#include <plot/data/series.hpp>
#include <string>

namespace plot {

/// How a trace's geometry is gathered from its LOD pyramid. The level choice
/// is unchanged; this picks what a bucket contributes (see
/// `data::GatherMode`).
using TraceMode = data::GatherMode;

/// A marker shape for per-sample points. Drawn with the trace's own colour
/// through the shared line pipeline; `marker_every == 0` strides
/// automatically (one marker per pixel column at most).
enum class Marker { None, Cross, Circle, Square };

/// How a caller asks for a trace. The series pointer is borrowed and must outlive
/// the plot's use of it; `axis_x`/`axis_y` index the plot's x and y axis lists.
struct TraceDesc {
  const data::Series* series = nullptr;
  Color color = Color::hex(0x4FA3FF);
  /// The stroke's width in **logical** pixels, like every stroke in `Style` (see
  /// that struct's unit rule): the renderer converts it once, so a trace has the
  /// same weight against the axis lines whatever the display's DPI. `0` draws
  /// the markers only -- a scatter trace.
  f32 width = 1.5f;
  u32 axis_x = 0, axis_y = 0;
  /// What the trace is called, for the legend. Empty means "do not list it", which
  /// is the whole cost of a legend for a caller that never names one: the trailing
  /// default is what keeps the five-field aggregate initialisation every existing
  /// caller writes -- `{&series, colour, width, axis_x, axis_y}` -- working
  /// unchanged, exactly as `AxisDesc`'s trailing format does (and, in a build with
  /// `-Wextra`, warning-clean).
  std::string name{};
  /// Downsample policy for the LOD buckets (Envelope by default).
  TraceMode mode = TraceMode::Envelope;
  /// Dash pattern in logical pixels: ink, then gap. `dash_off <= 0` (and the
  /// default) is a solid line -- no geometry is added, the dash is a
  /// fragment-shader discard.
  f32 dash_on = 0.0f;
  f32 dash_off = 0.0f;
  /// Per-sample markers (see `Marker`). `marker_every == 0` strides
  /// automatically -- at most about one marker per pixel column -- so a dense
  /// trace never stages more markers than it has columns; a positive value
  /// draws every n-th gathered sample literally.
  Marker marker = Marker::None;
  f32 marker_size_px = 3.0f;
  u32 marker_every = 0;
};

/// A series bound to a colour, width and axis pair. The series pointer may be
/// null (a trace whose data has not arrived yet): every consumer skips such a
/// trace rather than dereferencing it.
struct Trace {
  const data::Series* series = nullptr;
  Color color = Color::hex(0x4FA3FF);
  /// Logical pixels, as in `TraceDesc::width`: converted to device pixels by the
  /// renderer's one `Style::device()` call per stroke. `0` = scatter (markers
  /// only, if any).
  f32 width = 1.5f;
  u32 axis_x = 0, axis_y = 0;
  /// The legend's entry for this trace, empty when it has none. A name does not
  /// make a trace drawable: the legend lists a trace only when it is visible, so a
  /// null series is skipped there exactly as it is by every other consumer.
  std::string name{};
  /// Same fields as `TraceDesc`, applied by the renderer.
  TraceMode mode = TraceMode::Envelope;
  f32 dash_on = 0.0f;
  f32 dash_off = 0.0f;
  Marker marker = Marker::None;
  f32 marker_size_px = 3.0f;
  u32 marker_every = 0;

  /// True when the trace has a series with at least one sample to draw.
  bool visible() const noexcept { return series != nullptr && series->size() > 0; }
};

}  // namespace plot