Okay. Apparently, I am an idiot who can’t do math.

One of the longer chapters in Tonc is
Mode 7 part 2, which covers
pretty much all the hairy details of producing mode 7 effects on the
GBA. The money shot for in terms of code is the following functions,
which calculates the affine parameters of the background for each
scanline in section 21.7.3.

For details on what all the terms mean, go the page in question.
For now, just note that call to DivSafe() to calculate
the scaling factor λ and recall that division on the GBA is
pretty slow. In Mode 7 part 1,
I used a LUT, but here I figured that since the yb term
can be anything thanks to the pitch you can’t do that. After helping
Ruben with his mode 7 demo, it turns out that you can.

Fig 1.

Fig 1 shows the situation. There is a camera
(the black triangle) that is tilted down by pitch angle θ. I’ve
put the origin at the back of the camera because it makes things
easier to read. The
front of the camera is the projection plane, which is essentially
the screen. A ray is cast from the back of the camera on to the floor
and this ray intersects the projection plane. The coordinates
of this point are x_p =
(y_p, D) in projection plane space, which
corresponds to point (y_b, z_b) in
world space. This is simply rotating point x_p by
θ. The scaling factor is the ratio between the y or
z coordinates of the points on the floor and on the projection
plane, so that’s:

title="\lambda = y_c / y_b," alt="\lambda = y_c / y_b," />

and for y_b the rotation gives us:

title="y_b = y_p cos \theta + D sin \theta," alt="y_b = y_p cos \theta + D sin \theta," />

where y_c is the camera height,
y_p is a scanline offset (measured from the center of the screen) and D is the focus
length.

Now, the point is that while y_b is variable
and non-integral when θ ≠ 0, it is still bounded! What’s more,
you can easily calculate its maximum value, since it’s simply the
maximum length of x_p. Calling this factor R,
we get:

title="R = \sqrt{max(y_p)^2 + D^2}" alt="R = \sqrt{max(y_p)^2 + D^2}" />

This factor R, rounded up, is the size of the required LUT.
In my particular case, I’ve used y_p= scanline−80
and D = 256, which gives
R = sqrt((160−80)² + 256²)
= 268.2. In other words, I need a division LUT with 269 entries. Using .16
fixed point numbers for this LUT, the replacement code is essentially:

At this point, several questions may arise.

• What about negative y_b? The beauty here
  is that while y_b may be negative in principle,
  such values would correspond to lines above the horizon and we don’t
  calculate those anyway.
• Won’t non-integral y_b cause inaccurate look-ups?
  True, y_b will have a fractional part that
  is simply cut off during a simple look-up and some sort of
  interpolation would be better. However, in testing there were no
  noticeable differences between direct look-up, lerped look-up or
  using Div(), so the simplest method suffices.
• Are .16 fixed point numbers enough?. Yes, apparently so.
• ZOMG OVERFLOW! Are .16 fixed point numbers too high?
  Technically, yes, there is a risk of overflow when the camera height
  gets too high. However, at high altitudes the map is going to look
  like crap anyway due to the low resolution of the screen.
  Furthermore, the hardware only uses 8.8 fixeds, so scales above
  256.0 wouldn’t work anyway.

And finally:

• What do I win?
  With Div() m7_prep_affines() takes
  about 51k cycles. With the direct look-up this reduces to about 13k:
  a speed increase by a factor of 4.

So yeah, this is what I should have figured out years ago, but
somehow kept overlooking it. I’m not sure if I’ll add this whole thing to
Tonc’s text and code, but I’ll at least put up a link to here. Thanks
Ruben, for showing me how to do this properly.

This will be the last version of Tonc. It’s really gone on long enough now.

Files and linkies :

• Main site : www.coranac.com/tonc
• Tonclib manual : www.coranac.com/man/tonclib/

• Example binaries : tonc-bin.zip (521k)
• Example code + tonclib : tonc-code.zip (1.1M)
• Text + images : tonc-text.zip (1.4M)
• Text in CHM : tonc.chm (1.7M)
• Text in PDF : tonc.pdf (6.9M. No, I don’t know where the extra 3 MB came from either.)

Right! Now what …

The changes mostly relate to the new
Tonc Text Engine, a text system for all occasions. There’s a new chapter describing how TTE works, how to write general character printers for (almost) for arbitrary sized fonts and every type of graphics, and a few other things. It’s fairly long and could use sanity checking from someone else.

Also, many of the older demos now use TTE for their text as well. As a result they look cleaner and prettier, but it’s possible there are some left-overs from older versions. So have at it.

• Tonc 1.4 preview (PDF, 4.3 MB).
• TTE chapter only (PDF, 584 kB).
• All relevant 1.4 files: here.

I’ve rebuilt the routines around a surface description struct called
TSurface (see above). This way, I can just initialize the
surface somewhere and just pass the pointer to that surface around.
There are a number of different kinds of surfaces. The most important
ones are these three:

• bmp16. 16bpp bitmap surfaces.
• bmp8. 8bpp bitmap surfaces.
• chr4c. 4bpp tiled surfaces, in column-major order (i.e., tile 1 is
  under tile 0 instead of to the right). Column-major order may seem
  strange, but it actually simplifies the code considerably. There is also a
  chr4r mode for normal, row-major tiling, but that’s unfinished
  and will probably remain so.

alt="surface.gba movie" />
Demonstrating surface routines for 4bpp tiles.

For each of these three, I have the most important rendering functions:
plotting pixels, lines, rectangles and blits. Yes, blits too. Even for
chr4c-mode. There are routines for frames (empty
rectangles) and floodfill as well. The functions have a uniform interface
with respect to surface-type, so switching between them should be
easy were it necessary. There are also tables with function pointers
to these routines, so by using those you need not really care about
the details of the surface after its creation. I’ll probably add a
pointer to such a table in TSurface in the future.

Linkies

• Demo project: surface.zip.
• Tonclib: tonclib.
• Tonclib manual, TSurface module.

The image on the right is the result of the following routine.
Turret pic semi-knowingly provided by
Kawa.

For testing purposes, I filled each region with a different color so that ifwhen something went wrong, I could easily identify the problem. When playing around with the test app, I more or less accidentally came up with this:

Hmmm … Mondriaany.

Anyway, it seems that this thing went alright. So now tonclib also has plot, hline, vline, line, rect and frame functions for 4bpp tiled modes. No, there’s no blitting yet. In anyone wants that, I’m going to insist on some mental hazard pay.

There is, however, one small annoying fact about these two: they’re not
VRAM-safe. If the alignment and size aren’t right for the word transfers,
they will transfer bytes. Not only will this be slow, of course, but because
you can’t write to VRAM in bytes, the data will be corrupted.

The solutions for this have mostly come down to “so don’t do that
then”. Often, this can be sufficient: tiles in VRAM are word-aligned by definition, and source graphics data can and should be word-aligned anyway. However, now that
I’m finally working on a bitmap blitter for 8bpp and 16bpp, I find that it’s
simply not enough. So I wrote the following set of functions to serve as
replacements.

The code

My main goal here was to create smallish and portable replacements, not to
have the greatest and fastestest code around because that’s rather platform
dependent. Yes, even the difference between GBA and NDS should matter,
because of the differences in ldr/str times and caching.

There are 5 functions here. The main functions here are
tonccpy and __toncset for copying and
filling words, respectively. The other 3 are interfaces for __toncset
for filling 8-bit, 16-bit and 32-bit data; you need these for, say, filling with a color
instead of 8-bit data. For the rest of the discussion, I will use the name
“toncset” for the internal routine for convenience.

Discussion

Both tonccpy and toncset have the
following structure: the destination memory is divided into an
unaligned head, followed by an aligned main stint
and then a tail for any trailing bytes. In the optimal case there
is no head (i.e., the destination (and source) are word-aligned) and perhaps
no tail either (dstv+size is aligned). If that happens you’re in
luck: a 4x unrolled word copier will blaze through memory. And yes, that is a
Duff’s Device I’m
using there; I know it’s evil, but I’ve always wanted to try one. Interestingly,
it is also the only way I’ve been able to get DKA to create the optimal output
for an unrolled loop.

When you aren’t lucky, you’ll have to go through the motions of masking off
halfwords and/or words to insert the bytes. Technically it’s faster to use
words rather than halfwords, but this can be extremely unpleasant because
it’s also possible for the transfer to be in the middle of a word. For example,
dst%4== 1 and size = 2 would require a
dst-mask of 0xFF0000FF. I still have this in
toncset, but for the copier you have to deal with such
annoying cases that I preferred to go with the simplicity of halfwords for now.

Tests

I’ve tested the routines with all alignment variations and many different sizes
and found them to work accurately. I’ve also tested them for speed. The
following graphics show the results of the tests; while reading, remember
that all items have been compiled with -O2 -mthumb and are
in ROM. The source data for the copiers was in EWRAM and the destination
was VRAM.

Fig 1a and Fig 1b show
tonccpy(), memcpy() and something called
vramcpy. vramcpy() is a more optimized
version of tonccpy(), but it’s not ready yet. It uses
memcpy32() for the aligned main stint, so that should
represent optimal copying speed. The “a” and “u”
affixes mean aligned and unaligned pointers, respectively.

As you can see, even though tonccpy() is more complicated
than memcpy(), it’s a little faster in almost all cases. Only for short stints is memcpy() faster because
tonccpy() has a larger overhead. The vramcpy()
lines show that there is much room for optimization for longer stints. Using
a dedicated word copier (memcpy32(), DMA) would help,
but I wanted tonccpy() to be portable and self-sufficient.

You can also see the incredible differences between when the source
and destination have equal alignments (a) and when they don’t
(u). I know it is possible to speed up the unaligned parts by
50% to 100% or so as well, but I haven’t quite zeroed in on the right solution yet.

alt="" />
Fig 1a: copier comparisons, long stints.
a: src=dst alignment; u: unaligned.

alt="" />
Fig 1b: copier comparisons, short stints.
a: src=dst alignment; u: unaligned.

The results of the fillers are in fig 2a and
fig 2b. These pictures show
toncset(), memset() and
toncset2(). toncset2() is essentially
toncset() using memset32() for the
main stint. Because there’s no source alignment to worry about,
there is no chance for src-dst misalignments. This is why there
is little difference between the aligned and unaligned cases for the
toncset() variants; only memset()
is very slow in the unaligned case.

alt="" />
Fig 2a: fill comparisons, long stints.
a: dst = aligned; u: unaligned.

alt="" />
Fig 2b: fill comparisons, short stints.
a: dst = aligned; u: unaligned.

Lastly, the numbers for the transfer-rate and the overhead for calling
them. Please remember that the actual numbers depend very much on
what the waitstates are for the source and destination and where the
code resides. That said, the figures should be useful for relative
comparisons. Also, these are GBA timings; the NDS figures will be
different, but I’ll test for them when I get round to it.

Conclusions

tonccpy() and toncset() are essentially
variations of memcpy() and memset() that
also work for GBA/NDS VRAM even in the worse circumstances. They’re
actually a little faster as well, so I can recommend using them instead of
memcpy/set in all cases. This is not to say that they are
the optimal solutions: faster general solutions certainly exist, but they
will be longer, hairier and probably less portable. Faster non-general
solutions exist as well, of course. If you know your pointers and sizes
will be word-aligned, consider DMA32, CpuFastSet or the memcpy32/set32
routines from tonclib.

There have also been a few changes in the text parts: build-specs are set to cart-boot there too now, and I fixed some broken links. I’ve also fixed a slew of spelling and grammar issues that Patater sent in. These part of the text shouldn’t be gibberish anymore – just unintelligible :P.

Also, there are separate pasting modes: one that matches the colors to
the current palette (potentially mixing up the colors) and a
direct-pixel paste, regardless of colors. Thanks, gauauu, for finally
making me do this. Secondly, Kawa’s been badgering me (politely)
about editing colors in raw hex rather than via RGB triplets. This can
be found, for various bad reasons, under the Palette menu under
‘Advanced color edit’.

Both of these items have … interesting side effects. Through
the former, you can replace colors of a given palette-entry by
copy-all, swap and paste. The color-edit accepts multiple colors
separated by white-space and, later on, by commas as well, meaning that
accidentally it’s now possible to take previously exported palettes
and add them again. Yes, it’s
feep, but
it’s interesting, somewhat hidden and cheap feep, so that’s alright. I’m
thinking about adding something similar for the image itself as well
(plus raw image imports), but only when I’m bored enough.

To show off the font exporter and the TTE system itself, there is a
little demo of what it can do here.
I’m still pondering over what it should and should not be able to do, but
most of the things shown in the demo would be in the final version
as well.

Oh, RE: that wordpress bug. A v2.3.1 has been released now with the fix. Interesting factoid: the error (#5088) was classified as “highestomgbbq”.

• A more unified interface for the base drawing routines. Whereas I
  used to have something like bm8_foo(...), I now have
  bmp8_foo(..., void *dstBase, u32 dstPitch) for
  everything. Although the extra parameters make the routines a little
  slower, it makes it easier to switch video-modes.
• A few color routines like blending/fading, convert to rgbscale
  (like grayscale, but for any color vector) and a few color adjustments.
• I’m trying to include (well, annex, really) some of libgba’s
  functionality. In terms of shared functionality, the libgba names can
  be used by including tonc_libgba.h. This is definitely not a
  finished item yet.
• Tonc’s Text Engine. I already had some basic routines for
  text on different video types, but this is a good deal better. Instead
  of having separate foo_puts() routines, TTE uses function
  pointers for placing glyphs on screen. This means there can be a single
  interface for all modes, and customizable writers. Already provides are
  glyph renderers for 8/16bit bitmaps and 4bit tiles, using a 1bpp bitpacked
  font. In principle, the renderers can handle any sized fixed and
  variable-width fonts (within reason: 128×128 fonts would be impractical,
  for example). There are also hooks for the stdio functions
  (printf, yay!) and some simple commands for positioning, color and font
  changes. Example of use:

  // Set-up 4bpp tile rendering bg 0 using cbb=0 and sbb=31.
  // The default options set implicitly here are: verdana 9 font, yellow for
  // text color
  tte_init_chr4_dflt(0, BG_CBB(0)|BG_SBB(31));
  // Init stdio hooks
  tte_init_con();
  // Print something at position (10,10)
  iprintf("\\{P:10,10}'Ello world!, %d", 1337);
  

  Aside from the initializer, using TTE is basically independent of what
  you’re writing with or on. Of course, all this stuff does have a fair
  amount of per-character overhead (about 150 cycles, I believe). It shouldn’t be too hard to port TTE to NDS; I am planning to do this at some point.

There are more smaller changes here and there, but those are of lesser consequence.

tonclib 1.3 linky.