198 lines
6.9 KiB
Text
198 lines
6.9 KiB
Text
[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 |Colours 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.
|
|
|===
|