#altik-reference

Enums and Bitmasks are the best!

Especially when working on software like a game, you find often certain lines of execution need to change based on what state the program is in. For example, if you're paused, you should skip over all the main update loop stuff, but instead you should run pause menu update stuff. It gets even messier when you start talking internal states in the software.

In C, the nicest way (at least that I've found so far) to accomplish this is to track what state you're in, and branch on those states. In the pause example, you would track "this game is now in paused mode", and at the top of your logic loop you just switch on the enum you created to give nice names to these states, and you end up with something like:

switch (state) { case normal:  normalFunc();  break; case paused:  pauseFunc();  break; ... default:  error(); }

And the thing is, this is perfectly fine for C. You split those functions out to a few different files if they get too messy, and your code actually stays quite maintainable.

But now enter Object-Oriented Land, after training yourself on that sort of system, and you start saying to yourself "Okay, I've got these room things which have a few different options for implementation, so maybe I'll just branch on cases and track a state for the class. Works in C, so it must be good!"

The problem is, this is not so nice and clean as in C. Now, in order to maintain your code, you can't really split out the helper functions as you would in C to keep things clean. They're basically private helper functions, so those functions get stuck in the same file and you bulk up your code massively, giving you a huge headache to deal with down the line.

So, how do you do this nicely with clases? With classes.

Okay, that might sound dumb, but here's the thing: a good portion of the time you have these state-based execution paths in OOP (at least in my experience), it's because you say something like "This room could have enemies, or it could have a shop, or it could...". In C, you're usually looking at "This program should branch depending on user input...".

The subtle difference here is that if a class's "type" isn't going to dynamically change (like it very well might in the C case), you don't need to track it at all, nor do you need to branch. Just create a base class and use inheritance to do your job for you - that's what it's for.

Plus, now you get a huge upshot. In C, if your various states have some shared code between states (I need to update the enemy attacking stuff in standard execution, as well as when the user opens their inventory, but not when paused), you have a mess on your hands trying to get this code to merge. In OOP, just create another nested level and youre golden. Granted that doesn't always work, but if it gets too convoluted, you can probably reorganize the structure to make things work out.

An extension to this idea is tracking values in bit-fields. By doing that, you are able to pack more data into a small space, and vastly optimize large fields of repeated types of data. At some point, you just start doing it by habit in other programming, especially to keep track of these states we just talked about.

This pushes a much more menacing and probably pervasive issue in programming: premature optimization. Yes, if you only need 8 values for some integer, and 16 for another, sharing bits saves space. However, if you just start doing that by default, you make your code almost illegible (because shifts and masks to get values is a lot less intuitive to an outside party than just calling a property name), and further very difficult to modify later.

Fun bug from this afternoon: let's say you have a custom ListAdapter you're working with to fill in data into a ListView, and you're trying to implement a method which allows you to insert a new element into that list. You're competent with the use of Adapters, so you're confident it works - in fact, the model for your add function matches most of the recommendations on StackOverflow:

So, you're confident everything is looking good, yet whenever you actually go to add the new string, the list doesn't update! It comes up when you leave and return to the activity (because you're properly serializing elsewhere in code), but it won't update on the spot.

So you go hunting further into StackOverflow to see if there was something subtle you missed about how to hook up a ListAdapter properly in your ListFragment. Maybe using setListAdapter doesn't properly set up your fragment's ListView as an observer for the adapter? That wouldn't make much sense, but you aren't sure. Perhaps it was something else...

Regardless, you spend a few hours hunting, and nothing comes up. All the errors with NotifyDataSetChanged are pretty dumb errors regarding simply misusing the class, which you've confirmed many times over by now that you haven't done.

So what's the problem?

Well, in case you had the same issues I did this afternoon, it may be that you accidentally let Eclipse fill in your functions for you, so among them you overwrote registerDataSetObserver and unregisterDataSetObserver, and they're filled in with TODO messages rather than calling the superclass's versions. WHOOPS.

Step 1) Ensure you're on the same subnet (Google will tell you!)

Step 2) On windows: go to the folder you'd like to share, open properties, go to Share tab, click Share... button, click Share at bottom.

Step 3) On mac: go to finder, go to the Go tab, select Connect to Server... (or Cmd-K). Connect to smb://[window's IP address here].

For the longest time now I've been doing NDS development and thought there was no way to do any debugging. For the most part I've just slid by on my wits of figuring out what might cause issues. Actually, it's kind of impressive the bugs I've found by just thinking about the issue - but it's completely unreasonable to do this all the time! It takes me a day or two to figure out just where the issue lies in most cases, and 9 times out of 10, once I figure out where the issue is, the issue is pretty much obvious.

Of course, that's where a good debugger comes in. As I said, I figured all this time that there was no option for doing debugging on the NDS. Generally speaking, this is correct: obviously the device doesn't come with a console window or GDB built in, and even if it did, there's no good way to step through source code on there. And most emulators aren't going to be nice enough to do much beyond just, y'know, emulating the device.

However, it turns out that the creators of DeSmuME are kinder than most developers! If you get the right distribution (currently, the only version I've found for windows is 9.6, 32-bit version, but I can't say for sure if there aren't newer ones - just don't get an x64 build), there is an included executable, DeSmuMe_dev.exe. This executable includes a flag: --arm9gdb=[PORT NUMBER] which turns the emulator into something like a debugging server.

Short version (to my understanding): running the dev executable with that flag and a filepath to the executable you wish to debug will launch the emulator, streaming out debugging information over a local port. Then you can find an IDE that can hook into such a server (the WinGDB extension for Visual Studio works nicely if you have a full version - a tutorial for setting up everything can be found here: http://vgcoding.blogspot.com/2011/01/how-to-debug-your-nds-rom-using-visual.html), and PRESTO: you have exactly the same sort of debugging you'd expect from any other programming project!

This is seriously godsend, I promise. Memory bugs crop up all the time on the NDS, since there's no dynamic allocation. You just get your pointers when you get them, and oftentimes you accidentally reuse them or tell your half-baked allocator to double-free a pointer, causing everything to crash.

Most commonly, I see this pop up when working with libnds's pre-cooked OAM "allocator", which, upon a request to allocate a sprite, will just hand you a pointer to VRAM to put your tiles and give you nothing else. All your subsequent calls to their shadow OAM setup expects not only that handed out pointer, but also a unique ID and various other stats.

This all means if you expect to have even remotely complex allocation of sprites in your system, you'll have to bake up your own allocator for IDs just to make sure you don't overuse them (fun fact: give an ID that's too big, and their shadow OAM will silently fail an assert and the emulation freezes).

Blah blah, rant rant - the point is, the debugger is real and helped me spot a nasty bug with my interactions with the libnds OAM manager in a few minutes, that would have otherwise taken me a day or two to find.

Fun fact: sometimes when you try to compile your code, the devkitPro compiler will not be happy and have compiler errors, but still reports back a successful compilation. Generally that's not a problem so long as you're not relying on the bottom message to decide if your code worked or not, but if you're developing in, say, Visual Studio, and your IDE is just reading the last bit to decide if stuff worked, and you always launch into the emulator right after building, you'll just keep seeing an old version that isn't new and your bugs won't go away and you'll spend a lot of time working out things you've actually already fixed...

TL;DR, just read the output logs when you have bugs - it could save your life. :D

If you're thinking of using sentinel values in a return from a C# function, because you really need an int but you also need to check if something is true, why not just return a bool and remember you've got out parameters?

So, I'm going to make this post with the assumption that the readers know how tile based graphics work in a rough sense - in particular, I'm coming from a background of working on the GBA and using tile graphics there, so if you're completely out of the know, go read Tonc's pages on this first.

To set up Sprites on the NDS, you've got to initialize a lot more stuff than with bitmap modes. libnds makes this kind of easy and kind of hard, depending on your perspective: it seems to me that they pretty much assume you'll use just their system for getting everything set up, so you have a lot of distinct steps in the process that end up getting merged together in their library.

What I mean is that there are a lot of situations like this: just like on the GBA, the NDS uses a DISPCNT register to control video modes and various parameters for them. If you were working with tonclib or making your own system to interface with the registers, what you'd expect to do would be to initialize this register first with all the parameters you expect, then proceed to set up the OAM and VRAM in their own initialization functions. libnds, on the other hand, sets up DISPCNT while you call various other functions - ie, when you call the built in OAM setup function, this is when the DISPCNT register is set to allow you to use sprites.

Like I said, this is good or bad depending on your perspective. The good thing about it is that it'll be easier to control exactly what bit-depth you want and when, and it abstracts things away a bit, making it easier to just make function calls and not have to think about the hardware. On the other hand, the documentation for libnds is pretty poor, and most tutorials are grossly out of date, so trying to figure out exactly what you're supposed to do is a bit tricky without doing some pretty hardcore research yourself. Plus, since everything is so entwined into their various functions, you'll pretty much be stuck using whatever functionality they've pre-programmed for you - no building your own OAM Manager to optimize some particular feature, or get a sense of how it works yourself; not unless you're willing to rewrite the entire graphics portion of the library.

So what I'm going to do for you is run down what you should do (as of libnds 1.7.3) to get simple sprites set up and display on the screen:

1) Make your sprite, and export the data to .c code. You can do this with Usenti or Grit, both applications written by Cearn (the guy who wrote Tonc). Personally I prefer Usenti because it has an easier to use palette manager and an actual interface to draw a sprite itself, but Grit seems to be more standard in the NDS community.

2) In main, do the following function calls in order:

videoSetMode(VIDEO_MODE) - this sets the first few bits of DISPCNT indicating which video mode the graphics card should be using. HOWEVER, it doesn't set anything else.

vramSetBankX(VRAM_X_MODE) - this sets whichever data is necessary to set what the VRAM X bank will be used for. Generally, you'll use VRAM_A and VRAM_B for the main engine and VRAM_C and VRAM_D for the sub engine (specifically, VRAM_C for the sub screen background, and VRAM_D for sprites - they aren't applicable the other way around), but not necessarily. Look into the hardware specs to see exactly what each bank can be used for and how to access them if you're interested.

oamInit(&oamMain / &oamSub, SpriteMapping_1D_BOUNDARY, usingExtPalette) - this initializes the OAM managers that are built into the library. Intuitively, oamMain is for the main engine and oamSub is for the sub engine. The second parameter indicates how you want sprites mapped in memory; more on this later. The third indicates whether you are using extended palettes - I haven't used these, so I don't know how they work, but generally I'd think you probably won't use them.

u16* gfx = oamAllocateGfx(&oamMain / &oamSub, SPRITE_SIZE, SPRITE_COLOR_FORMAT) - this function tells the OAM manager to allocate a sprite and some VRAM memory to but data into it and set up. SPRITE_SIZE refers to how large the sprite can be: there are several options, but the gist of it is that you have between 8x8 and 64x64 pixel sprites composed of 8x8 tiles. SPRITE_COLOR_FORMAT indicates whether you are using bitmap, 256, or 16 color modes (ie 16, 8, or 4 bits per pixel respectively).

Copy the data you've exported from Usenti/Grit into memory at the address stored in gfx - the value returned from oamAllocateGfx is an address to VRAM where the OAM expects its sprite data to be. So after allocating your sprite, simply copy the data into the memory at that location (using, say, dmaCopy, in libnds) and you'll have your tiles in VRAM.

Save the palettes in memory - libnds has predefined locations for the main and sub sprite palettes, namely SPRITE_PALETTE and SPRITE_PALETTE_SUB. Just copy 16 bit colors into these locations and you'll be golden.

Call oamSet() for each of your sprites - the function takes an OAM manager and an OAM index (ie, which sprite to modify) and sets the various values of that sprite. For example, you call this function to set the x and y position of the sprites on screen. Check the documentation for the complete list of parameters.

swiWaitForVblank() - the OAM can only be written to during a Vblank, while the screen isn't drawing, so this just halts execution until you can change the data

oamUpdate(&oamMain / &oamSub) - this copies the shadow OAM you've been modifying outside of Vblank into actual OAM to change the display. This should be pretty much the last think you do in your main loop.

Those should be sufficient to get basic sprite graphics functioning. IMO it's a bit more obnoxious than doing the GBA graphics with tonclib, but it isn't the end of the world once you get it.

If you're still having troubles with the library, I'd recommend updating your version of devkitPro (just to make sure you're up to date) then looking into their nds examples - particularly examples/nds/Graphics/Sprites. These bits of code are much more topical and also up-to-date relative to the current version of libnds than pretty much any tutorial you'll find online. Therefore no fuss in worrying over whether things tutorials recommend are outdated or deprecated.

One last thing: on tile memory settings:

There are lots of different modes for this, but it comes down to two different factors:

1D or 2D: 1D means each tile is laid out in memory in order that you want to insert them into sprites. This is the easiest and most practical way to use them, IMO. 2D maps the tiles out so that if you were to look at memory in a table, you'd be able to recognize the sprites you drew. This is actually really impractical to use, since a lot of data will be misaligned and you'll have to carefully determine where to store your tiles. TL;DR, don't use 2D mode. 

Bitmap vs Non-Bitmap: Bitmap sprites just mean you're using a full 16-bit color for each pixel in your tile, rather than a compressed color that behaves as an index into a palette. This means you can get many, MANY more colors into your sprite, but at the cost of being very very big in memory consumption. Generally I don't think this is necessary, but it's an option.

Memory boundary: One of the settings for a sprite's OAM entry is the starting tile index. Because there are only 10 bits to specify this value, you have two consequences: 1) you have an absolute maximum of 1024 distinct sprites that are possible at any one time, and 2) you can't directly index into the total tiles you have in VRAM, because you'll have far more than 1024. The Memory Boundary setting tells the OAM how far apart to jump between starting tiles: ie, if you set it to 32, then OAM's starting tile 0 will be at position 0 in VRAM, and OAM's starting tile 1 will be 32 bytes later. Likewise, if you set it to 64, there are 64 bytes between tile entries.

The Memory boundary setting is the most complex part of this, but it really comes down to this: check GBATEK for how big the VRAM bank you're using for sprites is. Use the memory boundary that matches the number of kB that the bank is, and you'll be golden. If you use a smaller size, you won't be able to access the full VRAM bank, and if you use a higher size, you'll have fewer unique sprites that you'll be able to define. Neither of these are the end of the world, but they do waste your resources a bit (in general, anyway).