118 lines
4 KiB
Text
118 lines
4 KiB
Text
== Introduction
|
|
|
|
=== What JoeyLib Is
|
|
|
|
JoeyLib is a single-codebase C game library for five 16-bit and 32-bit retro
|
|
machines. 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.
|
|
|
|
|Atari ST
|
|
|68000 (STF or STE)
|
|
|512 KB
|
|
|Word-interleaved planar. Shares 68000 assembly with the Amiga port.
|
|
|
|
|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 centred in a 512x512 screen.
|
|
|===
|
|
|
|
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 colours on screen at once*, chosen per scanline from one of 16 palettes.
|
|
* *Colour 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 colour 0 of the active palette, and
|
|
colour 0 is the transparent colour for sprite drawing. You have 15 usable
|
|
colours per palette.
|
|
* Colours 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. There are no "fast unclipped" variants in
|
|
the public API, so you cannot corrupt memory by drawing off the edge.
|
|
|
|
=== What the Library Hides
|
|
|
|
The five 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
|
|
|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
|
|
|Text-plane planes, four planes 128 KB apart.
|
|
|===
|
|
|
|
Every public entry point speaks in *colour 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 colour-0 transparency and *runtime-compiled blitters* -- the
|
|
library emits native 65816, 68000 or x86 code for each sprite at run time
|
|
* 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
|
|
|
|
=== 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.
|
|
|
|
<<_adding_your_program_to_the_build>> explains how to get your own program
|
|
compiling for all five targets.
|
|
|
|
The API Reference documents every public function: its exact signature, each
|
|
parameter, what it returns, and any per-platform behaviour you need to know
|
|
about.
|