XGlk: X Windows Implementation of the Glk API. XGlk Library: version 0.4.11 Glk API which this implements: version 0.6.1. Designed by Andrew Plotkin http://www.eblong.com/zarf/glk/index.html This is source code for an implementation of the Glk library which runs under X windows. * Command-line arguments and X resources: XGlk can accept command-line arguments both for itself and on behalf of the underlying program. The ones it accepts for itself are taken both from X resources and from command-line options. See the PREFS file for complete information. * Bugs: Image display is experimental (read: "probably not broken, but I'm not guaranteeing anything".) Images only display on displays with 32 bits per pixel, 24, 16, 8, or 1 (monochrome.) On other displays, images just won't display. Nothing will appear at all, and glk_image_draw() will return false. (Note: "16" actually includes 15 bits per pixels (5 per color component), as well as the extremely weird NeXT color display, which has 12 bpp.) I've tested images on displays with all the above depths. However, I haven't tried a very wide range, nor have I tested each depth with both endiannesses. I would not be surprised to learn that it fails on some systems. If you see images displaying badly or not at all, please do "setenv XGLK_DEBUG", run the program again, and email me with (1) the command-line output, (2) your machine type and OS, (3) what you saw. Thanks. On 8-bit paletted displays, XGlk tries to allocate a 6x6x6 color cube (the Palette of the Beast), plus assorted text and border colors. If it can't get all of these, the display goes badly wrong. * Notes on building this mess: This is set up for a fairly generic ANSI C compiler. If you get it to compile under some particular system, please send me mail, and I'll stick in the relevant #ifdefs and whatnot. If your compiler can't find X11 headers or libraries, change the definitions of XLIB and XINCLUDE in the Makefile. There are some sample values there. If you find other values that work on particular operating systems, send me email. If your compiler can't find PNG headers or libraries, change the definitions of PNGLIB and PNGINCLUDE. If you don't have pnglib installed on your system at all, uncomment the definition of -DNO_PNG_AVAILABLE. I am told that pnglib version 0.96 is too old to work with XGlk. I've tested it with pnglib 1.0.1 and 1.0.3, both of which are fine. If your compiler can't find JPEG headers or libraries, change the definitions of JPEGLIB and JPEGINCLUDE. If you don't have libjpeg installed on your system at all, uncomment the definition of -DNO_JPEG_AVAILABLE. If you get errors in xio.c about fd_set or FD_SET being undefined, put "-DNEEDS_SELECT_H" in the SYSTEMFLAGS line, as has been done for the RS6000. There are a few compile-time options. These are defined in xglk_option.h. Before you compile, you should go into xglk_option.h and make any changes necessary. You may also need to edit some include and library paths in the Makefile. See the top of the Makefile for comments on installation. When you compile a Glk program and link it with GlkTerm, you must supply one more file: you must define a function called glkunix_startup_code(), and an array glkunix_arguments[]. These set up various Unix-specific options used by the Glk library. There is a sample "glkstart.c" file included in this package; you should modify it to your needs. The glkunix_arguments[] array is a list of command-line arguments that your program can accept. The library will sort these out of the command line and pass them on to your code. The array structure looks like this: typedef struct glkunix_argumentlist_struct { char *name; int argtype; char *desc; } glkunix_argumentlist_t; extern glkunix_argumentlist_t glkunix_arguments[]; In each entry, name is the option as it would appear on the command line (including the leading dash, if any.) The desc is a description of the argument; this is used when the library is printing a list of options. And argtype is one of the following constants: glkunix_arg_NoValue: The argument appears by itself. glkunix_arg_ValueFollows: The argument must be followed by another argument (the value). glkunix_arg_ValueCanFollow: The argument may be followed by a value, optionally. (If the next argument starts with a dash, it is taken to be a new argument, not the value of this one.) glkunix_arg_NumberValue: The argument must be followed by a number, which may be the next argument or part of this one. (That is, either "-width 20" or "-width20" will be accepted.) glkunix_arg_End: The glkunix_arguments[] array must be terminated with an entry containing this value. To accept arbitrary arguments which lack dashes, specify a name of "" and an argtype of glkunix_arg_ValueFollows. If you don't care about command-line arguments, you must still define an empty arguments list, as follows: glkunix_argumentlist_t glkunix_arguments[] = { { NULL, glkunix_arg_End, NULL } }; Here is a more complete sample list: glkunix_argumentlist_t glkunix_arguments[] = { { "", glkunix_arg_ValueFollows, "filename: The game file to load." }, { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." }, { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on the NUM, if given)." }, { "-goo", glkunix_arg_NoValue, "-goo: Find goo." }, { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." }, { NULL, glkunix_arg_End, NULL } }; This would match the arguments "thingfile -goo -wob8 -bom -hum song". After the library parses the command line, it does various occult rituals of initialization, and then calls glkunix_startup_code(). int glkunix_startup_code(glkunix_startup_t *data); This should return TRUE if everything initializes properly. If it returns FALSE, the library will shut down without ever calling your glk_main() function. The data structure looks like this: typedef struct glkunix_startup_struct { int argc; char **argv; } glkunix_startup_t; The fields are a standard Unix (argc, argv) list, which contain the arguments you requested from the command line. In deference to custom, argv[0] is always the program name. You can put other startup code in glkunix_startup_code(). This should generally be limited to finding and opening data files. There are a few Unix Glk library functions which are convenient for this purpose: strid_t glkunix_stream_open_pathname(char *pathname, glui32 textmode, glui32 rock); This opens an arbitrary file, in read-only mode. Note that this function is *only* available during glkunix_startup_code(). It is inherent non-portable; it should not and cannot be called from inside glk_main(). void glkunix_set_base_file(char *filename); This sets the library's idea of the "current directory" for the executing program. The argument should be the name of a file (not a directory). When this is set, fileref_create_by_name() will create files in the same directory as that file, and create_by_prompt() will base default filenames off of the file. If this is not called, the library works in the Unix current working directory, and picks reasonable default defaults. * Notes on the source code: Functions which begin with glk_ are, of course, Glk API functions. These are declared in glk.h. Functions which begin with gli_, xglk_, and other prefixes are internal to the XGlk library implementation. They don't exist in every Glk library, because different libraries implement things in different ways. (In fact, they may be declared differently, or have different meanings, in different Glk libraries.) These gli_ functions (and other internal constants and structures) are declared in xg_internal.h and xglk.h. As you can see from the code, I've kept a policy of catching every error that I can possibly catch, and printing visible warnings. Thanks to Torbjorn Andersson for monochrome display patches. * Permissions The source code in this package is copyright 1998-9 by Andrew Plotkin. You may copy and distribute it freely, by any means and under any conditions, as long as the code and documentation is not changed. You may also incorporate this code into your own program and distribute that, or modify this code and use and distribute the modified version, as long as you retain a notice in your program or documentation which mentions my name and the URL shown above. * Version history: 0.4.11: Upgraded to Glk API version 0.6.1; i.e., a couple of new gestalt selectors. Fixed dispatch bug for glk_get_char_stream. 0.4.10: Fixed a couple of display bugs (one that could cause freezes) 0.4.9: Added hyperlink code, and other changes for Glk 0.6.0. Improved mouse-clicking code for textgrids. 0.4.8: Changed the default save game name to "game.sav". Added "-defprompt" switch, to suppress default file names. Added glkunix_set_base_file(). Added support for function keys. 0.4.7: Fixed a small bug in image code, sometimes prevented JPEGs from loading. 0.4.6: Fixed various problems with Blorb support. 0.4.5: Added JPEG image support. 0.4.4: Updated for Glk API 0.5.2; that is, added sound channel stubs. Made the license a bit friendlier. 0.4.3, 0.4.2: Image display slowly nears acceptable functionality. 0.4.1: Fixed display of images on 8-bit displays. Also added a -ditherimage switch and resource (default is "true") Fixed text flowing around margin images. 0.4: Updated for Glk API 0.5.1. 0.3: Updated for Glk API 0.5. 0.2: The one true Unix Glk Makefile system. Startup code and command-line argument system. 0.1 alpha: initial release.