# Core ggplot-like WebGL layers

This vignette covers the core two-dimensional `ggplot2`-style layers and the renderer-ready specification workflow. The code examples construct `ggplot2`-style WebGL layers and, when evaluated, convert them into browser-side WebGL htmlwidgets with `ggplot_webgl()` or `ggWebGL()`.

Code evaluation is disabled during CRAN, package checks, and CI unless explicitly enabled with `GGWEBGL_EVAL_COVERAGE_VIGNETTE=true` or `NOT_CRAN=true`. Live WebGL widget rendering is additionally disabled unless `GGWEBGL_EVAL_LIVE_WIDGETS=true` is set. Rich local or pkgdown builds should set both `GGWEBGL_EVAL_COVERAGE_VIGNETTE=true` and `GGWEBGL_EVAL_LIVE_WIDGETS=true`.

> Example chunks are shown but not evaluated in this build. Set `GGWEBGL_EVAL_COVERAGE_VIGNETTE=true` or `NOT_CRAN=true` to evaluate them during a local non-CI render.

# Two Workflows

## Applet: Grammar-style points and lines

    p <- ggplot(mtcars, aes(wt, mpg, colour = factor(cyl))) +
      geom_point_webgl() +
      geom_line_webgl(aes(group = cyl), alpha = 0.35) +
      labs(title = "Grammar-style points and lines") +
      theme_webgl(shader = "density_splat")

    ggplot_webgl(p, height = 420)

## Applet: Renderer-ready point specification

Renderer-ready specifications are useful when data have already been transformed into primitive payloads.

    spec <- ggwebgl_spec(
      layers = list(
        ggwebgl_layer_points(mtcars, x = "wt", y = "mpg", colour = "#2563eb")
      ),
      labels = list(title = "Renderer-ready point specification"),
      webgl = webgl_spec(shader = "density_splat")
    )

    ggWebGL(spec)

# Coverage Summary

Family | Public APIs | Status | Notes
--- | --- | --- | ---
Points | `geom_point_webgl()` | Stable | Core scatter and dense point rendering.
Lines and paths | `geom_line_webgl()`, `geom_path_webgl()`, `geom_path3d_webgl()` | Stable / Experimental | Two-dimensional line/path rendering is core; 3D paths are experimental.
Segments and vectors | `geom_segment_webgl()`, `geom_vector_webgl()` | Stable / Experimental | Segments are plain line segments; vectors add arrow-oriented metadata.
Rectangles and tiles | `geom_rect_webgl()`, `geom_tile_webgl()` | Stable | Uses `ggplot2`-built rectangle bounds.
Count and bin geoms | `geom_bar_webgl()`, `geom_histogram_webgl()`, `geom_bin2d_webgl()` | Experimental | Counts and bins are computed by `ggplot2`; WebGL serialization is newer than core point/line/raster paths.
Curves and contours | `geom_freqpoly_webgl()`, `geom_density_webgl()`, `geom_density2d_webgl()`, `geom_contour_webgl()` | Experimental | Rendered as line/path primitives; see the statistical coverage vignette.

Status labels reflect API maturity, test coverage, and rendering-contract stability; they are not simply an export list.

# Core 2D Layers

## Applet: Ordered 2D path with segments

    trajectory <- data.frame(
      x = cos(seq(0, 2 * pi, length.out = 48)) * seq(0.2, 1, length.out = 48),
      y = sin(seq(0, 2 * pi, length.out = 48)) * seq(0.2, 1, length.out = 48),
      frame = seq_len(48),
      group = "spiral"
    )

    arrows <- data.frame(
      x = c(-0.8, -0.2, 0.4),
      y = c(-0.6, 0.1, 0.5),
      xend = c(-0.45, 0.15, 0.75),
      yend = c(-0.25, 0.35, 0.2)
    )

    p <- ggplot(trajectory, aes(x, y, group = group)) +
      geom_path_webgl(aes(frame = frame), colour = "#2563eb", linewidth = 1.2) +
      geom_point_webgl(aes(frame = frame), colour = "#0f766e", size = 1.8) +
      geom_segment_webgl(
        data = arrows,
        aes(x = x, y = y, xend = xend, yend = yend),
        inherit.aes = FALSE,
        colour = "#334155"
      ) +
      labs(title = "Ordered 2D path with segments")

    ggplot_webgl(p, height = 420)

## Applet: Line sorting versus path order

`geom_line_webgl()` keeps the usual line semantics, while `geom_path_webgl()` preserves row order within groups.

    ordered <- data.frame(
      x = c(3, 1, 2, 4),
      y = c(1, 3, 2, 4),
      group = "ordered"
    )

    p <- ggplot(ordered, aes(x, y, group = group)) +
      geom_line_webgl(colour = "#64748b") +
      geom_path_webgl(colour = "#dc2626", linewidth = 1.2) +
      labs(title = "Line sorting versus path order")

    ggplot_webgl(p, height = 420)

# Rectangles, Tiles, and Bins

Rectangle-style geoms use boundaries computed by `ggplot2::ggplot_build()`. This keeps position adjustments and statistical transformations owned by `ggplot2`.

## Applet: Tile grid

    tile_grid <- expand.grid(
      x = seq_len(5),
      y = seq_len(4),
      KEEP.OUT.ATTRS = FALSE
    )
    tile_grid$value <- with(tile_grid, sin(x / 2) + cos(y / 2))

    p <- ggplot(tile_grid, aes(x, y, fill = value)) +
      geom_tile_webgl(alpha = 0.85) +
      labs(title = "Tile grid")
    ggplot_webgl(p, height = 420)

## Applet: Stacked bar counts

    p <- ggplot(mtcars, aes(factor(cyl), fill = factor(am))) +
      geom_bar_webgl(position = "stack") +
      labs(title = "Stacked bar counts")
    ggplot_webgl(p, height = 420)

## Applet: Histogram bins

    p <- ggplot(mtcars, aes(mpg)) +
      geom_histogram_webgl(binwidth = 4) +
      labs(title = "Histogram bins")
    ggplot_webgl(p, height = 420)

## Applet: Two-dimensional bins

    p <- ggplot(mtcars, aes(wt, mpg)) +
      geom_bin2d_webgl(bins = 8) +
      labs(title = "Two-dimensional bins")
    ggplot_webgl(p, height = 420)

## Applet: Explicit rectangles

    rectangles <- data.frame(
      xmin = c(0.0, 1.2),
      xmax = c(1.0, 2.0),
      ymin = c(0.0, 0.4),
      ymax = c(0.8, 1.4),
      label = c("a", "b")
    )

    p <- ggplot(rectangles) +
      geom_rect_webgl(
        aes(xmin = xmin, xmax = xmax, ymin = ymin, ymax = ymax, fill = label),
        alpha = 0.75
      ) +
      labs(title = "Explicit rectangles")

    ggplot_webgl(p, height = 420)

# Curves and Contours

Curve and contour applets are in `vignette("ggplot-coverage-summaries", package = "ggWebGL")` so this page keeps its live widget count moderate.