Arkos Player Functions

Plays next music cycle of the present song with Arkos Tracker Player.  Song has had to be previously established with cpct_akp_musicInit.

C Definition

void cpct_akp_musicPlay ()

Assembly call (Input parameters on registers)

call cpct_akp_musicPlay_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Details

This function is to be called to start and continue playing the presently selected song with Arkos Tracker Player.  Depending on the frequency at which the song were created, this function should be called 12, 25, 50, 100, 200 or 300 times per second.

Each time you call the function, it plays 1/frequency seconds.  This means that you have to manually synchronize your calls to this function to have a stable music playing.  If you call too fast or too slow you will either interrupt sound or have sound valleys.  Therefore, you are responsible for calling this function with the most accurate timing possible, to get best sound results.

Destroyed Register values

AF, AF’, BC, DE, HL, IX, IY

Required memory

1794 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

To be done

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Sets up a music into Arkos Tracker Player to be played later on with cpct_akp_musicPlay.

C Definition

void cpct_akp_musicInit (void* songdata)

Input Parameters (2 bytes)

Assembly call (Input parameters on registers)

call cpct_akp_musicInit_asm

Parameter Restrictions

• songdata must be an array containing dong’s data in AKS binary format.  Take into account that AKS binary format enforces a concrete start location in memory.  Therefore, song must have been created in Arkos Tracker and exported to the same memory location that songdata points to.  If you fail to locate the song at the same memory location it was exported for in Arkos Tracker, unexpected results will happen (Typically, noise will be played but, occasionally your program may hang or crash).

Known limitations

• songdata must be the same memory address that the one given to Arkos Tracker when exporting song’s binary.  Arkos Tracker songs are created to be at a concrete memory location, due to optimization constraints.  Therefore, this must be taken into account.  If you wanted to change the memory location of the song, you should first open the song into Arkos Tracker and export it again with the new desired memory location.
• This function will not work from ROM, as it uses self-modifying code.

Details

This function should be called fist to initialize the song that is to be played.  The function reads the song header and sets up the player to start playing it.  Once this process is done, cpct_akp_musicPlay should be called at the required frequency to continuously play the song.

Destroyed Register values

AF, AF’, BC, DE, HL, IX, IY

Required memory

92 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

To be done

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Stops playing musing and sound effects on all 3 channels.

C Definition

void cpct_akp_stop ()

Assembly call (Input parameters on registers)

call cpct_akp_stop_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Details

This function stops the music and sound effects playing in the 3 channels.  It can be later continued again calling cpct_akp_musicPlay.  Please, take into account that sound effects cannot be played while music is stopped, as code for sound effects and music play is integrated.

Destroyed Register values

AF, AF’, BC, DE, HL, IX, IY

Required memory

19 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

To be done

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Returns the number of the instrument which is playing SFX in the selected channel (0 = Channel free / not playing SFX).

C Definition

u16 cpct_akp_SFXGetInstrument (u8 channel_bitmask)

Assembly call (Input parameters on registers)

call cpct_akp_SFXGetInstrument_asm

Details

This function returns the number of the instrumeent which is playing in the given channel.  You may use it to check the status of an FX reproduction.  If this function returns a 0 it means that no SFX is playing on the channel (i.e. the channel is free for reproducing new SFXs).

Destroyed Register values

AF, HL

Required memory

25 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

   Case    | Cycles | microSecs (us)
--------------------------------------
  Best     |   68   |  17.00
--------------------------------------
  Worst    |   82   |  20.50
--------------------------------------
Asm saving |  -28   |  -7.00
--------------------------------------

Initializes sound effect instruments to be able to play sound effects.

C Definition

void cpct_akp_SFXInit (void* sfx_song_data)

Input Parameters (2 bytes)

Assembly call (Input parameters on registers)

call cpct_akp_SFXInit_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Parameter Restrictions

• sfx_song_data must be a song in binary AKS format.  However, this song only needs to have instruments defined (there is not need for an actual “song” as a list of notes, patterns and others).  Instruments will be set up for playing SFX later on with functions like cpct_akp_SFXPlay.

Details

This function initializes instruments that will be used later on to play FX sounds at will using cpct_akp_SFXPlay.  In order for the instruments to be initialized, sfx_song_data must point to a song defined in AKS format.  For the purpose of this function, the song only requires to have instruments defined in it, as patterns, notes and other information is not used for FX sounds.

You may use instruments from another song or a specific song containing instrument data only.  Any song with instruments defined in it is valid to set up SFX with Arkos Tracker Player.

Destroyed Register values

AF, DE, HL

Required memory

14 bytes (+13 bytes from cpct_akp_SFXStopAll that comes next to this function and is used in initialization)

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

   Case    | Cycles | microSecs (us)
--------------------------------
   Any     |  146   |  36.50
--------------------------------
Asm saving |  -41   | -10.25
-------------------------------

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Stops the reproduction of any sound effect in the 3 channels.

C Definition

void cpct_akp_SFXStopAll ()

Assembly call (Input parameters on registers)

call cpct_akp_SFXStopAll_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Details

This function stops all sound FX reproduction on all the 3 sound channels.

Destroyed Register values

HL

Required memory

13 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

   Case    | Cycles | microSecs (us)
--------------------------------
   Any     |   68   |  15.50
--------------------------------
Asm saving |    0   |   0
-------------------------------

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Plays a concrete sound effect, using the instruments of the “SFX song” given to cpct_akp_SFXInit when initializing sound effects.

C Definition

void cpct_akp_SFXPlay (u8 sfx_num, u8 volume, u8 note, u8 speed, u16 inverted_pitch, u8 channel_bitmask)

Input Parameters (7 bytes)

Assembly call (Input parameters on registers)

call cpct_akp_SFXPlay_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Details

Plays a given sound effect, along with the music, in a concrete channel and with some parameters (Volume, Note, Speed, Inverted Pitch).  This lets you create lots of different (and potentially complex) sound effects from a set of instruments.  In fact, you could play a song made of sound effect calls.

Destroyed Register values

AF, BC, DE, HL,

Required memory

95 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2089 bytes.

Time Measures

   Case    | Cycles  | microSecs (us)
--------------------------------------
   Any     |     To be done
--------------------------------------
Asm saving |  -141   |  -45.25
--------------------------------------

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Stops the reproduction sound FX on given channels

C Definition

void cpct_akp_SFXStop (u8 stop_bitmask)

Input Parameters (1 byte)

Assembly call (Input parameters on registers)

call cpct_akp_SFXStop_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Parameter Restrictions

• stop_bitmask must be a value that operates as a set of enabled / disabled bits (a bitmask).  Concretely, the 3 Least Significant bits, 2, 1 and 0 (xxxxx210) refer to Channels C, B and A respectively.  Rest of the bits are ignored.  Bits set to 1 mean that those channels will be stopped.  Bits set to 0 mean that those channels are to be left as they are.

Details

This function lets you selectively stop sound FX reproduction on one, two or the 3 available channels.  A stop_bitmask is given as parameter containing the information about what channels shall be stopped.

Destroyed Register values

AF, HL

Required memory

30 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2082 bytes.

Time Measures

Case       | Cycles | microSecs (us)
--------------------------------
Best (0)   |  101   |  25.25
--------------------------------
Best (1)   |  149   |  37.25
--------------------------------
Asm saving |  -28   |  -7.00
--------------------------------

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.

Sets global volumes for creating fade in / out effects.

C Definition

void cpct_akp_setFadeVolume (u8 volume)

Input Parameters (1 byte)

Assembly call (Input parameters on registers)

call cpct_akp_setFadeVolume_asm

Known limitations

• This function will not work from ROM, as it uses self-modifying code.

Parameter Restrictions

• volume must be a value in the range [0-15] for some meaning.  Values greater than 15 mean no volume at all.  0 is the maximum volume, 15 the minimum.

Details

This function controls the global reproduction volume for all channels.  This lets you do Fade in / out effects, by making the volume progressively go up or down.

Destroyed Register values

AF, HL

Required memory

15 bytes

However, take into account that all of Arkos Tracker Player’s functions are linked and included, because they depend on each other.  Total memory requirement is around 2082 bytes.

Time Measures

   Case    | Cycles | microSecs (us)
-------------------------------------
   Any     |   51   |  12.75
-------------------------------------
Asm saving |  -28   |   7.00
-------------------------------------

Credits

This is a modification of the original Arkos Tracker Player code from Targhan / Arkos.  Madram / Overlander and Grim / Arkos have also contributed to this source.