1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
/*
* ============================================================================
* oot_bitset
* ============================================================================
*
* oot_bitsets ie. (`uint16_t bits[30]`) are compact bitsets used in Ocarina of Time
* for tracking file that tracks hundreds of one-bit flags — e.g., whether
* you’ve talked to an NPC, triggered a cutscene, etc.
*
* In the above example, 30 * uint16_t words stores up to 480 flags, each biset
* ID (see below) is an index into this bitset.
*
* oot_bitsets *must* operate on arrays io uint16_t words!
*
* ----------------------------------------------------------------------------
* Encoding
* ----------------------------------------------------------------------------
*
* Each flag is a unique 16-bit ID where:
* - Upper 12 bits (flag >> 4): word index (0–29) (maximum of 4096 words)
* - Lower 4 bits (flag & 0xF): bit index (0–15)
*
* Layout:
* 15 4 3 0
* [ word index ][ bit index ]
*
* Example:
* Flag (hex) Word Bit
* ---------- ----- ---
* 0x75 7 5
* 0x61 6 1
* 0x1AC 26 12
*
* 0x75 -> word 7, bit 5
* 0x61 -> word 6, bit 1
* 0x1AC -> word 26, bit 12
*
* Because hex digits are 4 bits each, you can visually parse a flag as "word:bit":
* These can simply by increasing values in an enum:
*
* enum FlagsOfInterest {
* FLAG_HAS_SEEN_BOB = 0x00, // 1st word, 1st bit
* FLAG_HAS_SEEN_ALICE = 0x01, // 1st word, 2nd bit
*
* // you can even organize different bits by different words
* FLAG_HAS_SEEN_LINK = 0x10, // 2nd word, 1st bit
* FLAG_HAS_SEEN_ZELDA = 0x1A, // 2nd word, 11th bit
* }
*
* or you can just keep it simple:
*
* enum FlagsOfInterest {
* FLAG_HAS_SEEN_BOB,
* FLAG_HAS_SEEN_ALICE,
* FLAG_HAS_SEEN_LINK,
* FLAG_HAS_SEEN_ZELDA,
* }
*
*/
/**
* @brief Return a reference to the 16-bit word that contains @p flag.
*
* @param set Pointer to the first element of the bitset (array of `uint16_t`
* words).
* @param flag Encoded 16-bit flag ID.
* @return L-value referring to the relevant word in the bitset.
*
* @warning This macro evaluates its arguments more than once; pass only
* side-effect-free expressions.
*/
/**
* @brief Extract the word index from an encoded flag ID.
*
* The upper twelve bits of a flag encode the index of the 16‑bit word that
* stores the flag. `bitset_index()` isolates those bits.
*
* @param flag Encoded 16‑bit flag ID.
* @return Zero‑based word index (0 – 4095).
*/
static inline uint16_t
/**
* @brief Convert a flag ID to a single‑bit mask.
*
* The lower four bits of @p flag specify which bit inside the word is used. The
* resulting mask has exactly one bit set; e.g. a bit index of 5 yields
* `0x0020`.
*
* @param flag Encoded 16‑bit flag ID.
* @return 16‑bit mask with a single bit set.
*/
static inline uint16_t
/**
* @brief Test whether a flag is set.
*
* @param set Pointer to the first element of the bitset (array of
* `uint16_t` words). The array must contain at least
* `bitset_index(flag) + 1` elements.
* @param flag Encoded 16‑bit flag ID.
* @return `true` if the bit is currently set; `false` otherwise.
*/
static inline bool
/**
* @brief Set (enable) a flag.
*
* @param set Pointer to the bitset array.
* @param flag Encoded flag ID.
*/
static inline void
/**
* @brief Clear (disable) a flag.
*
* @param set Pointer to the bitset array.
* @param flag Encoded flag ID.
*/
static inline void
/* OOT_BITSET_H */