# Arkos Player Functions

Summary

Arkos Player Functions |
Constants |
Arkos Player Compilation Constants | Constants used to control which features are enabled / disabled in the Arkos Tracker Player code.
Functions |
cpct_akp_musicPlay | Plays next music cycle of the present song with Arkos Tracker Player.
cpct_akp_musicInit | Sets up a music into Arkos Tracker Player to be played later on with cpct_akp_musicPlay.
cpct_akp_stop | Stops playing musing and sound effects on all 3 channels.
cpct_akp_SFXGetInstrument | Returns the number of the instrument which is playing SFX in the selected channel (0 = Channel free / not playing SFX).
cpct_akp_SFXInit | Initializes sound effect instruments to be able to play sound effects.
cpct_akp_SFXStopAll | Stops the reproduction of any sound effect in the 3 channels.
cpct_akp_SFXPlay | Plays a concrete sound effect, using the instruments of the “SFX song” given to cpct_akp_SFXInit when initializing sound effects.
cpct_akp_SFXStop | Stops the reproduction sound FX on given channels
cpct_akp_setFadeVolume | Sets global volumes for creating fade in / out effects.

### Constants

### Arkos Player Compilation Constants

Constants used to control which features are enabled / disabled in the Arkos Tracker Player code. Changing them requires recompiling CPCtelera’s library to take effect.

PLY_UseSoundEffects | Set to 1 if you want to use Sound Effects in your player. Both CPU and memory consuming. It is set to 1 by default in CPCtelera.
PLY_UseFades | Set to 1 to allow fades in / out. A little CPU and memory consuming. _cpct_akp_setFadeVolume becomes available.
PLY_SystemFriendly | Set to 1 if you want to save the Registers used by AMSDOS (AF’, BC’, IX, IY) which allows you to call this player in BASIC. As this option is system-friendly, it cuts interruptions, and restores them ONLY IF NECESSARY. It is set to 0 by default. However, IX and IY registers are always saved.
PLY_RetrigValue | Value used to trigger the Re-trig of Register 13. 0xFE corresponds to ‘CP xx’. Do not change it!

### Functions

### cpct_akp_musicPlay

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.

### cpct_akp_musicInit

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)

(2B DE) songdata | Pointer to the start of the array containing song’s data in AKS binary format

#### 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.

### cpct_akp_stop

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.

### cpct_akp_SFXGetInstrument

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
>     --------------------------------------

### cpct_akp_SFXInit

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)

(2B DE) sfx_song_data | Pointer to the start of a song file containing instrument data for SFX

#### 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.

### cpct_akp_SFXStopAll

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.

### cpct_akp_SFXPlay

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)

(1B L ) sfx_num | Number of the instrument in the SFX Song (>0), same as the number given to the instrument in Arkos Tracker.
(1B H ) volume | Volume [0-15], 0 = off, 15 = maximum volume.
(1B E ) note | Note to be played with the given instrument [0-143]
(1B D ) speed | Speed (0 = As original, [1-255] = new Speed (1 is fastest))
(2B BC) inverted_pitch | Inverted Pitch (-0xFFFF -> 0xFFFF). 0 is no pitch. The higher the pitch, the lower the sound.
(1B A ) channel_bitmask | Bitmask representing channels to use for reproducing the sound (Ch.A = 001 (1), Ch.B = 010 (2), Ch.C = 100 (4))

#### 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.

### cpct_akp_SFXStop

Stops the reproduction sound FX on given channels

#### C Definition

void cpct_akp_SFXStop (u8 stop_bitmask)

#### Input Parameters (1 byte)

(1B A) stop_bitmask | A value where the 3 Least Significant Bits represent which channels to stop (bits enabled = channels to stop)

#### 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.

### cpct_akp_setFadeVolume

Sets global volumes for creating fade in / out effects.

#### C Definition

void cpct_akp_setFadeVolume (u8 volume)

#### Input Parameters (1 byte)

(1B A) volume | Global volume for all channels, [0-15]. 0 = max volume, 16 or more = no volume

#### 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.

Plays next music cycle of the present song with Arkos Tracker Player.
Initializes sound effect instruments to be able to play sound effects.
Sets up a music into Arkos Tracker Player to be played later on with cpct_akp_musicPlay.
Stops playing musing and sound effects on all 3 channels.
unsigned int (u16 = unsigned 16-bits, 2 bytes)
Returns the number of the instrument which is playing SFX in the selected channel (0 = Channel free / not playing SFX).
unsigned char (u8 = unsigned 8-bits, 1 byte )
Plays a concrete sound effect, using the instruments of the “SFX song” given to cpct_akp_SFXInit when initializing sound effects.
Stops the reproduction of any sound effect in the 3 channels.
Stops the reproduction sound FX on given channels
Sets global volumes for creating fade in / out effects.
Close