Volume Number: 15 (1999)
Issue Number: 8
Column Tag: Programmer's Challenge

Aug 99 Prgrammer's Challenge

by Bob Boonstra, Westford, MA

Some of the people who have recently written to suggest possible Challenge problems have asked for Challenges that are more specific to the Macintosh. Well, not everyone is actually that subtle about it. One writer lamented "yet another plain-vanilla Challenge that could just as well have appeared in a Linux or Windows programming magazine". Ouch!! Since this column is based on demonstrating efficient performance, many of the problems naturally carry over to other platforms. But the writer has a point, and this month's Challenge will have more to do with the Mac OS.

Back in April, readers were asked to find a path through three-dimensional terrain that minimized elevation change. This month, you'll also be dealing with 3D terrain, but you'll be flying over it, and displaying a perspective view of that terrain. In the process, you'll have the opportunity to learn a little about QuickDraw3D.

The prototype for the code you should write is:

#include <QD3D.h>
#include <QD3DLight.h>
#include <QD3DCamera.h>

#include <Windows.h>

#if defined(__cplusplus)
extern "C" {
#endif

typedef struct MyTriangles {
	long pointIndices[3];
	TQ3ColorRGB triangleColor;
} MyTriangles;

void InitFlyBy(
	CWindowPtr theWindow,
	long numPoints,
	const TQ3Point3D thePoints[],
	long numTriangles,
	const MyTriangles theTriangles[],
	const TQ3ViewAngleAspectCameraData	perspectiveData,
		// perspectiveData.cameraData.range.hither	= 0.0;
		// perspectiveData.cameraData.range.yon 	= 1000.0
		// perspectiveData.cameraData.viewPort.origin.x = -1.0
		// perspectiveData.cameraData.viewPort.origin.y = 1.0
		// perspectiveData.cameraData.viewPort.width = 2.0
		// perspectiveData.cameraData.viewPort.height = 2.0
		// perspectiveData.fov				= 1.0
		// perspectiveData.aspectRatioXToY	=
		// 	    (float) (theWindow->portRect.right - theWindow->portRect.left) / 
		//     (float) (theWindow->portRect.bottom - theWindow->portRect.top)
	const TQ3ColorRGB backgroundColor
		// color of background
);

void GenerateView(
	TQ3CameraPlacement		viewPoint
);

void TermFlyBy(void);

#if defined(__cplusplus)
}
#endif

Your code consists of three routines: InitFlyBy. called once for each terrain map; GenerateView, called repeatedly with different view positions as you fly through the terrain; and TermFlyBy, called at the end of each flight.

InitFlyBy is given everything needed to describe the scene to be generated except the viewPoint. The terrain consists of numPoints terrain coordinates provided in thePoints. The terrain is divided into numTriangles triangles, provided in theTriangles, each of which is described by 3 pointIndices into thePoints array, plus a color for the triangle.

Each time GenerateView is called, the terrain should be displayed in theWindow from the viewPoint using the projection information provided in perspectiveData. The projection will be a perspective, as opposed to an orthographic, projection, described using the TQ3ViewAngleAspectCameraData structure. The range, viewPort, fov, and aspectRationXToY elements of that structure are guaranteed to be defined using the simplifying values shown in the prototype commentary above.

Triangles should be displayed in the triangleColor, and areas of the scene not included in theTriangles should be displayed in the backgroundColor.

To optimize your code, you can rely on the fact that the viewPoint cameraLocation provided on successive calls to GenerateView will not change very much, simulating an actual flight. Similarly, the viewPoint pointOfInterest that determines the viewing direction, and the viewPoint upVector that governs orientation will not change by large amounts. They will change as the simulated flying machine banks and turns to avoid terrain.

A more realistic FlyBy Challenge would include one or more light sources, an illumination model, and the projection of shadows. For simplicity, we'll omit those minor details. We'll also allow you to fly without worrying about intersecting the terrain ("crashing") - the test code won't do that.

TermFlyBy should deallocate any dynamically allocated memory. Remember, your solutions need to properly initialize and clean up after themselves so they can be executed repeatedly.

Information on QuickDraw3D data structures can be found at: http://developer.apple.com/techpubs/quicktime/qtdevdocs/QD3D/qd3d_book.htm

The winner will be the solution that accurately depicts multiple flights through terrain using the least amount of execution time. This will be a native PowerPC Challenge, using the latest CodeWarrior environment. Solutions may be coded in C, C++, or Pascal.

Three Months Ago Winner

Congratulations to Ernst Munter (Kanata, Ontario) for submitting the winning solution to the May "Piper" Challenge. The Challenge, based on a TidBITS column by Rick Holzgrafe, was to map a string of characters into the smallest rectangle, placing adjacent characters in the string into adjacent positions (horizontally, vertically, or diagonally). The rules allowed (and encouraged) characters to be reused, so that a string like "How much wood would a woodchuck chuck if a woodchuck could chuck wood?" can be mapped into a compact 4x4 rectangle:

				hwhu
				oocm
				udwk
				lafi

Five people submitted entries to this Challenge, and I also evaluated a version of Rick Holzgrafe's code, modified to work with the API specified by the problem statement. Scoring was based on the area of the rectangle produced by the solution, with a 1% penalty added for each second of execution time. I evaluated the entries using 5 test cases with input strings ranging from 38 characters to 198 characters. Besides chucking wood, the entries had the opportunity to pick pickled peppers, sell sea shells by the sea shore, travel to St. Ives with the man with seven wives, and chow down on green eggs and ham with Dr. Seuss. One of the solutions, plus Rick's, outlasted my patience on the longer problems, but all of the solutions submitted (and Rick's) solved the short test cases correctly and compactly. Four solutions solved the "woodchuck" input more quickly than Rick's baseline solution, as shown in the following table:

All of the entries submitted were recursive, except for the winning one. Ernst eliminated the natural recursion by placing possible moves and associated state information on the heap. Eliminating recursion probably improved the efficiency of Ernst's solutions, but his real advantage came from the fact that he generated very compact results, more compact than any other entry in three of five test cases. Ernst used two hueristics in deciding which possible move to explore first: the number of empty cells in the solution rectangle after the move, and a projection of the size of the final rectangle based on the number of unique characters yet to be placed in the box.

The next table lists, for each of the solutions submitted, the sum of the areas of the rectangles generated for all of the inputs, the total execution time, and the total score. As usual, the number in parentheses after the entrant's name is the total number of Challenge points earned in all Challenges prior to this one.

Top Contestants

Listed here are the Top Contestants for the Programmer's Challenge, including everyone who has accumulated 10 or more points during the past two years. The numbers below include points awarded over the 24 most recent contests, including points earned by this month's entrants.

There are three ways to earn points: (1) scoring in the top 5 of any Challenge, (2) being the first person to find a bug in a published winning solution or, (3) being the first person to suggest a Challenge that I use. The points you can win are:

Here is Ernst Munter's winning Piper solution:

/*
Problem Statement
---------
Pack the letters of a character string in the smallest possible
rectangle such that the string can be read by tracing the
characters in the box from field to adjacent field.

A penalty of 1% is added for each second of run time.

Solution Strategy
---------
Solutions are represented by the leaves of a search tree, where
each node stands for a character in the string, associated with
a particular field in the rectangle.  Each node can have up to
eight adjacent fields, and the tree grows very rapidly.

We are interested in the (or one of possibly several) trajectory
where all nodes are packed closely together, to result in the
smallest area.  Each field, with its character, can be visited
several times.

The objective then is to find the more promising trajectories
early, and cut off any search path as soon as it is clear that
it cannot lead to a better solution than the one already obtained.

In addition, the search must be cut off after a few seconds, or
the time penalty will outweigh any likely improvement in area.

Tactics
----
The search relies on two heuristics:

		at each step, all possible next moves are evaluated
		and then executed in order of the lowest "vacancy",
		that is the number of empty fields in the box after
		that move,

	-	the final size of the box at each depth is projected,
		bearing in mind the number of unique single characters
		and pairs in the remainder of the string.

The usual techniques are used to make the program as efficient
as possible, in order to execute as many moves as possible
before the timer cuts the search short.

Recursion Removal
---------
The problem by its nature suggests a recursive solution.
I chose to remove recursion by building a stack of nodes (States)
on the heap.  At each level, up to 8 child nodes ("moves" or
PartialStates) are created and stacked in the preferred order.
Then the node at the top of the stack is expanded into a full node
(with children etc), until either no more moves are possible, or
the last character of the string is reached (leaf node).

When backtracking, there will either be another move stacked on
the previous State, to be expanded; or all moves of the previous
State have been exhausted, and we step back to the previous State
from that; until the initial State is reached, at which point
all branches of the tree have been explored.

*/
#include <stdlib.h>
#include <string.h>
#include <ctype.h>
#include "Piper.h"

#include <lowmem.h>

typedef unsigned char 	U8;
typedef unsigned long 	U32;
typedef unsigned short	U16;
typedef unsigned short	Pair[32];

enum {
	kMaxDim		= 256,		// 256 by 256 grid
	kGridHeight	= kMaxDim,
	kGridWidth	= kMaxDim,
	kGridSize	= kGridHeight * kGridWidth,
	kBorderChar	= 0x1F,

	kWasBlank	= 0x20,

	kDefaultLoop= 0x100000,	// initial run, before timing of loops
	kTolerance	= 8			// accept up to 8 % running time penalty
};

struct Pnt
// A Point (Pnt) in the grid is represented by a short which
// can directly serve as index into the grid.
struct Pnt {
	U16	w;	// = y*256 + x
	Pnt(){}
	Pnt(U32 z):w(z){}
	Pnt(int xx,int yy) : w(xx + (yy<<8)) {}
	int X(){return w & 0xFF;}
	int Y(){return w >> 8;}
	U32 Linear(){return w;}
	void GoUp()  	{w -= 0x0100;}
	void GoDown()	{w += 0x0100;}
	void GoLeft()	{w -= 0x0001;}
	void GoRight()	{w += 0x0001;}
	void Shift(int dx,int dy){w += dx + dy*0x100;}
};

struct Rct
// A Rect (Rct) is the concatenation of two points into a long
struct Rct {
	U32 w;	// = ((top*256 + left)*256 + bottom)*256 + right
	Rct(){}
	Rct(U32 ww){w=ww;}
	Rct(Pnt & TL,Pnt & BR){w = (TL.Linear()<<16) | BR.Linear();}
	int Size()	{return Height() * Width();}
	int Top()	{return  w>>24;}
	int Left()	{return (w>>16) & 0xFF;}
	int Bottom(){return (w>>8) & 0xFF;}
	int Right()	{return  w & 0xFF;}
	int Height(){return Bottom()-Top();}
	int Width()	{return Right()-Left();}
	void ExpandTop()	{w -= (1<<24);}
	void ExpandLeft()	{w -= (1<<16);}
	void ExpandBottom()	{w += (1<<8);}
	void ExpandRight()	{w +=  1;}
};

struct Grid
// Grid is a 256 by 256 grid of characters.
// This box can hold any string up to almost 64K length, and many
// that are longer, but run time would be intolerably long anyway.
// The top, left and bottom margins are set to a border char;
// this confines the string to the box, without wrap or range checks.
static struct Grid {
 	char	g[kGridSize];
 	Grid()
 	{
 		char* gp=g;
 		memset(gp,kBorderChar,kGridWidth);
 		for (int i=1;i < kGridWidth-1;i++)
 		{
 			gp += kGridWidth;
 			memset(gp,0,kGridWidth);
 			*gp=kBorderChar;
 		}
 		memset(gp+kGridWidth,kBorderChar,kGridWidth);
 	}
 	void	Set(/*const*/ Pnt & p,const char c){g[p.Linear()]=c;}
 	int		Value(/*const*/ Pnt & p){return g[p.Linear()];}
 	Pnt &	Center(){return Pnt(kGridWidth/2,kGridWidth/2);}
}
// The grid is declared static and global.
grid;

struct PreProcess
// The PreProcess analyzes the string statically to determine for each
// string position the number of remaining unique characters, and
// the number of remaining unique pairs.  This is then summarized
// as a "tail" figure for each string index, indicating the number
// of fields (at least) that will be required for characters beyond
// the current index position.
struct PreProcess {
	U16*	indexMap;
	U16*	tail;
	char*	str;
	int		oldLen;
	int		netLen;
	PreProcess(char* s)
// All characters are reduced to the range 1 to 26, and non-alpha
// characters are removed from the string s.
// As characters are removed, an index map is created to relate
// the new character indices back to their original positions.
	{
		oldLen=strlen(s);
		indexMap=new U16[oldLen];
		str=s;
		U16* imp=indexMap;
		char* strp=str;
		for (int i=0;i<oldLen;i++)
		{
			U32 c=*s++;
			if (isalpha(c))
			{
				*imp++ = i;
				*strp++ = c & 0x1F;
			}
		}
		netLen=strp-str;
		*strp=0;

		tail=new U16[netLen];
	}
	~PreProcess()
	{
		delete [] tail;
		delete [] indexMap;
	}

	void TrivialSolution(GridPoint pt[])
// If the string is less than 4 characters long, a box of
// height 1 is optimal.
	{
		for (int i=0;i<netLen;i++)
		{
			int j=indexMap[i];
			if ((i==2) && (str[0]==str[2])) pt[j].x=0;
			else pt[j].x=i;
			pt[j].y=0;
		}
	}

	void ComputeProfile()
// Computes the tail array, just once for a given string.
	{
  		U32 cmap=0,R=0;
  		U32 link[32];
  		memset(link,0,sizeof(link));
  		int numLink[32];
  		memset(numLink,0,sizeof(numLink));

  		char* s=str;
  		int len=netLen;
  		U32 a=s[0];
  		for (int i=0;i<len;i++)
  		{
			U32 bit=1 << s[i];
 			if (0 == (cmap & bit)) {R++; cmap |= bit;}
			if (i)
			{
				int b=s[i];
				U32 bbit=1 << s[b];
				if (0 == (link[a] & bbit))
				{
					numLink[a]++;	link[a] |= bbit;
				}
				U32 abit=1 << s[a];
				if (0 == (link[b] & abit))
				{
					numLink[b]++;	link[b] |= abit;
				}
				a=b;
			}
  		}

		Pair* pair=new Pair[netLen];
  		a=s[0];
  		for (int i=0;i<len;i++)
  		{
			U32 bit=1 << s[i];
			if (cmap & bit) { R-; cmap &= ~bit;}

			tail[i]=R;

			for (int z=1;z<26;z++) pair[i][z]=numLink[z];
			if (i>0)
			{
				U32 b=s[i];
				U32 bbit=1 << s[b];
				if (link[a] & bbit)
				{
					numLink[a]-;	link[a] &= ~bbit;
				}
				pair[i][a]=numLink[a];
				U32 abit=1 << s[a];
				if (link[b] & abit)
				{
					numLink[b]-;	link[b] &= ~abit;
				}
				pair[i][b]=numLink[b];
				a=b;
			}
  		}

  		for (int i=0;i<len;i++)
     		for (a=1;a<26;a++)
				tail[i]+=(pair[i][a])/8;
		delete [] pair;
	}

	int Len(){return netLen;}
	int Index(int i){return indexMap[i];}
	char* String(){return str;}
};

struct PartialState
// The PartialState represents a child node, or a "move" forward.
// It records the bounding box , the position in the grid, and
// miscellaneous items in preparation for the move.
struct PartialState {
	Rct	corners;	// 	of rectangle in grid
	Pnt		gridPos;	// 	x-y pos of last char placed in grid
	U16		misc;		//10+1+5 bits=vacancy+wasBlank+gridChar
	void Init(
		const Rct cs,
		const Pnt gp,
		const U32 ms)
	{
		corners=cs;
		gridPos=gp;
		misc=ms;
	}
	U32 Size(){return corners.Size();}
	U32 GridChar(){return misc & 0x1F;}
	U32 WasBlank(){return misc & 0x20;}
	U32 Vacancy() {return misc >> 6;}
	void SetGrid(){grid.Set(gridPos,GridChar());}
	void ClearGrid(){grid.Set(gridPos,0);}
};

struct State:PartialState
// The State struct expands the PartialState to include a pointer
// back up the tree (previous State) and the list of children.
struct State:PartialState {
	State*			prevState;
	int				numMoves;
	PartialState	move[8];//	up to 8 possible next states
	void Init(const char* s)
	{
		prevState=0;
		numMoves=0;
		Pnt corner0=grid.Center();
		Pnt corner1=corner0;
		corner1.GoDown();corner1.GoRight();
// first character, center of grid, 0 vacancy
		PartialState::Init(Rct(corner0,corner1),corner0,*s);
		SetGrid();
	}

	State* BackTrack()
// Backtrack to immediate parent.
	{
		if (WasBlank()) ClearGrid();
		return prevState;
	}

	State* BackTrack(int & index)
// Backtrack to the first parent that has any moves left.
	{
		State* S=this;
		do
		{
			index-;
			if (S->WasBlank()) S->ClearGrid();
			S=S->prevState;
		} while (S && (0 == S->numMoves));
		return S;
	}

	State* PlaceNextChar()
// typecasts the highest numbered move (partial state) to full state
//		and places the character in the grid
	{
		if (numMoves)
		{
			State* S = (State*)(&move[-numMoves]);
			S->prevState=this;
			S->numMoves=0;
			S->SetGrid();
			return S;
		}
		return 0;
	}

	State* Add5Moves(int bestSize,int tail,char ch)
// Used only at step two, i.e. for the third letter in the string
// For the third letter, 3 moves can be eliminated because of symmetry
	{
		Add1Move(bestSize,tail,ch,0,1);
		Add1Move(bestSize,tail,ch,1,1);
		Add1Move(bestSize,tail,ch,1,0);
		Add1Move(bestSize,tail,ch,-1,-1);
		Add1Move(bestSize,tail,ch,-1,0);
	return this;
	}

// Some code sequences as macros for clarity and to save listing space
#define OVERLAY														\
	{	int spill=tail-oldVacancy;							\
		U32 newSize=oldSize;									\
		if (spill>0) newSize+=spill;						\
		if (newSize < bestSize)								\
		{																		\
			move[numMoves++].Init(corners,newPos,	\
			(oldVacancy << 6) /* | 0 */ | ch);				\
			}																\
	}

#define CHECK_LEFT												\
	if (newPos.X() <  corners.Left()) 				\
	{																			\
		newCorners.ExpandLeft();								\
		vacancy+=newCorners.Height();					\
		newSize+=newCorners.Height();					\
	}

#define CHECK_RIGHT												\
	if (newPos.X() >=  corners.Right())	 			\
	{																			\
		newCorners.ExpandRight();							\
		vacancy+=newCorners.Height();					\
		newSize+=newCorners.Height();					\
	}

#define CHECK_TOP													\
	if (newPos.Y() < corners.Top()) 					\
	{																			\
		newCorners.ExpandTop();								\
		vacancy+=newCorners.Width();						\
		newSize+=newCorners.Width();						\
	}

#define CHECK_BOTTOM											\
	if (newPos.Y() >= corners.Bottom()) 			\
	{																			\
		newCorners.ExpandBottom();							\
		vacancy+=newCorners.Width();						\
		newSize+=newCorners.Width();						\
	}

#define FINISH														\
	{	int spill=tail-vacancy;								\
		if (spill>0) newSize+=spill; 					\
	    if (newSize < bestSize) 							\
	    {																	\
		move[numMoves++].Init(newCorners,newPos,	\
		(vacancy << 6) | kWasBlank | ch);			\
		}																		\
	}

	void Add1Move(int bestSize,int tail,char ch,int dx,int dy)
// Adds a single move.
	{
		U32 oldSize=corners.Size();
		U32 oldVacancy=Vacancy();

		Pnt newPos=gridPos;
		newPos.Shift(dx,dy);
		U32 oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;

			CHECK_LEFT else CHECK_RIGHT
			CHECK_TOP else CHECK_BOTTOM

			FINISH
		}

	}

	void Add8Moves_non_optimized(int bestSize,int tail,char ch)
// Adds all 8 possible moves.
// This function is replaced by the optimized version, below.
	{
		Add1Move(bestSize,tail,ch,0,1);
		Add1Move(bestSize,tail,ch,1,1);
		Add1Move(bestSize,tail,ch,1,0);
		Add1Move(bestSize,tail,ch,1,-1);
		Add1Move(bestSize,tail,ch,0,-1);
		Add1Move(bestSize,tail,ch,-1,-1);
		Add1Move(bestSize,tail,ch,-1,0);
		Add1Move(bestSize,tail,ch,-1,1);
	}

	void Add8Moves(int bestSize,int tail,char ch)
// Same functionality as Add8Moves_non_optimized, but inlined
//		and avoiding unnecessary box-corner tests: 35% faster
	{
		Pnt newPos=gridPos;
		U32 oldSize=corners.Size();
		U32 oldVacancy=Vacancy();

// move down
		newPos.GoDown();
		U32 oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_BOTTOM
			FINISH
		}

// move down and right
		newPos.GoRight();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_BOTTOM
			CHECK_RIGHT
			FINISH
		}

// move right
		newPos.GoUp();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_RIGHT
			FINISH
		}

// move up and right
		newPos.GoUp();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_TOP
			CHECK_RIGHT
			FINISH
		}

// move up
		newPos.GoLeft();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_TOP
			FINISH
		}

// move up and left
		newPos.GoLeft();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_TOP
			CHECK_LEFT
			FINISH
		}

// move left
		newPos.GoDown();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_LEFT
			FINISH
		}

// move down and left
		newPos.GoDown();
		oldC=grid.Value(newPos);
		if (oldC == ch) OVERLAY
		else if (oldC==0)
		{
			Rct newCorners=corners;
			U32 newSize=oldSize;
			U32 vacancy=oldVacancy-1;
			CHECK_BOTTOM
			CHECK_LEFT
			FINISH
		}
	}

	void SortMoves()
// Sorts by vacancy: lower vacancy moves go first (from top of stack)
	{
		for (int i=1;i<numMoves;i++)
		for (int j=0;j<i;j++)
			if (move[j].misc > move[i].misc)
			{
				double t=*((double*)(move+i));
				*((double*)(move+i))=*((double*)(move+j));
				*((double*)(move+j))=t;
			}
	}

	void CopyPoint(const int i,GridPoint pt[])
// Copies a single point to the result,
// mapping my grid's center to the result grids origin (0,0)
	{
		pt[i].x=gridPos.X()-kGridWidth/2;
		pt[i].y=gridPos.Y()-kGridHeight/2;
	}

	void CopySolution(const int len,
				/*const*/ PreProcess & pp,GridPoint pt[])
// Copies my grid point sequence to the result grid point array
// using the index mapping setup by the PreProcess object.

	{
		State* S=this;
		for (int k=len-1;k>=0;k-)
		{
			int i=pp.Index(k);
			S->CopyPoint(i,pt);
			S=S->prevState;
			if (S==0) break;	// safety catch
		}
	}
};

struct Solver
// The Solver object is the main actor to execute the tree search.
struct Solver {
	State*	states;
	int		stringLen;
	int		bestSize;
	Solver(PreProcess & pp) :
		states(new State[pp.netLen]),
		stringLen(pp.netLen),
		bestSize(pp.netLen+1)

// The constructor places the first character in the grid and
// computes the first move-list, containing only two moves
// (no need for the other possible 6 moves because of symmetry).
// Unfortunately, if one starts with the wrong one (of the two)
// one may not find the optimum solution box as quickly, but
// I have not been able to find a heuristic to make a good choice.

	{
		states[0].Init(pp.str);
		states[0].Add1Move(bestSize,pp.tail[1],pp.str[1],1,0);
		states[0].Add1Move(bestSize,pp.tail[1],pp.str[1],1,1);
	}

	~Solver(){delete [] states;}

	void GenerateSolution(const PreProcess & pp,GridPoint pt[]);
};

struct LoopTimer
// The loop timer uses LMGetTicks() to obtain an estimate of
// the average loop time, and then sets up the loop to run for
// one second at a time, until the elapsed time exceeds the
// time allowance, set by a constant (kTolerance).

struct LoopTimer {
	int loopCheck;
	int T0;
	int	elapsed;
	int	timeAllowance;
	LoopTimer() :
		loopCheck(kDefaultLoop),
		T0(LMGetTicks()),
		elapsed(0),
		timeAllowance(kTolerance*60) {}
	int AdjustLoop()

	{
		int t=LMGetTicks();
		int period=t-T0;
		T0=t;
		elapsed+=period;
		if (elapsed>timeAllowance) return 0;

		loopCheck=loopCheck*60/period;
		return loopCheck;
	}
};

Solver::GenerateSolution
void Solver::GenerateSolution(const PreProcess & 				pp,GridPoint pt[])

// The tree search function.
// Explores the solution tree until time runs out, or until
// all branches have been exhausted.

{
	int index=0;		// string index for the current state
	State* S=&states[0];
	int loopCounter=kDefaultLoop;
	LoopTimer loopTimer;

	do
	{
		if (-loopCounter == 0)
		{
			loopCounter=loopTimer.AdjustLoop();
			if (loopCounter==0)
			{
				while (S) S=S->BackTrack();
				break;// give up after kTolerance secs
			}
		}
		if (index>=stringLen-1) // have reached the end of the string
		{														// we get here only if size is better
			bestSize=S->Size();
			S->CopySolution(stringLen,
				/*added*/(PreProcess)/*end add*/pp,pt);
			S=S->BackTrack(index);
		}
		else
		{
			State* nextS=S->PlaceNextChar();
			if (nextS)
			{
				index++;
				S=nextS;

				if (index==1) // i.e. to place the 3rd character

	S->Add5Moves(bestSize,pp.tail[index+1],pp.str[index+1]);

				else

	S->Add8Moves(bestSize,pp.tail[index+1],pp.str[index+1]);

				S->SortMoves();
			}
			else S=S->BackTrack(index);// out of moves
		}
	} while (S);
}

Piper
void Piper(char *s,GridPoint pt[])
// External function published in the header file "Piper.h"
{
	PreProcess pp(s);
	if (pp.Len() <= 3) pp.TrivialSolution(pt);
	else
	{
		pp.ComputeProfile();
		Solver solve(pp);
		solve.GenerateSolution(pp,pt);
	}
}