[appendix]
== Constants Reference

=== Surface

[cols="3,1,4", options="header"]
|===
|Name |Value |Meaning
|`JL_SURFACE_WIDTH` |320 |Surface width in pixels.
|`JL_SURFACE_HEIGHT` |200 |Surface height in pixels.
|`JL_SURFACE_BYTES_PER_ROW` |160 |Bytes per row, chunky 4bpp.
|`JL_SURFACE_PIXELS_SIZE` |32000 |Total pixel bytes.
|`JL_SURFACE_PALETTE_COUNT` |16 |Palettes per surface.
|`JL_SURFACE_COLORS_PER_PALETTE` |16 |Colors per palette.
|`JL_SURFACE_PALETTE_ENTRIES` |256 |Total palette entries.
|===

=== Tiles

[cols="3,1,4", options="header"]
|===
|Name |Value |Meaning
|`JL_TILE_PIXELS_PER_SIDE` |8 |Tile edge in pixels.
|`JL_TILE_BYTES_PER_ROW` |4 |Bytes per tile row.
|`JL_TILE_BYTES` |32 |Bytes per tile.
|`JL_TILE_BLOCKS_PER_ROW` |40 |Tile columns per surface.
|`JL_TILE_BLOCKS_PER_COL` |25 |Tile rows per surface.
|`JL_TILE_NO_GLYPH` |0xFFFF |`jlDrawText`: skip this character.
|`JL_TILE_MAP_SKIP` |0xFF |`jlTileMapPaste`: leave this cell untouched.
|===

=== Input

[cols="3,1,4", options="header"]
|===
|Name |Value |Meaning
|`JL_JOYSTICK_AXIS_MAX` |127 |Maximum axis value.
|`JL_JOYSTICK_AXIS_MIN` |-127 |Minimum axis value.
|`JL_CHAR_QUEUE_SIZE` |32 |Queue capacity; 31 characters can be pending.
|`JL_CHAR_BACKSPACE` |0x08 |Backspace, deletes before the caret.
|`JL_CHAR_TAB` |0x09 |Tab.
|`JL_CHAR_RETURN` |0x0D |Return.
|`JL_CHAR_ESCAPE` |0x1B |Escape.
|`JL_CHAR_DELETE` |0x7F |Forward delete, removes the character under the caret.
|===

=== Audio

[cols="3,1,4", options="header"]
|===
|Name |Value |Meaning
|`JL_AUDIO_SFX_SLOTS` |5 |Sound effect slots, 0..4.
|`JL_AUDIO_VOICES` |3 |Tone voices, 0..2.
|`JL_SFX_RAW_SIGNED8` |0 |Raw stream format: signed 8-bit PCM.
|`JL_SFX_RAW_UNSIGNED8_NOZERO` |1 |Raw stream format: unsigned biased 0x80.
|===

[appendix]
== Function Index by Header

[cols="2,5", options="header"]
|===
|Header |Functions

|`core.h`
|`jlInit`, `jlShutdown`, `jlLastError`, `jlPlatformName`, `jlVersionString`,
 `jlAlloc`, `jlFree`, `jlMemCopy`, `jlWaitVBL`, `jlFrameCount`, `jlFrameHz`,
 `jlMillisElapsed`, `jlRandom`, `jlRandomRange`, `jlRandomSeed`

|`surface.h`
|`jlSurfaceCreate`, `jlSurfaceDestroy`, `jlStageGet`, `jlSurfaceCopy`,
 `jlSurfaceCopyRect`, `jlSurfacePasteIndexed`, `jlSurfaceSnapIndexed`,
 `jlSurfaceSaveFile`, `jlSurfaceLoadFile`, `jlSurfaceHash`

|`present.h`
|`jlStagePresent`

|`palette.h`
|`jlPaletteSet`, `jlPaletteGet`, `jlScbSet`, `jlScbSetRange`, `jlScbGet`

|`draw.h`
|`jlSurfaceClear`, `jlDrawPixel`, `jlSamplePixel`, `jlDrawLine`, `jlDrawRect`,
 `jlFillRect`, `jlDrawCircle`, `jlFillCircle`, `jlFloodFill`,
 `jlFloodFillBounded`

|`tile.h`
|`jlTileCopy`, `jlTileCopyMasked`, `jlTileFill`, `jlTileBankLoad`,
 `jlTileBankLoadToSurface`, `jlTileSnap`, `jlTilePaste`, `jlTilePasteMono`,
 `jlTilePasteGlyph`, `jlDrawText`, `jlTileMapPaste`, `jlTileLayerCreate`,
 `jlTileLayerDestroy`, `jlTileLayerDraw`, `jlTileLayerSetTile`

|`sprite.h`
|`jlSpriteBankLoad`, `jlSpriteBankLoadPrecompiled`,
 `jlSpriteBankSavePrecompiled`, `jlSpriteCreate`, `jlSpriteDestroy`,
 `jlSpriteCompile`, `jlSpriteCompiledSize`, `jlSpriteDraw`,
 `jlSpriteDrawTrusted`, `jlSpriteSaveUnder`, `jlSpriteSaveUnderTrusted`,
 `jlSpriteRestoreUnder`, `jlSpriteRestoreUnderTrusted`, `jlSpriteSaveAndDraw`,
 `jlSpriteSaveAndDrawTrusted`, `jlSpriteCreateFromSurface`, `jlSpriteCompact`,
 `jlSpriteCodegenBytesUsed`, `jlSpriteCodegenBytesTotal`

|`input.h`
|`jlInputPoll`, `jlInputGetChar`, `jlWaitForAnyKey`, `jlKeyDown`,
 `jlKeyPressed`, `jlKeyReleased`, `jlMousePresent`, `jlMouseX`, `jlMouseY`,
 `jlMouseDown`, `jlMousePressed`, `jlMouseReleased`, `jlJoystickConnected`,
 `jlJoystickX`, `jlJoystickY`, `jlJoyDown`, `jlJoyPressed`, `jlJoyReleased`,
 `jlJoystickReset`

|`audio.h`
|`jlAudioPlayMod`, `jlAudioStopMod`,
 `jlAudioIsPlayingMod`, `jlAudioPlaySfx`, `jlAudioPlaySfxStream`,
 `jlAudioSfxRawFormat`, `jlAudioPlaySfxStreamRaw`, `jlAudioSetPan`,
 `jlAudioStopSfx`, `jlAudioTone`, `jlAudioTickRegister`,
 `jlAudioCriticalEnter`, `jlAudioCriticalExit`, `jlAudioVoice`, `jlAudioNoise`,
 `jlMusicPlay`, `jlMusicStop`, `jlMusicIsPlaying`, `jlMusicPause`,
 `jlMusicResume`, `jlMusicSetAtten`, `jlAudioFrameTick`

|`file.h`
|`jlDataOpen`, `jlSaveOpen`, `jlSaveWrite`, `jlSaveRead`, `jlSaveExists`,
 `jlSaveDelete`, `jlDiskFree`

|`serial.h` (opt-in)
|`jlSerialOpen`, `jlSerialClose`, `jlSerialPoll`, `jlSerialAvailable`,
 `jlSerialRead`, `jlSerialWrite`, `jlSerialWriteByte`, `jlSerialReadByte`,
 `jlSerialFlush`, `jlSerialSetDtr`, `jlSerialSetRts`

|`debug.h`
|`jlLog`, `jlLogF`, `jlLogFlush`, `jlLogReset`
|===

[appendix]
== Troubleshooting

[cols="2,5", options="header"]
|===
|Symptom |Likely cause

|`make` stops with "toolchain:PORT is not installed"
|That port's cross toolchain is missing or incomplete. Run
 `./install.sh install toolchain:PORT`; `./install.sh doctor`
 smoke-tests what is installed.

|Sprites draw but the game crawls
|The sprites were never compiled. Call `jlSpriteCompile` during loading. Check
 `jlSpriteCompiledSize` returns non-zero.

|Sprites compile on some machines and not others
|`codegenBytes` is too small for the 68000 or x86 emitters, which need four to
 eight times the IIgs figure. Measure with `jlSpriteCompiledSize`.

|Works everywhere except the IIgs, failing at startup
|A `malloc` too large for the IIgs's C heap, which is 32 KB to 48 KB in all.
 Use `jlAlloc`.

|Crashes on IIgs deep in a call chain
|A large function-local array overflowing the soft stack. Make it `static`.

|Nothing appears on screen
|`jlStagePresent` was never called, or drawing went to a surface that is not
 the stage.

|Runs at different speeds on different machines
|Per-frame steps are hard-coded. Scale by `jlFrameHz()` or use
 `jlMillisElapsed()`.

|Edge predicates never fire
|`jlInputPoll` is being called more than once per frame, or not at all.

|Typed text misses characters
|The character queue holds 31 entries and drops the rest. Pop it every frame.

|Music plays but `jlAudioVoice` does nothing
|On the Amiga the module player owns those channels, and on the plain ST
 voice 0 is silent while digital sound plays. Use one layer per scene.

|A note sounds for only a fraction of a second
|`jlAudioFrameTick` is not being called every frame. The IIgs plays each note
 as a short sample and restarts the notes being held from it.

|A streaming sound effect stops after its first chunk
|`jlAudioFrameTick` is not being called every frame. Every port feeds streams
 from it.

|Sprite trails or corruption around moving objects
|Save-under and clean-buffer erasing are being mixed in one region, or a
 `jlSurfaceCopyRect` invalidated a live backup by snapping outward to the
 16-pixel grid.

|Save and restore are unexpectedly slow on the Amiga, ST, or X68000, or the
 trusted variants crash on the Amiga or ST
|The backup buffer is at an odd address. Declare it `uint16_t`.

|A tile bank refuses to load
|`.tbk` files are per-target. Bake one for each platform.

|Your program is missing from the IIgs disk image
|The 800 KB floppy is full. Build with `JOEY_DISK_EXAMPLES` naming it, and
 check the packager's `added:` line.
|===