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