APEX AUDIO SYSTEM Instruction Manual

intro | getting started | conv2aas | example | faq api : index | general | sfx | mod | misc | mixer

Note that if you downloaded the AAS release package, the needed library, examples and conv2aas program for both Linux and Windows are already present in the ‹root›/build directory.

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 (for PREFIX and TOOLS, don't forget suffix slash forward..):

• $(CROSS): 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 PATH, the line would be:
  • export CROSS = /opt/devkitpro/devkitARM/bin/arm-none-eabi-
• $(PREFIX): 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:
  • export PREFIX = /usr/local/
• $(TOOLS): The directory path to common gba tools. Specifically we need to find gbafix in this directory. If you installed devkitpro, which includes gbafix, the line would be:
  • export TOOLS = /opt/devkitpro/tools/bin/

Run make without arguments in the root of the repo to build aas, conv2aas and the examples

. The files can be found in ‹root›/build:

• aas : Folder. Contents:
  • lib : Folder. Contents:
    • LibAAS.a : Main AAS Library.
  • include : Folder. Contents:
    • AAS.h : Main AAS header file. Should always be included in your projects.
    • AAS_Mixer.h : Optional AAS header file. Should only be included if you intend to access the mixer directly (not recommended).
• conv2aas : Folder. Contents:
  • conv2aas
• examples : Folder. Contents:
  • AASExample.gba: AAS Example for projects with no other CPU intensive interrupts
  • AASExample2.gba: AAS Example for projects with other CPU intensive interrupts
  • AASExamplePlusPlus: AAS C++ Example for projects with no other CPU intensive interrupts

To build one or more individual components, add their name as argument to the makefile:

• aas
• conv2aas
• example
• example2
• example_cpp

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 AAS_Timer1InterruptHandler (or AAS_FastTimer1InterruptHandler with a seperate call to AAS_DoWork). The example code section in this documentation, and the code included with AAS demonstrates how to do this. Users are encouraged to reuse the code shown in their own projects.

It is also recommended that the project's makefile be modified so that Conv2AAS is automatically called when the project is compiled, and its output is assembled and linked with the main code. The makefile included with the example code shows how to do this.

It is also important that none of the following resources are used in your code as they are required by AAS:

• DMA1 and DMA2. These are used to transfer the sound data.
• Timer 0 and Timer 1. These are used to syncronise the sound output.

Also note that DMA3 can be used, but only via the AAS_DoDMA3 function call or with a single stmia instruction. Once these steps have been successfully completed AAS should be ready for use. A detailed description of AAS's API can be found here and some example code can be found here.

Whilst every effort has been made to make AAS as easy to use as possible, there are a few things to look out for:

• Be careful when using DMA3. AAS's mixer uses DMA3 for extra speed, which means that if you're using it in your code you must take precautions to prevent clashes. All DMA3's parameters must be written out with a single stmia instruction. The AAS_DoDMA3 function has been provided to do this for you.
• Do not use DMA1, DMA2, Timer 0 or Timer 1. They are reserved for use by AAS.
• Always call AAS_SetConfig before calling any other sound functions. AAS_SetConfig must be called before any other AAS function, with the exception of AAS_DoDMA3 and AAS_ShowLogo.
• Make sure that Conv2AAS's output is assembled and linked with your project. Conv2AAS is a tool for including data files in your project so that they can be used by AAS. It produces a header file (which should be included in your project) and an assembler file (which must be assembled and linked with your project). It is important to call Conv2AAS in your makefile before any other files are compiled so that the header file it produces is up-to-date.