Cream's Jam API, a missing manualAuthor: Saulot - Published 04-02-2012 19:00
Small introductionJam is plugin based, custom format music player. It comes with GEM and custom GUI frontend. It allows rehearsal of tunes in various formats made on Atari ST/Amiga/C64/Atari 8-bit on Atari ST/STe/Mega/TT/Falcon030 machines.
Here is actual list of supported formats:
- SNDH (Atari ST/E/TT/Falcon)
- COSO / TFMX (Jochen Hippel)
- TFMX (Chris Huelsbeck)
- Future Composer 1.3/1.4
- PSID (C64)
- SAP (Atari XL)
- David Whittaker (Amiga)
- Tim Follin (Amiga)
- Protracker 3.0
- Art Of Noise
- AHX (Amiga)
- TSD (Tao's DMA-SID)
- HPN (Mad Max B.I.G.-Demo)
- Sonic Arranger (Amiga)
The good thing is that you can reuse those plugins in your own programs/games/demos (as recent D-BUG Atari ST games revamps had shown e.g. Wings of Death with Amiga music), here I will describe how to do it.
The advantages of those plugins is quite simple, once you load the plugin and activate it, you're using the same interface, no matter of the file format. By detecting machine during runtime, you can decide to load CPU or DSP based replay routine.
I've also provided Jam API C wrapper with example usage. You can download it from here. It is targetted for modern gcc 4.xx and vasm. It can be modified for other compilers too (sources are under MIT licence). Jam plugins and tunes for an example are not provided, get them from Cream HQ Jam page.
Additional notes: This article is not about Jam plugin development, if you want to write one then read the official API documentation. You should also use this documentation as a reference for more thorough commands descriptions, although not all of them were documented. Commands are described from plugin programmer point of view, so it's little confusing at times.
Second thing is that m68k source code is HiSoft Devpac/VASM compatible and assumes that parameters are passed by stack (a default gcc way) and values are are returned in d0. If you are using for example Pure C (where parameter passing is via registers), you have to adjust the code a little, because function parameters are put into address registers directly (check your compiler documentation for details).
All the commands to Jam has to be performed in Supervisor mode. If you will not do this expect bus errors .
Third thing, there is a bug in Wiki CMS, and square brackets in the source code are turned into links sometimes. This is especially visible on arrays in C structs, so use provided source code as a reference.
Thanks go to: Cream (Abyss/Tao) for Atari Jam player and great replay routines, GGN/D-BUG for the relocation tip, Sqward for sending me m68k relocation routine of unknown hero.