Modules/arkos/Usage - Revision history

Aoineko at 22:44, 25 October 2025

2025-10-25T22:44:21Z

Aoineko at 22:42, 25 October 2025

2025-10-25T22:42:59Z

Aoineko: /* Interruption */

2025-10-19T18:13:49Z

‎Interruption

Aoineko at 18:13, 19 October 2025

2025-10-19T18:13:13Z

Aoineko: /* Interruption */

2025-10-19T18:12:30Z

‎Interruption

Aoineko at 18:10, 19 October 2025

2025-10-19T18:10:04Z

Aoineko at 18:07, 19 October 2025

2025-10-19T18:07:20Z

Aoineko: /* Music address */

2024-12-27T22:12:25Z

‎Music address

Aoineko at 22:11, 27 December 2024

2024-12-27T22:11:55Z

Aoineko: /* Music address */

2024-12-27T22:10:55Z

‎Music address

← Older revision		Revision as of 22:44, 25 October 2025
Line 1:		Line 1:
−	⚠️ ~~Working~~ area address in RAM is hardcoded. Default value is 0xF000 but can be change in library configuration (see [[#Settings]]).	+	⚠️ Arkos tracker working area address in RAM is hardcoded. You must manually ensure that this area does not overlap any other content in RAM. Default value is 0xF000 but can be change in library configuration (see [[#Settings]]).

	=== Music address ===		=== Music address ===

← Older revision		Revision as of 22:42, 25 October 2025
Line 1:		Line 1:
		+	⚠️ Working area address in RAM is hardcoded. Default value is 0xF000 but can be change in library configuration (see [[#Settings]]).
		+
	=== Music address ===		=== Music address ===
	Arkos music is designed to work only if played at a specific address.		Arkos music is designed to work only if played at a specific address.

@@ Line 21: / Line 21: @@
 <syntaxhighlight lang="C">
 DisableInterrupt();
-{{{1|AKG}}}_Decode();
+AKG_Decode();
 EnableInterrupt();
 </syntaxhighlight>
@@ Line 27: / Line 27: @@
 A better solution is to execute the music update directly from the interrupt handler. Not only does this remove the risk of an interrupt occurring in the middle of the update, but it also allows your music to play at a constant speed even if the main loop takes several frames (for example, when you load a level or unpack data).
-However, in this case, this means that all functions that change music data — notably the <tt>{{{1|AKG}}}_Play()</tt> functions — must also be called from the handler or executed with interrupts disabled.
+However, in this case, this means that all functions that change music data — notably the <tt>{{{1|AKG}}}_Play()</tt> function — must also be called from the handler or executed with interrupts disabled.

@@ Line 15: / Line 15: @@
 === Interruption ===
-The <tt>AKx_Decode()</tt> function temporarily changes the call stack address (SP register value) to optimize its execution and restores the correct value at the end.
+The <tt>{{{1|AKG}}}_Decode()</tt> function temporarily changes the call stack address (SP register value) to optimize its execution and restores the correct value at the end.
 If the update function is called from the main loop, an interrupt may occur while the call stack address is incorrect, potentially overwriting music data and causing the game to crash.
@@ Line 21: / Line 21: @@
 <syntaxhighlight lang="C">
 DisableInterrupt();
-AKx_Decode();
+{{{1|AKG}}}_Decode();
 EnableInterrupt();
 </syntaxhighlight>
@@ Line 27: / Line 27: @@
 A better solution is to execute the music update directly from the interrupt handler. Not only does this remove the risk of an interrupt occurring in the middle of the update, but it also allows your music to play at a constant speed even if the main loop takes several frames (for example, when you load a level or unpack data).
-However, in this case, this means that all functions that change music data — notably the <tt>AKx_Play()</tt> functions — must also be called from the handler or executed with interrupts disabled.
+However, in this case, this means that all functions that change music data — notably the <tt>{{{1|AKG}}}_Play()</tt> functions — must also be called from the handler or executed with interrupts disabled.

← Older revision		Revision as of 18:12, 19 October 2025
Line 26:		Line 26:

	A better solution is to execute the music update directly from the interrupt handler. Not only does this remove the risk of an interrupt occurring in the middle of the update, but it also allows your music to play at a constant speed even if the main loop takes several frames (for example, when you load a level or unpack data).		A better solution is to execute the music update directly from the interrupt handler. Not only does this remove the risk of an interrupt occurring in the middle of the update, but it also allows your music to play at a constant speed even if the main loop takes several frames (for example, when you load a level or unpack data).
		+
		+	However, in this case, this means that all functions that change music data — notably the <tt>AKx_Play()</tt> functions — must also be called from the handler or executed with interrupts disabled.

← Older revision		Revision as of 18:10, 19 October 2025
Line 24:		Line 24:
	EnableInterrupt();		EnableInterrupt();
	</syntaxhighlight>		</syntaxhighlight>
		+
		+	A better solution is to execute the music update directly from the interrupt handler. Not only does this remove the risk of an interrupt occurring in the middle of the update, but it also allows your music to play at a constant speed even if the main loop takes several frames (for example, when you load a level or unpack data).

← Older revision		Revision as of 18:07, 19 October 2025
Line 13:		Line 13:
	** SFX at <tt>0xE000</tt> (1 KB up to <tt>0xE3FF</tt>)		** SFX at <tt>0xE000</tt> (1 KB up to <tt>0xE3FF</tt>)
	* Put the music directly in the "right" place in your program. This can be quite complicated in C, unless you manually place the data at a given address (with the <tt>__at()</tt> directive). This is possible in page 0 of 48 KB ROMs, for example, or more simply with mapper segments. For example, with an 8 KB mapper, you could use the last bank (<tt>0xA000</tt>-<tt>0xBFFF</tt>) to put your music at the beginning of the segment, so that it's readable in <tt>0xA000</tt>.		* Put the music directly in the "right" place in your program. This can be quite complicated in C, unless you manually place the data at a given address (with the <tt>__at()</tt> directive). This is possible in page 0 of 48 KB ROMs, for example, or more simply with mapper segments. For example, with an 8 KB mapper, you could use the last bank (<tt>0xA000</tt>-<tt>0xBFFF</tt>) to put your music at the beginning of the segment, so that it's readable in <tt>0xA000</tt>.
		+
		+	=== Interruption ===
		+	The <tt>AKx_Decode()</tt> function temporarily changes the call stack address (SP register value) to optimize its execution and restores the correct value at the end.
		+	If the update function is called from the main loop, an interrupt may occur while the call stack address is incorrect, potentially overwriting music data and causing the game to crash.
		+
		+	In such cases, a simple solution is to disable interrupts while updating the music:
		+	<syntaxhighlight lang="C">
		+	DisableInterrupt();
		+	AKx_Decode();
		+	EnableInterrupt();
		+	</syntaxhighlight>

@@ Line 3: / Line 3: @@
 When you export a music file from Arkos Tracker, you select this address (e.g., <tt>0xD000</tt>).
 {|
-| [[image:Arkos export.png|x500px|thumb|Arkos Tracker II's AKG exporter<br/>Encode to address (bottom-left)]]
+| [[image:Arkos export.png|x400px|thumb|Arkos Tracker II's AKG exporter<br/>Encode to address (bottom-left)]]
-| [[image:Arkos3 export.png|x500px|thumb|Arkos Tracker 3's AKG exporter<br/>Encode to address (middle)]]
+| [[image:Arkos3 export.png|x400px|thumb|Arkos Tracker 3's AKG exporter<br/>Encode to address (middle)]]
 |}
 In your program, you must ensure that the music is placed at this address to initialize the playback properly.

@@ Line 2: / Line 2: @@
 Arkos music is designed to work only if played at a specific address.
 When you export a music file from Arkos Tracker, you select this address (e.g., <tt>0xD000</tt>).
 In your program, you must ensure that the music is placed at this address to initialize the playback properly.
@@ Line 9: / Line 13: @@
 ** SFX at <tt>0xE000</tt> (1 KB up to <tt>0xE3FF</tt>)
 * Put the music directly in the "right" place in your program. This can be quite complicated in C, unless you manually place the data at a given address (with the <tt>__at()</tt> directive). This is possible in page 0 of 48 KB ROMs, for example, or more simply with mapper segments. For example, with an 8 KB mapper, you could use the last bank (<tt>0xA000</tt>-<tt>0xBFFF</tt>) to put your music at the beginning of the segment, so that it's readable in <tt>0xA000</tt>.