Uzebox Mode 3 with Scrolling Guide

Topics on software tools like TileStudio, comments on documentation and tutorials (or the lack of) should go here.
User avatar
Artcfox
Posts: 1382
Joined: Thu Jun 04, 2015 5:35 pm
Contact:

Uzebox Mode 3 with Scrolling Guide

Post by Artcfox »

I just finished writing up a guide on how to use mode 3 with scrolling in three different configurations:
  • Horizontal Scrolling
  • Vertical Scrolling
  • Horizontal & Vertical Scrolling
This is something that I wish existed back when I first started developing on the Uzebox.

It includes diagrams to help explain the relationship between VRAM, the screen, and your level data, and it walks the reader through writing the code for each different scrolling configuration line by line, explaining things as much as possible. The scrolling is bi-directional, it only loads data for a row and/or column when absolutely necessary, always loads the tiles into the hidden areas of VRAM, and it allows you to scroll the screen by up to 8 pixels per call to the Camera_update function.

It doesn't cover everything, but it should be a pretty good start for people who want to learn how to use this video mode.

There are full projects available for all the examples in the guide in its git repository.

Here's a couple thumbnails of pages in the guide:
tn_guide_dual.png
tn_guide_dual.png (94.13 KiB) Viewed 41454 times
Edit v2: Add additional bounds check I removed in haste in the code for horiz-vert.c
Edit v3: English grammar fix "goes" -> "go" on page 2
Attachments
uzebox_mode3_scrolling.pdf
v3, last updated March 31, 2018 (English grammar fix, no code changes since v2)
(262.54 KiB) Downloaded 866 times
Last edited by Artcfox on Sun Apr 01, 2018 12:01 am, edited 3 times in total.
rocifier
Posts: 71
Joined: Thu Jan 22, 2015 6:35 am

Re: Uzebox Mode 3 with Scrolling Guide

Post by rocifier »

Wow !!!!!!!!!!! very nice thank you so much! Tons of work gone into all those diagrams!
User avatar
D3thAdd3r
Posts: 3175
Joined: Wed Apr 29, 2009 10:00 am
Location: Minneapolis, United States

Re: Uzebox Mode 3 with Scrolling Guide

Post by D3thAdd3r »

Man this is the ultimate scrolling tutorial. This is going to help a lot of people no doubt. Very detailed analysis and solution, and the visuals are great here as well! Above and beyond well done :D
User avatar
Artcfox
Posts: 1382
Joined: Thu Jun 04, 2015 5:35 pm
Contact:

Re: Uzebox Mode 3 with Scrolling Guide

Post by Artcfox »

rocifier wrote: Sat Mar 24, 2018 12:49 pm Wow !!!!!!!!!!! very nice thank you so much! Tons of work gone into all those diagrams!
No problem! I figured now would be the perfect time to make a guide like this, both with the code being so fresh in my mind, and with the UCC 2018 coming up.
D3thAdd3r wrote: Sat Mar 24, 2018 1:24 pm Man this is the ultimate scrolling tutorial. This is going to help a lot of people no doubt. Very detailed analysis and solution, and the visuals are great here as well! Above and beyond well done :D
Thanks! :)
User avatar
Artcfox
Posts: 1382
Joined: Thu Jun 04, 2015 5:35 pm
Contact:

Re: Uzebox Mode 3 with Scrolling Guide

Post by Artcfox »

I apologize, when I was up all night last night editing this guide, I accidentally removed two required bounds checks in the Horizontal and Vertical Scrolling configuration in the Level_drawColumn and Level_drawRow functions. :oops:

The code in the guide and on GitHub has been corrected, along with the explanations in the guide.

The attachment in my original post has been updated with the new March 25, 2018 version, those of you who have the March 24, 2018 version should grab an updated copy.

For the curious, here is the patch:

Code: Select all

diff --git a/horiz-vert/horiz-vert.c b/horiz-vert/horiz-vert.c
index ceb8f8e..d10685f 100644
--- a/horiz-vert/horiz-vert.c
+++ b/horiz-vert/horiz-vert.c
@@ -60,6 +60,8 @@ void Level_drawColumn(LEVEL *l, uint8_t x, uint16_t y, int16_t realX)
   uint8_t tx = x % VRAM_TILES_H;
 
   for (uint8_t i = 0; i < VRAM_TILES_V - 2; ++i) {
+    if ((y + i) > l->height - 1)
+      break;
     uint16_t index = (y + i) * l->width + realX;
     SetTile(tx, (y + i) % VRAM_TILES_V, Level_getTileAt(l, index));
   }
@@ -79,6 +81,8 @@ void Level_drawRow(LEVEL *l, uint16_t x, uint8_t y, int16_t realY)
   uint8_t ty = y % VRAM_TILES_V;
 
   for (uint8_t i = 0; i < VRAM_TILES_H - 2; ++i) {
+    if ((x + i) > l->width - 1)
+      break;
     uint16_t index = realY * l->width + (x + i);
     SetTile((x + i) % VRAM_TILES_H, ty, Level_getTileAt(l, index));
   }
User avatar
ry755
Posts: 225
Joined: Mon May 22, 2017 6:01 am

Re: Uzebox Mode 3 with Scrolling Guide

Post by ry755 »

Wow, this is really cool! :) And good timing too, since I have an idea for a new game that'll use horizontal scrolling. This guide will certainty help!

I never thought of the VRAM as a torus. But that makes sense though since it wraps around.
User avatar
Artcfox
Posts: 1382
Joined: Thu Jun 04, 2015 5:35 pm
Contact:

Re: Uzebox Mode 3 with Scrolling Guide

Post by Artcfox »

ry755 wrote: Sun Mar 25, 2018 8:33 am Wow, this is really cool! :) And good timing too, since I have an idea for a new game that'll use horizontal scrolling. This guide will certainty help!

I never thought of the VRAM as a torus. But that makes sense though since it wraps around.
Thanks! Let me know how it goes.

For some reason I find topology fascinating, enough that I have bought and read multiple books on the subject.
User avatar
Jubatian
Posts: 1560
Joined: Thu Oct 01, 2015 9:44 pm
Location: Hungary
Contact:

Re: Uzebox Mode 3 with Scrolling Guide

Post by Jubatian »

Nice stuff, great to have some documentation! :) Mode 3 is interesting in this regard, at least I never utilized this layout for my modes, however it certainly works a lot more like the more advanced video hardwares of the past (as then there was no time to copy around the entire VRAM, which for example makes scrolling particularly difficult on the C64).
User avatar
Artcfox
Posts: 1382
Joined: Thu Jun 04, 2015 5:35 pm
Contact:

Re: Uzebox Mode 3 with Scrolling Guide

Post by Artcfox »

Jubatian wrote: Mon Mar 26, 2018 5:38 pm Nice stuff, great to have some documentation! :) Mode 3 is interesting in this regard, at least I never utilized this layout for my modes, however it certainly works a lot more like the more advanced video hardwares of the past (as then there was no time to copy around the entire VRAM, which for example makes scrolling particularly difficult on the C64).
Thanks! Now I just need to figure out how to stream new level tiles in from the SD card as needed. I know that your mode 74 supports loading random access data from SD card during spare HSync time, would you be able to add support for that to the scrolling version of mode 3, or are there just not enough free clocks available during its HSync? Even if it has to come at the expense of some of the sound channels, or the USART support (compile-time configurable), that would essentially allow an unlimited number of arbitrarily sized levels.
User avatar
Jubatian
Posts: 1560
Joined: Thu Oct 01, 2015 9:44 pm
Location: Hungary
Contact:

Re: Uzebox Mode 3 with Scrolling Guide

Post by Jubatian »

Artcfox wrote: Mon Mar 26, 2018 8:11 pmThanks! Now I just need to figure out how to stream new level tiles in from the SD card as needed. I know that your mode 74 supports loading random access data from SD card during spare HSync time, would you be able to add support for that to the scrolling version of mode 3, or are there just not enough free clocks available during its HSync? Even if it has to come at the expense of some of the sound channels, or the USART support (compile-time configurable), that would essentially allow an unlimited number of arbitrarily sized levels.
I will most likely deprecate that in Mode 74 as it is only really suitable for streaming, especially if the new bootloader gains wider adoption (if you have that, even more sloppy SD cards, contacts and solderings will work, making games which try to use the SD at full-speed without any CRC check more often failing).

Mode 74 can only do it at 22 tiles width when scrolling, and even the 24 tiles wide Mode 74 is narrower than a 30 tiles wide Mode 3. So there is no room in Mode 3 to add something alike.

For SD heavy stuff without SPI RAM, I would now suggest Mode 72 which I think I will soon add to Master. Since it has no RAM tiles, it has lots of free RAM to load SD content, and even with the VSync mixer, a lot more CPU time to spare for SD access. Streaming level data (without any checking) I think shouldn't be done, or if you do, it needs a stable SD interface. In my case I found it rare to work reliably with real hardware.
Post Reply