programming/hugo/source/porting.txt

NOTES ON PORTING HUGO
---------------------

(Porters are encouraged to review these notes with each new source
release, as they will contain information on incorporating the latest
changes, as well as clarification of existing porting issues.)


LATEST (v2.5.01) NOTES:

1.  If you're using stub functions for things like hugo_displaypicture(),
hugo_playmusic(), etc., make sure to fclose() the supplied FILE pointer
since it is passed open.

2.  If compiling a non-v3.0 package (i.e., v2.5.0x), #define COMPILE_V25
in your makefile.


NOTES ON THE DISPLAY CHANGES (for v2.5):

I've done a lot of work on the display internals.  Windowing/text output
functions must now set/adhere to physical_windowtop, physical_windowleft,
etc., instead of the old WINDOWTOP, WINDOWLEFT.  (Although, of course,
to save on rewriting, a port can still set and use WINDOW...; it must
just also set physical_window... appropriately.)  The physical_window...
measurements are all ZERO-BASED, e.g. 0-79 for a character-based system,
0-639 for a pixel-based system, etc.  Depending on the type of output
being done, i.e., fixed-width character based or proportional-capable
pixel-based (or fixed-width pixel-based), character or pixel measurements
may be used.  However, these must be used consistently.

CHARWIDTH and LINEHEIGHT have been renamed FIXEDCHARWIDTH and
FIXEDLINEHEIGHT.  These should always be accurate measurements for the
nonproportional font.  charwidth and lineheight represent measurements
for the _currently selected_ font, the flags for which are always
reflected in currentfont.

Also, the hugo_settextpos(), hugo_settextwindow(), debug_settextpos(),
debug_windowsave(), debug_windowscroll(), and debug_windowshadow() functions
have all had their arguments reordered so that they're consistently (x, y)
or (x1, y1, x2, y2), as appropriate.

A quick skim through the "Display Control" section in HEBLANK.C might clarify
some of the changes that should hopefully make the incorporation of such things
as proportional printing about 200% easier.

A quick summary of changes/replacements is:

  Old				New
  ---				---
  SCREENLEFT, SCREENRIGHT	SCREENWIDTH, SCREENHEIGHT
  SCREENTOP, SCREENBOTTOM

  CHARWIDTH, LINEHEIGHT		charwidth, lineheight
				- of currentfont font

				FIXEDCHARWIDTH, FIXEDLINEHEIGHT
				- of fixed font, regardless of
				  currentfont selection

  WINDOWTOP, WINDOWBOTTOM,	- no longer required; may still be set
  WINDOWLEFT, WINDOWRIGHT	  and used by the port

  physical_window...		- must be set by the port as pixels
				  or characters; zero-based

  currentpos, currentline	currentpos, currentline (no change)

Next, a brief clarification on exactly what hugo_displaypicture() is
expected to do.  Basically, it loads a given JPEG image (stored in
a file which is opened _before_ passing to the function) and displays
it in the currently defined text window--i.e., physical_windowleft,
physical_windowtop, physical_windowright, and physical_windowbottom.
The image must be reduced to fit the window if necessary, but it
should not be enlarged.  In any case, the image should be centered
in the window.

My ports--i.e., the DOS and Windows versions--both use the IJG
JPEG decompression code.  It is up to the porter to look after determining
the quality of the decompressed image.  For example, the image quality
of the 16-bit DOS version is considerably lower than the 32-bit due
to tradeoffs in quality vs. increased speed.

There are new color constants--DEF_SLFCOLOR and DEF_SLBGCOLOR, default
colors for statusline foreground and background--that must be accounted
for by hugo_color().  See hedjgpp.c for an example.


ADDITIONAL NOTES:

Those interested in porting Hugo to different operating systems and computer
platforms should find the task relatively easy.

1.  The files HC.MAK (for the compiler), HE.MAK (for the engine), and
HD.MAK (for the debugger) are the makefiles for djgpp.  They should adapt
readily to other ports with minor modifications.

2.  If you're using a gcc variant, be sure to compile with the
'-fwritable-strings' switch.  Djgpp seems to survive without it, but its
omission has caused runtime errors with gcc under both Linux and OS/2.

3.  The debugger is largely a front-end for the engine allowing control
over runtime behavior.  Currently there exist a number of hooks in the
original engine source files (i.e., HE*.C) that are compiled only if
DEBUGGER is defined.  What this means is that when going back and forth
between the engine and the debugger, the HE*.C files will have to be
rebuilt each time.  On the positive side, however, the more complex
screen i/o of the debugger should have no impact on that of the engine,
so once the engine is successfully ported, there should be no need to
recompile it (at least not excessively) during porting of the debugger.

4.  HCHEADER.H, HEHEADER.H, and HDHEADER.H, while mostly comprising
routine prototypes and global variable definitions, also contain short
sections of conditional definitions that are included only if the
appropriate compiler is defined.  It will be necessary to add a similar
section to the start of each header file that makes the appropriate
definitions for the system in question.

5.  HCQUICKC.C, HEQUICKC.C, and HDQUICKC.C contain primarily i/o routines
for MS-DOS in general and QuickC in particular.  These functions will be
adapted or replaced entirely as part of the porting process.  These two
files will then be replaced in the new makefile with files containing
functions that accomplish the same tasks for the new system.  IOTEST.C
is a test file that isolates and tests the screen-output routines for the
engine.

6.  HEJPEG.C is another (somewhat) system-specific file used by the engine
for graphics initialization/display.  The only function called directly
by the engine proper is hugo_displaypicture(FILE *infile), and need only
read a JPEG image from the currently open file and display it in the
currently defined text window.  Although hugo_displaypicture() passed an
open file, it is responsible for closing it before returning, regardless
of success or failure.

7.  The existing ports for other systems (such as the Amiga port by David
Kinder, Bill Lash's gcc/curses port, and Colin Turnbull's port to the
Acorn RiscPC and Archimedes, or the author's own Win32 or Allegro ports)
are excellent resources to see where system-specific changes may need to
be implemented.  David's port is of particular note in that it replaces
almost all of the debugger's generic windowing/menu routines with Amiga
library calls.  The Win32 port successfully incorporates an event-driven
wrapper around the linear-running engine.

8.  The debugger's display/windowing system was built on the assumption
that at least 4 flippable or alternately selectable and otherwise
equivalent text pages/windows are available.

9.  It has arisen on a couple of occasions that the Hugo source code expects
an int to be 16 bits and a char to be signed.  While these situations have
largely been addressed, it is certainly more reliable to override the
default behavior of a compiler that is either 32-bit based and/or has
unsigned characters as the default.  Please report obvious or not-so-obvious
conflicts to the author.

10.  A stack size of 16,384 bytes is currently recommended for each of the
executables.

11. Hugo supports proper windowing.  The hugo_settextwindow() function
should now define a text window anywhere on the screen, with variable
left, top, right, and bottom parameters.  These parameters are supplied as
text-screen coordinates, and should be used by the port's display system
to contain text.  The port must set the physical_window_... parameters
as demonstrated in HEBLANK.C (see below).

13. Certain engine functions including hugo_settextposition(),
hugo_settextwindow(), hugo_clearfullscreen(), and hugo_clearwindow() are
responsible for setting variables such as FIXEDCHARWIDTH, FIXEDLINEHEIGHT,
and the physical_window_... variables, as well as other relevant variables
such as currentpos and currentline.  See HEBLANK.C for details.

14. Be sure when writing hugo_*(FILE *infile, ...) functions for
resources (such as hugo_displaypicture(), hugo_playmusic(), etc.) to
close infile before returning, since it is passed opened and positioned
(since the actual source of the resource can vary in terms of position,
file, etc.).

Porters are encouraged to contact me with any questions, concerns, or 
comments.


Kent Tessman  <tessman@interlog.com>