== Introduction === What JoeyLib Is JoeyLib is a single-codebase C game library for five 16-bit and 32-bit retro machines, for DVX, a DOS desktop whose programs run in windows, for today's desktops, browsers, and the PSP through SDL3, and for Windows from 3.1 on. You write one program against one API, and the same source compiles and runs on all of them: [cols="2,2,2,4", options="header"] |=== |Platform |CPU |RAM |Notes |Apple IIgs |65C816 at 2.8 MHz |1 MB typical |The reference platform. Accelerators run faster with no code changes. |Commodore Amiga |68000 (A500 class) |512 KB chip, 512 KB fast recommended |OCS chipset. Native planar bitplanes. Also tested on an A1200 (68020, AGA) and an A4000 (68040, AGA). |Atari ST, STe, Mega STe |68000 at 8 MHz (16 MHz on a Mega STe) |512 KB |Word-interleaved planar. Shares 68000 assembly with the Amiga port. Two builds: the ST build runs on every ST and never uses STe hardware; the STe build (`make ste`) uses the STe's 4-bit palette, DMA sound, BLiTTER, enhanced joystick ports, and a Mega STe's 16 MHz, and runs only there. See <<_the_atari_st_family>>. |MS-DOS |386 or later |2 MB |VGA required. DPMI supplied by an embedded CWSDPMI. |Sharp X68000 |68000 at 10 MHz |stock |Draws into the text plane, 320x200 centered in a 512x512 screen. |DVX |486 or later |what DVX needs |A program in a window on the DVX desktop, at 1x to 3x, or on the whole screen at 320x200. The MS-DOS port's stage and code; a virtual 70 Hz. See <<_dvx_programs>>. |SDL3 |whatever the host has |whatever the host has |A native program in a window (Linux today), scaled to fit at 4:3 or with square pixels, or on the whole screen. Sprites are interpreted; a virtual 60 Hz. The fast way to try a change without an emulator. See <<_sdl3_programs>>. |Web |the browser's |the browser's |The SDL3 port compiled to WebAssembly: a program is a web page anyone can open. See <<_web_programs>>. |Win32 |386 or later |what Windows needs |A Windows program for Windows 95 through today: the hosted core with a backend written to the Win32 API. See <<_windows_programs>>. |Win16 |386 or later |what Windows 3.1 in 386 enhanced mode needs |A Windows 3.x program: the hosted core with a backend written to the Windows 3.1 API, in 32-bit code through Open Watcom's Win386 extender; 8-bit indexed, so every palette is exact on a 256-color display, and sprites compiled as on DOS. See <<_windows_programs>>. |PSP |MIPS Allegrex at 222 MHz |32 MB (PSP-1000) |PSP homebrew, for custom firmware and PPSSPP: the SDL3 port built with pspdev. The stage sits at 1:1 in the middle of the 480x272 screen; the d-pad, cross, and circle are joystick 0; the analog nub is the mouse, with L and R its buttons; Start is Return, Select is Escape, and Square opens a keyboard on the screen for every other key. See <<_psp_programs>>. |=== The Apple IIgs is deliberately the slowest target and the design reference. If something performs acceptably there, it performs acceptably everywhere. === The Display Contract Every JoeyLib program gets exactly the same screen on every platform: * *320 x 200 pixels*, always. There is no other resolution. * *16 colors per scanline*: each line shows one of 16 palettes of 16 colors, so up to 241 colors are on the screen at once (256, less the 15 extra blacks, since color 0 is black in every palette). * *Color 0 of every palette is black*, always, and is forced to black by the library even if you try to set it to something else. This is not negotiable: the Amiga and ST hardware border follows color 0 of the active palette, and color 0 is the transparent color for sprite drawing. You have 15 usable colors per palette. * Colors are *12-bit `$0RGB`*: bits 11..8 red, 7..4 green, 3..0 blue. * Origin `(0, 0)` is *top-left*. X increases right, Y increases down. Coordinates are signed `int16_t`, so off-screen positions are representable. Every drawing primitive clips to the surface rectangle. An out-of-bounds draw is a silent no-op, never an error, so you cannot corrupt memory by drawing off the edge. The exceptions are the sprite calls whose names end in `Trusted` (`jlSpriteDrawTrusted`, `jlSpriteSaveUnderTrusted`, `jlSpriteRestoreUnderTrusted`, and `jlSpriteSaveAndDrawTrusted`): for speed they skip the checks, so the sprite must lie wholly on the surface, and one that does not corrupts memory (<<_the_trusted_variants>>). === What the Library Hides The machines store pixels in genuinely incompatible ways. JoeyLib keeps that out of your program: [cols="2,3", options="header"] |=== |Platform |In-memory pixel storage |Apple IIgs, MS-DOS, DVX, SDL3, Web, PSP, Win32, Win16, Haiku, BeOS |Chunky 4bpp packed: two pixels per byte, high nibble is the left pixel. |Commodore Amiga |Native planar: four separate bitplanes. |Atari ST |Native planar, word-interleaved: four plane words per 16 pixels, per row. |Sharp X68000 |Native planar: four separate bitplanes, as on the Amiga. The display they are copied to is the text plane, four planes 128 KB apart. |=== Every public entry point speaks in *color indices, 0 to 15*. Your code never sees the storage format. The one place the difference leaks through is documented and flagged in this manual -- see <<_writing_portable_code>>. === What You Get * Surfaces, palettes, and per-scanline palette selection * Drawing primitives: pixels, lines, rectangles, circles, flood fill * 8x8 tiles, tile banks, tile maps, and bitmap text * Sprites with color-0 transparency and *runtime-compiled blitters* -- the library emits native 65816, 68000, or x86 code for each sprite at run time (on the hosted ports other than Win16 every sprite is interpreted) * Keyboard (both game-style predicates and a typed-character queue), mouse, and joystick * Four-channel Protracker `.MOD` music, a portable chip-tracker music format, digital one-shot and streaming sound effects, and a PSG-style tone and noise layer * Read-only game data files and writable save files * An optional RS-232 serial add-on * A deterministic, seedable random generator that produces *bit-identical* output on every port for a given seed === License JoeyLib is distributed under the MIT License (`LICENSE.md`). A program built with it has JoeyLib compiled in, so it carries JoeyLib's copyright and permission notice, in its documentation for instance. A program also carries code from the libraries each port links (PTPlayer for music on the Amiga, the toolchains' C libraries and start files), whose terms `LICENSES.md` lists with what a shipped program owes them. On the Atari ST that includes MiNTLib's LGPL parts: a closed-source game lets its users relink it against a changed MiNTLib (by shipping its object files, for instance). For Windows 3.x, see the Win16 port's "Shipping" note in <<_windows_programs>>. === How to Read This Manual If you are new to JoeyLib, read <<_getting_started>>, then <<_anatomy_of_a_joeylib_program>>, then <<_writing_portable_code>>. Those three chapters are the whole programming model. <<_creating_assets>> covers getting graphics, music, and sound into a form the library can load. <<_building_your_program>> explains how to get your own program, in a directory of its own, compiling for every target. The API Reference documents every public function: its exact signature, each parameter, what it returns, and any per-platform behavior you need to know about.