Adding bitmask explainer to docs.

doc/1-intro/glossary.md

@@ -14,6 +14,8 @@
 
 **bitbang**: to achieve PCM sound by sending a rapid stream of volume commands to a non-PCM channel.
 
+**bitmask**: a set of bits which represent individual single-bit toggles or groups representing small numbers. these are explained fully in the [hexadecimal primer](hex.md).
+
 **BRR**: a lossy sample format used by the SNES. it has a fixed compression ratio; groups of 32 bytes (16 samples) are encoded in 9 bytes each.
 - usually stored in .brr files.
 

doc/1-intro/hex.md

@@ -96,6 +96,36 @@ now for decimal number `69420`:
 = 10F2C
 ```
 
+## bitmask
+
+a bitmask is a value that actually represents a set of individual binary bits to be toggled, some of which may be grouped to form small binary numbers. these are used by adding up the value of each bit and converting the result to hex. in macros, these are shown in decimal.
+
+bit   |   binary    | decimal
+:-----|:-----------:|--------:
+bit 7 | `1000 0000` | 128
+bit 6 | `0100 0000` |  64
+bit 5 | `0010 0000` |  32
+bit 4 | `0001 0000` |  16
+bit 3 | `0000 1000` |   8
+bit 2 | `0000 0100` |   4
+bit 1 | `0000 0010` |   2
+bit 0 | `0000 0001` |   1
+
+for example, to turn bits 7 and 5 on, and put `110` (decimal 6) in bits 1 to 3:
+
+```
+bit 7 = `1... ....` = 128
+bit 6 = `.0.. ....` =   0
+bit 5 = `..1. ....` =  32
+bit 4 = `...0 ....` =   0
+bit 3 = `.... 1...` =   8
+bit 2 = `.... .1..` =   4
+bit 1 = `.... ..0.` =   0
+bit 0 = `.... ...0` =   0
+``````
+
+added together, the resulting binary is `1010 1100`, which converts to hex as `AC` and to decimal as 172.
+
 ## hex to decimal table
 
   hex | `0` | `1` | `2` | `3` | `4` | `5` | `6` | `7` | `8` | `9` | `A` | `B` | `C` | `D` | `E` | `F`