New "Setting up a development environment" chapter (#72)

Clean up CSS and make <dfn> tags bold-italic first.md: replace <tt> with italics setup.md/first.md content changes setup.md: - Explain manual build steps - Reword some things - Ensure what's explained matches what's mentioned in first.md first.md: - Remove hand-rolled Makefile - Remove reference to Programmer's Notepad - Point to community instead of 'troubleshooting' section which no longer exists Minor formatting/style tweaks Remove metadata setup.md switch to new admonition syntax Remove -mthumb-interwork from build steps example
gbadev-org · Dec 20, 2023 · fdad656 · fdad656
1 parent 53f492f
commit fdad656
Show file tree

Hide file tree

Showing 8 changed files with 201 additions and 646 deletions.
diff --git a/content/first.md b/content/first.md
diff --git a/content/img/setup/devkitpro.png b/content/img/setup/devkitpro.png
diff --git a/content/img/setup/mgba_game.png b/content/img/setup/mgba_game.png
diff --git a/content/img/setup/mgba_hello.png b/content/img/setup/mgba_hello.png
diff --git a/content/img/setup/text_editor.png b/content/img/setup/text_editor.png
diff --git a/content/setup.md b/content/setup.md
diff --git a/content/video.md b/content/video.md
@@ -56,9 +56,9 @@ Both the [CowBite Spec](http://www.cs.rit.edu/~tjh8300/CowBite/CowBiteSpec.htm#G
 The GBA is capable of displaying 16bit colors in a 5.5.5 format. That means 5 bits for red, 5 for green and 5 for blue; the leftover bit is unused. Basically, the bit-pattern looks like this: “<code>x<font color=blue>bbbbb</font><font color= green>ggggg</font><font color= red>rrrrr</font></code>”. There are a number of defines and macros in `color.h` that will make dealing with color easier.
 <br>  
 Now, as for palettes...  
-`<rant>`
 
-Guys, the word here is **“palette”**! One ‘l’, two ‘t’s and an ‘e’ at the end. It is not a **“pallet”**, which is “a low, portable platform, usually double-faced, on which materials are stacked for storage or transportation, as in a warehouse”, nor is it a **“pallette”**, meaning “a plate protecting the armpit, in a suit of armor”. The word **“pallete”**, its most common variant, isn't even in the dictionary, thus not even worth considering. It's “palette”, people, “palette”.  
+`<rant>`  
+_Guys, the word here is **“palette”**! One ‘l’, two ‘t’s and an ‘e’ at the end. It is not a **“pallet”**, which is “a low, portable platform, usually double-faced, on which materials are stacked for storage or transportation, as in a warehouse”, nor is it a **“pallette”**, meaning “a plate protecting the armpit, in a suit of armor”. The word **“pallete”**, its most common variant, isn't even in the dictionary, thus not even worth considering. It's “palette”, people, “palette”._  
 `</rant>`
 
 Anyhoo, the GBA has two palettes, one for sprites (objects) and one for backgrounds. Both palettes contain 256 entries of 16bit colors (512 bytes, each). The background palette starts at `0500:0000h`, immediately followed by the sprite palette at `0500:0200h`. Sprites and backgrounds can use these palettes in two ways: as a single palette with 256 colors (8 bits per pixel); or as 16 sub-palettes or <dfn>palette banks</dfn> of 16 colors (4 bits per pixel).
@@ -272,7 +272,11 @@ void vid_vsync()
 {    while(REG_VCOUNT < 160);   }
 ```
 
-Unfortunately, there are a few problems with this code. First of all, if you're simply doing an empty `while` loop to wait for 160, the compiler may try to get smart, notice that the loop doesn't change `REG_VCOUNT` and put its value in a register for easy reference. Since there is a good chance that that value will be below 160 at some point, you have a nice little infinite loop on your hand. To prevent this, use the keyword `volatile` (see `regs.h`). Second, in small demos simply waiting for the VBlank isn't enough; you may still be in that VBlank when you call `vid_sync()` again, which will be blazed through immediately. That does not sync to 60 fps. To do this, you first have to wait until the *next* VDraw. This makes our `vid_sync` look a little like this:
+Unfortunately, there are a few problems with this code. 
+
+First of all, if you're simply doing an empty `while` loop to wait for 160, the compiler may try to get smart, notice that the loop doesn't change `REG_VCOUNT` and put its value in a register for easy reference. Since there is a good chance that that value will be below 160 at some point, you have a nice little infinite loop on your hand. To prevent this, use the keyword _`volatile`_ (see `regs.h`).
+
+Second, in small demos simply waiting for the VBlank isn't enough; you may still be in that VBlank when you call `vid_sync()` again, which will be blazed through immediately. That does not sync to 60 fps. To do this, you first have to wait until the *next* VDraw. This makes our `vid_sync` look a little like this:
 
 ```c
 #define REG_VCOUNT *(vu16*)0x04000006
@@ -284,6 +288,6 @@ void vid_vsync()
 }
 ```
 
-This will always wait until the start of the next VBlank occurs. And `REG_VCOUNT` is now `volatile` (the “`vu16`” is `typedef`ed as a <u>v</u>olatile <u>u</u>nsigned (<u>16</u>bit) short. I'll be using a lot of this kind of shorthand, so get used to it). That's one way to do it. Another is checking the last bit in the display status register, `REG_DISPSTAT`\{0\}.
+This will always wait until the start of the next VBlank occurs. And `REG_VCOUNT` is now _`volatile`_ (the “`vu16`” is `typedef`ed as a <u>v</u>olatile <u>u</u>nsigned (<u>16</u>bit) short. I'll be using a lot of this kind of shorthand, so get used to it). That's one way to do it. Another is checking the last bit in the display status register, `REG_DISPSTAT`\{0\}.
 <br>  
 So we're done here, right? Errm ... no, not exactly. While it's true that you now have an easy way to vsync, it's also a very poor one. While you're in the while loop, you're still burning CPU cycles. Which, of course, costs battery power. And since you're doing absolutely nothing inside that while-loop, you're not just using it, you're actually wasting battery power. Moreover, since you will probably make only small games at first, you'll be wasting a *LOT* of battery power. The recommended way to vsync is putting the CPU in low-power mode when you're done and then use interrupts to bring it back to life again. You can read about the procedure [here](swi.html#sec-vsync2), but since you have to know how to use [interrupts](interrupts.html) and [BIOS calls](swi.html), you might want to wait a while.
diff --git a/theme/css/general.css b/theme/css/general.css
@@ -237,12 +237,16 @@ kbd {
 
 /* Style sheet for TONC */
 
+dfn {
+  font-style: italic;
+  font-weight: bold;
+}
+
 div.note {
-	width: 94%;
-	margin: 0.7em auto;
-	/* padding: 6px 12px 1px 16px; */
+  width: 94%;
+  margin: 0.7em auto;
   padding: 4px 10px;
-	page-break-inside: avoid;
+  page-break-inside: avoid;
   background-color: var(--table-alternate-bg);
 }
 div.note p, div.note ul {
@@ -251,17 +255,19 @@ div.note p, div.note ul {
 div.note ul {
   padding-left: 20px;
 }
+div.note p + p {
+  margin-top: 12px;
+}
 
 div.nh, div.nhgood, div.nhbad, div.nhcare {
   font-weight: bold;
   margin-top: 5px;
-  /* margin-bottom: -0.5em; */
-  padding-bottom: 3px;
+  padding-bottom: 2px;
   border-bottom: 1px solid var(--quote-border);
 }
 
 /* TODO: can we use colours from the syntax highlighting style instead? */
-
+/*       (or just tweak them a bit per-theme) */
 div.nhbad, span.rem, .ack {
   color: #ec1256;
 }
@@ -272,23 +278,21 @@ div.nhcare {
   color: #e88f42;
 }
 
-div.endtag	{ text-align:right; font-size: 70%;	}
-
 /* --- picture+caption frames --- */
 div.cpt, div.cpt_fl, div.cpt_fr {
-	margin: .5em;		padding: 4px;
-	border: 1px var(--table-border-color) solid;
+  margin: .5em;  padding: 4px;
+  border: 1px var(--table-border-color) solid;
   background-color: var(--table-alternate-bg);
-	font-size: 80%; 
-	page-break-inside: avoid;
+  font-size: 80%; 
+  page-break-inside: avoid;
 }
 
-div.cpt_fl	{ float:left;	}
-div.cpt_fr	{ float:right; }
+div.cpt_fl { float:left; }
+div.cpt_fr { float:right; }
 
 /* Margins inside tables work differently. */
 td div.cpt, td div.dpt_fl, td div.cpt_fr {
-	margin: 0;
+  margin: 0;
 }
 
 .cpt p, .cpt_fl p, .cpt_fr p {
@@ -298,19 +302,19 @@ td div.cpt, td div.dpt_fl, td div.cpt_fr {
 /* --- table block styles --- */
 /* yes, table and caption forms are required */
 
-div.reg			{	margin: 8px auto;	text-align:center;	width: 94%;	}
-div.reg table	{	margin: 1px auto; margin-bottom: 12px;	text-align:left;	}
-div.reg caption	{	margin: 0px auto;	text-align:left;	}
+div.reg         { margin: 8px auto; text-align: center; width: 94%; }
+div.reg table   { margin: 1px auto; margin-bottom: 12px; text-align: left; }
+div.reg caption { margin: 0px auto; text-align: left; }
 
-div.cblock			{	margin: 6px auto;	text-align:center;	}
-div.cblock div		{	margin: 2px auto;	text-align:left;	}
-div.cblock table	{	margin: 2px auto;	text-align:left;	}
-div.cblock caption	{	margin: 0px auto;	text-align:left;	}
+div.cblock         { margin: 6px auto; text-align: center; }
+div.cblock div     { margin: 2px auto; text-align: left; }
+div.cblock table   { margin: 2px auto; text-align: left; }
+div.cblock caption { margin: 0px auto; text-align: left; }
 
-/* div.lblock			{	margin: 6px 3em;	}
-div.lblock table	{	margin: 2px 0;		} */
+/* div.lblock   { margin: 6px 3em; }
+div.lblock table { margin: 2px 0;  } */
 
-div.cblock div.cpt	{ margin: 0.5em auto; }
+div.cblock div.cpt { margin: 0.5em auto; }
 
 /* Fix oversight in the mdBook styles? */
 table, table th {
@@ -328,28 +332,28 @@ table.reg-huge th, table.reg-huge td {
 
 /* === Table styles === */
 
-td.fill, th.fill	{ width: 16px; }
+td.fill, th.fill { width: 16px; }
 
 /* --- reg table --- */
 table.reg {
-	font: 90% var(--mono-font);
-	page-break-inside: avoid;
+  font: 90% var(--mono-font);
+  page-break-inside: avoid;
 }
-caption.reg			{ caption-side:top; }
+caption.reg   { caption-side:top; }
 
 caption[align="bottom"], div.cblock caption[align="bottom"] {
   margin-top: 6px;
 }
 
-tr.bits, tr.bf, col.bits, col.bf, col.def { text-align:center; }
-col.bits, col.bf, col.def {	vertical-align:top; 	}
-tr.bits, col.bits		{	font: 90% var(--mono-font);	}
-tr.bf, col.bf			{	font-weight:bold;			}
-col.def					{	font: 90% var(--mono-font);	}
+tr.bits, tr.bf, col.bits, col.bf, col.def { text-align: center; }
+col.bits, col.bf, col.def { vertical-align: top; }
+tr.bits, col.bits { font: 90% var(--mono-font); }
+tr.bf, col.bf { font-weight: bold; }
+col.def { font: 90% var(--mono-font); }
 
 /* read only, write only */
-.rof	{ text-decoration:overline;  color: #f22;  }
-.wof	{ text-decoration:underline; color: #44f; }
+.rof { text-decoration: overline;  color: #f22; }
+.wof { text-decoration: underline; color: #44f; }
 
 /* reg colors */
 .rclr0 { color: #ef0d4b; }
@@ -360,8 +364,8 @@ col.def					{	font: 90% var(--mono-font);	}
 .rclr5 { color: #d09a4c; }
 .rclr6 { color: #e7849b; }
 .rclr7 { color: #dce24b; }
-.rclr8	{ color:teal;		}
-.rclr9	{ color:gray;		}
+.rclr8 { color:teal; }
+.rclr9 { color:gray; }
 
 font[color="blue"] { color: #43a8e6; }
 font[color="green"] { color: #45e774; }