diff --git a/doc/1-intro/glossary.md b/doc/1-intro/glossary.md
index 54d9fab1d..e64fb91c0 100644
--- a/doc/1-intro/glossary.md
+++ b/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.
 
diff --git a/doc/1-intro/hex.md b/doc/1-intro/hex.md
index d433a38a8..d596c2684 100644
--- a/doc/1-intro/hex.md
+++ b/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`