Programmers’ Challenge

By Mike Scanlin, MacTech Magazine Regular Contributing Author

BLOCKMOVEBITS

Because I’ve had several requests for it and because I’ve wanted to do it for a while and because this column is primarily about about efficient coding and because the lazy days of summer are over and it’s time to get serious, I’m happy to say that September will from now on be the annual MacTech Assembly Language Programmer’s Challenge. When submitting entries to September challenges you may use as much in-line 68040 assembly source inside of a Think C function as you like. In fact, a C wrapper around a 100% assembly language solution is allowed (and preferred). You should optimize for the 040 cause that’s what I’ll run the time tests on (and your code can require an 020, 030 and/or 040 if it wants to). You must preserve all registers except A0-A1/D0-D2. OK. Let’s get to it.

This first assembly language challenge is to move a block of contiguous bits when given the number of bits to move along with source and destination byte and bit offsets (the source and destination bit ranges do not overlap). This could be used, for example, inside a bit-blitting graphics routine that’s working with bitMaps.

The prototype of the function you write is:

void BlockMoveBits(srcBytePtr, 
 destBytePtr, srcBitOffset, 
 destBitOffset, bitCount)
char    *srcBytePtr;
char    *destBytePtr;
unsigned char    srcBitOffset;
unsigned char    destBitOffset;
unsigned short bitCount;

The srcBytePtr and destBytePtr point to the bytes containing the first source bit and first destination bit. The actual bits are at bit offsets srcBitOffset and destBitOffset (both of which will be less than 8). The most number of bits you can move at one time with this routine is 2^16 - 1 or 65535 (it’s possible that bitCount will be zero, which means you should move zero bits, not 64K bits). You should not disturb any of the bits in the destination bytes that aren’t part of the move.

Here’s an example. Say srcBitOffset is 2, destBitOffset is 5 and bitCount is 10. You have the following before the move (‘s’ is a source bit, ‘d’ is a destination bit and the ‘S’ bits (capital S) are going to be copied:

bit position : 76543210 76543210
srcBytePtr  -> ssSSSSSS SSSSssss
destBytePtr -> dddddddd dddddddd

and you have this after the move:

bit position : 76543210 76543210
srcBytePtr  -> ssSSSSSS SSSSssss
destBytePtr -> dddddSSS SSSSSSSd

It’s very likely that your implementation will have this shell:

void BlockMoveBits(srcBytePtr, 
 destBytePtr, srcBitOffset, 
 destBitOffset, bitCount)
char    *srcBytePtr;
char    *destBytePtr;
unsigned char    srcBitOffset;
unsigned char    destBitOffset;
unsigned short bitCount;
{
 asm {
 ;get parameters into registers
 Move.L srcBytePtr,A0
 Move.L destBytePtr,A1
 ... and so on
 }
}

Please note that because of the increased level of difficulty of reading assembly compared to C, it is very important that your code contains at least a few comments explaining what’s going on. I don’t want to see 200 lines of blazingly fast completely undocumented code. That won’t be of much use to anyone. And use meaningful labels where you can (rather than randomly ordered numeric ones from @258 to @431 or whatever).

TWO MONTHS AGO WINNER

I guess I scared away too many people with my “don’t use MoveWindow or SizeWindow” suggestion in the Tile Windows challenge because I only received three entries this month. However, all three entrants managed to find ways around using those traps and their times were very close to each other (and all three were at least an order of magnitude faster than the MoveWindow/SizeWindow equivalent). Congrats to Raffi Kasparian (Baltimore, MD) for being somewhat faster than the other guys. Raffi’s performance gain comes from manipulating some of the window’s fields directly, which is less than ideal in terms of future compatibility but it works on today’s machines so I’ll let it stand.

Here are the times (for tiling 80 windows) and sizes:

Name bytes ticks

Raffi Kasparian 716 81

Jordan Zimmerman 948 123

Ken Franklin/Michael Staw 806 126

Note that tiling 80 windows in 2 seconds (120 ticks) or less is quite fast. MPW, for comparison, took 10 seconds to tile 20 windows (and I found out that the “New” menu item becomes disabled after you create 45 Untitled windows).

The key to winning this challenge was to make use of the routines MovePortTo, PortSize, PaintBehind and CalcVisBehind. If you do it right then you can have the entire desktop (spread over multiple devices) updated with all the new windows blinking into place with a single call to PaintBehind. It’s really interesting to trap on PaintBehind in a debugger and then to step over that one trap and watch the whole desktop get rearranged (after all ports have been positioned and sized correctly, of course).

Since the winning solution does things in a less than future compatible way (it doesn’t call the window’s defProc to calculate the new regions, for instance) and since my goal with this challenge was to release a generic, efficient window tiling and stacking mechanism into the world, I’ve included some of my own code after Raffi’s.

If you think about minimal screen updating, which parts of the desktop need to be invalidated by rearranging the windows? The answer is the sum of the strucRgns in the windows’ old positions and the sum of the strucRgns in the windows’ new positions. No other area on the screen needs to be invalidated or redrawn. Therefore, my routine keeps track of the sum of these two sets of regions as it works. The resulting region, sumOfStructRgns, is then used as the clobberedRgn parameter to PaintBehind and CalcVisBehind. Any desktop pixel or background app pixel not in this region is not redrawn (i.e. there is no unnecessary flicker).

My routine, TileStackWindows, takes a function pointer parameter to a proc you write that does something with a list of windows inside a given rectangle (the function callback is similar to the challenge’s TileWindows function). This callback is called once per device, with the device’s gdRect given as the rect (inset a few pixels) and the list of windows set to all windows that are more on that device than on any other device. Thus, TileStackWindows is a generic, per-device window rearranging routine. All you have to do is come up with interesting tiling algorithms and bake them into the proc you pass to TileStackWindows. The efficient updating of the desktop and region maintenance is taken care of for you.

There are a couple of restrictions for the callback. First, it must resize a window before it repositions a window. Second, it must call MySizeWindow and MyMoveWindow instead of SizeWindow and MoveWindow. The callback should return TRUE if it moved or sized at least one window and FALSE if it did nothing. The reason for this is because if you have a Tile Windows menu item in your application and the user chooses it twice in a row, it is nice if the second time it is chosen the code is smart enough to see that things are already as they should be and does not cause any flickering or redrawing to take place.

An example callback function, StackWindows, is given here. It takes advantage of the fact that the list of windows it is passed is in order from the frontmost window to the backmost window (for that device). The last window in the list (the backmost) ends up being the largest window after the set has been stacked and the frontmost window (first in the list) ends up being the smallest window after the set has been stacked. It is done this way so that you can read all window titles after they’ve been stacked.

If you want to do tiling rather than stacking, all you have to do is replace StackWindows with your own TileWindows function and come up with a way to calculate each window’s new size and position. Hopefully application writers who have tiling and stacking options within their programs (including MPW) will implement this type of a scheme so that we no longer have to wait so long while we watch windows being moved and sized one at a time with maximum intermediate screen updating.

Here’s Raffi’s winning solution followed by my own version of a generic window tiling/stacking routine and a piece of test code so you can try it out:

TileWindows.c Listing
/*----------------------------------------------------
TileWindows
by Raffi Kasparian
----------------------------------------------------*/
#define StackingOffset 10
 
void TileWindows(enclosingRectPtr, windowPtrArray,
                 windowCount, pixelsBetween,
                 minHorzSize, minVertSize)
 
Rect            *enclosingRectPtr;
WindowPtr       windowPtrArray[];
unsigned short  windowCount;
unsigned short  pixelsBetween;
unsigned short  minHorzSize;
unsigned short  minVertSize;
 
#define mx minHorzSize
#define my minVertSize
#define d  pixelsBetween
 
#define struc  ((WindowPeek)(windowPtrArray[num]))->strucRgn
#define strucL (**struc).rgnBBox.left
#define strucT (**struc).rgnBBox.top
#define strucR (**struc).rgnBBox.right
#define strucB (**struc).rgnBBox.bottom
 
#define cont  ((WindowPeek)(windowPtrArray[num]))->contRgn
#define contL (**cont).rgnBBox.left
#define contT (**cont).rgnBBox.top
#define contR (**cont).rgnBBox.right
#define contB (**cont).rgnBBox.bottom
 
#define pBits  windowPtrArray[num]->portBits.bounds
#define pBitsL pBits.left
#define pBitsT pBits.top
#define pBitsR pBits.right
#define pBitsB pBits.bottom
 
#define pRect  windowPtrArray[num]->portRect
#define pRectL pRect.left
#define pRectT pRect.top
#define pRectR pRect.right
#define pRectB pRect.bottom
 
{
 register short dL, dT, dR, dB, BR, x, y, maxx, maxy,
                num, rL, rT, rR, rB;
 Rect           er = *enclosingRectPtr;
 
#define erL er.left
#define erT er.top
#define erR er.right
#define erB er.bottom
 
 num = 0;
 
 while (true) {
 
  maxy = (erB - erT + d)/(my + d);
  maxx = (erR - erL + d)/(mx + d);
  if ((BR = maxx * maxy) > windowCount) {
   maxx = (windowCount - 1) / maxy + 1;
   maxy = (windowCount - 1) / maxx + 1;
   BR = windowCount;
  }
  BR--;
 
  if (num <= BR) {
   mx = ((erR - erL) - ((maxx - 1) * d)) / maxx;
   my = ((erB - erT) - ((maxy - 1) * d)) / maxy;
  }
 
  rT = erT - (my + d);
  for (y = 1; y <= maxy; y++) {
   rL = erL - (mx + d);
   rT += my + d;
   rB = (y == maxy) && (num <= BR) ? erB : rT + my;
   for (x = 1; x <= maxx; x++, num++) {
 
    rL += mx + d;
    rR = ((x == maxx) && (num <= BR)) ||
      (num == BR) ? erR : rL + mx;
 
    dL = rL - strucL;
    dT = rT - strucT;
    dR = rR - strucR;
    dB = rB - strucB;
 
    SetRectRgn(struc, rL, rT, rR, rB);
    SetRectRgn(cont, contL + dL, contT + dT,
      contR + dR,  contB + dB);
      
    pBitsL -= dL;
    pBitsT -= dT;
    pBitsR -= dL;
    pBitsB -= dT;
 
    pRectR = contR - contL + pRectL;
    pRectB = contB - contT + pRectT;
 
    if (num == windowCount - 1) {
     PaintBehind((WindowPeek)FrontWindow(),
       GrayRgn);
     CalcVisBehind((WindowPeek)FrontWindow(),
       GrayRgn);
     return;
    }
   }
  }
  if (erR - erL - StackingOffset >= mx)
   erL += StackingOffset;
  if (erB - erT - StackingOffset >= my)
   erT += StackingOffset;
 }
}

TileStackWindows.h Listing
/*****************************************************
 * TileStackWindowsWindows.h
 ****************************************************/

/*****************************************************
 * typedefs
 ****************************************************/

typedef struct WindowElement {
 WindowPeek theWindowPtr;
 GDHandle theDevHndl;
} WindowElement, *WindowElementPtr;

typedef Boolean (*TileStackWindowsProc)
 (Rect *enclosingRectPtr,
 WindowElementPtr p, int wCount);
 
 
/*****************************************************
 * prototypes
 ****************************************************/
 
void  TileStackWindows(TileStackWindowsProc
 theTileStackProc);
Boolean MyMoveWindow(WindowPtr w, int leftGlobal,
 int topGlobal, Boolean sizeChanged);
Boolean MySizeWindow(WindowPtr w, int width,
 int height);

TileStackWindows.c Listing
/*****************************************************
 * TileStackWindows.c
 *
 * Set of routines to quickly rearrange windows
 * on multiple devices.
 *
 * Mike Scanlin  10 July 1993
 ****************************************************/

#include <GestaltEqu.h>
#include <Traps.h>
#include "TileStackWindows.h"

/*****************************************************
 * defines
 ****************************************************/

#define BAD_DEVICE ((GDHandle) -1)
#define TOPLEFT_SLOP 2
#define BOTRIGHT_SLOP3
#define NIL 0L

/* MAX_WINDOWS is not a real limit but stack space
 * requirements for TileStackWindows are equal to
 * (sizeof(WindowElement) * 2 * MAX_WINDOWS) so
 * don't make it too big. It's the max number of
 * windows that TileStackWindows can deal with.
 */
#define MAX_WINDOWS100

/*****************************************************
 * typedefs
 ****************************************************/

typedef pascal long(**WDefProcHndl)(int var,
 WindowPtr w, int message, long param);

/*****************************************************
 * prototypes
 ****************************************************/
 
static GDHandle DominantDevice(Rect *theRect);

/*****************************************************
 * TileStackWindows
 *
 * Calls theTileStackProc on a per-device basis to
 * clean up (stack, tile or whatever else you can
 * think of) all the windows on that device. Once
 * all devices have been taken care of the part of
 * the screen that needs to be updated is updated.
 ****************************************************/
void TileStackWindows(TileStackWindowsProc
 theTileStackProc)
{
 WindowElementPtrp, dp;
 WindowPeek w;
 GDHandle deviceHndl;
 RgnHandle  sumOfStructRgns;
 WindowElement   theWindows[MAX_WINDOWS],
 theDeviceWindows[MAX_WINDOWS];
 long   theQDVers;
 Rect   enclosingRect;
 int    i, totalWindows,
 windowsToClean,
 deviceWindows;
 BooleanneedToRedraw, hasColorQD;
 
 /* check for color QuickDraw */
 hasColorQD = FALSE;
 if (TrapIsAvailable(_Gestalt)) {
 Gestalt(gestaltQuickdrawVersion, &theQDVers);
 hasColorQD = theQDVers >= 0x0100;
 }

 sumOfStructRgns = NewRgn();
 needToRedraw = FALSE;
 
 /* find the dominant device for each window
  * as we add it to our list of windows
  */
 p = theWindows;
 totalWindows = 0;
 w = (WindowPeek) FrontWindow();
 while (w != NIL && totalWindows < MAX_WINDOWS) {
 p->theWindowPtr = w;
 p->theDevHndl = NIL;
 if (hasColorQD)
 p->theDevHndl =
   DominantDevice(&(*w->strucRgn)->rgnBBox);
 p++;
 totalWindows++;
 /* or the old struct region into the
  * update region
  */
 UnionRgn(sumOfStructRgns, w->strucRgn,
 sumOfStructRgns);
 w = w->nextWindow;
 }
 
 if (totalWindows == 0)
 goto Exit;
 
 /* set up enclosingRect here in case we don't
  * have color QD; if we do have colorQD then
  * enclosingRect is set again in the loop below
  * on a per-device basis
  */
 enclosingRect = (*GetGrayRgn())->rgnBBox;
 enclosingRect.top += TOPLEFT_SLOP;
 enclosingRect.left += TOPLEFT_SLOP;
 enclosingRect.bottom -= BOTRIGHT_SLOP;
 enclosingRect.right -= BOTRIGHT_SLOP;

 windowsToClean = totalWindows;
 do {
 /* find the first device in the list that we
  * haven't already done and copy all elements
  * from that device into a new list
  */
 p = theWindows;
 dp = theDeviceWindows;
 deviceWindows = 0;
 deviceHndl = BAD_DEVICE;
 i = totalWindows;
 do {
 if (p->theDevHndl != BAD_DEVICE) {
 if (deviceHndl == BAD_DEVICE) {
 /* this is the first time we've
  * seen this device so we do a
  * little set up first
  */
 deviceHndl = p->theDevHndl;
 /* if we have colorQD, use the
  * device's rect
  */
 if (deviceHndl != NIL) {
 enclosingRect = (*deviceHndl)->gdRect;
 enclosingRect.top += TOPLEFT_SLOP;
 enclosingRect.left += TOPLEFT_SLOP;
 enclosingRect.bottom -= BOTRIGHT_SLOP;
 enclosingRect.right -= BOTRIGHT_SLOP;
 if (deviceHndl == GetMainDevice())
 enclosingRect.top += GetMBarHeight();
 }
 }
 if (deviceHndl == p->theDevHndl) {
 /* it's on the current device,
  * add it to the list
  */
 *dp++ = *p;
 deviceWindows++;
 /* we don't want to see this
  * one again
  */
 p->theDevHndl = BAD_DEVICE;
 }
 }
 p++;
 } while (--i);
 
 if (deviceWindows > 0) {
 /* do something to the windows on
  * this device
  */
 needToRedraw |= (*theTileStackProc)
   (&enclosingRect, theDeviceWindows,
   deviceWindows);
 windowsToClean -= deviceWindows;
 }
 
 } while (windowsToClean > 0);
 
 if (needToRedraw) {
 
 /* add all of the new struct regions to the
  * update region
  */
 p = theWindows;
 do {
 UnionRgn(sumOfStructRgns,
   p->theWindowPtr->strucRgn,
   sumOfStructRgns);
 p++;
 } while (--totalWindows);
 
 /* To see a cool effect, trap on the next
  * instruction and watch the screen as you
  * step over it. All window frames are drawn
  * with this one call to the ROMs.
  */
 PaintBehind(theWindows[0].theWindowPtr,
   sumOfStructRgns);
 
 /* Need to reset the visRgns since
  * MySizeWindow nuked 'em.
  */
 CalcVisBehind(theWindows[0].theWindowPtr,
   sumOfStructRgns);
 }

Exit:

 DisposeRgn(sumOfStructRgns);
}


/*****************************************************
 * DominantDevice
 *
 * This returns a device hndl to the device that
 * owns most of the given Rect (which is in global
 * coordinates). This routine requires ColorQD.
 ****************************************************/
static GDHandle DominantDevice(Rect *theRect)
{
 GDHandle nthDevice, theDevice;
 long   greatestArea, sectArea;
 Rect   theSect;
 
 nthDevice = theDevice = GetDeviceList();
 greatestArea = 0;
 do {
 if (TestDeviceAttribute(nthDevice, screenDevice) &&
   TestDeviceAttribute(nthDevice, screenActive)) {
 SectRect(theRect, &(*nthDevice)->gdRect,
   &theSect);
 sectArea =
   ((long) (theSect.bottom - theSect.top)) *
   ((long) (theSect.right - theSect.left));
 if (sectArea > greatestArea) {
 greatestArea = sectArea;
 theDevice = nthDevice;
 }
 }
 nthDevice = GetNextDevice(nthDevice);
 } while (nthDevice != NIL);
 
 return (theDevice);
}


/*****************************************************
 * MyMoveWindow
 *
 * Quickly move the window. No screen updating
 * will take place.
 ****************************************************/
Boolean MyMoveWindow(WindowPtr w, int leftGlobal,
 int topGlobal, Boolean sizeChanged)
{
 Handle theDefProc;
 GrafPtroldPort;
 Point  upperLeft;
 char   oldState;
 BooleanitMoved;
 
 itMoved = FALSE;

 oldPort = thePort;
 SetPort(w);
 
 /* Don't move it if it's already there, unless
  * it was just resized (in which case we don't
  * really need to call MovePortTo but we do
  * need to call the windowDefProc below to fix
  * up the regions).
  */
 if (!sizeChanged) {
 upperLeft = topLeft(w->portRect);
 LocalToGlobal(&upperLeft);
 if (upperLeft.h == leftGlobal &&
   upperLeft.v == topGlobal)
 goto Exit;
 }
 
 itMoved = TRUE;
 
 MovePortTo(leftGlobal, topGlobal);
 
 theDefProc = ((WindowPeek) w)->windowDefProc;
 oldState = HGetState(theDefProc);
 HLock(theDefProc);
 
 /* call the WDEF to update the regions */
 (*(WDefProcHndl) theDefProc)(zoomDocProc, w,
   wCalcRgns, 0);

 HSetState(theDefProc, oldState);

Exit:

 SetPort(oldPort);
 
 return (itMoved);
}


/*****************************************************
 * MySizeWindow
 *
 * Quickly set the size of a window. Set the
 * visRgn to NIL so that no screen updating takes
 * place. The visRgn will be reset when we call
 * CalcVisBehind later.
 ****************************************************/
Boolean MySizeWindow(WindowPtr w, int width,
 int height)
{
 GrafPtroldPort;
 
 /* don't size it if it's already the right size */
 if (w->portRect.right - w->portRect.left == width &&
   w->portRect.bottom - w->portRect.top == height)
   return(FALSE);
   
 oldPort = thePort;
 SetPort(w);
 
 PortSize(width, height);
 
 /* nuke the visRgn so that moving this port
  * (in MyMoveWindow) won't cause any screen
  * drawing
  */
 SetEmptyRgn(((GrafPtr) w)->visRgn);
 
 SetPort(oldPort);
 
 return(TRUE);
}

test.c Listing
/*****************************************************
 * test.c
 *
 * Driver function and example TileStackWindows
 * function to test out TileStackWindows.
 ****************************************************/

#include "TileStackWindows.h"

/*****************************************************
 * defines
 ****************************************************/

#define NUM_TEST_WINDOWS  20

/*****************************************************
 * prototypes
 ****************************************************/
 
static Boolean StackWindows(Rect *enclosingRectPtr,
 WindowElementPtr p, int wCount);

/*****************************************************
 * main
 ****************************************************/
void main()
{
 WindowPtr*p, windowPtrArray[NUM_TEST_WINDOWS];
 Rect   theBounds;
 int    i;
 
 theBounds.top = 50;
 theBounds.left = 50;
 theBounds.bottom = 200;
 theBounds.right = 200;
 
 p = windowPtrArray;
 i = NUM_TEST_WINDOWS;
 do {
 *p++ = NewWindow(0L, &theBounds, "\pTest",
 TRUE, 0, (WindowPtr) -1, TRUE, 0);
 OffsetRect(&theBounds, 3, 2);
 } while (--i);
 
 TileStackWindows(StackWindows);
}


/* window stacking variables used by StackWindows */
#define WTitleHeight 18
#define StaggerH 7
#define StaggerV (WTitleHeight - 2)
#define MinVertSize200
#define NextRowOffsetH    2
#define NextRowOffsetV    4

/*****************************************************
 * StackWindows -- example TileStackWindows proc
 *
 * Stack all the windows so you can see their
 * titles. Returns TRUE if we moved or sized at
 * least one window (if not then we don't need to
 * redraw the screen).
 ****************************************************/
static Boolean StackWindows(enclosingRectPtr, p, wCount)
Rect    *enclosingRectPtr;
WindowElementPtr p;
intwCount;
{
 WindowPtrw;
 Rect   theBounds;
 Point  upperLeft;
 int    width;
 BooleandidOne, sizeChanged;
 
 theBounds = *enclosingRectPtr;
 theBounds.top += WTitleHeight;
 upperLeft = topLeft(theBounds);
 width = theBounds.right - theBounds.left;
 
 didOne = FALSE;
 
 /* this particular routine starts at the back
  * of the list and works it's way forward
  * (to the frontmost window)
  */
 p += wCount;
 do {
 p--;
 w = (WindowPtr) p->theWindowPtr;
 sizeChanged = MySizeWindow(w,
 theBounds.right - theBounds.left,
 theBounds.bottom - theBounds.top);
 didOne |= sizeChanged;
 didOne |= MyMoveWindow(w, theBounds.left,
 theBounds.top, sizeChanged);
 theBounds.left += StaggerH;
 theBounds.right += StaggerH;
 theBounds.top += StaggerV;
 if (theBounds.top >
   enclosingRectPtr->bottom - MinVertSize) {
 upperLeft.h += NextRowOffsetH;
 upperLeft.v += NextRowOffsetV;
 topLeft(theBounds) = upperLeft;
 theBounds.right = theBounds.left + width;
 }
 if (theBounds.right > enclosingRectPtr->right)
 theBounds.right = enclosingRectPtr->right;
 } while (--wCount);
 
 return (didOne);
}

The Rules

Here’s how it works: Each month there will be a different programming challenge presented here. First, you must write some code that solves the challenge. Second, you must optimize your code (a lot). Then, submit your solution to MacTech Magazine (formerly MacTutor). A winner will be chosen based on code correctness, speed, size and elegance (in that order of importance) as well as the postmark of the answer. In the event of multiple equally desirable solutions, one winner will be chosen at random (with honorable mention, but no prize, given to the runners up). The prize for the best solution each month is $50 and a limited edition “The Winner! MacTech Magazine Programming Challenge” T-shirt (not to be found in stores).