191 lines
7.3 KiB
Text
191 lines
7.3 KiB
Text
== 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.
|