Overview
License
Installation
Using a Windows Glk Program
Using Windows Glk with Visual C++
Using Windows Glk with Cygwin
Using Windows Glk with other C compilers
Start-up of a Windows Glk program
Windows specific Glk functions
Example Programs
Graphics and Sound Resources
Acknowledgements
Release History
This is a Windows implementation of Andrew Plotkin's Glk library specification, an attempt to define a portable API for text adventures, and more generally, any program with primarily textual input and output. It works with any version of Windows from Windows 95 onwards.
This help file describes the specifics of the Windows version of Glk, and should be read in conjunction with Andrew's Glk specification document. This and other relevant files on Glk can be found at the Interactive Fiction Archive, in the directory
http://www.ifarchive.org/indexes/if-archiveXprogrammingXglulx.html
and Andrew's Glk web page
http://www.eblong.com/zarf/glk/
The source code and compiled Glk DLL in this package are copyright 1998-2007 by David Kinder. You may copy and distribute both the source code and the compiled DLL 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 Glk web page.
Ogg Vorbis music resources are played using libogg and libvorbis by the Xiph.org Foundation. The license for these libraries is as follows:
Copyright (c) 2002, Xiph.org Foundation
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
- Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
- Neither the name of the Xiph.org Foundation nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
This Windows version of Glk is implemented as a dynamic link library Glk.dll, which should be in the same directory as the Glk application.
Windows Glk is aware of Windows XP's themes, and can display dialogs, etc. appropriately. However, in order for this to happen the Glk application must either have a manifest file with the same name as the executable (For example, for "Foo.exe" the manifest file would be "Foo.exe.manifest") or a manifest included in the application's resources. For a suitable manifest see the example programs.
Windows Glk can use Microsoft's Speech Engine API 4.0 to speak text. Microsoft's Speech Engine is often included with speech recognition software. If you have not got the engine installed, it can be downloaded from Microsoft:
http://www.microsoft.com/downloads/release.asp?ReleaseID=26299
Windows Glk does not work with version 5 of Microsoft's Speech Engine API.
Programs using Windows Glk appear to the user as a single Windows frame window containing child windows that correspond with the Glk definition of windows.
By default, Windows Glk adds a toolbar and menu to the frame window, which allows the user to bring up the options dialog, change font settings and review the previous output shown in text buffer windows. These options can also be accessed from the system menu (this is the menu which appears when single-clicking on the icon at the left of the title bar), which is the only means of access if toolbars and menus have been switched off in the options dialog.
If Microsoft's Speech Engine API 4.0 is installed, Windows Glk can speak the text printed in text buffer windows. If the Speech Engine is installed, a "Speech..." button is available on the Options dialog. This opens a further dialog in which speech can be switched on and a voice chosen for the speech.
To use Windows Glk with Microsoft Visual C++ (version 4 or later), use the AppWizard accessed by the File/New menu item to create a new Win32 application.
The application should include the file Glk.c and a file winglk_startup.c, which should contain an implementation of the function winglk_startup_code(). An example of this function is given in the example programs.
The application must also be linked with Glk.lib, which is the import library for Glk.dll.
To use Windows Glk with Cygwin's version of the GCC compiler (available from http://www.cygwin.com/), open a Cygwin Bash shell and generate an import library to link against:
dlltool --dllname=Glk.dll --def=Glk.def --output-lib=libglk.a
The application should include the file Glk.c and a file winglk_startup.c, which should contain an implementation of the function winglk_startup_code(). An example of this function is given in the example programs.
The application must also be linked with the library libglk.a; should not use the Cygwin DLL; and should be marked as being a Windows GUI application. For example, the command line to build the example model program under Cygwin is
gcc model.c winglk_startup.c Glk.c -o model -lglk -L. -mno-cygwin -mwindows
In general, how Windows Glk is used with other compilers is very dependant on that compiler. However, the following rules must be followed.
The application produced must be a standard Win32 application (not a Win32 console application), whose entry point is the WinMain() function.
The application should include the file Glk.c and a file winglk_startup.c, which should contain an implementation of the function winglk_startup_code(). An example of this function is given in the example programs.
The application must be linked with a suitable import library to ensure dynamic linking with Glk.dll. For most compilers a tool is supplied which takes a dynamic link library and produces a suitable import library (for Microsoft Visual C++ this tool is lib.exe; for Borland C++ it is implib.exe). The supplied import library Glk.lib is for Microsoft Visual C++, but may work with other compilers. For further information, you should consult your compiler documentation.
A Windows Glk program should include the source file Glk.c, which implements the WinMain() entry point into the program. The implementation of WinMain() initializes Glk.dll and checks that the version of Glk is suitable for the program. After this, the function winglk_startup_code() is called. This is a function that must be supplied by the author of the Windows Glk program, though at its simplest the function need not do anything at all.
Experienced Win32 developers may wish to implement their own WinMain() function, bypassing the normal Windows Glk startup code. If you do this, you should make sure that InitGlk() is called before glk_main().
The prototypes for all these functions can be obtained by including the file WinGlk.h. These functions are all implemented by Windows Glk, except for winglk_startup_code().
int winglk_startup_code(const char* cmdline)
This function must be supplied by the author of the Windows Glk program, and is called before glk_main() in order to allow platform specific initialization. The function should return zero if an error occurred, or a non-zero value if successful. The simplest implementation of the function is
int winglk_startup_code(const char* cmdline) { return 1; }The cmdline argument passed to winglk_startup_code() is a pointer to the command line with which the program was started up. See the example program WinGlkStart for an example of this routine which sets the application name and window title, then brings up a file dialog to request a file from the user.
This function is only called from within the WinMain() function in Glk.c. If you decide to write your own WinMain() (only recommended for experienced Win32 developers) then there is no need to supply the winglk_startup_code() function.
void winglk_app_set_name(const char* name)
Call this function to set the name of the Windows Glk program. This name is used as the title for the main window, and for storing user settings such as font and window size. This function should be called in winglk_startup_code(), e.g.
int winglk_startup_code(void) { winglk_app_set_name("Glk Example"); return 1; }void winglk_window_set_title(const char* title)
Call this function to change the window title. This function can be called at any point, either before or after the main window opens. It should be called after winglk_app_set_name().
void winglk_set_about_text(const char* text)
Call this function to set the text that appears in the first line of the About dialog box. The text should contain the name and version number of the application.
void winglk_set_menu_name(const char* name)
Call this function to set the name of the default Glk menu. The short cut key is indicated by a leading ampersand; for example, a name of "&Glulxe" produces the menu name Glulxe. The menu name is also used in the name of the menu item showing the About dialog, and in the text in that dialog.
void winglk_set_help_file(const char* filename)
Call this function to set the path of a HTMLHelp format help file. Calling this function causes a "Help" item to appear in the menu and a "Help" button on the toolbar.
const char* winglk_get_initial_filename(const char* cmdline, const char* title, const char* filter)
This function is designed to simplify writing startup code for a Windows Glk program. It examines the cmdline argument (which will usually be the cmdline argument passed to winglk_startup_code()) and attempts to extract a file name from it. If you don't want a command line string to be processed, just pass NULL for cmdline.
If a file name cannot be extracted from cmdline, a file dialog appears prompting the user for a file. The title argument will be used as the title of the file dialog, and the filter argument used as the file dialog's filter.
The filter string contains pairs of strings, the first part of which is the text describing the file type and the second is the actual filter. Each part is separated by a vertical bar and the end of the filter indicated by two vertical bars. For example, the filter string in Windows Glulxe is
"Glulx Files (.ulx;.blb;.blorb;.glb;.gblorb)|*.ulx;*.blb;*.blorb;*.glb;*.gblorb|All Files (*.*)|*.*||"The function returns a pointer to the file name if successful, or NULL. If the function does not return NULL, it will also use the filename to set the default filenames for calls to glk_fileref_create_by_prompt().
See the example program WinGlkStart for an example of this routine.
void winglk_set_resource_directory(const char* dir)
Call this function to change the directory from which Glk.dll will attempt to load resources. The default is the current directory for the program.
void winglk_set_gui(unsigned int id)
Call this function in winglk_startup_code() to set up any or all of a custom menu, a custom toolbar and a custom icon for the application's window. The function takes the numeric identifier of the menu, toolbar and icon in your application, e.g.
winglk_set_gui(IDR_EXAMPLE);When setting up menus and toolbars, you should keep resource identifiers below 0x7500 and command identifiers below 0xD000. This is not usually a problem as most development environments generate identifiers well below these values.
If the user selects a menu item or clicks on a toolbar button, your application will receive an event of type winglk_evtype_GuiInput. val1 will be the command identifier, and val2 zero.
See the example program WinGlkStart for an example of this routine.
void winglk_load_config_file(const char* gamename)
Call this function to load a Windows Glk configuration file appropriate to the given game file name. For example, if the function is passed an argument of "Photopia.blb", it will attempt to load a configuration file called "Photopia.cfg".
The configuration file is a text file where each line contains a key name, followed by an equals sign, then a value, e.g. "WindowBorders=no". Possible keys are:
WindowBorders=[yes/no] Turns on or off borders between Glk windows. WindowFrame=[yes/no] Turns on or off the Glk application window frame, that is, the title bar and the border around the whole window. WindowMask=[number] Uses the given Blorb resource number to set the mask for the window from the graphic. If a particular pixel in the graphic is white then the window is transparent at that point, else it is opaque. This key only takes effect if "WindowFrame=no". WindowWidth=[width] Sets the width of the Glk application window so that a single, full-size Glk window will have a width of the given value. WindowHeight=[height] Sets the height of the Glk application window so that a single, full-size Glk window will have a height of the given value. FontName=[font] Sets the font used for proportional text to the given font name, e.g. "Times New Roman". FontSize=[size] Sets the size of the font used for proportional text to the given value, measured in points. FixedFontName=[font] Sets the font used for fixed width text to the given font name. FixedFontSize=[size] Sets the size of the font used for fixed width text to the given value. strid_t winglk_stream_open_resource(const char* name, const char* type, glui32 rock)
This function opens a Glk memory stream using a resource. The first two arguments specify the name and type of the resource. For example, if data has been stored in the resources of the executable as "EXAMPLE" in the resource type "DATA", then the stream could be opened with rock value 1 by the following call:
strid_t str = winglk_stream_open_resource("EXAMPLE","DATA",1);void* winglk_get_resource_handle(void)
This function returns a handle to the resource module being used by Glk.dll. This is the resource handle of Glk.dll itself unless a translation is being used, in which case it is the resource handle of the translation DLL.
frefid_t winglk_fileref_create_by_name(glui32 usage, char *name, glui32 rock, int validate)
This function is the same as glk_fileref_create_by_name(), except that it takes an extra validate argument. If validate is non-zero then the name argument is validated to remove directory separator characters; if it is zero then the name argument is not checked.
void winglk_show_game_dialog(void)
This function tells Glk.dll to show the "About This Game" dialog when a Blorb file is set by a call to giblorb_set_resource_map(), provided that the Blorb file contains an "IFmd" chunk, and that the dialog has not been shown for this game before. If the "IFmd" chunk is present, an "About This Game" menu item is also added to the application's menu, the game's title is included in the title of the Windows Glulxe window, and an option to control whether the dialog is shown initially appears in the options dialog.
void sglk_set_basename(char *s)
This function sets the default filenames for calls to glk_fileref_create_by_prompt(), which may be useful if you do not use winglk_get_initial_filename() in your startup code. This function is part of L. Ross Raszewski's (the maintainer of DOS Glk) suggested additions to Glk.
The Examples directory contains three example programs. Model and Multiwin are generic Glk example programs written by Andrew Plotkin. WinGlkStart is a Windows Glk specific example, which demonstrates the common requirement of asking the user for a file name at startup.
If you have Visual C++, load up the workspace Examples.dsw, which contains each example as
a separate project.
If you are not using Visual C++, then for each example you need to compile the following
source files:
Model model.c, winglk_startup.c, Glk.c Multiwin multiwin.c, winglk_startup.c, Glk.c WinGlkStart WinGlkStart.c, Glk.c
where Glk.c is the standard Windows Glk source file in the main Glk directory. To create executables you will need to link all the source files in each example together and link along with a suitable import library for Glk.dll.
For example, with Cygwin, the command to build the model example would be:
gcc model.c winglk_startup.c Glk.c -o model -lglk -L. -mno-cygwin -Wl,--subsystem,windows
Windows Glk supports resources stored either in Blorb files or as separate files.
If a Glk program is to use resources from a Blorb file, the standard Blorb function giblorb_set_resource_map() (which is part of Glk.dll) must be called with the identifier of a stream opened on the Blorb file. If this is done then Windows Glk will first look for resources in the Blorb file.
If Windows Glk cannot find a requested resource in the Blorb file (or no Blorb file has been set up), it will look for a suitably named file in the current directory (or the directory specified by a call to winglk_set_resource_directory(), if such a call has been made).
If a resource was found in either the Blorb file or in a directory, it will be loaded. The resource formats currently supported are shown below, along with the filename for which Windows Glk will look if the resource is not in the Blorb file (as an example, the filename is for resource number 1):
Format Type Example Filename PNG image pic1.png JPEG image pic1.jpg AIFF sound snd1.aif or snd1.aiff MOD music mus1.mod OGGV music mus1.ogg
If PNG images have an alpha channel or transparency information, Windows Glk will use it. In graphics windows PNG images are alpha blended with the graphic window bitmap; in text buffer windows PNG images are alpha blended with the default background colour.
The user interface for Windows Glk has been translated into Spanish by Javier San José, and into Italian by Tommaso Caldarola.
Windows Glk uses the following libraries:
jpeglib by the Independent JPEG Group.
libpng by Guy Eric Schalnat, Andreas Dilger, Glenn Randers-Pehrson, and others.
zlib by Jean-loup Gailly and Mark Adler.
ModPlug by Olivier Lapicque.
libogg and libvorbis by the Xiph.org Foundation.
Windows Glk also contains source code written by Chris Maunder and Eran Yariv. The code that handles Ogg Vorbis music resources is based on code submitted by David Moreno.