pushinbr / pam-native-canvas
Retained-mode native 2D canvas for PAM Native.
Package info
github.com/push-in/pam-native-canvas
Type:pam-native-plugin
pkg:composer/pushinbr/pam-native-canvas
Requires
- php: ^8.5
- pushinbr/pam-native: ^0.8 || ^0.9 || ^0.10 || ^1.0
Requires (Dev)
- phpstan/phpstan: ^2.1
- pushinbr/pam-native-plugin-kit: ^0.2.0
Suggests
None
Provides
None
Conflicts
None
Replaces
None
This package is auto-updated.
Last update: 2026-11-10 00:30:36 UTC
README
Retained-mode 2D graphics built for native frame budgets.
Compose drawing surfaces, paths, paints and interactions without shipping a WebView or replaying a PHP scene every frame.
Install · Quick example · Platforms · Reference · Docs · Issues
Install
Inside a PAM Native project, add only this capability:
pam composer require pushinbr/pam-native-canvas pam doctor --fix
New to PAM? Create a project with pam init my-app --template native (see the PAM Native overview), then come back here. Composer owns the manifest and the lockfile; pam composer runs it on PAM's verified PHP runtime.
Quick example
A line chart with a gradient area, a 2dp curve, a dashed baseline and aligned labels:
use Pam\Native\Canvas\Canvas; use Pam\Native\Canvas\CanvasView; use Pam\Native\Canvas\FontWeight; use Pam\Native\Canvas\Path; use Pam\Native\Canvas\PathMode; use Pam\Native\Canvas\TextAlign; $line = Path::start(0, 120) ->curveTo(40, 120, 60, 40, 100, 40) ->curveTo(140, 40, 160, 90, 200, 90) ->curveTo(240, 90, 260, 20, 300, 20); $area = $line->lineTo(300, 160)->lineTo(0, 160)->close(); $scene = (new Canvas()) ->dashedLine(0, 160, 300, 160, '#2c3947', 1, 4, 4) ->save() ->alpha(0.35) ->gradientPath($area, 0, 20, 0, 160, '#19c5ff', '#19c5ff00') ->restore() ->path($line, '#19c5ff', 2, PathMode::Stroke) ->circle(300, 20, 4, '#19c5ff') ->label('$1,234', 300, 10, 12, '#f4f7fa', TextAlign::Right, FontWeight::SemiBold) ->label('Mon', 0, 178, 11, '#a0adbb') ->label('Fri', 300, 178, 11, '#a0adbb', TextAlign::Right) ->scene(); return CanvasView::make($scene, revision: 1)->dp();
PHP builds a bounded display list; Android Canvas and Core Graphics render it without calling PHP for each frame.
Platform support
| Platform | Support | Notes |
|---|---|---|
| Android | API 26+ | Android Canvas |
| iOS | 15.0+ | Core Graphics, UIKit |
| PAM Native | 0.8.0 to < 2.0.0 | From pam-native.plugin.json; PHP 8.5+ |
Requirements
No runtime permissions. The plugin registers one native view, canvas.view, and declares no Android permissions or iOS usage descriptions.
What you can build
- Charts, signatures and annotation tools
- Custom controls and data visualization
- Lightweight games and interactive diagrams
This is a horizontal retained-mode 2D drawing primitive, not a UI framework, feed, application template, GPU shader engine or 3D engine. Ready-made charts (line, area, bar, donut, sparkline, progress ring) live in pushinbr/pam-native-charts, which builds on this plugin.
| Native path | Android Canvas · Core Graphics |
| Application model | Composer package + generated native integration |
| Design rule | Independent module; no feed, vertical or application template bundled |
Units and sizing
CanvasView::make($scene)->dp() (the default) draws in density-independent pixels: Android scales the canvas by the display density and iOS already draws in points. ->px() draws in raw device pixels. Pointer events (onPointer) arrive in the units the scene uses.
The view takes its size from layout like any element (class/style width and height); give it an explicit width and height and draw inside that box.
CanvasView::make($scene, revision: $tick) ->dp() ->onPointer(fn (CanvasEventKind $kind, float $x, float $y) => $this->select($x));
Bump revision whenever the scene changes so the native view redraws.
Scenes are immutable, capped at 10,000 commands, and use integer-backed command/event kinds. Angles are degrees, 0° at 12 o'clock, clockwise positive. Colors are CSS hex: #rgb, #rrggbb or #rrggbbaa; anything else throws InvalidArgumentException.
Docs
- Drawing commands: every
Canvasmethod at a glance - Command reference: every kind, its arguments, the enums,
Path, limits and pointer events - examples/ProgressRing.php: arcs with round caps and a centered label
- Contributing
- PAM Native overview
- PAM introduction
- Changelog
- Report an issue
Part of the PAM ecosystem
PAM runs PHP natively on servers, desktops and phones. This repository is one piece of it.
| PAM | PAM Desktop | PAM Native | Ecosystem |
|---|---|---|---|
| the runtime and CLI | native desktop apps in PHP | native Android and iOS apps in PHP | every official package and plugin |
Docs: push-in.github.io/pam-docs · Issues
Apache License 2.0 · Made in Brazil by Pushin