The SGADE Frequently Asked Questions

1. About

1.1 What does SGADE mean?
1.2 Why was the SGADE released?
1.3 What is the SGADE's history?
1.4 Who made the SGADE and how can I contact them?
1.5 Hey, why didn't you reply to my email?

2. Legal stuff

2.1 In what ways am I allowed to use the SGADE?
2.2 What about amateur usage?
2.3 What about commercial usage?

3. Contributions

3.1 Can I contribute to the SGADE?
3.2 How can I contribute to the SGADE?
3.2 Why do you have to be so difficult about contributing code to the SGADE?

4. Setup

4.1 Where can I get the SGADE?
4.2 How do I install the SGADE?
4.3 How do I create my first SGADE program?

5. Coding

5.1 Why don't you use C++?
5.2 Why don't you define all registers into one huge header file?
5.3 I've coded something awesome and want to release it. Now what?
5.4 Why are there several fixed point divide and multiply macros?
5.5 Why don't you locate some of your code in IWRam?

6. Miscellaneous

6.1 What should I do when my question still isn't answered?

1. About

1.1 What does SGADE mean?

SGADE is an acronym which stands for Socrates Gameboy Advance Development Engine. When Jaap began writing the Gameboy Advance code that later became the SGADE, he was reading Plato's The Republic which is about Socrates. He was so inspired that he named the project after this great Greek philosopher.

Contrary to what you may think, the main reason for releasing the SGADE was not to stuff another generic SDK down the collective throat of the GBADEV scene. Rather it was released because the only alternative was to let it rot on Jaap's hard disk, occasionally dusting it off when he felt inspired enough to write another GBA demo. You benefit from this because now you can point and laugh at it.

Jaap Suter created the workspace file for the SGADE in Les Deux Alpes, France at July 2001. He was there to snowboard, but everyday ski lifts closed at 14:00, so afternoons he was coding happily on his laptop -- coding at the side of the pool with a view on the mountains is very productive. When he got back to the Netherlands he decided that the project was good enough to continue.

In January 2002, Jaap created the mailing list. Over the next several months many good extensions were submitted by mailing list members and the library grew. Things were good until work and other commitments forced Jaap to quit development of the library. He put out a call to the mailing list for someone to take over the reigns of development, and it was luckily answered by Mark Price.

And it goes on...

Even though Jaap Suter started the whole thing, at this moment several people are working on the SGADE. If you want to get in touch with them I suggest you subscribe to the mailinglist.

For a complete list of the current SGADE contributors, see the Info page, some even have mailing addresses.

I get lots of email everyday and I don't have time to answer them all. If your email isn't answered within two weeks after you send it, you can assume it won't get a reply at all. Possible reasons for this include:

• You may have mailed the wrong person. For example, I probably won't reply to general GBA development questions. There is a great GBADev mailing list for that. Join, and we'll talk there.
• Instead of bugging me, you should have used Google or any other search engine to get your information. Learn to find your own information, or admit that you're lazy.
• I might not be able to answer your question and I'm probably too ashamed to admit it.

2. Legal Stuff

The SGADE is distributed under a very liberal (and short) license.

If you're too lazy to read it, here's the gist: you are free to write and distribute any kind of software using the SGADE with no licensing fee, and without any restrictions on your own code; you just can't claim that you wrote the SGADE code itself. In short:

There are no restrictions on any programs that use the SGADE.

Of course, we would love to get some credit, but it is not neccesary.
As a result We cannot be held responsible for anything that might happen when you use this code. So if you find yourself in a pile of blood after downloading the SGADE, don't call us.

There are no special rules for amateur usage. Question 2.1 applies.

Not that I am expecting anybody ever to use the SGADE for commercial use, but the question looks cool on a FAQ. Anyway, there are no special rules for commercial usage, Question 2.1 applies.

3. Contributions

Yes, I encourage people to contribute to SGADE. I have a busy life, and working on the SGADE is not my top priority (even though I like it a lot). So if other people can make the SGADE into something better, I'm all for it.

Of course if you contribute in any possible way, you will get full credit.

You can contribute in several ways.

• Write new functionality for the SGADE.
  
  If you have some code lying around that might fit into the SGADE contact me A.S.A.P. I would love to see other people's code into the SGADE. So start writing!
  
  However, note that there are rather strict rules for code in the SGADE. All code must comply to the code style in order to be part of the SGADE. Take a look at question 3.3 for more information.
  
  If this is a problem for you, I'd be happy convert the code myself. So if you have a nifty piece of code lying around that might fit in the SGADE. Send it along, and I'll fit it in myself. You'll still get the credit of course.
  
  
• Write a demo using the SGADE.
  
  If you write a demo using the SGADE I'd love to host it on this site. Check the demos section to see what other people have done. Of course you can still host the demos on other sites as well. Contact me if you have a demo.
  
  You are recommended to release the source code as well, but even without the code I love to host it. Of course, for demos the codestyle rules do not apply. So if you created a demo using your own style I don't care. As long as it uses the SGADE, I'll put it online.
  
  Make sure your demo contains no sexual, discriminating or other questionable content. I'd love some good sarcasm though. Thank you.
  
  
• Other ways...
  
  Maybe you want to help me with the documentation? Maybe you want to write a SGADE specific tool? Or you have a completely different idea? Let me know by clicking here.

We have seen good online community open source projects deteriorate into piles of unrelated inconsistent code garbage because everybody had their own plans with it.

We am not saying that the current state of the SGADE is a masterpiece of software engineering. Far from it even. But we are at least making the effort to keep things clean.

Still, while we are enforcing a single code style onto contributions, we would love to hear input from you if you have ideas on how to make the SGADE better. We're always open for suggestions. So if you think our code style, design or architecture sucks, let us know.

4. Setup

The SGADE can be downloaded on the download page.

If you have Microsoft Visual Studio it's going to be very easy. Download the complete SGADE package and load the Visual Studio workspace. Read the readme, and you will see it says that you should set two directories (compiler and source) in the makefile (which is included in the workspace). After that you are ready to build, and everything should work.

If you don't have Visual Studio but use GCC make or another tool it's gonna be a bit more difficult. I suggest you check http://www.devrs.com/gba/. They have some excellent information on compiling stuff for the Gameboy Advance.

If all fails, use the mailinglist.

I would recommend taking a look at the sample included in the distribution. It shows how to use many of the library. If you need more help, check out the tutorial.

5. Coding

C++ has its uses for certain projects, but for the SGADE it would mean overhead. I know that technically C++ shouldn't have any overhead over C, but those who think it comes easy should read the book Effective C++ by Scott Meyers. I program a lot of C++ at work, and I use it for most of my other projects. But for the SGADE I want to stick to C and Assembly. Of course this does not mean that you can't program in C++ as SGADE supports being called from a C++.

Information hiding is one of the keys to succesfull programming. I don't want to use one huge bloated headerfile just so you can use everything from everywhere. Besides the fact that it helps compile times, it keeps things clean and hidden.

So you managed to compile something? Well, you're not done yet. You've got to crank it up! This is not really my territory, and you should check the excellent documentation on http://www.devrs.com/gba/ for more information. Here I'll just provide a few guidelines for building a true release program.

• Make sure you have the -O2 setting enabled when compiling.
• Make sure SO_DEBUG is not defined, otherwise you'll be doing assertions at release time. Something you don't want...
• Don't you want to move some code to IWRam? Maybe your own code, maybe some SGADE stuff.
• Deadstrip all unused code. Maybe you're not using the mode 4 polygon rasterizer at all. Then why link it in? Make sure you're not compiling and linking any unused code. However, watch out for interrupts. They may not be called directly from the code and the compiler might think they're not used. While in fact they are.

For this to explain, you have to know what happens when you multiply two fixed point numbers. Suppose you have two 16.16 fixed point numbers. When you multiply these you will get a 32.32 point number. You'd have to store this in a 64 register and shift this back 16 bits in order to get the correct number again. I could fix this using an 64 bits SMULL. However, by sacrificing some accuracy I can use a regular MULL and be quicker. For example we could do this by first shifting the two numbers back to 16.8 format. Then multiplying that to a 32.16 number. If the numbers are small enough you can cap the front 16 bits of and you are left with a 16.16 number again. With divisions this works basically the same.

Now what I did, is write different cases for different multiplies and divisions. When you multiply two numbers, most of the time you know what kind of ranges you are looking at. So use big for anything over 256, and small for everything below that. Very often you have to multiply a very big number by another number that is between zero and one. You should use the SO_FIXED_MULTIPLY_BIG_SMALL for that one. Cause it will keep accuracy in the fraction of the small number (where you want it).

If you need more accuracy than any of the macros supply, or your number overflows the limited range they provide you should use the SoFixedMultiply() or SoFixedMultiplyByFraction() functions. These give you an accurate result at the cost of being about four and two times slower respectively.

Because most of the IWRam solutions require special make settings or crt0.s files. I want this to compile as simply as possible. Once you have something up and running, and you want to optimize, you should be able to move stuff to IWRam yourself. Go here for more information about moving stuff to IWRam, or contact me if you can't figure it out.

Maybe in the future -- when I find a clean and simple solution -- the SGADE will put certain code in IWRam by default. But at the moment, you have to do it yourself.

6. Miscellaneous

Use the mailinglist and post your question there. If it pops up often, I'll add it to the FAQ.