Tag Archives: IIGS

Calling GTE Tool 160 from C

One of the KansasFest 2022 presentations that particularly stood out to me was Lucas Scharenbroich’s Generic Tile Engine for the Apple IIgs (GTE). In his presentation, Lucas demonstrated a number of awesome capabilities in GTE and how it handles the details of working with the quirks of Apple IIgs graphics so you can focus on writing game logic code. I’m excited to try using this to write a game; but, I’m significantly more comfortable programming in C than in assembly. This is a capture of my first successful attempt in doing that in case it helps others get started.

Dev Environment

Runtime Environment

Nuance – I did modify the 2mg image for System 6.0.1 in my project so it has Tool 160 already installed in the tools folder.

The Code

The core of the code is in a main.c file which starts up the tools, waits in a loop for the option key to be pressed, and then shuts down the tools and exits. The details of the functions and the mask of values for GTEReadControl were taken from the GTE Toolbox documentation.

Nuance – it did take me a little bit to realize I needed A0 for the XX in the toolbox calls. Finding the macro file was the thing that helped me realize 160 decimal -> A0 hexadecimal.

[Updated 2022-Jul-28: The below code originally incorrectly passed address 0 to GTEStartUp for the dPageAddr parameter. Thank you to Lucas Scharenbroich for noticing and for the updated code which correctly allocates 2 consecutive pages of bank 0 memory and passes that instead.]

#include <locator.h>
#include <memory.h>
#include <misctool.h>
#include <types.h>

#include "main.h"

#define TOOLFAIL(string) \
    if (toolerror()) SysFailMgr(toolerror(), "\p" string "\n\r    Error Code -> $");

extern pascal void GTEStartUp(Word dPageAddr, Word capFlags, Word userID) inline(0x02A0, dispatcher);
extern pascal void GTEShutDown(void) inline(0x03A0, dispatcher);

extern pascal Word GTEReadControl(void) inline(0x09A0, dispatcher);


int main (void) {
  Ref toolStartupRef;
  Word controlMask;
  unsigned int userId;
  Handle dpHndl;
  Word dpWord;

  userId = MMStartUp();
  TOOLFAIL("Unable to start memory manager");

  TLStartUp();
  TOOLFAIL("Unable to start tool locator");

  toolStartupRef = StartUpTools(userId, refIsResource, rez_tools);
  TOOLFAIL("Unable to start tools");

  dpHndl = NewHandle(0x0200, userId, 0x4015, 0);
  if (dpHndl == NULL) {
    TOOLFAIL("Unable to allocate bank 0 memory");
  }
  dpWord = (Word)(*dpHndl);
  if ((dpWord & 0x00FF) != 0x0000) {
    TOOLFAIL("Allocated bank 0 memory is not aligned");
  }

  GTEStartUp(dpWord, 0x0000, userId);
  TOOLFAIL("Unable to start GTE");

  do {
    controlMask = GTEReadControl();
  } while ((controlMask & 0x0100) == 0x00);

  GTEShutDown();
  TOOLFAIL("Unable to shutdown GTE");

  ShutDownTools(refIsHandle, toolStartupRef);
  TOOLFAIL("Unable to shutdown tools");

  TLShutDown();
  TOOLFAIL("Unable to shutdown tool locator");

  MMShutDown(userId);
  TOOLFAIL("Unable to shutdown memory manager");
}

The main.h file really just sets up the constants for the tool list resource:

#ifndef _GUARD_PROJECTGTETest1_FILEmain_
#define _GUARD_PROJECTGTETest1_FILEmain_

#define rez_tools                                  1

#endif /* defined(_GUARD_PROJECTGTETest1_FILEmain_) */

The main.rez file is just a tool list resource:

#include "types.rez"
#include "main.h"

resource rToolStartup (rez_tools) {
  mode320,
  {
    3,   $0302,     /* Misc Tool */
    160, $0100      /* GTE */
  }
};

While this is a relatively small step, it did prove out to me that I can call into the tool from C. I’m looking forward to trying more of the API in the near future.

Standard

Running lcov on a GitHub Linux Runner

For Wordle GS, I’ve been trying to maintain decent unit test coverage of the core game logic. My approach has been to leverage Cpputest, gcov, & lcov both locally as well as on the Ubuntu GitHub Runner based CI builds. To simplify checking coverage on PRs, I added lcov-reporter-action to the mix. There was just one problem – the summary numbers in the comments left were clearly bogus. With overall coverage showing as NaN% (with a +/- change of NaN% to boot) and the totals for all the other metrics showing as 100% (despite the clear presence of uncovered lines), this wasn’t as usable as I’d hoped.

Continue reading →
Standard

Classic Computer, Modern IDE

Years ago, I spent a week in the wilderness of Utah.  The night sky was breathtaking; the days were spent in canyons mostly untouched by humans.  It was an amazing experience that I will always be grateful for.  However, by the end of the week, I was happy to return to modern conveniences.

Programming the IIGS on the IIGS feels like experiencing those canyons in Utah and, overall, very authentic. I’ve relived my early attempts in all their glory and frustration. Knowing the convenience of modern development environments, the second part has been bothering me more this time. I am accustomed to syntax highlighting, large screens, fast compile cycles, and all the other conveniences. Thankfully, there’s a solution for this:

With those three packages installed on my Mac, I can develop for the IIGS in Xcode and test in emulation.  This was a very straightforward installation process with one exception.  I did struggle a bit on Step 5 – Install ProFUSE. After some head scratching and overthinking the problem, I realized that from GitLab, I could simply select Repository -> Tags and then filter using the term profuse and a pkg file was provided.

With everything up and running, the function I wrote for the first lesson is formatted and highlighted as I would expect:

Additionally, compile/test cycles are dramatically shortened with this setup. Overall, I feel like this is a reasonable compromise between staying 100% authentic to the original experience and having modern conveniences.

Standard

Revisiting a Past Failure

When I was fifteen, I failed to write a game for the IIGS.  In fact, I failed repeatedly to write any number of games.  I remember the rush of excitement each time I started a new one, followed by the crash of running into the limit of my abilities.  Many hours were spent sitting at that genuine faux wood veneer computer desk (with hutch) that held the machine that was alternately thrilling and frustrating.  Eventually, I moved on to programming other computers without having finished any of those game.

The IIGS, getting ready for the new attempt

Looking back, I question if I was more interested in writing a game or in being the person who had written a game.  I daydreamed about my games being listed in the Big Red Computer Club catalog and how the shareware checks would roll in.  That time could have likely been better spent learning more about programming or the IIGS itself.  At the same time, in hindsight, I was fighting some unnecessary uphill battles.  It took a while for me to realize that I’d need to learn something beyond Applesoft BASIC and then a while longer to save up money for a Pascal compiler.  Some of it was giving up on debugging and playing a little more Neuromancer (which still holds up as one of my favorite games, so I regret nothing on that front).

The monks of Pong asked for fewer years than it has taken me

Having recently unearthed my IIGS, a lot of memories and questions about programming have been slowly resurfacing.  Can I write a game for the IIGS?  How many of the challenges would be addressed by proper tools and books?  Will I instead finish playing Neuromancer?  I’m hoping to find out.

Standard