---
title: "Interactive benchmark metrics with ggWebGL"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Interactive benchmark metrics with ggWebGL}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r, include = FALSE}
knitr::opts_chunk$set(collapse = TRUE, comment = "#>")

if (file.exists("DESCRIPTION") && requireNamespace("pkgload", quietly = TRUE)) {
  pkgload::load_all(".", export_all = FALSE, helpers = FALSE, quiet = TRUE)
} else if (file.exists("../DESCRIPTION") && requireNamespace("pkgload", quietly = TRUE)) {
  pkgload::load_all("..", export_all = FALSE, helpers = FALSE, quiet = TRUE)
} else {
  library(ggWebGL)
}

benchmark_candidates <- c(
  "inst/benchmarks/benchmark-scene-types.R",
  file.path("..", "inst", "benchmarks", "benchmark-scene-types.R"),
  system.file("benchmarks", "benchmark-scene-types.R", package = "ggWebGL")
)
benchmark_candidates <- benchmark_candidates[nzchar(benchmark_candidates) & file.exists(benchmark_candidates)]
if (!length(benchmark_candidates)) {
  stop("Could not find benchmark-scene-types.R")
}
sys.source(benchmark_candidates[[1L]], envir = knitr::knit_global())

workflow_candidates <- c(
  "inst/examples/htmlwidget/workflow-comparison.R",
  file.path("..", "inst", "examples", "htmlwidget", "workflow-comparison.R"),
  system.file("examples", "htmlwidget", "workflow-comparison.R", package = "ggWebGL")
)
workflow_candidates <- workflow_candidates[nzchar(workflow_candidates) & file.exists(workflow_candidates)]
if (!length(workflow_candidates)) {
  stop("Could not find workflow-comparison.R")
}
sys.source(workflow_candidates[[1L]], envir = knitr::knit_global())
```

# Purpose

`ggWebGL` includes manual benchmark helpers for measuring browser rendering
behavior across representative scene types. These helpers are diagnostic: rows
without browser metadata are not complete browser measurements, and fixed
performance numbers should not be reported from incomplete rows.

**Status.** Compact transport, progressive upload metadata, and browser metric
helpers are `Experimental` diagnostics. They support local measurement and
smoke testing, not public fixed-FPS claims.

The benchmark scripts are not run automatically by package checks. They write
only to an explicit `output_dir` or `tempdir()`.

# Metric Schema

The scene benchmark helper records a stable set of columns so local browser
runs can be compared without changing downstream analysis code.

```{r benchmark-columns}
benchmark_scene_columns()
```

The most important groups are:

- scene identity and package metadata;
- payload and artifact sizes;
- startup and browser frame timings;
- browser, device, GPU, and pixel-size metadata;
- artifact paths and completion status.

# Manual Dense Embedding Run

The dense embedding helper builds a deterministic million-point scene using
compact point transport, progressive upload metadata, the `density_splat`
shader, and rectangular brush selection.

```{r dense-benchmark-command, eval = FALSE}
source(system.file("examples", "htmlwidget", "million-point-embedding.R", package = "ggWebGL"))
run_manual_million_point_embedding()
```

# Scene-Type Metrics

Use `benchmark_scene_types()` to produce a CSV with one row per scene. Browser
metrics are populated only when a browser capture path is explicitly requested
and available.

```{r scene-type-command, eval = FALSE}
source(system.file("benchmarks", "benchmark-scene-types.R", package = "ggWebGL"))
metrics <- benchmark_scene_types(
  output_dir = tempdir(),
  scenes = c("embedding", "trajectories", "surface_mesh", "workflow"),
  point_count = 1000000L,
  include_browser = FALSE
)
metrics[, c("scene_id", "serialized_bytes", "artifact_bytes", "status")]
```

# Workflow Comparison

A useful smoke check is whether the same data mapping can be inspected both as a
static `ggplot2` graphic and as a browser-native WebGL widget. The reduced
example below uses deterministic in-memory data.

```{r workflow-static, fig.width=6, fig.height=4}
workflow_comparison_plot(800L)
```

```{r workflow-webgl, out.width='100%'}
workflow_comparison_widget(800L, height = 360)
```

# Interpreting Results

Rows with `status = "browser_skipped"` are useful for checking payload size and
widget artifact size only. Browser timing fields should be interpreted only
when the row includes browser, GPU, device, and pixel-size metadata from the
machine that performed the run.