Jonlib

An independent graphics and game-programming library written in Bend 2, working toward 100% raylib 6.0 parity.

The master plan defines the full target, implementation phases and completion gates. The API progression dashboard maps every public release-header API and supporting declaration to a work package, Bend target, dependencies and verification status. Current limited profiles remain explicitly partial.

The first implementation is a headless, owned RGBA8 image library. Its drawing algorithms are Bend source. A separate C executable runs pinned raylib as a differential test reference.

Modules

• Jonlib (jonlib.bend) ports raylib's core geometry/image/runtime surface.
• Jonmath (jonmath.bend) ports raymath and owns shared vector/matrix types.

Port names follow ray<suffix> → jon<suffix> (for example, a future raygui port is Jongui). See module names and import migration.

import Base
import ./jonlib.bend as J
import ./jonmath.bend as M

Image decoding supports shared memory/file dispatch through J.Surface.decode_image(file_type, bytes) and J.Surface.load_image(path). See supported payloads, extension aliases and bounds.

Implemented

• Packed RGBA colors and integer alpha blending.
• Image creation, clear, pixel access and independent copies.
• Clipped pixel/rectangle drawing and raylib-compatible midpoint circles.
• Fixed-point lines, vector-line rounding, filled triangles and triangle outlines.
• Unscaled image composition with clipping, tint, alpha and source preservation.
• Checked region extraction/cropping, source-rectangle drawing and exact fixed-point nearest-neighbor resizing.
• Default filtered RGBA8 resize with precision-correct coefficient normalization and alpha-aware Catmull-Rom/Mitchell filtering.
• Scaled/source-clipped image composition, including bounded fractional rectangles.
• Vector drawing variants, outlines, thick lines, fans/strips and vertex-colored triangles.
• RGBA8 color/alpha transforms, checkerboards and quarter-turn rotations.
• Alpha bounds/cropping, raw canvas resizing and square gradients.
• Checked general image rotation and power-of-two canvas expansion.
• Source-preserving channel extraction and eleven scoped pure 2D collision queries.
• Vector3 arithmetic, cross/dot products, and bounded sphere/box collision queries.
• Matrix arithmetic/inversion, binary64-input projections, view/rotation constructors, vector transforms and paired-vector orthonormalization.
• Four-component vector arithmetic and immutable float-list exports with checked length laws.
• Normalized/HSV color conversions and quaternion Hamilton-product foundations.
• Owned seeded random streams and reference-exact white-noise images.
• Radial and one-cycle linear gradient profiles with balanced owned-array generation.
• QOI decoding/encoding and real byte-file loading/export, with typed failures.
• CORE indexed/RGB24 and 40/56/108/124-byte BMP profiles with native palette, bitfield and alpha behavior; exact RGBA8 V4 export and owned raw image-file IO.
• TGA raw/RLE true-color, grayscale and indexed decoding with byte-exact default RLE export.
• Binary 8/16-bit PGM/PPM decoding with native header, maxval and little-endian sample behavior.
• Raw/PackBits PSD decoding with native channels/alpha, explicit matte arithmetic, depth rules, defaults and metadata skipping.
• Raw/pure-RLE/mixed-RLE Softimage PIC decoding with native clipping, white defaults and channel overwrite order.
• First-frame GIF decoding with offsets/interlacing, native background fills, global/local palettes, transparency and bounded LZW.
• Bounded owned GIF animations from memory/files and generic single-image fallback, with native retain/restore disposal and complete frame comparisons.
• Owned raw/scanline-RLE Radiance RGBE float images and bounded file loading, with exhaustive native F32-bit comparisons including subnormals.
• Native RGB float/RGBA8 conversion with retained owners on unsupported samples and stack-bounded large image exports.
• Exact non-NaN RGB float raw-byte import/export, including signed zero, subnormals and infinities.
• Lossless RGB float copies, flips and quarter-turn rotations with native sample-word comparisons.
• RGB float region extraction and clipped cropping with retained-owner and independent-region checks.
• Native RGB float nearest/default-filtered resizing, including RGBA8 quantization and retained rejected owners.
• RGB float canvas/POT operations preserving native sample movement, zero-fill quirks and same-size no-ops.
• RGB float tint/invert/contrast/brightness/replacement with native quantization, clamping and alpha behavior.
• Direct RGB float conversion to byte/integer formats and grayscale with verified packed-rounding boundaries.
• RGB float RAW file loading/writing with native header selection, exact words and retained owners on rejected writes.
• Bounded raw DEFLATE decompression with native empty-block semantics.
• PNG decoding across supported 1/2/4/8/16-bit formats, Adam7 and native-default CgBI.
• Byte-exact default PNG export: byte-format memory output and all seven checked image formats through file export.
• Bounded PNG/BMP/TGA/PGM/PPM/QOI file loading with native supported suffix/content detection.
• Jonmath scalar/vector/matrix/quaternion profiles with exact reference arithmetic.
• Horizontal and vertical flips.
• Conversion to Bend's Base.Image quadtree.
• P3 PPM encoding and file export through Base IO.
• Exact full-pixel differential testing, deterministic seeded scenarios, a dimension-preservation law, and ownership/adapter contract checks.
• Verified native CPU, JavaScript and Metal execution with the declared compiler overlay.

See the master plan, API, compatibility ledger, verification record, and roadmap. This is an early library: desktop interaction, textures/fonts, additional codecs, audio, 3D, and broader platform support remain future work.

Requirements

Use existing installations of Python 3.12+, Bun 1.3.12, CMake (3.25+), and clang. The local verification commands below do not install tools or download dependencies. GitHub Actions provisions its own pinned dependencies on hosted runners.

The harness requires these base revisions. Bend additionally needs the exact declared compiler overlay; raylib remains unmodified:

Dependency	Revision
Bend 2.0.27 + Jonlib Metal overlay	b7ebee9217c8813067e200b0c0c9153a3be31c5e
raylib 6.0	dbc56a87da87d973a9c5baa4e7438a9d20121d28

Keep the dependency checkouts wherever you prefer. From Jonlib's repository root, set these variables to their absolute paths (replace the example values):

export BEND_SOURCE="/path/to/bend"
export RAYLIB_SOURCE="/path/to/raylib"

The commands below pass these paths explicitly. toolchain.json records the base commits, patch hash and exact resulting compiler-file hashes. Apply the overlay once to a checkout already at the pinned Bend revision:

git -C "$BEND_SOURCE" apply --check "$PWD/patches/bend-metal-dispatch.patch"
git -C "$BEND_SOURCE" apply "$PWD/patches/bend-metal-dispatch.patch"

Verification never patches or updates the checkout itself. An unmodified installed Bend 2.0.27 is not equivalent to this declared source toolchain.

Verify

From the repository root:

python3 -m unittest discover -s tests -v
python3 tools/conformance.py --bend-source "$BEND_SOURCE" --raylib-source "$RAYLIB_SOURCE"

The harness builds raylib's headless Memory backend under .build/, generates both runners from tests/fixtures/images.json, and compares every packed RGBA pixel on native CPU (one/two threads) and JS. It also checks the proof, owned copies, bounds, Base.Image conversion, and the three headless PPM examples. Empty suites, missing outputs and mismatches fail.

python3 tools/conformance.py --bend-source "$BEND_SOURCE" --raylib-source "$RAYLIB_SOURCE" --gpu

The optional GPU command forces device execution and fails if the device or results are unavailable. The full current corpus passes on the tested M1 with the declared overlay, including every RGBA pixel. Stock Bend's failure and the compiler fix are documented in the investigation. Hosted CI validates CPU/JavaScript; it does not claim GPU validation.

Default filtered resizing also has a dedicated exact-bit/pixel gate:

python3 tools/resize_conformance.py --bend-source "$BEND_SOURCE" --raylib-source "$RAYLIB_SOURCE" --gpu

It checks normalization, complete filter kernels, all four retained precision counterexamples and a 529-image corpus including 4096-pixel axis boundaries. See resampling status and evidence.

The compiler overlay also has a focused upstream regression runner:

python3 tools/verify_bend.py --bend-source "$BEND_SOURCE"
python3 tools/verify_bend.py --bend-source "$BEND_SOURCE" --gpu

Gradient arithmetic and measured parallel generation have separate probes:

python3 tools/trig_probe.py --bend-source "$BEND_SOURCE" --gpu
python3 tools/gradient_bench.py --bend-source "$BEND_SOURCE" --raylib-source "$RAYLIB_SOURCE" --gpu

See GRADIENTS.md for the verified direction range, retained wider-angle counterexamples and timing scope.

Evidence is written to .build/conformance.json, with source/input hashes, toolchain, host and per-lane results. Generated programs and complete reference/ candidate pixel outputs remain beside it. Each run initially marks the report failed, so an unsuccessful rerun cannot leave an old success as its result. The run checks the complete API ledger against the pinned headers and exports its 600 public raylib.h functions into .build/api-inventory.json. Its progress summary comes from the same ledger. Mapped image operations cover only the declared profile.

Follow the full parity plan

• Progress dashboard and next steps
• Every core API, raymath, rlgl, camera, gestures, configuration
• How to update and verify progress

python3 tools/api_plan.py report
python3 tools/api_plan.py show raylib:function:ImageResize

Run the headless example

mkdir -p .build
BEND_NO_TELEMETRY=1 bun "$BEND_SOURCE/bend2/main.ts" examples/headless.bend -o .build/headless
./.build/headless

This writes .build/headless.ppm: the rectangle/circle regression scene, rendered by Jonlib. It opens no window. The conformance command checks its RGB values against raylib's actual image output.

The second example combines filled/outlined triangles, a line and a tinted image:

BEND_NO_TELEMETRY=1 bun "$BEND_SOURCE/bend2/main.ts" examples/composite.bend -o .build/composite
./.build/composite

It writes .build/composite.ppm; all 3,072 RGB pixels are compared with raylib.

The PNG above is a documentation preview converted from the verified PPM output.

The transformation example crops and enlarges pixel art with ImageResizeNN semantics:

BEND_NO_TELEMETRY=1 bun "$BEND_SOURCE/bend2/main.ts" examples/transforms.bend -o .build/transforms
./.build/transforms

It writes .build/transforms.ppm. Default filtered resize is available separately as Surface.resize: resampling status and precision evidence.

This is a documentation PNG preview of the verified PPM output.

The QOI example performs a real file export/load round trip:

BEND_NO_TELEMETRY=1 bun "$BEND_SOURCE/bend2/main.ts" examples/qoi_roundtrip.bend -o .build/qoi-roundtrip
./.build/qoi-roundtrip

It writes .build/qoi-roundtrip.qoi and prints the loaded dimensions/pixels. The harness checks its exact bytes against actual raylib ExportImage and runs file/decode error checks. See CODECS.md and MATH.md.

Ownership and compatibility

Drawing returns the updated Surface; the old value is consumed. Reads return the surface alongside an optional pixel. The initial profile uses RGBA8 images up to 4096×4096 and bounded integral coordinates represented as F32. See the API document for the vector variants, exact domains, ownership returns and reference edge behavior. Full image drawing, formats and platform coverage remain open work.

Matching CPU ImageDraw* operations does not establish GPU Draw* behavior, performance parity, platform parity, or full raylib compatibility.

License and credits

Jonlib's original code uses the zlib license. Adapted raylib algorithms retain their notices in THIRD_PARTY_NOTICES.md and LICENSES/raylib.txt. The separately identified Bend compiler patch is Apache-2.0, with the original license retained in LICENSES/bend.txt.

Inspired by raylib, created by Ramon Santamaria and contributors. Uses Bend 2, created by HigherOrderCO and contributors. Jonlib is not affiliated with or endorsed by either project.

Contributing

See CONTRIBUTING.md for setup, test expectations, CI and bug reports.