12.14.04
GTE and API Design
Well, now that the Fall Quarter is over I have a bit of time to myself, and that means resurrecting the project that is GTE. Since I consider the library to be nearly feature complete, I’ve turned my attention to refactoring the API to make it cleaner and also fixing the warts and bumps that have been introduced during the constant revision process. Even though I’ve just begun, I’ve come to the conclusion that many before me have shared — designing a good API is hard
In the context of GTE this is doubly difficult. Due to the high-performance nature of the project, it is necessary to expose very detailed, implementation-specific data structures and subroutines in order for the user to efficiently manipulate the engine. However, this dramatically increases the severity of the learning curve since, not only does the user need to understand basic tile-based game concepts, but also the peculiarities of this engine’s implementation.
Let me give an example of a change I’ve already made and the thought process that went into its evolution. I welcome feedback, especially from GTE users (all 2 of you?), about the direction I’m taking the API.
Originally, to start up the engine, a GTE_Init() call was issued followed by the GTE_StartUp(mode, width, height) call. This was loosely inspired by the Toolbox conventions which have a BootInit() and StartUp call for each tool. However, upon further reflection, one realizes that the user of a Toolbox never actually has to call BootInit themself. In fact, the Toolbox documentation states that the user should never make this call directly. So, in the revised API, the actions performed by GTE_Init() have been folded into GTE_StartUp().
Now, that change is, really, quite trivial. A not-so-trivial change is the following. One of the more powerful features of GTE is its support for parallax scrolling with almost no speed penalty. However, the internal code cases get a bit more complicated when both backgrounds are active, so there was a separate function which allocated the additional Bank 00 memory for the second layer and set up the appropriate internal data structures. However, this functionality is not obvious and requires learning about the peculiarities of the parallax initialization function which are different than the generic StartUp function. So, in the revised API, I’ve extended the definition of the mode parameter of GTE_StartUp() to allow for the parallax layer to be activated at start up. This provides a direct way to get a default parallax layer, but the full suite of parallax-specific functions remain available for tweaking the allocation and behavior of the second layer for more complicated uses. For reference, the new definition of mode is:
bit 0-1
00: 4x4 Tiles
01: 8x8 Tiles
10: 16x16 Tiles
bit 2-3
00: No Second Layer
01: Pixmap
10: Tilemap
11: Dynamic Tiles
The API refactoring will involve quite a bit of code refactoring as well. But, in the end, I hope to have a much improved API and perhaps some performance improvements in GTE itself due to the cleaner design.
Permalink Comments off