The first step is to always setup your project. The link provided here will show you step-by-step how to do that. If you've already downloaded Devkitpro, then you can skip that step and focus on setting up the folder structure. This is something you'll do for every project so in later projects I'll just assume you've completed this step.
Single Pixel
In this tutorial we're going to start simple, I mean really simple. We are going to draw a single red pixel in the upper left corner of the screen step-by-step. Creating something as simple as a single pixel can be more difficult than you might think, so let's get started.
Project Setup
Create main.cpp
Assuming you now have your project set up, the first thing we're going to do is create a file called main.cpp and stick the the following code into it. You need to place this into the source directory and not the include directory. There's really only 4 lines of code to worry about, but it probably all looks like gibberish to you. Well, the first 2 lines should look like gibberish, but the last 2 lines should look familiar if you've programmed in C or C++ before.
The while(1); line just means to loop forever. You actually don't need it in this particular program for it to work. I always just include it by default since it's basically the game loop. When we start working on more complicated projects, then we'll put stuff in that loop, but for now it's empty.
The return 0 line is standard in C and C++. Notice that our main function has to return an integer when the program finishes. If some error occurred in the program and it has to terminate early then some integer will be returned that corresponds to some error code. If it makes it to this line here, then we can assume that everything ran fine and we can return 0, meaning that no errors have occurred.
Now for the two gibberish lines, I'll explain below.
main.cpp
int main()
{
*(volatile unsigned short*)0x04000000 = 0x0403;
*(volatile unsigned short*)0x06000000 = 0x001F;
while(1);
return 0;
}
First Line Explanation
Take a look at the first line here:
*(volatile unsigned short*)0x04000000 = 0x0403;
This looks like a mess and you should never program this way unless you really like making life hard on yourself. In the future we'll make lines like this more readable, but I think it helps to see it in its more or less raw form. The GameBoy Advance has a bunch of registers that serve different purposes. Most of these registers are 16 bits wide and stored in an area of memory called the Input / Output Memory or IORAM which starts at memory address 0x0400:0000h.
One such register called the display register or "REG_DISP" for short. It's conveniently located in the first location in the IORAM, that is it has the same memory address of 0x0400:0000h. There are various settings in here that we can set. I'm not going to go over everything, just what we need to know for this project. So, there's really only 2 things we need to set:
- The mode we're using
- Which background to use.
REG_DISP
Second Line Explanation
Moving on to the second line we see:
*(volatile unsigned short*)0x06000000 = 0x001F;
Knowing what we know from the previous explanation this probably doesn't look as intimidating now right? We can see that we are storing a 2 byte value into memory location 0x0600:0000 this time. The two questions you need to be asking are, what does that 2 byte value mean and why are we storing it here?
First off, the memory address 0x0600:0000 refers to Video Memory or VRAM for short. The Gameboy Advance has 96KB of VRAM and this is where it starts. In mode 3, the location in VRAM corresponds directly to the location of pixels on the screen. The first pixel on the screen is in the top left corner, so this should correspond to the first memory address in VRAM.
So the value we're trying to store in this location represents a color. In fact, it represents the color red. I would suggest you click on the link to learn more about colors on the Gameboy Advance.
REG_DISP
Run and Finish
Now that all of that is explained, all we have left to do is compile and run our little program. Please make sure you have your project set up and structured as explained in the Project Setup section and that you're Makefile is in place. Once you've done that go ahead and compile the program as explained in the Setup section. Now open up your Gameboy Advance emulator and navigate to your project folder and open up the file with the .gba extension. What you should see is the image on the right. You may not be able to see it so I would suggest making the window bigger. You can set the window size to x4 in the Options -> Video menu.
If you don't see the red pixel then try going through everything again and see if there was anything you missed.
VisualBoy Advance
