== Writing Portable Code A JoeyLib program that follows the rules in this chapter compiles and behaves the same on all five machines and on DVX. Most of the rules exist because one particular target cannot do something the others can, and the Apple IIgs is usually that target. === The Rules, in Short . Use `jlAlloc` for anything large, never `malloc`. . Never assume a frame rate. Ask `jlFrameHz()` or use `jlMillisElapsed()`. . Never assume colour 0 is anything but black. . Compile your sprites before you draw them. . Keep large objects out of function-local variables on the IIgs. . Use `jlRandom`, not `rand`, when identical behaviour across ports matters. . Keep file names short, uppercase-safe and 8.3-compatible. . Do not mix save-under with clean-buffer erasing in the same screen region. . Pick one of the audio layers per scene, not two. The rest of this chapter explains each one. === Memory This is the rule that catches everyone. *The C heap on the IIgs is tiny.* It lives in bank 0, and a single `malloc` is capped at roughly 32 KB -- often far less in practice, because the clang libc heap on that port can be a few hundred bytes. A program that `malloc`s a 32000-byte buffer works on four targets and fails on the reference one. Use the library allocator, which is backed by each platform's native allocator (the Memory Manager on the IIgs): [source,c] ---- uint8_t *buffer = (uint8_t *)jlAlloc(32000); if (buffer == NULL) { // handle it -- this genuinely can fail on a stock machine } // ... jlFree(buffer); ---- `jlAlloc` does *not* zero the memory it returns. For bulk copies, prefer `jlMemCopy` over `memcpy`. It has the same contract (no overlap) but the IIgs implements it as `MVN` block moves at 7 cycles per byte instead of a libc byte loop, split correctly at bank boundaries. ==== Large Local Variables On the IIgs, a large function-local variable in a deep call chain can silently overflow the soft stack and crash -- roughly 2 KB is enough to do it, and the trigger is call depth rather than anything the compiler warns about. Make big buffers `static`, or allocate them with `jlAlloc`: [source,c] ---- // DANGEROUS on the IIgs, especially deep in a call chain: void renderScene(void) { uint8_t scratch[2048]; // ... } // Safe everywhere: void renderScene(void) { static uint8_t scratch[2048]; // ... } ---- === Timing Covered in <<_frame_rate_independence>>, and worth repeating because it is the second most common portability bug: the targets run at 50, 60 and 70 Hz. Scale by `jlFrameHz()` or work from `jlMillisElapsed()`. `jlFrameCount()` is a 16-bit counter, so you must poll it faster than twice the frame rate or you will miss edges, and it wraps roughly every 18 minutes at 60 Hz. === Colour and the Palette Colour 0 is black in every palette on every platform, and `jlPaletteSet` silently rewrites entry 0 to `$000` no matter what you pass. Do not design artwork that needs colour 0 to be something else -- you have 15 free colours per palette, and 16 palettes to switch between per scanline. Colour 0 is also the transparent colour for sprites. A sprite pixel of colour 0 is never drawn. If you need an opaque rectangle, use the tile operations, which have both opaque and masked forms. === Sprites Two rules. *Compile before drawing.* `jlSpriteDraw` never compiles on demand. An uncompiled sprite runs through the interpreter at roughly 1/40th the speed, and nothing warns you. *Align your backup buffers.* Give any `jlSpriteBackupT` backing array 2-byte alignment, by declaring it `uint16_t` or with an alignment attribute. An odd buffer address routes save and restore onto slow interpreted paths on the planar ports, because the 68000 cannot perform word accesses at odd addresses. [source,c] ---- // Right: 2-byte aligned by construction. static uint16_t gBacking[JOEY_SPRITE_BACKUP_BYTES(4, 4) / 2]; // Risky: may land on an odd address. static uint8_t gBacking[JOEY_SPRITE_BACKUP_BYTES(4, 4)]; ---- Note also that on the planar ports the region a save-under actually captures is the *16-pixel-aligned window* containing the sprite, not the sprite rectangle. `jlSpriteSaveUnder` reports the true geometry in the backup structure's `x`, `width`, `height` and `sizeBytes` fields. It is that recorded window you must not overwrite before restoring. === Randomness `rand()` differs wildly between C libraries, so a procedurally generated level would not match across ports. `jlRandom` is xorshift32 and produces *bit-identical* output on every platform for a given seed: [source,c] ---- jlRandomSeed(12345); uint16_t roll = jlRandomRange(6); // 0..5, same everywhere ---- A seed of 0 is remapped to 1, because xorshift cannot escape the all-zero state. This generator is fine for games and useless for cryptography. === Files Two directories sit beside the executable, and the library prefixes them for you: * `DATA/` -- read-only game content, opened with `jlDataOpen` * `SAVES/` -- writable saves and preferences, via the `jlSave*` calls Pass bare names: `jlDataOpen("levels/title.dat", "rb")`, never `"DATA/levels/title.dat"`. On DVX the two are not in the current directory at all (<<_dvx_programs>>), so a program that opens `"DATA/..."` itself finds nothing there. Keep names portable across the retro filesystems this library targets: *at most 8 characters plus a short extension, letters and digits only*, so they satisfy both ProDOS and DOS 8.3. Do not rely on case being preserved. A failed save is not fatal -- the calls report failure and your program should degrade gracefully, because on some volumes `SAVES/` simply is not writable. === Audio JoeyLib gives you three sound layers, and on two platforms they share physical hardware: [cols="2,5", options="header"] |=== |Layer |What it is |Module playback |`jlAudioPlayMod` -- four-channel Protracker `.MOD`, mixed in software on DOS and ST, hardware-replayed on Amiga and IIgs. |Chip tracker |`jlMusicPlay` -- a portable event stream driving three tone voices plus noise, at register-write cost with no CPU mixing. |Voices and effects |`jlAudioVoice`, `jlAudioNoise`, `jlAudioPlaySfx` and the streaming forms. |=== [WARNING] ==== On the Atari ST and Amiga, the tone voices *are* the same hardware the module player drives. While a `.MOD` is playing, `jlAudioVoice` writes fight the player's register writes and lose. Choose the module layer or the voice and tracker layer *per scene*, not both at once. ==== The chip tracker is the portable choice for music. It costs almost nothing on every port -- unlike `.MOD` playback, which needs real CPU mixing and is marginal on the ST. On the IIgs, `jlAudioVoice` and `jlAudioNoise` require `jlAudioInit` (they ride the tracker engine's DOC path) and behave as retriggered one-shots of about 80 ms, so a note held longer must be re-asserted roughly once a frame. On DOS, ST and Amiga those two calls are direct hardware programming and work without `jlAudioInit`. A failed `jlAudioInit` is *not* fatal. `jlInit` still succeeds and every audio call becomes a silent no-op, so a program need not treat missing sound as an error. === Per-Platform Behaviour Summary The API is uniform; these are the places where what you get differs. [cols="2,2,2,2,2,2,2", options="header"] |=== |Feature |IIgs |Amiga |Atari ST |MS-DOS |X68000 |DVX |Frame rate |60 Hz |50 Hz (PAL) |60 Hz (NTSC) |70 Hz |60 Hz |70 Hz (virtual; the real retrace on the whole screen) |Pixel storage |chunky 4bpp |planar |planar, interleaved |chunky 4bpp |text-plane planar |chunky 4bpp |Stereo pan |all three |left and right |ignored (mono) |ignored (mono) |ignored |all three |`jlAudioTone` |DOC oscillator |Paula |YM2149 |PIT counter 2 |- |a DVX tone (FM chip or mixer) |Joystick |analog, auto-disables |digital |digital |digital |digital |analog (DVX calibrates) |Keyboard layout |machine's own |machine's own |machine's own |fixed US |machine's own |DVX's |Serial ports |modem, printer, slot card |`serial.device` |Modem port |COM1..COM4 |- |COM1..COM4 (DVX's library) |=== The joystick row deserves a note: the IIgs port *auto-disables* joystick polling after a short window with no stick detected, because polling costs about 3 ms per frame there. It does not re-probe on its own. If a user plugs a stick in while the program is running, you must call `jlJoystickReset` to resume polling. === A Portability Checklist Before you call a program portable, confirm: * [ ] No `malloc` of anything over a few hundred bytes -- use `jlAlloc`. * [ ] No large function-local arrays; they are `static` or heap. * [ ] Movement and animation scale with `jlFrameHz()` or `jlMillisElapsed()`. * [ ] `jlInputPoll()` is called exactly once per frame. * [ ] `jlAudioFrameTick()` is called every frame. * [ ] Every sprite is compiled during loading. * [ ] Sprite backup buffers are 2-byte aligned and sized with the macro. * [ ] Save file names are 8.3-safe. * [ ] Only one audio layer is active per scene. * [ ] `jlShutdown()` runs on every exit path. * [ ] The program has actually been run on every target, not just built. That last item is the one that matters. Every port has emulator run scripts under `scripts/`, and building successfully proves considerably less than running. === DVX Programs DVX is a DOS desktop: a VESA graphics GUI with windows, cooperative multitasking and its own libraries for sound, music, joysticks and serial ports. On DVX a JoeyLib program is one of its programs, a `.app` module running in a window of its own beside the others. The graphics are the MS-DOS port's -- the same chunky stage and the same x86 code, so UBER's hashes are DOS's -- and the rest behaves like this: * *A window, or the whole screen.* The window's content is the 320x200 stage at the largest whole scale, up to 3x, that fits the desktop: 1x at 640x480, 2x at 800x600, 3x at 1024x768. The stage reaches the desktop through one colour table per palette, so SCB palettes are exact on 15-, 16- and 32-bit desktops. On a 256-colour desktop every colour is the nearest one in DVX's palette, which all programs share: gradients band. * *Full screen.* Game > Full Screen, or Alt+Enter, puts the program on the whole screen in DVX's full-screen mode, 320x200 in 256 colours (VGA mode 13h, or a VBE mode of that size), and back in its window. There it looks exactly as on MS-DOS: the screen's 256 colours hold all 16 palettes, so SCB palettes are exact at any desktop depth and palette changes are free. The other programs run on meanwhile. Alt+Tab, Ctrl+Esc or another window coming to the front brings the desktop back, with the program still running and drawing in its window; giving its window the focus again puts it back on the whole screen. The choice is kept in the program's settings folder (`JOEYLIB.INI`), so it starts the way it was left. It is the user's choice: JoeyLib's API has no full-screen call. (Under DOSBox, Alt+Enter is DOSBox's own full-screen key; use Alt with the keypad's Enter, or the menu.) * *A virtual 70 Hz.* A window has no vertical blank. `jlFrameHz()` is 70, as on DOS, and `jlWaitVBL()` waits for the next seventieth of a second of DVX's clock while the other programs run; nothing prevents tearing. On the whole screen `jlWaitVBL()` gives the other programs a turn, then waits for the screen's real vertical retrace, as on DOS, so a present right after it does not tear. The frame count is the same clock in both, so switching never makes it jump. * *Keys DVX keeps.* While the window is active, or the program has the whole screen, every key goes to the program, F1, F10 and Alt included, except Alt+Tab (switch programs), Ctrl+Esc (Task Manager) and Alt+F4 (close the window), and Alt+Enter, which the port keeps for full screen. The window's Game menu has Full Screen, Help (the program's help file) and Exit. Typed characters come through DVX's keyboard layout. * *Closing ends the program.* Alt+F4, the close box and Game > Exit end the program at its next `jlWaitVBL`, `jlInputPoll`, `jlStagePresent` or `jlSerialPoll`, as `exit()` does anywhere: its `atexit` handlers run, then `jlShutdown`, and its log is closed. * *Sharing the machine.* DVX multitasks cooperatively: the other programs, and this one's own window events, run only while it yields. `jlWaitVBL` yields, and so do `jlInputPoll`, `jlStagePresent` and `jlSerialPoll`, at most once a frame. A loop that calls none of them freezes the desktop until it ends. * *Files.* DVX's programs share one current directory, so JoeyLib roots its files at run time: `DATA/` is found beside the program (its folder under `APPS`), while `SAVES/` and `joeylog.txt` go to the program's own settings folder, `CONFIG\APPS\JOEYLIB\NAME`, which DVX keeps apart from the program files so a reinstall never overwrites them. * *Sound* goes through DVX's sound and music libraries, mixed with every other program's: `.MOD` music, SFX in stereo, and the tone voices on the FM chip when there is one. A `jlAudioTickRegister` callback runs in program time, at the next `jlAudioFrameTick`, because DVX's sound library may not be called from an interrupt. * *Joysticks* are DVX's, calibrated in its Control Panel: real analog axes. DVX's keyboard joystick is not reported as one. * *Serial ports* belong to DVX's serial library, one program each. As on every port, closing one leaves DTR as it is. * A program's `main` is compiled as `jlGameMain`, which the port calls with `argv[0]` the `.app`'s path. `make dvx` builds every example as a DVX program (the `dvx` installer component supplies DVX and its SDK, <<_setting_up_the_toolchains>>), and `./joey-run --port dvx NAME` starts one in DVX under DOSBox Staging.