Sprites, Tiles and Their Unholy Union in Sprite Memory

There are several demos both packaged with devkitpro and in various tutorials that use sprites, but they almost all involve drawing one sprite (possibly multiple times) on screen. As I started trying to add to the demos, I found that I was having trouble drawing more than two sprites.

Several examples setup sprite OAM (Object Attribute Memory) as follows:

int spriteID = 0; // the sprite id
int spriteX = 0; // X position
int spriteY = 0; // Y position
sprites[0].attribute[0] = ATTR0_COLOR_16 | ATTR0_SQUARE | spriteX;
sprites[0].attribute[1] = ATTR1_SIZE_16 | spriteY;
sprites[0].attribute[2] = spriteID;

ATTR0_COLOR_16 specifies 16 color mode, ATTR0_SQUARE says the sprite is square (heigth = width), ATTR1_SIZE_16 makes the sprite 16x16.

And then sprite data is written like:

/* size of sprite in words (word is 16 bits) = 16 * 16 / 4
* 16-color mode = 4 bits per pixel (2 pixels per byte, or 4 per word)
* 16 pixel by 16 pixel sprite, 4 pixels per word = 16 * 16 / 4 bytes
*/
int size = 64;
int pali = 2; // Palette index
for( int i = 0; i < size; i++ ){
  SPRITE_GFX[ spriteID * size + i] = (pali << 12) | (pali << 8) | (pali << 4) | pali;
}

This just fills the entire sprite area with whatever color is defined at index 2 of the palette.

What was confusing me was the representation of sprites as tiles, how they are stored in sprite memory, the allocation of sprite IDs, and the way that sprite OAM uses sprite memory. If you are unclear on the meaning of tiles, check out Patater's tutorial.

Basically, tiles are 8 pixel by 8 pixel images, and all sprites are made up of them. What's important to understand here is that the sprite IDs reference the location of tiles in memory. If a sprite is larger than 8x8 then it uses more than one tile and covers a range of tile/sprite IDs. This means that two 16x16 sprites (each 4 tiles) stored in adjacent memory can't be allocated ID 0 and ID 1. The two images will overlap since the 16x16 sprite at ID 0 is defined as tiles 0 to 3, and the 16x16 sprite at ID 1 is defined as tiles 1 to 4.

You have to keep in mind the size of one pixel in memory and the dimensions of the sprite both when storing pixel data in sprite memory, and when allocating sprite IDs in sprite OAM.

In the example above (two 16-color 16x16 sprites):

1. The first sprite is assigned ID 0 (8x8 tiles 0 to 3) and is stored in 128 bytes (16pix * 16pix / 2 pixels-per-byte) of sprite memory starting at index 0.


2. The second sprite should be assigned ID 4 (8x8 tiles 4 to 7) and is stored in 128 bytes of sprite memory starting at index 128 + 1 (right after the first sprite).

NOTE: In the code above I offset by 64 rather than 128 because we are using word-aligned (16 bit) rather than byte-aligned (8 bit) addressing since SPRITE_GFX is an array of 16-bit values.

PassMes, M3s, and GBAMPs, oh my!

Odds are, if you've been interested in running homebrew code on the Nintendo DS, you were probably more than a little lost/confused initially (if you ever got it figured out). There *is* an active community out there, but most of the information is spread out across different bulletin boards, in different threads, often containing more than a little incorrect and/or outdated information, and using terminology/abbreviations you're probably not yet familiar with. Maybe I'm just the kind of person that really likes to have a good grasp of what I'm doing and what all my options are rather than running with "just do X" as posted by some_random_guy023.

Far and away the best write up I've come across is the Running Homebrew wiki entry at DSLinux. It does a nice job of presenting the various requirements and what your options are, the between them such as in which circumstances you can use them and what the pros/cons are, as well as providing links (via Pocketheaven) to specific products/manufacturers.

Check it out and save yourself a lot of headache/irritation.

Virtual Desktop Environments for Windows XP

Anyone that has experience with a *nix (and possibly other non-Microsoft OSes) environment is probably frequently annoyed with XPs lack of virtual desktops. After you've been working for a while, or work on several different projects simultaneously, it doesn't take long to end up in task bar hell. Alt-tab and friends are rendered nigh completely useless.

I got fed up with this in the course of my DS programming and decided to seek out a virtual desktop environment add-on for XP. I should first point out that my standard of comparison is IceWM, a light-weight, configurable window manager with hotkeys for pretty much everything. If you're not familiar with IceWM, don't worry, the idea is to have a very simple, responsive virtual desktop environment that is easy to navigate with shortcuts. Further, I use a laptop with a second monitor, so dual-head support is really key. Finally, it needs to be free. There are probably pretty good programs that you can pay for, but poor students like me can't eat and pay for each and every little piece of software we use.

Spoiler alert!!!!

I ended up deciding on Virtual Dimension as it provided pretty much everything I was looking for. Features:

• Small- memory usage comes in around 6.4MB.


• Shortcuts for all the things I was looking for: move a window to different desktop, and move to different desktop.


• Fast switching between desktops.


• Supports a variable number of desktops and configurable layout of them.


• Easily to understand/configure/use.


• No strange behavior with a second monitor.

It even has some features I didn't expect/require but appreciate:

• Support for a shortcut to maximize the height of the current window (this is awesome and loved it in IceWM yet so few window managers actually support it).


• Lets you set the transparency of windows.


• Configurable preview window for all desktops: auto-hide, transparency, always on top, etc. This is actually really slick and I like it more and more as I continue using it.


• Non-intrusive, configurable indicator of the desktop you just switched to (WindowMaker-esque).


• Can right-click title bars to access VD functionality.


• Is open source so I can always add a feature myself if nobody else does.


• Per-desktop wallpaper and switch-to hotkeys.


• Can minimize windows to the systray and sticky them to all desktops.

The drawbacks:

• Not many configuration options for using the mouse to switch desktops. Can change desktops, but no way to get the mouse to warp to the opposite side of the neighboring desktop as if the mouse had intuitively moved to the adjoining edge.
  

There's a screenshot up at their website that shows what your desktop ends up looking like. Been using it for about a week now and have absolutely no complaints. Damn satisfied. If I had to guess, I'd be willing to bet the devs are all ex-*nix users.


I actually test-drove quite a few other environments that I feel like I would mention if you, like me, found that there are quite a few virtual desktop programs floating around and wondering whether they're worth bothering with.

Honorable mention:

These are the virtual desktop programs that were really quite good and I would consider using were it not for a problem or lack of some feature that was a deal breaker for me. If Virtual Dimension doesn't quite cut the mustard for you, you're probably best off looking at these first.

VirtuaWin

Homepage: http://virtuawin.sourceforge.net/
This is probably my second choice, and a very close one at that. I kept writing up draw-backs for it and then as I used it more and more I found out how to do the things I wanted. It's probably one of the most configurable (yet not overwhelmingly so) options here.

The Good:

• Available hotkeys: switching to a particular desktop, cycling through desktops, making a window sticky.
  
• Provides really excellent support for using the mouse to switch desktops: can alter the delay, whether or not the mouse cursor warps to the adjacent edge or stays on the same side of the screen, etc.
• Desktop switching is very fast.
• Small- 5.8MB
• Has some kind of plug-in architecture.
• Quite a lot of configuration options.
• Can change the layout of screens and add/remove desktops.
  

The Bad:

• Desktop cycling (being able to wrap around from the last desktop to the first) isn't enabled by default, you have to enable it from the "Expert" tab in "Setup".
• No hotkey to move windows between desktops, would be nice to have a few more shortcuts (possible with a plug-in?).
• When you move to another desktop dragging a window, rather than the window staying with the mouse it appears at the original location of the window in the new desktop.
• No good "current desktop" indicator or desktop preview tool. It's in the systray which isn't visible if you have your task bar set to autohide.
  

The Ugly:

• None?
  

Deskillusion

Homepage: http://www.unfate.f2g.net
(homepage seems to be down a lot so you can get it from download.com)
The Good:

• Small- Just over 6MB of memory.
• Fast- Desktop switches are real quick.
• Unobtrusive indication of desktop you just switched to.
• Configurable shortcuts to switch to other desktops.
• Easy to add/remove virtual desktops.
• Simple to setup/use.
• No problems with multiple monitors.
• Right-clicking a window title bar allows you to: send it to another desktop, or sticky it.
  

The Bad:

• Too simple: lack of advanced configuration options, shortcuts.
  
• No way to set shortcut to move a window to another desktop- have to right-click title bar.

The Ugly:

• Occasionally some weirdness- windows appearing on more than one desktop, window order changing, etc.

SDesk

Homepage: http://www.nearestexit.com/sdesk/
This is actually different from the other programs as it doesn't create virtual desktops, it expands the size of the desktop beyond the size of the screen.

The Good:

• Small- under 6MB
• Fast- probably the fastest of them all since it doesn't actually create virtual desktops, it just expands the one you've got
• Very cool usage of a second monitor: it your secondary monitor is positioned above your primary display then moving to a lower part of the desktop will move what was shown in the primary display up into the secondary display. Very intuitive.
• An optional Unix-esque preview window
• Shortcuts for pretty much everything- using either/both the keyboard or/and mouse

The Bad:

• Not virtual desktops, so you still end up with all your tasks dumped onto one task bar.
• More difficult to configure than some of the others.
• Settings are peculiar when a second monitor is used that is a different resolution than the primary display- have to set the width to the resolution of the larger monitor in order to correctly move by the size of a desktop
  

The Ugly:

• Nasty handling of a secondary display:
• When the secondary display ends up showing a part of the desktop outside that controlled by SDesk, moving away and then moving back causes all the windows displayed on the secondary display to be reset.
  
• If the secondary display uses a different resolution than the primary display then windows will also be repositioned when moving to different parts of the desktop.
• No longer under development/maintained?- last updated in 2003...

I was completely in love with SDesk until I found how it handled a secondary monitor. It's functionality seems to clash with that used by Windows for dual-head support, especially if the two displays use a different resolution.

The Rest:

These are the virtual desktop programs that I just don't consider usable. You may find a real gem here depending on your needs/usage, but to each their own.

Virtual Desktop Toolbox

This was the most downloaded program from download.com. I figured its success was a sure sign of its suitability. I just couldn't see myself using it, however:

• Way too big- the download weighs in at over 12MB. When you look at the others and see that they're generally under 1MB you can't help but hear the Sesame Street song "One of These Things is not Like the Others".
• Way too big part 2- at runtime it consumes almost 18MB of memory... uh, yeah.
• Bigger just isn't better:
• Speed- was one of the slowest of all the programs I tested while switching desktops.
• Configuration was over-complicated: I found myself hunting through menus trying to disable annoying things that are enabled by default, or enabling things I wanted.
• Didn't seem to be any way to just move a window from one desktop to another.
• It also seemed to randomly cause programs to crash at runtime or on exit.
  

In its defence it did provide some features that none of the other programs had: the ability to setup special "scenarios" for certain usage situations, and the ability to specify settings that are automatically applied to specific programs that run. It also provided several different tools for managing windows, displaying the desktops, etc.

I just found it too slow, complicated, annoying to be worth the trouble. I've never seen a virtual desktop tool that was so complicated that it needed wizards, and I think there's a good reason why.

Microdesk

Pretty slick looking tool that comes default with 10 desktops and a toolbar similar to that used by Microsoft's IME. Didn't really match my needs, however:

• Bit on the heavy site- 9.4MB of memory.
  
• Requires some kind of registration.
• No simple/quick way to move windows from one desktop to another. Requires use of the "Application Manager".
  
• Configuration/usage was a bit more complicated/non-intuitive than really necessary.
• Not very refined:
• Clicking "Options" pops up an error-like window before actually showing the options window.
• Seemed to have some conflicts with the taskbar: sometimes I would switch desktops and the taskbar would be completely missing on one desktop while it wouldn't auto-hide on others.

It was the prettiest of the virtual desktop tools, however. They did a nice job working on neat effects and graphics for the UI, but their time would have been better spent making it more functional imho.

MultiDesk

• I couldn't even figure out how to use it, honestly. It claimed to have created 10 virtual desktops, but I never found any way to actually switch to them.
• Didn't seem to be any way to specify hotkeys of any kind.

Maybe this program is just too clever for me. But, it looks like it hasn't been updated since 2002, so I think it's just no longer usable on XP sp2.

Microsoft's Virtual Desktop Manager XP PowerToy

This is pretty simple and easy to use. You can specify a different wallpaper for each desktop, and shortcuts to move between them. Even provides a cool, preview of all four desktops and the ability to select the one you want to switch to.

Ultimately I decided against using it because:

• No way to cycle backwards/forwards through the desktops, you can only move to a specific one.
• No easy way to move a window to a different desktop.
• Pretty slow desktop switches (I believe it was the slowest).
  
• Forced to use 4, and only 4 virtual desktops.
  

Microsoft deserves credit for having the lightest-weight program out of all the ones I looked at: a tiny 3MB and change. Think this may be a first for the boys from Redmond.

PowerPro

It's actually a bit unfair to compare PowerPro to the other virtual desktop programs because it's actually quite a complex tool that just happens to also have the ability to do virtual desktops. It's really, really, really configurable and seems quite powerful, but it's virtual desktop functionality seemed more primitive because it's less specialized. It may, however, be possible to use the extensive scripting/toolbar creation functionality to improve it. I was unable to do so, though.

New Design

Despite my whining in the last post I got things mostly setup the way I wanted. Switched out to starting with simpler, shorter template, and made all my changes offline in vi. Only took another iteration or two to actually get everything working.

It's not quite perfect, but it's close. Let's say 85%. Good enough that I'm going to use it until we get closer to, say... 95%. Need to make sure it isn't actually hard to read or something else equally dysfunctional.

Despite my artistic handicap, I even managed to come up with a logo and matching favicon. Go me!

Blog Design Woes

Ever since the announcement that they got HTML editing setup and the new template language ready to go I've been thinking about doing a little redesign.

And, man, is it a pita. I've never been one for GUI design, honestly. Move this widget here. Push this thing over there. Wait, not yet. Do this thing a little more. Maybe that should be aligned the other way.

I swear you can do that stuff for hours. Throw colors in and I never actually get anything done since it never looks *quite* right. Their templating language is cool and all, but I find CSS in general to be extremely verbose. Couple that with the amount of processing they seem to do on the templates before it actually gets to your browser and its a bit annoying to figure out where a style is being applied. Not to mention a bit disorienting.

It doesn't really seem like downloading the template and editing it offline is really an option, either. If you try to display it, it just comes up with bits of a page. So, I've been using their online tools and it's been pretty slow going. Click on "Edit HTML" and muck around there, "Fonts and Colors" to set those, then to the other browser tab and refresh it to see what your page actually looks like.

I realize I could just ignore the "Fonts and Colors" friendly variable definitions, but it seems really negligent for some reason. And, I realize "Fonts and Colors" has a preview pane, but it seems to just be a static image so you can't see hover changes etc. Plus, it's cramped way down at the bottom of the view.

Having to use their plain-text editing window instead of vi sure is a drag, too.

Hmm...

DevKitPro Templated Build Directories

One thing worth mentioning that's part of the DevKitPro is the "templated" build directories for Nintendo DS projects. I figured I'd give them a brief explanation since they're kind of unique to DKP.

You'll find them in [DevKitPro root dir]/examples/nds/templates/.
There should be two sub-directories:

• arm9/
• combined/
  

arm9/ is the simpler of the two, but is for projects that only require an arm9 executable. combined/ is a bit more complicated but allows for easily creating programs that use both the arm7 and arm9.

I'll only talk about the combined/ directory because you can limit yourself to the arm9/ sub-directory if all you want to do is mess around with the arm9, AND you can continue using the same template you've gotten used to as you move on to more complex projects and actually need both processors. In any case, most things apply to both templates in one way or another, it's just that in the case of combined/ it may be found in a subdirectory.

Template Prep

First, what I did was copy the combined/ directory to a location where I can easily find it when doing DS programming. I then renamed it "template", but you can call it whatever you want. The basic idea is to be able to just make a copy and rename it for each project you want to start, and you'll have a nice build environment ready to go.

Next, I made some changes to the default template because there's some unnecessary junk there (afaic):

If you don't use Programmer's Notepad you can safely delete template.pnproj, template.pnps, and template.prj.

cd [template directory]
rm template.*

I honestly have no idea why this is included with DKP. Maybe they own stock in it or something.

Next, you're going to want to do a "make clean". At the time of this writing the template directories are being distributed already built. This can cause problems for you during the linking phase of your project if your directory structure isn't setup just like the developers:

make clean

Now create a "data" subdirectory in the arm7/ and/or arm9/ subdirectories and add them to the relevant Makefile's list of subdirectories:

# For arm9/
cd arm9
mkdir data

Edit arm9/'s Makefile from this:

BUILD  := build
SOURCES  := source
INCLUDES := include
DATA  :=

To this:

BUILD  := build
SOURCES  := source
INCLUDES := include
DATA  := data # Or whatever you called the subdirectory you created

Your template build directory is ready to go!

Template Usage

Creating new projects is as simple as:

1. Copying your template directory


2. Renaming it something that fits your project


3. Adding files as shown below

[root]/
    +- arm9/
           +- source/ ; Put all source files (*.c, *.cpp, etc.) here
           +- data/ ; Binary files (*.bin) go here
           +- build/  ; Project will be built here.  Also, *_bin.h files generated
                      ; for your *.bin files will end up here.
    +- arm7/  ; Basically same as arm9/ directory

Change to the [root] directory, run "make" to build everything, and you should have a nice *.nds file waiting for you to debug. =)

Mapping touch-screen input to pixel values on the DS

Finally got some school stuff out of the way so I can get back to the important things in life.... like the Nintendo DS.

Been messing around with touch-screen input a bit. It was fairly easy to get a demo running, but when I started trying to drag something around I found out that the touch screen uses a different coordinate system from the display. Dug around a little bit and came up with:

#define SCREEN_WIDTH   256
#define SCREEN_HEIGHT   192

// those are pixel positions of the two points you click 
// when calibrating
#define TOUCH_CNTRL_X1   (*(vu8*)0x027FFCDC)
#define TOUCH_CNTRL_Y1   (*(vu8*)0x027FFCDD)
#define TOUCH_CNTRL_X2   (*(vu8*)0x027FFCE2)
#define TOUCH_CNTRL_Y2   (*(vu8*)0x027FFCE3)

// those are the corresponding touchscreen values:
#define TOUCH_CAL_X1   (*(vu16*)0x027FFCD8)
#define TOUCH_CAL_Y1   (*(vu16*)0x027FFCDA)
#define TOUCH_CAL_X2   (*(vu16*)0x027FFCDE)
#define TOUCH_CAL_Y2   (*(vu16*)0x027FFCE0)

// linear mapping can be used to go from touchscreen position to 
// pixel position

// precalculate some values
static int16 TOUCH_WIDTH  = TOUCH_CAL_X2 - TOUCH_CAL_X1;
static int16 TOUCH_HEIGHT = TOUCH_CAL_Y2 - TOUCH_CAL_Y1;
static int16 CNTRL_WIDTH  = TOUCH_CNTRL_X2 - TOUCH_CNTRL_X1;
static int16 CNTRL_HEIGHT = TOUCH_CNTRL_Y2 - TOUCH_CNTRL_Y1;


// reading pixel position:
int16 x = (IPC->touchX - (int16) TOUCH_CAL_X1) 
    * CNTRL_WIDTH  / TOUCH_WIDTH  + (int16) TOUCH_CNTRL_X1;
int16 y = (IPC->touchY - (int16) TOUCH_CAL_Y1) 
    * CNTRL_HEIGHT / TOUCH_HEIGHT + (int16) TOUCH_CNTRL_Y1;

at NDSTech Wiki. The needed calibration values don't seem to be in ndslib so I think you need to define them yourself. Took around a minute of messing around to get a nice demo working where you could drag something around on screen just like you'd expect.

Something I did in my code that's worth pointing out is changing the calculations a bit to get rid of any extra operations (especially the division). Granted, I'm not sure how much the compiler can take care of, but it probably doesn't hurt.

First, if you separate the

IPC->touchX - (int16) TOUCH_CAL_X1

terms, the entire TOUCH_CAL_X1 component only needs to be calculated once.

Second, you can trade out the arbitrary divide for a shift by preforming the divide ahead of time and shifting the result to avoid using floating point. Then undoing the shift whenever you use the value. The numbers are small enough that you shouldn't have to worry about overflow when multiplying with a larger number... I think. i.e.

#define SHIFT 4
static u16 scale_value = (CNTRL_WIDTH << SHIFT) / TOUCH_WIDTH;
...
(IPC->touchX * scale_value) >> SHIFT ...

Gotta look into compiler optimizations and figure out whether the above is worth the trouble if you specify -O2, etc.