add MIT licensing and add/update documentation

LICENSE

@@ -0,0 +1,18 @@
+Copyright (c) 2003-2021 James Daniels
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software and associated documentation files (the "Software"), to deal in
+the Software without restriction, including without limitation the rights to
+use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
+the Software, and to permit persons to whom the Software is furnished to do so,
+subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
+FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
+COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
+IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
+CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Makefile

@@ -20,15 +20,20 @@ EXAMPLE_DIR = examples/AASExample
 EXAMPLE2_DIR = examples/AASExample2
 EXAMPLE_CPP_DIR = examples/AASExample_c++
 
+CONV2AAS_FILE = conv2aas
+ifeq ($(OS),Windows_NT)
+	CONV2AAS_FILE = conv2aas.exe
+endif
+
 LIB = $(BUILD)/aas/lib
 INCLUDE = $(BUILD)/aas/include
 BUILD_AAS = $(LIB)/libAAS.a
 BUILD_CONV2AAS_DIR = $(BUILD)/conv2aas
-BUILD_CONV2AAS = $(BUILD_CONV2AAS_DIR)/conv2aas
+BUILD_CONV2AAS = $(BUILD_CONV2AAS_DIR)/$(CONV2AAS_FILE)
 BUILD_EXAMPLES = $(BUILD)/examples
 
 AAS = $(AAS_DIR)/libAAS.a
-CONV2AAS = $(CONV2AAS_DIR)/conv2aas
+CONV2AAS = $(CONV2AAS_DIR)/$(CONV2AAS_FILE)
 EXAMPLE = $(EXAMPLE_DIR)/$(EXAMPLE_PREFIX).gba
 EXAMPLE2 = $(EXAMPLE2_DIR)/$(EXAMPLE2_PREFIX).gba
 EXAMPLE_CPP = $(EXAMPLE_CPP_DIR)/$(EXAMPLE_CPP_PREFIX).gba

README.md

@@ -0,0 +1,48 @@
+### Apex Audio System
+
+The Apex Audio System (AAS) is a sound library for the GBA. It includes a highly
+efficient mixer, MOD playing routines and support for up to 16 channels. It is
+designed for developers using a GCC-based development environment. AAS uses RAW,
+WAV or *tracker 1-16 channel MOD files as input.
+
+
+### Documentation
+
+AAS is fairly well documented. From building the library to a starter guide to
+an extensive description of the api. See <root>/docs/index.html
+
+
+### History
+
+Apex Audio System was made by James Daniels of Apex Systems back in 2003 for the
+GBA version of Payback. The library underwent several revisions, the latest of
+which was v1.11. At the beginning of 2021, James was so kind to donate the
+sources to the community, hence this Git repo.
+
+
+### Latest release
+
+The current release is v1.12. See the documentation for a list of changes.
+
+
+### Contact
+
+Github project page: https://github.com/stuij/apex-audio-system
+
+Pull requests are welcome, as are forks of course. If you want to report issues,
+open an issue on the Github project issue tracker.
+
+For a more realtime interactive experience, join gbadev on Discord. There's a
+good chance there's one or two people there that have used AAS before.
+
+
+### License
+
+AAS is now distributed under the MIT license. For licensing terms, see the
+LICENSE file in the root of this repo or go to
+http://opensource.org/licenses/MIT
+
+James only had one request when handing over the sources: that users of the
+library include a credit to Apex Designs. In essence this is now covered by the
+MIT license. It's up to you how you want to fill this in, but please be
+respectful of this requirement.

docs/api_mixer.html

@@ -88,7 +88,7 @@
 <tr>
 <td valign=top><b>NOTES</b></td>
 <td>
-<p>This function (and the others in this section of the documentation) should only be used if you've got a strong reason for needing to access the mixing routine directly. Because of this, it isn't included in the usual "AAS.h" header file - you'll need to include "AAS_Mixer.h" instead, which is in the "AASFiles\LibAAS\LowLevelAccess" folder of the AAS SDK. A good understanding of the GBA's sound hardware is required to use this routine directly.</p>
+<p>This function (and the others in this section of the documentation) should only be used if you've got a strong reason for needing to access the mixing routine directly. Because of this, it isn't included in the usual "AAS.h" header file - you'll need to include "AAS_Mixer.h" instead, which is in the "aas/" folder of either the release or the &lsaquo;root&rsaquo;/<b>build</b> file when building from source. A good understanding of the GBA's sound hardware is required to use this routine directly.</p>
 
 <p>The AAS_Channel structure is defined in the header file as follows:</p>
 

docs/conv2aas.html

@@ -125,7 +125,7 @@
 <br><font size=+1 color="#333377">:: Calling Conv2AAS</font>
 <blockquote>
 
-<p>Conv2AAS includes versions compiled for DOS/Windows (Conv2AAS.exe) and Linux (Conv2AAS). It should be called from the command line and only needs one parameter, which is the name of the folder that contains the data files. All the files in that folder will be processed so it is recommended that you create a subfolder for your project that contains all the sound files. Conv2AAS always creates two files in the current directory:</p>
+<p>Conv2AAS includes versions compiled for DOS/Windows and Linux. Both are named conv2aas. It should be called from the command line and only needs one parameter, which is the name of the folder that contains the data files. All the files in that folder will be processed so it is recommended that you create a subfolder for your project that contains all the sound files. Conv2AAS always creates two files in the current directory:</p>
 
 <p><b>AAS_Data.h</b> : This is the header file that you should include in your main code whenever you want access the AAS sound data.</p>
 

docs/example.html

@@ -52,17 +52,25 @@
 <li><b>Your .mod, .raw and .wav files</b> : In these examples there are three files here: Ambulance.wav, Boom.raw and one of FlatOutLies.mod, CALIBRA.MOD or its_just_sonorous.mod</li>
 </ul>
 </li>
-<li><b>LibAAS</b> : Folder. Contents:
-<ul>
-<li><b>LibAAS.a</b> : Main AAS Library.</li>
-<li><b>AAS.h</b> : Main AAS header file. Should always be included in your projects.</li>
-<li><b>AAS_Mixer.h</b> : Optional AAS header file. Should only be included if you intend to access the mixer directly (not recommended).</li>
-</ul>
+<li><b>aas</b> : Folder. Contents:
+  <ul>
+  <li><b>lib</b> : Folder. Contents:
+    <ul>
+    <li><b>LibAAS.a</b> : Main AAS Library.</li>
+    </ul>
+  </li>
+  <li><b>include</b> : Folder. Contents:
+    <ul>
+    <li><b>AAS.h</b> : Main AAS header file. Should always be included in your projects.</li>
+    <li><b>AAS_Mixer.h</b> : Optional AAS header file. Should only be included if you intend to access the mixer directly (not recommended).</li>
+    </ul>
+  </lib>
+  </ul>
 </li>
 <li><b>Makefile</b> : Your makefile. See below for suggestions on how to set it up to use AAS.</li>
 <li><b>crt0.s</b> : GBA startup code. AASExample2 requires the use of specially modified version. See below for suggestions on how to set it up to use AAS.</li>
 <li><b>lnkscript</b> : Standard GBA linkerscript.</li>
-<li><b>Conv2AAS.exe/conv2aas</b> : The AAS conversion tool. Use Windows/DOS or Linux version depending on your system.</li>
+<li><b>conv2aas</b> : The AAS conversion tool. Use Windows or Linux version depending on your system.</li>
 <li><b>Your .s, .c, .cpp, .h and other files</b> : In this example, there is just one file here: AASExample.c (or, in "AASExample_c++", AASExample.cpp).</li>
 </ul>
 
@@ -72,21 +80,26 @@
 
 <p>In order for your programs to compile successfully they must be linked to the AAS library. To do this, the following options should be passed to the linker:</p>
 
-<p><b>-LLibAAS</b> : Adds the "LibAAS" subfolder to the list of folders that will be searched for library files.</p>
+<p><b>-Laas/lib</b> : Adds the "aas/lib" subfolder to the list of folders that will be searched for library files.</p>
 <p><b>-lAAS</b> : Links the AAS library ("libAAS.a") to your project.</p>
 
 <p>In order for the compiler to be able to find AAS's include files, the follow option needs to be specified at the compilation stage:</p>
 
-<p><b>-ILibAAS</b> : Adds the specified subfolder ("LibAAS") to the list of folders that will be searched for include files.</p>
+<p><b>-Iaas/include</b> : Adds the specified subfolder ("aas/include") to the list of folders that will be searched for include files.</p>
+
+<p>Both of these options are specified in the Makefile included in the project. It may also be necessary to change the "CROSS =" line in the Makefile depending on the location and file names of the GBA tools on your system.</p>
 
-<p>Both of these options are specified in the Makefile included in the project. It may also be necessary to change the "CROSS =" line in the Makefile depending on the location and file names of the GBA tools on your system. Once the Makefile has been configured appropriately, it is safe to include the AAS header files in your project, as shown in the example code:</p>
+<p><b>NOTE</b>: the Makefiles in the individual example directories aren't selfcontaining for maintainability reasons. They include example.make which includes common.make. Both are found in &lsaquo;root&rsaquo;/<b>make</b>. To make a single makefile out of these, just recursively replace the include directive with the actual content of the included file.</p>
+
+<p>Once the Makefile has been configured appropriately, it is safe to include the AAS header files in your project, as shown in the example code:</p>
 
 <pre>
 #include "AAS.h"
 #include "AAS_Data.h"</pre>
 
 <p>The "AAS_Data.h" header file contains information specific to your project and is generated by the <a href="conv2aas.html">Conv2AAS</a> program. The makefile included with the example code automatically calls <a href="conv2aas.html">Conv2AAS</a> each time the program is compiled so that your project will always have an up-to-date header file and will be linked to the most recent version of the files in the "AAS_Data" folder.</p>
 
+
 </blockquote>
 <br><font size=+1 color="#333377">:: Interrupt Handling And crt0.s</font>
 <blockquote>

docs/faq.html

@@ -39,64 +39,6 @@
 
 <br>
 
-<br><font size=+1 color="#333377">:: Why do I get "undefined reference to _call_via_r3" when I link to AAS?</font>
-<blockquote>
-
-<p>This is usually caused by using ld to do the linking rather than gcc. (The "_call_via_rX" functions are defined in libgcc.a which is usually automatically linked to your project if you use gcc to link, but not if you use ld.)</p>
-
-</blockquote>
-<br><font size=+1 color="#333377">:: How do I use AAS with DevKitArm?</font>
-<blockquote>
-
-<p>AAS itself works fine with DevKitArm, but in order to get AASExample to compile under DevKitArm, you need to make the following changes to the makefile:</p>
-
-<ul>
-<li>"CROSS" needs to be changed from "arm-agb-elf-" to "arm-elf-".</li>
-<li>"-Xlinker -Map $(MAP)" needs to be removed from LDFLAGS. (This may be a bug in DevKitArm.)</li>
-</ul>
-
-<p>Also, assuming you're using Windows, you'll need to delete the Linux version of Conv2AAS (which has a filename of "conv2aas" (as opposed to "conv2aas.exe" for the Windows version)) from the AASExample folder to stop DevKitArm from attempting to use the wrong executable.</p>
-
-</blockquote>
-<br><font size=+1 color="#333377">:: How do I get AAS to work with HAM?</font>
-<blockquote>
-
-<p>There's a pretty good explanation online <a href="http://www.ngine.de/site/modules.php?name=Forums&file=viewtopic&p=2031#2031">here</a>.</p>
-
-</blockquote>
-<br><font size=+1 color="#333377">:: I've just upgraded from AAS v1.03 to v1.04 and now my code won't compile. Why?</font>
-<blockquote>
-
-<p>In order to avoid clashes with the user's own declarations, some of the variable types and definitions in AAS.h were renamed in v1.04:</p>
-
-<ul>
-<li>u32 -> AAS_u32</li>
-<li>s32 -> AAS_s32</li>
-<li>u16 -> AAS_u16</li>
-<li>s16 -> AAS_s16</li>
-<li>u8 -> AAS_u8</li>
-<li>s8 -> AAS_s8</li>
-<li>BOOL -> AAS_BOOL</li>
-<li>TRUE -> AAS_TRUE</li>
-<li>FALSE -> AAS_FALSE</li>
-<li>NULL -> AAS_NULL</li>
-</ul>
-
-<p>To fix this, you should either change your code to use the new definitions or you should add the declarations below whenever AAS.h is included in your code:</p>
-
-<pre>
-#define u32 unsigned int
-#define s32 signed int
-#define u16 unsigned short
-#define s16 signed short
-#define u8 unsigned char
-#define s8 signed char
-#define BOOL unsigned char
-#define TRUE 1
-#define FALSE 0
-#define NULL 0</pre>
-
-</blockquote>
 <br><font size=+1 color="#333377">:: How do I reference AAS sounds with numbers?</font>
 <blockquote>
 

docs/getting_started.html

@@ -39,10 +39,68 @@
 
 <br>
 
+<br><font size=+1 color="#333377">:: Building AAS components</font>
+<blockquote>
+
+<p>We use a makefile in the root of the repo to build the library, conversion tool and examples. It is expected that you have a cross-compiler and a host compiler installed on your system. The paths to these need to be configured at the top of the makefile:</p>
+<ul>
+<li><b>$(CROSS)</b>: The directory path and prefix of the cross-compilation tools. For example, if you have installed devkitPro to the default location, and the tools aren't visible in your <b>PATH</b>, the line would be:
+  <ul>
+  <li><tt>export CROSS = /opt/devkitpro/devkitARM/bin/arm-none-eabi-</tt></li>
+  </ul>
+</li>
+<li><b>$(PREFIX)</b>: The directory path and prefix of the host compiler. This can normally be left as is, but for example it could have been installed in user/local:
+  <ul>
+  <li><tt>export PREFIX = /usr/local/</tt></li>
+  </ul>
+</li>
+</ul>
+
+<p>Run <tt>make</tt> without arguments in the root of the repo to build aas, conv2aas and the examples</p>. The files can be found in &lsaquo;root&rsaquo;/<b>build</b>:</p>
+<ul>
+<li><b>aas</b> : Folder. Contents:
+  <ul>
+  <li><b>lib</b> : Folder. Contents:
+    <ul>
+    <li><b>LibAAS.a</b> : Main AAS Library.</li>
+    </ul>
+  </li>
+  <li><b>include</b> : Folder. Contents:
+    <ul>
+    <li><b>AAS.h</b> : Main AAS header file. Should always be included in your projects.</li>
+    <li><b>AAS_Mixer.h</b> : Optional AAS header file. Should only be included if you intend to access the mixer directly (not recommended).</li>
+    </ul>
+  </lib>
+  </ul>
+</li>
+<li><b>conv2aas</b> : Folder. Contents:
+  <ul>
+  <li><b>conv2aas</b></li>
+  </ul>
+</li>
+<li><b>examples</b> : Folder. Contents:
+  <ul>
+  <li><b>AASExample.gba</b>: AAS Example for projects with no other CPU intensive interrupts</li>
+  <li><b>AASExample2.gba</b>: AAS Example for projects with other CPU intensive interrupts</li>
+  <li><b>AASExamplePlusPlus</b>: AAS C++ Example for projects with no other CPU intensive interrupts</li>
+  </ul>
+</li>
+</ul>
+
+<p>To build one or more individual components, add their name as argument to the makefile:</p>
+<ul>
+<li>aas</li>
+<li>conv2aas</li>
+<li>example</li>
+<li>example2</li>
+<li>example_cpp</li>
+</ul>
+
+</blockquote>
 <br><font size=+1 color="#333377">:: First Steps</font>
 <blockquote>
 
-<p>First of all, the user must include the AAS header files ("AAS.h" and, optionally, "AAS_Mixer.h") and link "libAAS.a" with their project. Next, the interrupt handling routines must be set up so that a Timer 1 interrupt results in a call to <a href="api_general.html#AAS_Timer1InterruptHandler">AAS_Timer1InterruptHandler</a> (or <a href="api_general.html#AAS_FastTimer1InterruptHandler">AAS_FastTimer1InterruptHandler</a> with a seperate call to <a href="api_general.html#AAS_DoWork">AAS_DoWork</a> later if "AAS_MultipleInterrupts" are being used). The <a href="example.html">example code</a> included with AAS demonstrates how to do this, and users are encouraged to reuse the code shown in their own projects.</p>
+<p>Once the library and conv2aas are built, the user must include the AAS header files ("AAS.h" and, optionally, "AAS_Mixer.h") and link "libAAS.a" with their project. Next, the interrupt handling routines must be set up so that a Timer 1 interrupt results in a call to <a href="api_general.html#AAS_Timer1InterruptHandler">AAS_Timer1InterruptHandler</a> (or <a href="api_general.html#AAS_FastTimer1InterruptHandler">AAS_FastTimer1InterruptHandler</a> with a seperate call to <a href="api_general.html#AAS_DoWork">AAS_DoWork</a> later if "AAS_MultipleInterrupts" are being used). The <a href="example.html">example code</a> included with AAS demonstrates how to do this, and users are encouraged to reuse the code shown in their own projects.</p>
 
 <p>It is also recommended that the project's makefile be modified so that <a href="conv2aas.html">Conv2AAS</a> is automatically called when the project is compiled, and its output is assembled and linked with the main code. The makefile included with the <a href="example.html">example code</a> shows how to do this.</p>
 

docs/index.html

@@ -63,6 +63,22 @@
 </tr>
 </table>
 
+</blockquote>
+<br><font size=+1 color="#333377">:: History</font>
+<blockquote>
+
+<p>Apex Audio System was made by James Daniels of Apex Systems back in 2003 for his GBA game Payback. The library underwent several revisions, the latest of which was v1.11. At the beginning of 2021, James was so kind to donate the sources to the community.</p>
+
+<p>The current release is v1.12.</p>
+<p>Changes since v1.11:</p>
+<ul>
+<li>AAS is now open source under a MIT license and is hosted on Github</li>
+<li>code was updated to work with current devkitPro</li>
+<li>examples and code are driven by toplevel makefile</li>
+<li>library and example roms are to be found under &lsaquo;root&rsaquo;/<b>build</b></li>
+<li>updated documentation</li>
+</ul>
+
 </blockquote>
 <br><font size=+1 color="#333377">:: How Fast Is It?</font>
 <blockquote>
@@ -113,17 +129,19 @@
 <br><font size=+1 color="#333377">:: Licensing</font>
 <blockquote>
 
-<p>AAS is free for non-commercial use, although you must display the AAS splash screen using the AAS_ShowLogo() function when the program is first started if you distribute your work.</p>
+<p>AAS is now distributed under the MIT license. For licensing terms, see the LICENSE file in the root of this repo or go to http://opensource.org/licenses/MIT</p>
 
-<p>Commercial developers are not required to display the splash screen but need a license in order to use AAS in a published title. To discuss licensing terms, please contact us at <a href="mailto:[email protected]">[email protected]<a/>.</p>
+<p>James only had one request when handing over the sources: that users of the library include a credit to Apex Designs. In essence this is now covered by the MIT license. It's up to you how you want to fill this in, but please be respectful of this requirement.</p>
 
 </blockquote>
-<br><font size=+1 color="#333377">:: Contacting Us</font>
+<br><font size=+1 color="#333377">:: Contact</font>
 <blockquote>
 
-<p>Any questions, suggestions or bug reports should be sent to <a href="mailto:[email protected]">[email protected]<a/>.</p>
+<p>The sources are hosted on Github: https://github.com/stuij/apex-audio-system</p>
+
+<p>Pull requests are welcome, as are forks of course. If you want to report issues, open an issue on the Github project issue tracker.</p>
 
-<p>You can download the latest version of AAS from our website here: <a href="http://www.apex-designs.net/tools_aas.html">http://www.apex-designs.net/tools_aas.html</a>
+<p>For a more realtime interactive experience, join <b>gbadev</b> on Discord. There's a good chance there's one or two people there that have used AAS before.</p>
 
 </blockquote>
 

make/example.make

@@ -17,8 +17,13 @@ IWRAM =
 
 include ../../make/common.make
 
+CONV2AAS_FILE = conv2aas
+ifeq ($(OS),Windows_NT)
+	CONV2AAS_FILE = conv2aas.exe
+endif
+
 AAS_Data.o:
-	../../build/conv2aas/conv2aas AAS_Data
+	../../build/conv2aas/$(CONV2AAS_FILE) AAS_Data
 	$(AS) $(ASFLAGS) -o $@ AAS_Data.s
 
 $(NAME): crt0.o $(IWRAM) $(GFX) $(SOUND) $(SRC)

src/aas/AAS.h

@@ -1,3 +1,7 @@
+// Copyright (c) 2003-2021 James Daniels
+// Distributed under the MIT License
+// license terms: see LICENSE file in root or http://opensource.org/licenses/MIT
+
 // Main AAS include
 //
 // See API documentation for more information.

src/aas/AAS_ASM.s

@@ -1,3 +1,7 @@
+@ Copyright (c) 2003-2021 James Daniels
+@ Distributed under the MIT License
+@ license terms: see LICENSE file in root or http://opensource.org/licenses/MIT
+
 .TEXT
 .SECTION    .text,"ax",%progbits
 .ALIGN