# The Definitive Guide to Graphics with Perl

Perl is not the language people reach for when they think «graphics»,
and that reputation is mostly an accident of history rather than a
statement about the tools. The raster workhorse (`Imager`) is actively
maintained and fast, the vector engine everyone else uses under the
hood (`Cairo`) has clean bindings, and there is a self-contained GUI
toolkit with its own graphics core (`Prima`) that draws to a real
window with no external toolkit to fight. What Perl has lacked is not
libraries but a single place that puts them in order, from the pixel up
to a running program.

This guide is that place, for **two dimensions**. It starts at the
theory every graphics programmer eventually needs (how a line becomes
pixels, what a color space actually is, how transparency composites),
moves through the working CPAN toolkits, and then goes one step
further than the usual tour: it uses pperl’s native FFI to reach C
graphics libraries directly, the same way pperl already reaches libgmp
to give you `Math::GMP`. It ends with two things you can run: a drawing
application and a 2D game.

This is the first version. Three dimensions, OpenGL, game engines, and
the GPU are a planned sequel, not part of this book. The final chapter
draws that line explicitly.

## Which chapter do I want?

| I want to …                                                  | Start here                                      |
|--------------------------------------------------------------|-------------------------------------------------|
| understand how pixels, paths, and color actually work        | [foundations](foundations.md)                   |
| implement a line, circle, fill, or blur myself               | [raster-algorithms](raster-algorithms.md)       |
| draw on, load, or save a bitmap image                        | [raster-imager](raster-imager.md)               |
| use a GD or ImageMagick codebase, or their specific features | [raster-gd-magick](raster-gd-magick.md)         |
| produce resolution-independent vector paths, or SVG output   | [vector-cairo-svg](vector-cairo-svg.md)         |
| read image metadata, or draw a chart                         | [metadata-and-charts](metadata-and-charts.md)   |
| draw in a live window on Linux                               | [gui-toolkits](gui-toolkits.md)                 |
| reach a C graphics library that has no CPAN binding          | [ffi-graphics-primer](ffi-graphics-primer.md)   |
| see how pperl’s shipped native `Cairo` binding works         | [ffi-cairo-showcase](ffi-cairo-showcase.md)     |
| build a real drawing application                             | [capstone-drawing-app](capstone-drawing-app.md) |
| build a real 2D game                                         | [capstone-2d-game](capstone-2d-game.md)         |
| find 3D, game engines, or a complete SDL2 binding            | [whats-next](whats-next.md)                     |

## The three arcs of this guide

- **Foundations** - [foundations](foundations.md) and
  [raster-algorithms](raster-algorithms.md). The mental model and the
  classic algorithms, written in plain Perl so you own them before any
  library hides them. Read these once; every later chapter assumes the
  vocabulary.
- **Toolkits** - the five chapters from [raster-imager](raster-imager.md)
  through [gui-toolkits](gui-toolkits.md). The working CPAN 2D stack: what
  each library is good at and where one wins over another. Each chapter
  is self-contained; reach for the one that names your problem.
- **Reaching further** - [ffi-graphics-primer](ffi-graphics-primer.md)
  onward. pperl’s native FFI, the two capstone projects, and an honest
  map of where the road currently ends.

## A note on the runtime

These chapters target `pperl`, a faithful Rust reimplementation of Perl
5.42. The CPAN modules in the toolkit chapters are used exactly as they
are on any Perl 5, and the FFI chapters use pperl’s own `Peta::FFI`,
which has no perl5 equivalent.

## Known gaps

Everything three-dimensional, every GPU-programming topic, computer
vision and image analysis, and connectors to hosted image-generation
services are out of scope for this version. They are named, with the
reason and the plan, in [what’s next](whats-next.md). The FFI chapters
also flag, at the point where it matters, which C interfaces are
reachable today and which wait on the next layer of `Peta::FFI`.

## See also

- [Auto-FFI (Peta::FFI)](../pperl-architecture/ffi.md) - the native FFI
  layer the «reaching further» arc is built on: `dlopen`, `call`, the
  type-signature codes, and the curated-binding pattern.
- [PPerl Architecture guide](../pperl-architecture/index.md) - the JIT and
  how pperl provides C-backed modules natively.