Useful macros

Define or declare arrays with 1-bit elements

Define or declare arrays with 2-bits elements

Define or declare arrays with 4-bits elements

Define or declare arrays with 6-bits elements

Parameters (1 byte)

C Definitions

#define CPCT_6BITARRAY (Name, Elems)

#define CPCT_4BITARRAY (Name, Elems)

#define CPCT_2BITARRAY (Name, Elems)

#define CPCT_1BITARRAY (Name, Elems)

Details

These macros make more comfortable the process of declaring and defining bitarrays.  Any bitarray is a normal array of bytes in the end.  However, it is usually accessed through CPCtelera’s bitarray function to manage elements smaller than 1 byte.

When a bitarray is defined, a calculation has to be made to know how many bytes are required to store the total amount of X-bits elements it will contain.  For instance, to store 8 2-bits elements, 16 bits are needed, so 2 bytes needs to be allocated.  Therefore, in the next code segment, both sentences are equivalent:

CPCT_2BITSARRAY(my_array, 8);   // This allocates 2 bytes (8 2-bits elements)
u8 my_array[2];                 // This does exactly the same.

These 4 macros can be used either for defining and for declaring bitarrays.  This example shows how to define and declare different bitarrays:

// Declaring an array (without defining it)
//     This one is a 40 bits array (5 bytes, 10 4-bits elements)
extern CPCT_4BITSARRAY(an_array, 10);

// Define and populate a constant array
//      This other is a 16-bits array (2 bytes, 8 2-bits elements)
const CPCT_2BITSARRAY(other_array, 8) = {
    0b00011011, 0b11100100  // Populate with 8 elements (0,1,2,3,3,2,1,0)
};

Encodes 4 6-bits elements into 3 bytes for a CPCT_6BITARRAY

Encodes 2 4-bits elements into 1 byte for a CPCT_4BITARRAY

Encodes 4 2-bits elements into 1 byte for a CPCT_2BITARRAY

C Definitions

#define CPCT_ENCODE6BITS(A, B, C, D)

#define CPCT_ENCODE4BITS(A, B)

#define CPCT_ENCODE2BITS(A, B, C, D)

Parameters (2-4 bytes)

Parameter Restrictions

Details

These macros help in the initialization of bitarray elements mainly, and can also help on their population and modification.  They get individual elements (one number for each element) and pack them together, putting each element into its corresponding bits.

Let us understand this better with an example.  Suppose we wanted to initialize a CPCT_4BITARRAY with these elements: 5, 10, 15, 1.  We could do it manually this way:

// Define and populate a new bitarray with 4-bits elements
CPCT_4BITARRAY(mybitarray, 4) = {
   0x5A, // First 2 elements of the bitarray, 5 and 10, 4-bits each, hexadecimally codified
   0xF1  // Next 2 elements of the bitarray, 15 and 1, 4-bits each, hexadecimally codified
};

In this case, we know that each hexadecimal digit corresponds to 4-bits and use this to define 4 elements in 2 bytes, being each one a hexadecimal digit.  We can do exactly the same, easily, using CPCT_ENCODE4BITS macro:

// Define and populate a new bitarray with 4-bits elements
CPCT_4BITARRAY(mybitarray, 4) = {
   CPCT_ENCODE4BITS( 5, 10),  // Add elements 5 and 10
   CPCT_ENCODE4BITS(15,  1)   // Add elements 15 and 1
};

This code does the same as previous one, but its easier to do.  We use CPCT_ENCODE4BITS macro and directly write desired values in order, as in a conventional array definition.  This let us forget about internal codification and focus on our data.

Examples of use

This example is from a platform game, where user controls a running man that has to jump over metal spikes.  The game needs an array defining the layout of the floor, having 4 types of floor block: (0) normal floor, (1) decelerator floor, (2) jump-booster floor, (3) spikes.  This is the definition of the first level:

// Define level 1 layout. It starts with normal floor, going then through
// some easy jumps and ending with a decelerator floor previous to a
// jump-booster which is required for the final jump.
CPCT_2BITARRAY(level_1, 24) = {
     CPCT_ENCODE2BITS(0, 0, 0, 0) // Start with normal floor
   , CPCT_ENCODE2BITS(3, 0, 0, 0) // Some easy jumps (spike and then 3 floors)
   , CPCT_ENCODE2BITS(3, 0, 0, 0)
   , CPCT_ENCODE2BITS(1, 1, 2, 2) // Decelerator floor, followed by 2 jump-boosters
   , CPCT_ENCODE2BITS(3, 3, 3, 3) // Big spike hole
   , CPCT_ENCODE2BITS(0, 0, 0, 0) // Normal floor at the end of the level
}

The same operation this code does (defining and populating an array), could have been manually done this way:

// Defining and populating level 1, using 2 bits for each element
// (4 elements per byte, so 6 bytes required, as 6 x 4 = 24). We
// use binary numbers for clarity (2bits per element), and include hexadecimal
// and decimal for comparison purposes only.
level_1[6] = { 0b00000000, 0b11000000, 0b11000000, 0b01011010, 0b11111111, 0b00000000 };
//         = { 0x00, 0xC0, 0xC0, 0x5A, 0xFF, 0x00 }; Same in hexadecimal
//         = {    0,  192,  192,   80,  255,    0 }; Same in decimal

Another example could be the definition of a height map for a 2D lateral game filled with mountains.  Each element of the next array will refer to the height of the floor at a given location.  Thinking of a floor that will never be taller than 63 pixels, we can use a 6-bits array to define the layout of the map.  This would be a map for the second level of this game:

// Define the height map for the level 2 that     #        < 28
// will be a great mountain like this one >>     ###       < 24
CPCT_6BITARRAY(heightmap_l2, 12) = {      //     ###       < 20
     CPCT_ENCODE6BITS( 0,  4,  8, 16)     //    ######     < 16
   , CPCT_ENCODE6BITS(24, 28, 24, 16)     //    ######     < 12
   , CPCT_ENCODE6BITS(16,  4,  0,  0)     //   #######     <  8
};                                        // _#########__  <  4