dev>mode13h

Is Fixed-Point Still Relevant?

Sun, 28 Jun 2026 00:00:00 +0000

Over the last six months I’ve been polishing and optimizing Tofu Engine’s software renderer. Yeah, I know… a full and detailed devlog on this topic post is due, but while I’m organizing my thoughts on that, here’s an interesting byproduct the I think we shall talk about. :)

After quite a bit of rework to the blitter code, the hot-loop part of the routines (namely, the (roto)scaler) have been rewritten as incremental. We start from a source coordinate, add a constant step for each destination pixel, sample the source texture, and move on. You know the drill.

As a basic arithmetic type I’ve been using float since the very beginning, mostly on the assumption that modern CPUs (with their FPUs) and compilers are clever enough to operate on this type with roughly the same performance as integer types.

But are we that this assumption is correct?

While iterating through the destination area, every pixel coordinate (in the source texture) is computed as a float and then converted to int in order to sample the source texture pixel.

At that point, a few questions naturally appeared. Is the approximation done with float precise enough for this use case? Are we introducing unnecessary rounding noise while repeatedly accumulating small increments? How much does the float-to-int conversion cost? And, since we are in an accumulation hot-loop anyway, would a DDA-like approach be preferable?

I rapidly threw together some simple benchmarks and the results were… surprising. Floating point is, as expected, not the silver bullet we might think it is.

This led me to write a small utility library to pack the fixed-point functions I needed (yeah, I know that some other nice libraries exists, but you know… the thrill or reinventing the wheel). I chose for a Q16:16 format as the default, since the values I’ll be using won’t reasonably exceed the int16_t range. Having 16 bits of fractional part still gives enough subpixel precision, while keeping the integer part large enough for ordinary work. Addition and subtraction remain integer operations and conversion back to an integer pixel coordinate is basically a bit-shift.

I won’t be using it everywhere across my codebase, ‘though, especially to replace what naturally lives in floating point. Floating point math is perfectly suited for a lot of higher-level calculations. Also, I would avoid using it where values can easily escape the range above, as the library does not provide saturation or overflow protection. I’m aiming for is more of a hybrid strategy: do the comfortable high-level setup in float, convert stable starting values and increments once, then let fixed point handle the hot inner portion where it actually buys something.

You can find the library here, along with the benchmark results.

That is all for now. See ya next. :)

Garbage Collection

Sun, 11 Jan 2026 00:00:00 +0000

Recently, I upgraded Lua from version 5.4.x to 5.5.0. It has been a long-awaited minor release for our beloved embeddable scripting language. While running a few demos (just to make sure everything was behaving correctly) I noticed that, in at least two cases, a significant amount of memory kept accumulating without being released… to the point where the boids demo would freeze in less than a minute.

A closer inspection revealed that the temporary objects created during the update() step were continuously piling up. But why?

As it turned out, the engine’s continuous garbage-collection mode was poorly implemented. First of all, it was unnecessarily overcomplicated: there is no real need to track an arbitrary time window just to decide when to trigger a GC step. Moreover, the GC_MODE_CONTINUOUS mode itself was flawed, because the initial implementation did not take into account that executing a single LUA_GCSTEP roughly every ~15 seconds is not sufficient to keep up with aggressive allocation patterns. Memory is effectively reclaimed only at the end of a full collection cycle, so the backlog could easily grow out of control.

After some simplification and a fair amount of testing, I came to the conclusion that the generational strategy works well when it is left entirely to the virtual machine, but when finer control is required the incremental garbage collector is once again the better choice. By performing a single collection step at a lower-priority update frequency (for example, one step every four update() calls), memory usage remains stable even when large numbers of short-lived objects and tables are created.

I also experimented with running the garbage-collection in short “bursts”, instead of single steps. In theory, LUA_GCSTEP can be invoked in a loop until it returns a non-zero value, signaling that a full cycle has completed. However, with the generational collector this loop only terminates when a major collection is executed. If the GC keeps operating in minor collection mode, the loop may never end, effectively spinning forever. This means some form of capping is required, for example:

void luaX_gccycle(lua_State *L, int max_steps)
{
    for (;;) {
        if (max_steps >= 0 && max_steps-- == 0) { // To be used in generational GC mode
            break;
        }
        int result = lua_gc(L, LUA_GCSTEP);
        if (result == 1) {
            break;
        }
    }
}

That said, the actual behavior remains configurable (see the config.h file), but the policy of choice is:

Lua’s GC is stopped immediately, in order to disable automatic and uncontrolled garbage-collection triggers.
The incremental garbage-collection mode is explicitly selected.
A full cycle LUA_GCSTEP (see above) is executed during the low-priority update step.

A nice additional feature is that, when compiled with TOFU_INTERPRETER_GC_MODE set to GC_MODE_CONTINUOUS, the game engine automatically checks the state of the garbage collector and performs a LUA_GCSTEP only when the GC is stopped. This makes it possible, if needed, to switch back to an “automatic” mode at run time with minimal effort, without the engine continuing to drive the collection explicitly.

Finally, a useful byproduct of this work has been a refinement of the run-time debug information related to heap usage. The internal period counter was slightly off, and the VM memory usage was not being tracked accurately (nor was it accessible from Lua). These issues have now been cleaned up, and System.heap() correctly reports both system and VM memory consumption.

( I’m also considering to add a graphical overlay to report the current performance information )

This naturally led to a further consideration: when dealing with time-varying metrics, it is often useful to apply a moving average… but which variant should one choose? Let’s explore that in a future post! :)

Reworked Image Loading

Sun, 21 Sep 2025 00:00:00 +0000

A crucial concept behind the design of Tofu Engine is the idea of using palettized graphics. All image assets are PNG images, which are a popular choice for many other engines due to their lossless nature and wide support across graphics tools.

During the loading process, an image is automatically converted from its original format (e.g. 32-bit ARGB). A reference palette (with a variable size of up to 256 colours) is used, and the best matching colour is computed for each pixel and stored into an 8-bit-per-pixel buffer. The value of each pixel in this buffer is an index to a palette entry (also known as a CLUT, or colour look-up table).

Sounds simple enough, right? In practice, it’s that simple, and the initial implementation of the engine loading routine was as follows:

1) Load the PNG image into a 32-bit, WxH-sized buffer (A). 2) Allocate an 8-bit-per-pixel buffer B of size WxH. 3) For every pixel in buffer A, find the best matching colour in the palette and store it in buffer B. 4) Free buffer A.

With the help of some support libraries (namely, stb) this was an easy feat. However, there were some issues:

The full ARGB buffer is loaded only to be released almost immediately. This is a wasteful use of the heap that should be avoided.
It was also slow. This isn’t something one would notice at first since the assets of a 2D pixel art engine are usually quite small. However, when loading larger images, the conversion wasn’t as fast as one would hope.

The second issue can easily be solved using memoization: for each ARGB colour, the best matching colour only needs to be found and stored in a hash table once. Subsequent occurrences will skip the lengthy computation and simply use the cached value. For example, loading an 800x800 image took ~0.5 seconds; with memoization, this time was reduced to ~0.1 seconds. That’s quite an improvement!

Solving the first issue, however, is a different matter.

Ideally, the fastest loading time would be achieved if the original image were already in a palette-based format, as it could be loaded straight into the final buffer without any intermediate processes. However, this would contradict a fundamental design choice we made when designing the game engine: the reference palette is controlled by the script and shouldn’t be fixed.

We can, however, reach a compromise by mean of progressive loading of the PNG image. By loading it row-by-row and converting each scanline on the fly we would require only an additional buffer for the row. To accomplish this we switch to spng.

We adapted the engine code, moving all the image loading routines to an internal module called image and generalising the API to be callback-driven. This allowed us to achieve our objective of not affecting loading times (we are totally on par with the previous “non-progressive” implementation), while using only a fraction of the memory.

We also added miniz as a library, offering a ZLIB-grade stream compressor that we can use for other features in the future. Also, reworking the API gave us the opportunity to refactor it, making it far more generic and abstract (thanks to the loading callbacks).

I guess we should be satisfied with our results, as we can’t do any better without failing our design choices.

Or no? :)

Multimedia Backend Shenanigans

Sun, 27 Apr 2025 00:00:00 +0000

When I started working on Tofu Engine (way before its name was decided… and even before I had my first dog who, coincidentally, is also named Tofu) the first decision I made was that it had to be multi-platform.

Beyond more or less debatable personal choices on the technology stack (indeed, it would make sense to write a post describing it a little more in detail, with a nice description of the architecture), in order to make a game-engine work on different platforms (although now, much more than in the past, they significantly resemble each other) one fundamental problem must be solved: how to manage the multimedia compartment in a uniform way.

Because… well… in layman terms, all a video game down in its core has to do is:

receive inputs from the user,
display images, and
play sounds.

( and, of course, another ton of things :D )

If we were only to code on Windows (or derivative systems, such as the Xbox), we would natively have at our disposal Direct-X which, despite its age (it is now almost thirty years old) and above any criticism, absolves these three functions excellently and uniformly. Once you come to terms with DCOM and its idiosyncrasies, there is no need for any additional third-party components, as everything have already been included in the operating system itself since Windows 95-OSR2.

But, needless to say, it would have been too simple to just support Windows, with its huge market share in gaming. We also want to support Linux¹. And maybe some ARM architecture like the one running Raspberry and Ambernic devices. Or Android devices! And why not WebAssembly to have games our running into a web-browser?

( yes, for the moment that’s all the support macOS is getting :D )

Luckily, we do not have to work like hell and write a distinct and different multimedia support for each of the target platforms. There are valid third-party libraries that allow us to relieve ourselves of this task.

Initially, I chose to rely on SFML. At that early stage, I took it for granted that I wanted to use C++ for writing code, and this library seemed the most appropriate. When I had discarded C++ in favour of C99 (the reason why I did this is a topic for another post) I also moved to Raylib to have as quick as possible a proof-of-concept of what later became Tofu Engine. A while later, I finally settled to GFLW which is still in use today.

( If you are curious to read some of the details of this initial phase of development of the Tofu Engine, I suggest you read this post ).

GLFW is an amazing piece of software, and fulfils its task really well… however, over the the past year and a half I have grew increasingly uncomfortable. I began to question my initial choice of using GLFW as I observed that the library support from the authors (and contributors) was becoming increasingly slower and scarce at the point that the latest (minor) update dates more than one year ago. Which is not necessarily an issue when a project is stable and feature complete… but in the case of GLFW there is a conspicuous number of flaws awaiting resolution, and many missing features that I begin to fear will never see the light of day.

I held on for a long time, fighting my urge to find a solutions to this. Few things are worse that realizing you can’t trust the tech on top of which you have build your game-engine. It’s an obsession of mine to keep libraries always up-to-date so I forced myself to ignore that little voice inside me that kept complaining about it… until one day….

… on 21 January 2025, after a very long wait, SDL3 was released.

I initially had chosen not to use SDL because it seemed a bit (too much?) overabundant in the amount of features (and APIs) offered. I feared to bloat my codebase too much… and a tiny part of me didn’t want to be spoiled that much, as I didn’t want to deprive myself completely of the fun of reinventing the wheel! :D

( just kidding… sort of… :P )

Anyhow, SDL3 just seems way too interesting to be ignored, in particular:

it is written with full C99 support in mind, thing that not even GLFW does (I’m not proud of this, but I had to resort to a few tweaks to its code to selectively “silence” some of the more pedantic warnings that I personally enable by default and treat as blocking errors);
it has a far better gamepad support than ANY OTHER library (especially on Linux). I realised when I was working to the source code of another backend (RGFW) with the idea of extending it. Taking GLFW as a reference, I noticed that the gamepad support on Linux is really very (but very) primitive compared to SDL’s which is Steam-compliant.
it has native support for the always-up-to-date database of gamepad definitions. Also GLFW support it, but only at a very basic level without really taking into account the exceptions represented by special input devices (such as those on consoles);
it has full support for haptic feedback, the lack of which I have complained about before;
it is supported by Emscripten, which would comfortably open the door to WebAssembly and to browsers support;

But, above all, the fact that it is used by a huge number of commercial products makes us safe from the possibility of unexpected flaws and lack of continued and future support.

So… well, all that’s left to do is to start reworking the innermost part of the game-engine code and perform a delicate surgery. The doubts are still many (how complicated will it be to include and compile the code of SDL3 so as not to have external dependencies? Will it be possible to exclude certain “sub-modules” of the library?)…

… but it will definitely be a lot of fun. :)

Actually, I have always considered of primary importance supporting Linux. Nowadays, Linux is a more interesting and stimulating reality from the gaming point of view. Thanks to Valve’s SteamDeck the interest to the idea of Gaming-on-Linux (for the past three years) has shifted and attracted a lot of attention. ↩

Game Engine Sandboxing

Fri, 28 Feb 2025 00:00:00 +0000

A game engine is much like an operating systems. Or, better, a (virtual) guest machine running inside a (physical) host machine.

This has been true since pretty much the very beginning of game-development and we could trace even in the ’80s game in which the it’s core was reusable (and reused) more than once. Z-Machine and SCUMM have been a forerunners on the topic (and, personally, one if not the single reason I wanted to learn how to code games in the first place… so, shame on them! :D).

However, it was with DooM that the concept of a reusable game-engine could be said to have spread on a large scale (in addition to the concept of WAD files, another “passion” of mine in those years).

With appropriate tools and means, anyone was given the opportunity to modify the basic logic of the game at will and even change it almost radically. In the vast majority of cases, there was a DSL in the way, suitably constructed to fit like a glove.

Among the fundamental characteristics of the host machines of that time was that they were (1) isolated from other computers (we were still a long way from today’s state in which every electronic device is potentially continuously connected to a network) and (2) strictly single-user. Security problems, therefore, were not many… except for a few sporadic computer viruses that caused a sensation, spreading like a cold by exchanging infected disks (I remember the first experiences with boot sector viruses in the Amiga, like SCA Virus and Byte Bandit).

For this reason, all things considered, it is not surprising that for a long time, in the context of game-engines, very few were ever interested in the possible related security problems.

However, with the advent of general purpose scripting languages such as Lua, a little more care is required: what is known as sandboxing should be implemented, i.e. the idea of providing the user (in this case the programmer) with a controlled environment isolated from the host so that the integrity of the latter is guaranteed in any case.

For Tofu Engine this was achieved gradually and naturally.

The first step concerns an appropriate access management for the file system. To this end, we set about writing an abstraction library which (among other things) completely inhibits the use of absolute paths. In the case of Lua’s virtual machine, this also meant defining a custom reader and searcher (used for the resolution of the require() instruction). More specifically, we had to redefine the default Lua behaviour:

// Lua default searchers are stored as four entries in the `package.searchers` table, as follows:
//
//   - a searcher that looks for a loader in the `package.preload` table,
//   - a searcher that looks for a loader as a Lua library,
//   - a searcher that looks for a loader as a C library,
//   - a searcher that looks for an all-in-one, combined, loader.
//
// The function modifies the table by clearing table entries #3 and #4. The first one is kept (to enable module
// reuse), and the second one is overwritten with the given `searcher`.
//
// As a result the module loading process is confined to the custom searcher only.
//
// See: https://www.lua.org/manual/5.4/manual.html#pdf-package.searchers
void luaX_overridesearchers(lua_State *L, lua_CFunction searcher, int nup)
{
    lua_getglobal(L, "package");        // A ... A -> A ... A T
    lua_getfield(L, -1, "searchers");   // A ... A T -> A ... A T T

    // Move the `searchers` and `package` tables *before* the upvalues so we can "close" them into
    // a function-closure. Then use the closure to override the 2nd searcher (keeping the "preloaded" helper).
    lua_insert(L, -(nup + 2));          // A ... A T T -> T A ... A T
    lua_insert(L, -(nup + 2));          // T A ... A T -> T T A ... A
    lua_pushcclosure(L, searcher, nup); // T T A ... A -> T T F
    lua_rawseti(L, -2, 2);              // T T F -> T T

    // Discard the others (two) searchers.
    lua_pushnil(L);
    lua_rawseti(L, -2, 3); // package.searchers[3] = nil
    lua_pushnil(L);
    lua_rawseti(L, -2, 4); // package.searchers[4] = nil

    lua_pop(L, 2); // Pop the `package` and `searchers` table.

    // Upvalues have already been consumed by `lua_pushcclosure()`. No need to clear the stack.
}

The second fundamental aspect concerns the functions (Lua) leaves available to the programmer. As already mentioned, since Lua is a general-purpose language, it also makes available APIs that are potentially dangerous (among all those relating to file-system access) and definitely not suitable in the context of a sandboxed game-engine we long to.

When implementing the FFI interfacing module (called LuaX in the context of my game-engine), I initially simply made a clone of the luaL_openlibs() function:

void luaX_openlibs(lua_State *L)
{
    static const luaL_Reg libraries[] = {
        { LUA_GNAME, luaopen_base },
        { LUA_LOADLIBNAME, luaopen_package },
        { LUA_COLIBNAME, luaopen_coroutine },
        { LUA_TABLIBNAME, luaopen_table },
#if !defined(LUAX_NO_SYSTEM_LIBRARIES)
        // System libraries can be disabled to have a proper "sandbox" environment.
        { LUA_IOLIBNAME, luaopen_io },
        { LUA_OSLIBNAME, luaopen_os },
#endif  /* LUAX_NO_SYSTEM_LIBRARIES */
        { LUA_STRLIBNAME, luaopen_string },
        { LUA_MATHLIBNAME, luaopen_math },
        { LUA_UTF8LIBNAME, luaopen_utf8 },
#if defined(DEBUG)
        // Debug module is loaded only for the `DEBUG` build, of course.
        { LUA_DBLIBNAME, luaopen_debug },
#endif  /* DEBUG */
        { NULL, NULL }
    };
    for (const luaL_Reg *library = libraries; library->func; ++library) {
        luaL_requiref(L, library->name, library->func, 1);
        lua_pop(L, 1); // Remove the library (table) from the stack.
    }
}

The idea of replicating an existing function, although not optimal, seemed decent to me. In fact, for quite a while I continued to use it without any problems. Or any doubts it would be “enough”.

Little by little, however, I realised that this approach was not the best possible: while the io library was certainly to be avoided at all costs, parts of the os and debug libraries might guarantee better reuse of existing code. Specifically, I realised this when trying out a famous profiling module.

Hence the idea to look into the matter. Almost by chance, at some point, I came across the description of how Luau implements sandboxing. So, why not take a cue from those who have already made considerations in this regard, not least because of the enormous diffusion of the language itself and its use in a context where security is mandated (i.e. Roblox)?

Consequently, instead of making a “personal variant” of the luaL_openlibs() function, I opted to directly modify the code of the Lua implementation included in the game-engine, making the following changes:

the io. library has been removed in its entirety;
in the os. library the only supported functions are clock, date, difftime, and time;
the debug. library has stripped down almost completely with only the getinfo, sethook, and traceback functions available;
the package. library, as well, has been removed trimmed down a bit (in Luau it has been removed entirely) leaving only the require function and the searcher table-index available;
the dofile, loadfile and collectgarbage Lua standard functions have been removed.

Unlike in Luau, however, no changes have been made to support for pre-compiled sources (i.e., included in pre-compiled P-code format). These can be included without any problems as generated by luac since the programmer is given “full confidence” to include lawful code within the game he is making.

Although I don’t particularly like making changes to the libraries I use, it is something I have occasionally found myself having to do in the course of a project (if only to resolve compilation warnings). In principle, therefore, I find this kind of approach tolerable given the (fundamental) objective of having a system as sandboxed as possible.

After all, the fact that Lua’s codebase changes very rarely helps us in this endeavour. :)

A Case for Lua Performance

Sat, 14 Dec 2024 00:00:00 +0000

When using an embedded scripting language in a game-engine (or in any other real-time operating software) one should always take into account performances.

Even in the case of a JIT interpreter, scripted code more often that not loses when compared to native code (e.g. resulting from compiled C99 code). This is not only due to the fact that P-code can’t be faster than executing machine code, but also because of the different impact the data structure and memory usage have on the CPU.

As a rule-of-a-thumb, common sense suggest that complex algorithms should be implemented natively. Python, for example, proves this on daily basis with OpenCV: one can dismiss the language as “slow” (which is not, anyway), but the OpenCV library runs as native code and offers near real-time performances.

There are, however, other cases where it’s a tad more difficult to draw the line between what should be left on scripting side and what should be implemented as natively.

Important notice: I’ll be considering only the reference (PUC) Lua 5.4.7 release in the following. Neither Luajit or Luau will be taken into account.

A vector class

Any self-respecting game-engine almost certainly feature an abstraction of the (either 2D or 3D) vector concept. In the case of Tofu Engine this is a strictly a two-dimensional vector, implemented as a class, with an idiomatic form of this type.

local Vector = {}

Vector.__index = Vector

function Vector.new(x, y)
  local self = setmetatable({}, Vector)
  self.x = x
  self.y = y
  return self
end

-- Methods will be added here...

return Vector

Actually, in Tofu Engine there is an easier way to implement a class (i.e. via the class.lua module), but the substance does not change.

As a direct consequence every instance of the Vector class will be a Lua table. Let’s just keep this in mind and add some more methods.

local Vector = {}

Vector.__index = Vector

function Vector.new(x, y)
  local self = setmetatable({}, Vector)
  self.x = x
  self.y = y
  return self
end

function Vector:add(v)
  self.x, self.y = self.x + v.x, self.y + v.y
end

function Vector:dot(v)
  return self.x * v.x + self.y * v.y
end

function Vector:magnitude(v)
  local x, y = self.x, self.y -- Well know Lua tip! Use local variables to save table accesses!
  local m = x * x + y * y
  if m == 0.0 then
    return 0.0
  end
  return m ^ 0.5 -- Tip! Avoid FFI call to `math.sqrt()`!
end

function Vector:normalize(v)
  local m = self:magnitude()
  if m == 0.0 then
    return
  end
  self.x, self.y = x / m, y / m
end

function Vector:angle_to(v)
  return math.atan(v.y - self.y, v.x - self.x)
end

-- More methods would follow here...

return Vector

We have added only five methods, as they sum up pretty well three method categories of increasing computational impact:

two methods that perform simple operations using only Lua code (add() and dot()),
two more complex Lua-code-only methods (magnitude and normalize(), exploiting the equivalence sqrt(x) == pow(x, 0.5)),
a simple method that relies on an FFI function (angle_to()).

Taking a look at the full implementation straight from the game-engine shows that, in principle, all methods fall into one of these categories.

Finding the costs

It well known that « premature optimization is the root of all evil ». We simply can’t proceed and blindly optimize without proper data.

A simple (but effective) way evaluate the cost of a piece of code is to run it a given number of times and measure the time it took (also on average, if we are interested in that). In Lua, this can be achieved with a helper function.

-- `closure` (function) :- the function closure we want to profile
-- `tag` (string) :- string identifier used for debug
-- `rounds` (number) :- amount of iterations the function will be evaluated
-- `baseline` (number, optional) :- baseline value subtracted from the final result
local function profile(closure, tag, rounds, baseline)
  local s = os.clock()
  for _ = 1, rounds do
    closure()
  end
  local e = os.clock()
  local elapsed = (e - s) - (baseline or 0.0)
  print(string.format("`%s` took `%.3f` seconds", tag, elapsed))
  return elapsed
end

For example, we will use if as follows.

local ROUNDS <const> = 1000000

local a = Vector.new(0, 1)
local b = Vector.new(2, 3)

profile(function() a:add(b) end, "vector:add()", ROUNDS)

One may notice that there’s an additional cost in handling a closure call. However, with a sufficiently big amount of iterations the overhead will be dampened and won’t be that significant. Moreover, as long we profile everything in the same way we are good.

Most importantly, ‘though, we can measure the baseline of a nop() function. This will let us determine the (almost) exact amount of time spent due to the profiling overhead.

Let’s measure!

Now that we have a convenient way to profile our code, we can apply changes to Vector class and implement natively some existing methods. We need to mimics in C99 what we are doing in Lua. For example, the Vector:add() method is implemented in Lua as follows:

function Vector:add(v)
  self.x, self.y = self.x + v.x, self.y + v.y
end

which corresponds to the following P-code:

function <src/kernal/tofu/util/vector.lua:141,143> (11 instructions at 0x6187e71872a0)
params, 5 slots, 0 upvalues, 2 locals, 2 constants, 0 functions
[142]	GETFIELD 	2 0 0	; "x"
[142]	GETFIELD 	3 1 0	; "x"
[142]	ADD      	2 2 3
[142]	MMBIN    	2 3 6	; __add
[142]	GETFIELD 	3 0 1	; "y"
[142]	GETFIELD 	4 1 1	; "y"
[142]	ADD      	3 3 4
[142]	MMBIN    	3 4 6	; __add
[142]	SETFIELD 	0 1 3	; "y"
[142]	SETFIELD 	0 0 2	; "x"
[143]	RETURN0

and is natively implemented like this:

// I'm adopting a naming convention for the native Lua-exposed functions,
// and in general for the implementation, so bear with me if this seems a
// bit too verbose. :)
static int vector_add_native_2oo_0(lua_State *L)
{
    LUAX_SIGNATURE_BEGIN(L)
        LUAX_SIGNATURE_REQUIRED(LUA_TLOBJECT)
        LUAX_SIGNATURE_REQUIRED(LUA_TLOBJECT)
    LUAX_SIGNATURE_END

    lua_getfield(L, 1, "x");
    lua_getfield(L, 1, "y");
    lua_getfield(L, 2, "x");
    lua_getfield(L, 2, "y");

    float x0 = LUAX_NUMBER(L, -4);
    float y0 = LUAX_NUMBER(L, -3);
    float x1 = LUAX_NUMBER(L, -2);
    float y1 = LUAX_NUMBER(L, -1);

    lua_pop(L, 4);

    lua_pushnumber(L, x0 + x1);
    lua_pushnumber(L, y0 + y1);

    lua_setfield(L, 1, "y");
    lua_setfield(L, 1, "x");

    return 0;
}

The LUAX_ macros above are part of a custom-made Lua-to-C bridge module. It should be intuitively clear enough the sense of them, ‘though.

In a similar fashion I wrote native implementations for the magnitude, add, dot, normalize, and angle_to methods. Profiling the methods over 10000000 rounds the following results have been obtained:

Method	Lua (d)	LuaO (d)	LuaC (d)	Lua (r)	LuaO (r)	LuaC (r)	gF/sF	f(x)
magnitude	2.918	2.697	2.814	1.170	1.142	0.670	2	1
add	2.336	2.038	5.375	0.738	0.741	1.343	6	0
dot	1.863	1.792	4.340	0.621	0.631	1.043	4	0
normalize	5.930	5.710	4.523	1.959	1.874	1.023	2+2	1
angle_to	3.415	3.124	4.539	1.676	1.193	1.345	4	1

In the table above, Lua refers to the plain Lua Vector implementation, and LuaC to the one with the methods above implemented in native code. LuaO indicates a slightly optimized Lua implementation where

library functions are cached/accessed through local references (e.g. math.atan() assigned locally as local atan = math.atan), and
math.sqrt(x) have been replaced with x ^ 0.5 to save a FFI boundary function-call (in favor of the POWK P-code instruction).

Within parentheses the d indicates the DEBUG build (with additional signature checks in the C99 methods), and r the RELEASE one (with full compiler optimizations are enabled).

In the last two columns gF/sF reports the amount of lua_getfield() and lua_setfield() call required, and f(x) the number of external function calls (such as sqrt() and atan2()) present.

As a final notice, results are stripped of the baseline overhead: this is crucial for a better analysis.

Can we do better?

Yes, of course! We can implement the whole vector class as a native UDT (and leave to Lua only some minor embellishment methods).

The results are astonishing when compared to the (optimized) Lua implementation.

Method	LuaO (d)	C99 (d)	LuaO (r)	C99 (r)
new	20.419	4.223	7.501	2.239
magnitude	2.697	1.081	1.142	0.168
add	2.038	1.773	0.741	0.215
dot	1.792	1.738	0.631	0.253
normalize	5.710	2.074	1.874	0.270
angle_to	3.124	1.707	1.193	0.264

Even the vector object creation is (way) faster in the full-native C99 implementation, which is coherent with the fact that it vector class is not modelled with a Lua table.

This reminds us that the creation of an object is expensive (in general), and Lua makes no exception. It is advisable to recycle and reuse instances as much as possible when they are no longer needed, rather than always creating new ones. This concept is called object pooling and is one of the cornerstones in optimizing realtime systems (such as a video game).

Basing on the results above, we can draw some final observations:

Compiler optimizations do matter – as expected, the release build is significantly faster than the debug one, running on average almost twice as fast.
Optimize you Lua code – the Lua code runs marginally faster with the above optimization changes, and they are worth be taken into account.
Plain Lua wins – in all cases except one the Lua implementation isn’t the worst performing one, both in the debug ang release builds (with only two exceptional cases).
Accessing tables is a bottleneck – this is not a surprise, but the major setback when implementing the methods in native C99 code is that the lua_getfield() and lua_setfield() calls (used to access the vector data, implemented as a Lua table) significantly impacts performances. At the same time, the Lua VM does an amazing job in accessing tables, and the plain Lua implementation as no such issue. This is evident by comparing the add() and dot() methods, with the C99 code significantly slower as the to field access calls grow (way more than the plain Lua code).
Calling functions cost – Methods requiring complex mathematical functions have inherent performance penalties, and this is clear by comparing the dot() and magnitude() methods (identical, minus sqrt() call).

Epilogue

This concludes our brief (but hopefully interesting) journey into the world of optimization as it relates to the implementation of a pseudo-native UDT.

It was an opportunity to look in a little more detail at some aspects of Lua’s FFI API, and in particular to understand that some operations can hide unexpected complexities that impact performance. As is often the case, then, the choice of how to model a data type significantly affects the final performance.

Before leaving, however, we can take a chance to answer a final question: « How do I decide whether to keep an algorithm implementation in Lua or convert it to a native implementation? »

Essentially we can base our decision it in three points:

if the data structures are Lua-native, e.g. with extensive use of tables, it is better to stay within the Lua code (since table access via FFI is intrinsically slow). The performance gain offered by selective implementation of native methods is (on average) not significant enough to motivate the additional complexity.
if one still wants (or needs) to make a call to a native function, don’t pass tables as formal arguments but unpack the values as separate arguments for the native call.
if performance is an absolute priority, implementing the entire class in native code (or at least the most significant portion of the UDT) is a mandatory requirement.

That’s all for now. See ya next. :)

Going Mobile

Fri, 12 Apr 2024 00:00:00 +0000

The other day I came across the Anbernic RG35XX+, which I have to admit I had never heard of before (I’m not really into retro gaming, to be honest).

I’ve always been curious about mobile gaming… and I’m not talking about the kind that’s all the rage these days with the ubiquitous use of smartphones. I’m talking about the old-fashioned kind, where the gamer picks up a real console with the sole purpose of entertaining him/her.

The machine has more than its fair share of features: a quad-core 1.5GHz ARM 64-bit CPU, paired with an OpenGL/ES capable dual-core GPU, running on a 3.5-inch 640x480 display. Directional pad, buttons, and a Linux-derived operating system complete the picture.

What if I want to run Tofu Engine on it?

Oh… I need to buy one of those thingamabobs, first… and done! While waiting for it to arrive, I can tackle the first aspect: cross-compile to ARM.

From the beginning, I worked with the idea that Linux should be the one and only development/build environment for Tofu Engine. With little or no effort (thanks to GCC and MinGW) I managed to get both the Linux and Windows builds on the same development machine (or docker container). I have also tested the (interactive) build on a Raspberry Pi device and it executes flawlessly; it required a Pi4 device for this purpose, however.

I was aware that GCC is more than capable of cross-compiling to ARM. All that was needed was the “recipe” to make it work. In a word, multiarch. Taking advantage of this feature, I installed the arm64 and armhf (for the 64-bit and 32-bit ARM builds respectively) library dependencies and build tools… and with a bit of Makefile-fu… ta-da!

This also proved to be a good opportunity to reorganise the Makefile and unify the Raspberry Pi build with the RG55XX one (as they are both ARM based)… and lo and behold, it works on both Raspberry Pi 4 and 5! :D

Having reached this point, however, another problem becomes apparent to me: would the currently used OpenGL version (which is fixed at version 2.1 for simplicity’s sake) work on the RG35XX+ w/ GarlicOS.

According to the specifications of the Allwinner H700 chipset (the beating heart of the RG35XX+), the ARM Mali G31 GPU supports OpenGL ES 3.2 (and Vulkan 1.1, but I will not even explore this unknown territory for the moment).

I admit that the difference between OpenGL and OpenGL/ES is only clear to me from a conceptual point of view, so my current goal is to study the two variants closely and (hopefully) find a common point of contact.

It is also an opportunity to review and improve the integration with OpenGL in general, in anticipation of a (possible) future move to more intensive use of the GPU.

See you soon. :)

Back on Track

Thu, 21 Dec 2023 00:00:00 +0000

The end of the year is just around the corner…

… and we are actually a little behind on devlogs. Once again. As usual.

I wish I could say that I’ve neglected the blog because I’ve been concentrating so much on Tofu Engine that I couldn’t find the time to do it, but the harsh reality is different. That is, I have had other projects/commitments that sucked up my time and energy.

Nevertheless, I can see a glimmer of light on the horizon, having hopes (as well as a very strong urge and determination) to be able to devote some time and get my game engine back on track.

In the past days I resumed working on it. Not with the lengthy full-night sessions I was accustomed with, but it’s still something.

I tackled down what I do periodically to “jumpstart” my activities on the project, that is I have updated the engine’s dependencies. As I have said and reiterated several times, Tofu Engine was born with the idea of having (almost) no run-time dependencies. However, it does use other libraries (and it should) which I take care to keep as up-to-date as possible. In fact, if there’s one thing I can’t stand, it’s projects where dependencies are neglected… not keeping them up-to-date, in the long run, can cause quite a few problems. Please, fellows developers, keep your dependencies up to date! =D

I also took the opportunity to ponder on whether the libraries I had chosen at the time are still the ideal option. I must say that, in principle, I would make the same choice again even today. I do, however, want to make a few remarks on some of them.

For a short time, I feared that GLFW was about to fade away as a project. From both the website and the main channels, there were no updates and development seemed to be halted. A few pull-requests from contributors were crowding in, but without being integrated into the main code. Thankfully, however, the situation now seems to have improved and work is continuing (I must say also consistently, because it is rapidly approaching the long-awaited new release). In any case, for use in the game-engine what is now possible remains more than sufficient (with the exception of the input source management part, where I would particularly like to see support for force-feedback and gamepad rumble integrated).

In a similar vein, Chipmunk2D is in doubt as to whether or not to maintain it in the long term. Developments are at a standstill, considering that the library is stable and well established. However, Eric Catto, author of box2d, has been working for some time on a C99-compliant version of his famous middleware (which is currently written in C++). I plan to try to integrate it very soon.

Other than that, the first and most immediate objective will be to make the product (finally?) usable by the community. The official documentation absolutely must be completed (in many ways… from technical description, to examples/tutorials, to API documentation)! :P To this end, I intend to elaborate a bit on the project “presentation” so as to make request (veiled or not) for help from external contributors.

Obviously, then, there are features to be added (quite a few) that I have been taking notes on over the past few months… and others that could potentially be refined, simplified or even (why not) eliminated because they are overabundant.

On the sidelines, I want to revisit some of the more intimate details of the engine. Without radically revamping the API (hopefully without modifying it in any way) I intend to rework the rendering sub-system, in order to optimize it and make it more sensitive toward power consumption.

In short, there is a lot of work to be done. :D

Let’s get started!

Function Arguments Passing

Fri, 15 Sep 2023 00:00:00 +0000

Picture yourself working at your desk, tinkering on the design of some of the internals of your game engine (as I wrote in the previous devlog post), toward a significant redesign of the game-engine core.

That’s a lot of work, and you should try and focus as much as possible and limit yourself to what’s strictly related to what’s required.

But, alas, you already know from the very beginning that’s not going to happen and you’ll find some other interesting topic to let your mind wander about…

… and, of course, this time I’m making no exception to this by tinkering about arguments passing.

The Current Way

Since its inception, I invested a significant portion of time in making the game-engine scripting core efficient, elegant and clear to use. One feature I sought to implement it’s a reasonably performant function overloading as it was something I liked a lot in Wren, which I was using when I was developing Tofu Engine. Lua doesn’t support overloading straight out-of-the-box (as in C++ or Java, for example) but can be implemented with some minor effort by leveraging the fact that arguments can be optional (they are set to nil when missing from the actual arguments list).

Let’s see and basic example and write a hypothetical function in Lua that writes some text on screen leveraging another (internal and low-level) function:

local _default_color = { 255, 255, 255 }

function draw_text(x, y, message, color)
  local actual_color = color or _default_color -- This is the Lua idiomatic for the C ternary operator.
  _draw_text_internal(x, y, message, actual_color)
end

We are using the “missing arguments are nil” feature to handle the case when color is not provided… but we can achieve the same result using overloading by arity

local _default_color = { 255, 255, 255 }

function draw_text(...)
  local args = { ... }
  if #args == 3 then
    _draw_text_internal(args[1], args[2], args[3], actual_color)
  elseif #args == 4 then
    _draw_text_internal(args[1], args[2], args[3], args[4])
  end
end

In this case, we are differentiating the behaviour by checking the number of actual arguments (i.e. the function arity). It might appear to be more “redundant” and less clever as an approach but, in fact, is much more manageable in the long run as the resulting code is less convoluted and easier to read.

There are occasions, however, when we just can’t limit ourselves to using the arity to obtain different/specific behaviours, but we need to take into account also the type of the arguments. Let’s refer to this as overloading by type. An example of this is if we want to write a vec2:add(...) method that adds both a vector or a scalar to another vector. Since we have the same amount of arguments in the signature arity is not a sufficient discriminator, so we need to check the type of the actual argument to perform the correct operation:

function vec2:add(self, vector_or_scalar)
  if type(vector_or_scalar) == 'number' then
    return vec2.new(self.x + vector_or_scalar, self.y + vector_or_scalar)
  else
    return vec2.new(self.x + vector_or_scalar.x, self.y + vector_or_scalar.y)
  end
end

We could go even further and combine both approaches (I’ll leave that as an example for the reader :-P) making things more and more complex (and hairier).

I’m not suggesting that function overloading is the suggested way to write code. Quite the contrary, I’m an advocate of “descriptive code”. I favour using clear and explicit names for functions/methods, describing explicitly what they do rather than leveraging intuition. For example, I’d rather write separate vec2:add_scalar() and vec2:add_vector() methods, as they don’t require that additional boilerplate “dispatching” code which hinders performances (when we are using interpreted languages, as in compiled languages the overloading is resolved at compile-time) and artificially increases the code complexity. However, there are occasions where a well thought and placed overloaded function/method makes the code better (see, for example, the first example).

One thing I’m proud of is the relatively simple but clever and efficient way I implemented overloading-by-arity in Tofu Engine, with straight Lua C FFI API. With a sprinkle of ATL-inspired (who remembers it’s way to define and implement window-messages handling?) macro usage, the specific sub-function dispatch is called according to the actual number of arguments.

// Overloaded constructor for the `Bank` object. Dispatch is based upon
// only on the number of actual arguments.
//
// See `src/modules/bank.c`.
static int bank_new_v_1o(lua_State *L)
{
    LUAX_OVERLOAD_BEGIN(L)
        LUAX_OVERLOAD_ARITY(1, bank_new_1o_1o)
        LUAX_OVERLOAD_ARITY(2, bank_new_2os_1o)
        LUAX_OVERLOAD_ARITY(3, bank_new_3onn_1o)
    LUAX_OVERLOAD_END
}

An extension to this is the implementation of overloading-by-type.

// Overloaded constructor for the `Font` object. We are using a combination of
// the amount of actual arguments and their types. Please not how the type-based
// overloading check is done first, as the same arity-based check would trap it
// erroneously.
//
// See `src/modules/font.c`.
static int font_new_v_1o(lua_State *L)
{
    LUAX_OVERLOAD_BEGIN(L)
        LUAX_OVERLOAD_ARITY(2, font_new_3osS_1o)
        LUAX_OVERLOAD_SIGNATURE(font_new_4onnS_1o, LUA_TOBJECT, LUA_TNUMBER, LUA_TNUMBER)
        LUAX_OVERLOAD_ARITY(3, font_new_3osS_1o)
        LUAX_OVERLOAD_ARITY(4, font_new_4onnS_1o)
    LUAX_OVERLOAD_END
}

By having a look on how overloading is implemented one can guess that this second approach is slower than the first. This is correct, as the LUAX_OVERLOAD_SIGNATURE check is far more complex than LUAX_OVERLOAD_ARITY. Anyhow, when used in seldom-called functions/methods (like, for example, object constructors), this can give some benefits without significantly impacting the overall performance.

A Third Way?

It seems like we are acceptably satisfied with the results, so far. Why should we search for another way?

Well… because there can be cases where both arity- and type-based overloading are not enough. That’s the case, for example, when we have two different overloads of the same function with the same signature.

Back to the disclaimer I made above, I don’t think we should necessarily insist on overloading at this point. Probably a separate, specific, method/function would be preferable. However, we are mostly speculating here… and it’s always worth doing it! :)

I’m not particularly fond of Python but I like it’s name arguments feature. Arguments can be optional, too, and this opens the road to some quality seamless code… for example in Python’s requests module: when transmitting data we don’t have separate post_json() and post_bytes methods, but a single post(json=None, bytes=None) that applied a distinct behaviour according to the actual provided (named) arguments.

Is something like this possible in Lua?

Well… sort of. We just need to use *tables as arguments.

The idea is as simple as the name implies: we move the arguments’ whole list and pack it into a table. Then we pass it as the sole argument for the function/method call.

Easy peasy! :)

Let’s see a basic example, by rewriting the draw_text() function above mentioned

function draw_text(args)
  _draw_text_internal(args.x, args.y, args.message, args.color or _default_color)
end

which we would call as follows

draw_text({ x = 0, y = 0, message = "Hello, World!", { 0, 255, 0 } })

It’s definitely not rocket science, and it doesn’t seem like a huge improvement, but it’s an approach that gives a more clear and more open approach to extendibility. We can add new arguments and use them to discriminate the function behaviour accordingly, even when they are of the same type, just like in Python thanks to the named arguments feature. Also, we don’t have to stick to a rigid argument order and – overall – the code is more self-documenting. Moreover, unless we did otherwise on purpose, API backward compatibility is easier to implement.

That’s an interesting bunch of silver linings. Are there any black clouds? Yes, of course, and unfortunately they are pretty annoying!

First and foremost, the inner implementation of the functions/methods can quickly become intricate. We need to test the size of the table, the presence of some fields, and maybe their type (in a similar fashion as we did in the initial arity/type overloading examples). It’s not something that can be easily generalized and needs to be tailored to the case in order not to write dull/unoptimized code.

Secondly, tables are to be carefully used in Lua. They are the core of the language, deeply optimized in their usage and made as performant as possible… but they waste resources, nonetheless. When used as arguments they can hinder performance a lot. Access times for the table fields tend to be slower (albeit optimizable in plain C code with the FFI API), and creating anonymous tables for each call is expensive (both in space and in time).

For these reasons, they would end in causing bad performances if not properly used.

The Verdict

As usual, there’s no silver bullet. However, we can make some considerations and decide accordingly.

Since we are in the context of a game-engine, our top priority is not wasting resources (mostly CPU but not only) and having as good performance as possible.

I would relegate table-based overloading to less frequently used calls (e.g. class constructors)… but I like consistency while coding, so I would either move all my code to this approach or ditch it for good, despite being more versatile.

All being said, even an eight arguments long signature is not that bad when the codebase reaches maturity and you have a well-documented API! ;-)

( note for my future self: please commit yourself to ending the engine API documentation :-P )

tofu-engine v0.13.0

Mon, 29 May 2023 00:00:00 +0000

Hooray!

An exciting new release of Tofu Engine is now available! You can find the engine code here.

While this release may not be as groundbreaking as some of the previous ones, it is still incredibly important as it signifies the beginning of a new era.

There are two significant reasons for this.

I hinted at the arrival of some major changes in a previous post, which you can find here.

Let’s delve into these changes a bit.

The Rendering System

As you may already know, Tofu Engine currently utilizes a custom software-rendering approach. I take great pride in this achievement as it allowed me to implement algorithms I extensively worked on during the ’90s. Unfortunately, some of this knowledge has become lost over the past two decades. Back in the day, we were all busy crafting mind-bending roto-zoomers, but nowadays, only a select few know what they are and how to implement them. Additionally, this approach enabled me to incorporate unique and specific effects like Mode-7 transformations and Copper-lists.

However, running a software renderer on modern hardware… well, let’s just say it can be far from optimal.

It’s a legitimate choice if one aims to create a virtual retro-machine like pico-8, where the FPS and overall performance are intentionally limited. However, for a general-purpose game engine designed to run on modern hardware and support complex games, it’s not the most sensible choice.

Therefore, over the past year, I’ve been experimenting with reimplementing most of the features in Tofu Engine, leveraging the power of the GPU as much as possible. This involves transitioning back to full OpenGL (or Vulkan) usage, which, at the moment, is only utilized as a cross-platform way to present the framebuffer.

Fortunately, many of the engine’s current features can be reimplemented with minimal changes. Some may require some redesigning (leveraging fragment shaders, if needed), such as the stencil/alpha/tiled blitting and Copper-lists. Others may be permanently removed, like the Mode-7 inspired transformations.

I need to carefully weigh their importance and eliminate what isn’t truly necessary. For instance, the aforementioned Mode-7 transformations may be cool and unique, but it serves little purpose in a real-world scenario and can likely be discarded. On the other hand, certain Copper-list features have practical applications and can be maintained with some minor simplification.

If all goes well, this will results in a much more efficient game-engine, in its utilization of hardware resources. It will also reduce overall power consumption, as running an uncapped software renderer for FPS heavily drains the machine’s power. You notice this when the fans start making some noise!

Let’s hope that all the effort put into this endeavour will prove worthwhile! :)

( and let’s also hope to fix that diamond-rule issue that inspired me to implement a software renderer back in 2019, as I was facing challenges in ensuring pixel-perfect blitting )

Abstraction

When I initially began working on Tofu Engine, my goal was to create a straightforward environment. An easily accessible sandbox with all the essential components ready to be combined.

However, as development progressed, I found it increasingly challenging to restrain myself. I ended up making the engine more and more low-level and generic, which is a tendency of mine, as I prefer creating solutions that are applicable to a wide range of situations rather than specific ones.

This led to something that, to some extent, resembled other game engines (e.g. Löve, which I always cited as an influence), offering a scriptable framework that provides everything one would need to create almost any type of game but without specific assistance for game development.

This is particularly evident in the way the game loop interacts with the game “instance” (let’s refer to its class/object as Main), which involves calling the following methods:

Main.process(): called on each iteration after updating the input state,
Main.update(): called at regular intervals to update the game state, and
Main.render(): called on every iteration to present the graphics to the user.

While this approach is undoubtedly correct, it lacks abstraction of the engine’s internal workings. The scripted code matches almost one-to-one the engine’s one. Where’s the benefit of the abstraction that an engine should grant? It seems like we are coding for a virtual console for which Lua is the native language… :>

Furthermore, there are suboptimal design choices in this approach. For example, the Main.render() method is called on every frame, meaning we frequently cross the C-to-Lua boundary only to subsequently cross back from Lua to C for each drawing operation. It works, but it’s far from efficient.

( well, it does work, nonetheless :D )

Is this really what I envision for my game engine? I must admit that it deviates significantly from my initial idea, and I fear that, in the long run, developers would end up writing excessive boilerplate code even for the simplest tasks.

What’s Next?

As I grapple with this realization, it has become evident that a paradigm shift is necessary at this point. I need to go back to square one and completely rethink this aspect.

I’m currently taking notes and starting the ground-up redesign of these two crucial parts of the engine.

I anticipate that implementation will commence soon.

Probably. :)