After this I wanted to introduce the concept of food so the ants can react to it. When it finds food, it “grabs” it and heads straight home. Once it deposits the food, it goes back to wondering looking for more food.

Now that this simple addition is working, I needed to put a little more effort into the “wondering” mechanic. I needed the ants to have a real forward direction, and be able to rotate smoothly across random increments looking for food or pheromones. But the problem is, I had not established yet what the sensory range looked like for the ant when it came to detecting food or pheromones. Was it simply the forward direction? Was it a triangular cone in front of the ant? What I decided to do was create three sensory rectangles that are laid out in front of the ant. These would be front-left, front, and front-right. If the ant detected something in either the front left or right sensors, it would smoothly rotate towards that direction. For now, I just want the ant to continue to rotate in random directions, but with the power of visualization, I want to make sure that all my three sensors + my forward direction are behaving as expected!

My next step is to create the concept of a pheromone. I want ants to produce these pheromones on a short timer so they can construct a path. I also want these pheromones to dissipate over time. That way I want have them laying around permanently, and it would be more natural as the ants will be able to follow more recent paths. I’ll first focus on producing one kind of pheromone (to_home) as the other (to_food) will behave exactly the same way and won’t take much work to introduce when the time comes. The color of this pheromone will be depicted as purple.

Now that this basic functionality works, I want to start working on the actual behavior we care about. This is how it will work. Ants will spawn from a colony (a centralized location) and will wonder around looking for food while leaving to_home pheromones. Once they find food, the ant will collect 1 food and begin its journey home by following the to_home pheromones to deposit the food. While its looking returning to the colony, it will be leaving to_food pheromones (depicted in teal) to tell other ants the general direction of where it found food. I also want to increase the speed of the ants, as right now they feel a little slow and sluggish in regards to movement and rotation.

The end goal is to have a couple thousand ants running around, so lets try 2500 ants and see how they behave.

First objective accomplished! This is TERRIBLE performance and we need to make some improvements, this is a software renderer at the end of the day and isn’t going to be a powerhouse like any hardware rendering API. Before we get into major optimizations, lets get a rough understanding of how many entities we are working with and maybe we can do some simple things that could help in optimizing this program.

At the moment, we have a large Entity list that contains all of our Entities. If we do some rough math, we have 2500 ants, we have 3 areas of food each containing 2400 pieces of food, and finally each ant is producing pheromones at a 1/4 second interval which roughly translates to about 10k entities a second. Note that these pheromones dissipate over time so there is an upper bound on how many of them can exist at a time. So at its peek we should roughly have around 100k entities up and running at any given time.

The first thing I want to tackle is how my ants look for other entities. At the moment they simply iterate over this list and loop over every single entity. A simple change we can make is to separate out each entity type into its own list. Food list, to_home pheromone list and a to_food pheromone list. In addition to this, we can break our screen into multiple cells and have our ants only look at its own as well as neighboring cells for food and pheromones. This should look something like this.

Everything in the range of the red circle should be within the range of what an ant can iterate over and look for. This grid will be 16×16 and each cell will contain its own lists for each kind of entity. All I need to do now is every time I want to spawn a pheromone or food, I simply look at what cell I’m in, and add it to the corresponding list.

Next, lets take a look at SIMD and how we can optimize our rectangle blits. This is my first time working with SIMD so I had to use some solid resources to understand the basics. My two main sources where a few Handmade Hero episodes and Intel’s Intrinsics guide which documents all of the SIMD operations you might need for the family you want to target (In my case I wanted to target the SSE 128bit family).
HMH: https://guide.handmadehero.org/code/day089/#1247
Intel Intrinsics: https://www.intel.com/content/www/us/en/docs/intrinsics-guide/index.html#

For those who don’t know what SIMD is (Single Instruction Multi Data), a brief lame explanation is this. Your CPU has the capability to perform operations WIDE. So taking addition as an example, if you had 4 separate sets of independent additions you wanted do make, you can perform all those additions in a single CPU instruction [A + B][C + D][E + F][H + G]. So in the case of rendering, without SIMD, our general approach looks something like this:
– iterate over an 8×8 region (for Ants specifically)
– grab the existing color and linearly blend it with the new color (with some additional gamma correction)
– write out the new color the buffer

We do this pixel by pixel for each Ant, Pheromone, Food, Colony, everything. But since these pixels are independent from one another (as in we are not doing any anti aliasing or bilinear filtering, although this still works in those cases, its just a little more work), we can do this operation on multiple pixels at a time. Our colors at the moment are 4 channel 32bit values. Since we are using the SSE 128bit family, we can perform all of these operations on 4 pixels at a time. If we were to use a family that supports 256 or 512 bits, we would be able to perform these operations on 8 or 16 pixels at a time.

So when writing out to 1 color could look something like this (reduced for simplicity)

            // extract current colors
            f32 current_a = ((f32)((*pixel >> 24) & 0xFF) / 255.0f);
            f32 current_r = (f32)((*pixel >> 16) & 0xFF);
            f32 current_g = (f32)((*pixel >> 8) & 0xFF);
            f32 current_b = (f32)((*pixel >> 0) & 0xFF);

            // convert to 255 range
            color.r *= 255.0f;
            color.g *= 255.0f;
            color.b *= 255.0f;

            // perform linear blend
            f32 new_r = (1 - color.a) * current_r + (color.a * color.r);
            f32 new_g = (1 - color.a) * current_g + (color.a * color.g);
            f32 new_b = (1 - color.a) * current_b + (color.a * color.b);

            // write out new colors
            u32 new_color = (round_f32_s32(color.a * 255.0f) << 24 | round_f32_s32(new_r) << 16 | round_f32_s32(new_g) << 8 | round_f32_s32(new_b) << 0);
            *pixel = new_color;

Our code now would look more like this

            __m128i loaded_pixel_4x = _mm_loadu_si128((__m128i*)pixel);

            // from: argb-argb-argb-argb
            // to:   aaaa-rrrr-gggg-bbbb
            __m128 loaded_r_4x = _mm_cvtepi32_ps(_mm_and_si128(_mm_srli_epi32(loaded_pixel_4x, 16), mask_FF));
            __m128 loaded_g_4x = _mm_cvtepi32_ps(_mm_and_si128(_mm_srli_epi32(loaded_pixel_4x, 8),  mask_FF));
            __m128 loaded_b_4x = _mm_cvtepi32_ps(_mm_and_si128(loaded_pixel_4x, mask_FF));

            // linear blend between loaded color and input color
            __m128 new_loaded_r_4x = _mm_mul_ps(current_a_percent_4x, loaded_r_4x);
            __m128 new_loaded_g_4x = _mm_mul_ps(current_a_percent_4x, loaded_g_4x);
            __m128 new_loaded_b_4x = _mm_mul_ps(current_a_percent_4x, loaded_b_4x);

            __m128 new_r_4x = _mm_add_ps(new_loaded_r_4x, new_color_r_4x);
            __m128 new_g_4x = _mm_add_ps(new_loaded_g_4x, new_color_g_4x);
            __m128 new_b_4x = _mm_add_ps(new_loaded_b_4x, new_color_b_4x);
            __m128 new_a_4x = _mm_mul_ps(color_a_4x, color_255_4x);

            // convert to int, cvtps rounds to nearest. no need for +0.5f
            __m128i int_a_4x = _mm_cvtps_epi32(new_a_4x);
            __m128i int_r_4x = _mm_cvtps_epi32(new_r_4x);
            __m128i int_g_4x = _mm_cvtps_epi32(new_g_4x);
            __m128i int_b_4x = _mm_cvtps_epi32(new_b_4x);

            // shift argb order
            __m128i shifted_int_a_4x = _mm_slli_epi32(int_a_4x, 24);
            __m128i shifted_int_r_4x = _mm_slli_epi32(int_r_4x, 16);
            __m128i shifted_int_g_4x = _mm_slli_epi32(int_g_4x, 8);
            __m128i shifted_int_b_4x = int_b_4x;

            // OR everything together
            __m128i output_pixel_4x = _mm_or_si128(shifted_int_a_4x,
                                      _mm_or_si128(shifted_int_r_4x,
                                      _mm_or_si128(shifted_int_g_4x,
                                                   shifted_int_b_4x)));

            __m128i output_masked = _mm_and_si128(mask, output_pixel_4x);

            _mm_storeu_si128((__m128i * )pixel, output_masked);

            // normally would be 4, but can be less if we reach the end of the rectangle or buffer and want to modify less pixels
            pixel += increment;

Of course this is a much simpler and redacted version of what is actually in my function for brevity, as there are several edges cases you have to handle such as the last comment in this snippet that talks about having to increment at a different increment from the normal 4 based on whether or not you are reaching the end of your rectangle row or buffer.

Using tools techniques such as __rdtsc() and measuring cycles elapsed, I can see that we were rendering at around 500 cycles per rectangle, and now are down to about 150 cycles per rectangle. I want to note that this program is entirely inefficient and is not meant to run well nor is it meant to run fast. This is partly intentional but not in the sense that I made intentional bad decisions, simply that I didn’t care to write performant code, because I wanted to justify the use for optimization techniques like SIMD in order to noticeably see their value.

The final thing I want to try and tackle here is multi-threading… as of this blog, I hate multi-threading. It has nothing to do with the overall concepts of multi-threading and entirely to do with the C/C++ API implementation being entirely complicated and annoying to work with. But alas we must go down this path to… learn and get better!

The way we are going to do this is simple. We are going to create as many threads as my CPU allows (in this case 24), I will also create a work queue and push “work” on to this queue for the threads to operate on. This will simply be rendering work. So I will push chunks of rendering work and the next available thread will grab that piece of work and operate on it until its done. The work will be everything that needs to be rendered in a single cell from the 16×16 cells that I created earlier.

    HANDLE semaphore_handle = CreateSemaphoreExW(0, 0, thread_count, 0, 0, SEMAPHORE_ALL_ACCESS);

    for(u32 i=0; i<thread_count; ++i){
        DWORD thread_id;
        HANDLE thread_handle = CreateThread(0, 0, thread_proc, thread_context.queue, 0, &thread_id);
        CloseHandle(thread_handle);
    }

So once we have these threads up and running, we can simply feed them work by using the semaphore handles that will persist. So instead of having a single buffer that I push render commands to, I’m now pushing to 16×16 buffers (nothing intelligent here or anything I recommend anyone doing. This is just for experimentation and learning), and once there is work to do on those buffers, the next available thread will render my commands!

With all these optimizations done, my ant colony works pretty smoothly with 2500 ants all running around looking for food and bringing it back to the colony!

So… the first step was to figure out how to draw things using the windows API. The concept itself is pretty simple, although as usual Windows made it hard to figure out and complicate with the number of steps and settings you need to setup right off the bat. Once you are able to create and register a window class, you need to setup a few more things to be able to draw to a back buffer, such as a device context, bitmap info, and some basic information about how large this buffer is going to be. For this, I created a RenderBuffer struct that contained all this information for me, and once I populate the back buffer with data, I can display it using StretchDIBits().

typedef struct RenderBuffer{
    void* base; // pointer to the start of my backbuffer
    size_t size; // size of backbuffer

    s32 width; // width of backbuffer
    s32 height; // height of backbuffer
    s32 bytes_per_pixel; // 4 bytes per pixel (RGBA)
    s32 stride; 

    BITMAPINFO bitmap_info;
    HDC device_context;
} RenderBuffer;
RenderBuffer render_buffer;

// initialize the render buffer and all the data relevant for blitting to the screen
static void init_render_buffer(RenderBuffer* render_buffer, s32 width, s32 height){
    render_buffer->width = width;
    render_buffer->height = height;

    render_buffer->bitmap_info.bmiHeader.biSize = sizeof(BITMAPINFOHEADER);
    render_buffer->bitmap_info.bmiHeader.biWidth = width;
    render_buffer->bitmap_info.bmiHeader.biHeight = -height;
    render_buffer->bitmap_info.bmiHeader.biPlanes = 1;
    render_buffer->bitmap_info.bmiHeader.biBitCount = 32;
    render_buffer->bitmap_info.bmiHeader.biCompression = BI_RGB;

    s32 bytes_per_pixel = 4;
    render_buffer->bytes_per_pixel = bytes_per_pixel;
    render_buffer->stride = width * bytes_per_pixel;
    render_buffer->size = width * height * bytes_per_pixel;
    render_buffer->base = os_virtual_alloc(render_buffer->size);
    render_buffer->device_context = GetDC(window);
}

static void update_window(HWND window, RenderBuffer render_buffer){
    StretchDIBits(render_buffer.device_context,
                            0, 0, render_buffer.width, render_buffer.height,
                            0, 0, render_buffer.width, render_buffer.height,
                            render_buffer.base, &render_buffer.bitmap_info, DIB_RGB_COLORS, SRCCOPY))
}

With just this code, we can easily rasterize any rectangle we want with any color, by just iterating over some starting point in the buffer, and advancing by the stride to get to the next row of pixels we want to fill in.

static void draw_rect(RenderBuffer *render_buffer, f32 start_x, f32 start_y, s32 w, s32 h, RGBA color){

    // get starting position
    u8 *row = (u8 *)render_buffer->base + ((render_buffer->height - start_y - 1) * render_buffer->stride) + (start_x * render_buffer->bytes_per_pixel);

    // iterate until height
    for(f32 y = start_y; y <= start_y + height; ++y){
        u32 *pixel = (u32 *)row;

        // iterate until width
        for(f32 x = start_x; x <= start_x + width; ++x){

            // assign new color to pixel
            u32 new_color = (round_f32_s32(color.a * 255.0f) << 24 | round_f32_s32(color.r * 255.0f) << 16 | round_f32_s32(color.g * 255.0f) << 8 | round_f32_s32(color.b * 255.0f) << 0);
            *pixel++ = new_color;
        }

        pixel += render_buffer->stride;
    }

}

From here, we can start understanding how to draw all kinds of simple shapes such as a line, circle, ray, triangle, quad (2 triangles), …
So naturally we now want to be able to draw a triangle. And this turns out to be also pretty simple. But first we have to understand some terminology such as flat bottom triangle and flat top triangles. All this means is that every triangle we want to draw, either is flat at the bottom and meets at the top, or flat at the top and meets at the bottom.

From here, we just have to calculate the rise over run of both sides, in case it is not uniform and every time we rasterize a row, we either go up or down by the rise/run for each side to completely draw the entire triangle. The code for this looks something like this (where draw_flatbottom_triangle() would be the same except in the opposite direction):

static void draw_flattop_triangle(RenderBuffer *render_buffer, v2 p0, v2 p1, v2 p2, RGBA color){
    f32 left_slope = (p0.x - p2.x) / (p0.y - p2.y);
    f32 right_slope = (p1.x - p2.x) / (p1.y - p2.y);

    s32 start_y = (s32)round_f32_s32(p2.y);
    s32 end_y = (s32)round_f32_s32(p0.y);

    for(s32 y=start_y; y < end_y; ++y){
        f32 x0 = left_slope * (y + 0.5f - p0.y) + p0.x;
        f32 x1 = right_slope * (y + 0.5f - p1.y) + p1.x;
        s32 start_x = (s32)ceil(x0 - 0.5f);
        s32 end_x = (s32)ceil(x1 - 0.5f);
        for(s32 x=start_x; x < end_x; ++x){
            draw_pixel(render_buffer, (v2){(f32)x, (f32)y}, color); // a helper function to make it simpler to fill in a single pixel
        }
    }
}

Finally, we need to be able to rasterize all kinds of triangles, specifically ones that have not flat bottom or flat top. The way to do this is to realize that you can take any single triangle, split it in half and turn it into both a flat bottom and flat top triangle. To do this, you just need to figure out which point is in the middle with respect to height, and use that point as the splitting point to create one flat bottom and one flat top triangle. Once you have that information, you can just call the two functions to render both flat top and flat bottom triangles!

Now that I’m able to rasterize any triangle I want, I can start working towards replicating the example shown in Wikipedia while using the DirectX rasterization rules on how to resolve a) if a pixel is in our out of a triangle, and b) which triangle draws the line if two triangles overlap. After banging my head around this for a long time, it turned out that it all revolved around how you round your values, and a couple of ceils that you might have noticed in the above code to draw a flat top triangle.
So with a little bit of work, I’m able to draw the individual pixels that are identical to the wiki, enlarge them by 50 pixels or so, and pass them in as individual triangles to be rendered. The result is this:

At this point the project is pretty much done. But I did spend some more time playing around with shapes, colors and more and ended up drawing a whole bunch of stuff including some simple linear alpha blending. (line, ray, segment, circle (filled/outlined), rect (filled/outlined), quad (filled/outlined), triangle)

I began with some simple rects being rendered (my Entities) and with some functionality to moving them around with WASD and a mouse.

Once I was able to get a couple of Entities rendering on the screen, since this is a scene manager, the majority of the rest of the work was going to go into the UI and being able to transform save/load and transform these entities in various ways. So I began with a basic UI that shows me what group and layer my UI element was sitting on. This was going to help me render things in front or behind other objects by sorting.

Once that was done, began introducing the the concept of an Immediate Mode UI (Something I had just learned about at the time, thanks to Casey Muratori). In short, the UI is build and discarded every frame. Every frame, iterate over a portion of the code, and build/draw the UI in place as needed. I also introduced the concept of hot/active where you are either about to interact with a UI item, or you are interactive with a UI element. This helped a lot in being able to work with the various different situations where your mouse is over an element, but you are already typing in another element. Or you click on a button and drag our mouse out to let go of that button.
The code I wrote for this is my first poor attempt at doing something like this, and it took me many conversations with people who knew how to do this to understand the concepts and give it my best shot. The code looks something like this:

UI.do_canvas(UIID(), pygame.Rect(0, 910, 250, 400), 18, padding=v4(10,10,10,10))
UI.do_label(UIID(), "level - %s" % str(_globals.level_loaded), 18)

UI.do_canvas(UIID(), pygame.Rect(1026, 0, 250, 400), 18, padding=v4(10,10,10,10))
UI.do_label(UIID(), "Entities", 18)
for e in EM.entities.values():
    if UI.do_button(DUIID(), e._id, 18, tab=True):
        _globals.selection = e

UI.do_canvas(UIID(), pygame.Rect(0, 610, 250, 400), 18, padding=v4(10,10,10,10))
UI.do_label(UIID(), "Data", 18)
if _globals.selection:
    UI.do_label(UIID(), "_____________", 18)
    for label, value in _globals.selection.__dict__.items():
        if label == "sprite_source":
            UI.do_label(UIID(), value, 18)
        if label == "position":
            UI.do_label(UIID(), label, 18)
            _globals.selection.__dict__[label].x = UI.do_param(UIID(), 18, value[0], align=2)
            _globals.selection.__dict__[label].y = UI.do_param(UIID(), 18, value[1])
        if label == "scale":
            UI.do_label(UIID(), label, 18)
            _globals.selection.__dict__[label].x = UI.do_param(UIID(), 18, value[0], align=2)
            _globals.selection.__dict__[label].y = UI.do_param(UIID(), 18, value[1])

From this I was able to create a canvas, and populate the canvas with UI elements like (labels, buttons, text input boxes, …). So I created a couple canvases, one to show the list of entities I was working with, which behaved as buttons, and one to show which individual entity I was editing.

After this I began working on a drop down console. The goal was to make sure the console behaved just like any console that you might find in some games (Quake, CS) and somewhat Jonathan Blow inspired from watching his youtube channel. You can type input, move your cursor around, edit text anywhere in the input string, view history, auto complete known commands and a few other features. But most of the value comes from being able to serialize and deserialize the “level” I was working with.

Finally I wanted to put it all together. What this meant for the project was being able to load a level, make modifications to the entities that were loaded, and save them to disk with my own simple data format, to be loaded again later. The result is this.

Project done! the goal now is to be able to replicate this in C/C++, using DirectX and writing everything by hand myself.