X-Git-Url: https://git.stderr.nl/gitweb?p=rodin%2Fchimara.git;a=blobdiff_plain;f=libchimara%2Fdoc.c;h=cb20d6e8f15ca3f83e8a479b8324c5d0e4ad49cc;hp=2b603733e8705f11e326015d02d8b6481fd944a9;hb=7ef4ef1fecab7ae0f724e59f7de1315a96822152;hpb=0b85f1dd5993e2ed111ec2ba13bbbb4ebda06ada diff --git a/libchimara/doc.c b/libchimara/doc.c index 2b60373..cb20d6e 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -7,7 +7,7 @@ /** * SECTION:glk-exiting * @short_description: How to terminate a Glk program cleanly - * @include: glk.h + * @include: libchimara/glk.h * * A Glk program usually ends when the end of the glk_main() function is * reached. You can also terminate it earlier. @@ -17,7 +17,7 @@ * SECTION:glk-interrupt * @short_description: Specifying an interrupt handler for cleaning up critical * resources - * @include: glk.h + * @include: libchimara/glk.h * * Most platforms have some provision for interrupting a program — * command @@ -34,7 +34,7 @@ /** * SECTION:glk-tick * @short_description: Yielding time to the operating system - * @include: glk.h + * @include: libchimara/glk.h * * Many platforms have some annoying thing that has to be done every so often, * or the gnurrs come from the voodvork out and eat your computer. @@ -48,7 +48,7 @@ /** * SECTION:glk-types * @short_description: Basic types used in Glk - * @include: glk.h + * @include: libchimara/glk.h * * For simplicity, all the arguments used in Glk calls are of a very few types. * @@ -96,7 +96,7 @@ /** * SECTION:glk-opaque-objects * @short_description: Complex objects in Glk - * @include: glk.h + * @include: libchimara/glk.h * * Glk keeps track of a few classes of special objects. These are opaque to your * program; you always refer to them using pointers to opaque C structures. @@ -230,7 +230,7 @@ /** * SECTION:glk-gestalt * @short_description: Testing Glk's capabilities - * @include: glk.h + * @include: libchimara/glk.h * * The gestalt mechanism (cheerfully stolen from the Mac OS) is a * system by which the Glk API can be upgraded without making your life @@ -247,7 +247,7 @@ /** * SECTION:glk-character-input * @short_description: Waiting for a single keystroke - * @include: glk.h + * @include: libchimara/glk.h * * You can request that the player hit a single key. See Character Input Events. @@ -277,7 +277,7 @@ * action="simul">controlI * code when the tab key is * pressed. The Glk library, if it can recognize this at all, will generate a - * #keycode_Tab event (value 0xFFFFFFF7) when this occurs. + * %keycode_Tab event (value 0xFFFFFFF7) when this occurs. * Therefore, for these keyboards, no keyboard key will generate a controlI * event (value 9.) The Glk library will probably map many of the @@ -290,7 +290,7 @@ * legal. The idea is, however, that if your program asks the player to * press the tab * key, you should check for a - * #keycode_Tab event as opposed to a %keycode_Tab event as opposed to a control * I event. * @@ -307,7 +307,7 @@ * purposes of the interface. For example, the Mac Glk library reserves the * tab key for switching between different Glk * windows. Therefore, on the Mac, the library will never generate a - * #keycode_Tab event or a + * %keycode_Tab event or a * controlI * event. * @@ -316,8 +316,8 @@ * function="control">controlJ * character, which is the only printable control character, is probably not * typable. This is because, in most libraries, it will be converted to - * #keycode_Return. Again, you should check for - * #keycode_Return if your program asks the player to + * %keycode_Return. Again, you should check for + * %keycode_Return if your program asks the player to * press the return * key. * @@ -334,13 +334,13 @@ * large problem. * * - * You can test for this by using the #gestalt_CharInput selector. + * You can test for this by using the %gestalt_CharInput selector. * * * Glk porters take note: it is not a goal to be able to generate every * single possible key event. If the library says that it can generate a * particular keycode, then game programmers will assume that it is - * available, and ask players to use it. If a #keycode_Home + * available, and ask players to use it. If a %keycode_Home * event can only be generated by typing escapecontrolA @@ -348,7 +348,7 @@ * when the game says Press the home key to see the next * hint. It is better for the library to say that it - * cannot generate a #keycode_Home event; that way the game + * cannot generate a %keycode_Home event; that way the game * can detect the situation and ask the user to type H * instead. * @@ -359,14 +359,14 @@ * (the game programmer) should not depend on them. You must be certain to * check for the ones you want to use, including the arrow keys and return, and be prepared to use different keys in - * your interface if #gestalt_CharInput says they are not available. + * your interface if %gestalt_CharInput says they are not available. * */ /** * SECTION:glk-case * @short_description: Changing the case of strings - * @include: glk.h + * @include: libchimara/glk.h * * Glk has functions to manipulate the case of both Latin-1 and Unicode strings. * One Latin-1 lowercase character corresponds to one uppercase character, and @@ -377,7 +377,7 @@ /** * SECTION:glk-window-opening * @short_description: Creating new windows and closing them - * @include: glk.h + * @include: libchimara/glk.h * * You can open a new window using glk_window_open() and close it again using * glk_window_close(). @@ -386,7 +386,7 @@ /** * SECTION:glk-window-constraints * @short_description: Manipulating the size of a window - * @include: glk.h + * @include: libchimara/glk.h * * There are library functions to change and to measure the size of a window. */ @@ -394,7 +394,7 @@ /** * SECTION:glk-window-types * @short_description: Blank, pair, text grid, text buffer, and graphics windows - * @include: glk.h + * @include: libchimara/glk.h * * A technical description of all the window types, and exactly how they behave. */ @@ -402,7 +402,7 @@ /** * SECTION:glk-echo-streams * @short_description: Creating a copy of a window's output - * @include: glk.h + * @include: libchimara/glk.h * * Every window has an associated window stream; you print to the window by * printing to this stream. However, it is possible to attach a second stream to @@ -446,7 +446,7 @@ /** * SECTION:glk-window-other * @short_description: Miscellaneous functions for windows - * @include: glk.h + * @include: libchimara/glk.h * * This section contains functions for windows that don't fit anywhere else. */ @@ -454,7 +454,7 @@ /** * SECTION:glk-events * @short_description: Waiting for events - * @include: glk.h + * @include: libchimara/glk.h * * As described in Your * Program's Main Function, all player input is handed to your program by @@ -465,27 +465,91 @@ /** * SECTION:glk-character-input-events * @short_description: Events representing a single keystroke - * @include: glk.h + * @include: libchimara/glk.h * * You can request character input from text buffer and text grid windows. See - * #evtype_CharInput. There are separate functions for requesting Latin-1 input - * and Unicode input; see #gestalt_Unicode. + * %evtype_CharInput. There are separate functions for requesting Latin-1 input + * and Unicode input; see %gestalt_Unicode. */ /** * SECTION:glk-line-input-events * @short_description: Events representing a line of user input - * @include: glk.h + * @include: libchimara/glk.h * * You can request line input from text buffer and text grid windows. See - * #evtype_LineInput. There are separate functions for requesting Latin-1 input - * and Unicode input; see #gestalt_Unicode. + * %evtype_LineInput. There are separate functions for requesting Latin-1 input + * and Unicode input; see %gestalt_Unicode. */ +/** + * SECTION:glk-mouse-events + * @short_description: Events representing a mouse click + * @include: libchimara/glk.h + * + * On some platforms, Glk can recognize when the mouse (or other pointer) is + * used to select a spot in a window. You can request mouse input only in text + * grid windows and graphics windows. + * + * A window can have mouse input and character/line input pending at the same + * time. + * + * If the player clicks in a window which has a mouse input event pending, + * glk_select() will return an event whose type is %evtype_MouseInput. Again, + * once this happens, the request is complete, and you must request another if + * you want further mouse input. + * + * In the event structure, @win tells what window the event came from. + * + * In a text grid window, the @val1 and @val2 fields are the x and y coordinates + * of the character that was clicked on. + * So @val1 is the column, and @val2 is the row. + * The top leftmost character is considered to be (0,0). + * + * In a graphics window, they are the x and y coordinates of the pixel that was + * clicked on. Again, the top left corner of the window is (0,0). + * + * + * Most mouse-based idioms define standard functions for mouse hits in text + * windows — typically selecting or copying text. It is up to the + * library to separate this from Glk mouse input. The library may choose to + * select text when it is clicked normally, and cause Glk mouse events when + * text is control-clicked. Or the other way around. Or it may be the + * difference between clicking and double-clicking. Or the library may + * reserve a particular mouse button, on a multi-button mouse. It may even + * specify a keyboard key to be the "mouse button", referring to wherever the + * mouse cursor is when the key is hit. Or some even more esoteric positioning + * system. You need only know that the user can do it, or not. + * + * + * However, since different platforms will handle this issue differently, you + * should be careful how you instruct the player in your program. Do not tell + * the player to double-click, right-click, or + * control-click in a window. The preferred term is to + * touch the window, or a spot in the window. + * + * + * Goofy, but preferred. + * + */ + +/** + * SECTION:glk-timer-events + * @short_description: Events sent at fixed intervals + * @include: libchimara/glk.h + * + * You can request that an event be sent at fixed intervals, regardless of what + * the player does. Unlike input events, timer events can be tested for with + * glk_select_poll() as well as glk_select(). + * + * It is possible that the library does not support timer events. You can check + * this with the %gestalt_Timer selector. + */ + /** * SECTION:glk-streams * @short_description: Input and output abstractions - * @include: glk.h + * @include: libchimara/glk.h * * All character output in Glk is done through streams. Every window has an * output stream associated with it. You can also write to files on disk; every @@ -554,7 +618,7 @@ /** * SECTION:glk-print * @short_description: Printing to streams - * @include: glk.h + * @include: libchimara/glk.h * * You can print Latin-1 and Unicode characters, null-terminated strings, or * buffers to any stream. The characters will be converted into the appropriate @@ -564,7 +628,7 @@ /** * SECTION:glk-read * @short_description: Reading from streams - * @include: glk.h + * @include: libchimara/glk.h * * You can read Latin-1 or Unicode characters, buffers, or whole lines from any * stream. The characters will be converted into the form in which you request @@ -574,7 +638,7 @@ /** * SECTION:glk-closing-streams * @short_description: Closing streams and retrieving their character counts - * @include: glk.h + * @include: libchimara/glk.h * * When you close a Glk stream, you have the opportunity to examine the * character counts — the number of characters written to or read from the @@ -584,7 +648,7 @@ /** * SECTION:glk-stream-positions * @short_description: Moving the read/write mark - * @include: glk.h + * @include: libchimara/glk.h * * You can set the position of the read/write mark in a stream. * @@ -594,15 +658,140 @@ * */ +/** + * SECTION:glk-styles + * @short_description: Changing the appearance of printed text + * @include: libchimara/glk.h + * + * You can send style-changing commands to an output stream. After a style + * change, new text which is printed to that stream will be given the new style, + * whatever that means for the stream in question. For a window stream, the text + * will appear in that style. For a memory stream, style changes have no effect. + * For a file stream, if the machine supports styled text files, the styles may + * be written to the file; more likely the style changes will have no effect. + * + * Styles are exclusive. A character is shown with exactly one style, not a + * subset of the possible styles. + * + * + * Note that every stream and window has its own idea of the current + * style. Sending a style command to one window or stream does not + * affect any others. + * + * + * Except for a window's echo stream; see Echo Streams. + * + * + * The styles are intended to distinguish meaning and use, not formatting. There + * is no standard definition of what each style will look like. That is left up + * to the Glk library, which will choose an appearance appropriate for the + * platform's interface and the player's preferences. + * + * There are currently eleven styles defined. More may be defined in the future. + * + * Styles may be distinguished on screen by font, size, color, indentation, + * justification, and other attributes. Note that some attributes (notably + * justification and indentation) apply to entire paragraphs. If possible and + * relevant, you should apply a style to an entire paragraph — call + * glk_set_style() immediately after printing the newline at the beginning of + * the text, and do the same at the end. + * + * + * For example, %style_Header may well be centered text. If you print + * Welcome to Victim (a short interactive mystery), and only the + * word Victim is in the %style_Header, the center-justification + * attribute will be lost. Similarly, a block quote is usually indented on both + * sides, but indentation is only meaningful when applied to an entire line or + * paragraph, so block quotes should take up an entire paragraph. Contrariwise, + * %style_Emphasized need not be used on an entire paragraph. It is often used + * for single emphasized words in normal text, so you can expect that it will + * appear properly that way; it will be displayed in italics or underlining, + * not center-justified or indented. + * + * + * + * Yes, this is all a matter of mutual agreement between game authors and game + * players. It's not fixed by this specification. That's natural language for + * you. + * + */ + +/** + * SECTION:glk-stylehints + * @short_description: Setting style hints + * @include: libchimara/glk.h + * + * There are no guarantees of how styles will look, but you can make + * suggestions. + * + * Initially, no hints are set for any window type or style. Note that having no + * hint set is not the same as setting a hint with value 0. + * + * These functions do not affect + * existing windows. They affect the windows which you + * create subsequently. If you want to set hints for all your game windows, call + * glk_stylehint_set() before you start creating windows. If you want different + * hints for different windows, change the hints before creating each window. + * + * + * This policy makes life easier for the interpreter. It knows everything about + * a particular window's appearance when the window is created, and it doesn't + * have to change it while the window exists. + * + * + * Hints are hints. The interpreter may ignore them, or give the player a choice + * about whether to accept them. Also, it is never necessary to set hints. You + * don't have to suggest that %style_Preformatted be fixed-width, or + * %style_Emphasized be boldface or italic; they will have appropriate defaults. + * Hints are for situations when you want to change the + * appearance of a style from what it would ordinarily be. The most common case + * when this is appropriate is for the styles %style_User1 and %style_User2. + * + * There are currently ten style hints defined. More may be defined in the + * future. + * + * Again, when passing a style hint to a Glk function, any value is actually + * legal. If the interpreter does not recognize the stylehint value, it will + * ignore it. + * + * This policy allows for the future definition of style hints without breaking + * old Glk libraries. + * + */ + +/** + * SECTION:glk-style-measure + * @short_description: Finding out how the library displays your style hints + * @include: libchimara/glk.h + * + * You can suggest the appearance of a window's style before the window is + * created; after the window is created, you can test the style's actual + * appearance. These functions do not test the style hints; they test the + * attribute of the style as it appears to the player. + * + * Note that although you cannot change the appearance of a window's styles + * after the window is created, the library can. A platform may support dynamic + * preferences, which allow the player to change text formatting while your + * program is running. + * + * Changes that affect window size (such as font size changes) will be + * signalled by an %evtype_Arrange event. However, more subtle changes (such + * as text color differences) are not signalled. If you test the appearance of + * styles at the beginning of your program, you must keep in mind the + * possibility that the player will change them later. + * + */ + /** * SECTION:glk-stream-types * @short_description: Window, memory, and file streams - * @include: glk.h + * @include: libchimara/glk.h * * Window Streams * * Every window has an output stream associated with it. This is created - * automatically, with #filemode_Write, when you open the window. You get it + * automatically, with %filemode_Write, when you open the window. You get it * with glk_window_get_stream(). * * A window stream cannot be closed with glk_stream_close(). It is closed @@ -665,7 +854,7 @@ /** * SECTION:glk-stream-other * @short_description: Miscellaneous functions for streams - * @include: glk.h + * @include: libchimara/glk.h * * This section includes functions for streams that don't fit anywhere else. */ @@ -673,7 +862,7 @@ /** * SECTION:glk-fileref * @short_description: A platform-independent way to refer to disk files - * @include: glk.h + * @include: libchimara/glk.h * * You deal with disk files using file references. Each fileref is an opaque C * structure pointer; see Opaque @@ -701,15 +890,15 @@ * In general, you should use text mode if the player expects to read the file * with a platform-native text editor; you should use binary mode if the file is * to be read back by your program, or if the data must be stored exactly. Text - * mode is appropriate for #fileusage_Transcript; binary mode is appropriate for - * #fileusage_SavedGame and probably for #fileusage_InputRecord. #fileusage_Data + * mode is appropriate for %fileusage_Transcript; binary mode is appropriate for + * %fileusage_SavedGame and probably for %fileusage_InputRecord. %fileusage_Data * files may be text or binary, depending on what you use them for. */ /** * SECTION:glk-fileref-types * @short_description: Four different ways to create a file reference - * @include: glk.h + * @include: libchimara/glk.h * * There are four different functions for creating a fileref, depending on how * you wish to specify it. Remember that it is always possible that a fileref @@ -719,12 +908,280 @@ /** * SECTION:glk-fileref-other * @short_description: Miscellaneous functions for file references - * @include: glk.h + * @include: libchimara/glk.h * * This section includes functions for file references that don't fit anywhere * else. */ +/** + * SECTION:glk-image-resources + * @short_description: Graphics in Glk + * @include: libchimara/glk.h + * + * In accordance with this modern age, Glk provides for a modicum of graphical + * flair. It does not attempt to be a complete graphical toolkit. Those already + * exist. Glk strikes the usual uncomfortable balance between power, + * portability, and ease of implementation: commands for arranging pre-supplied + * images on the screen and intermixed with text. + * + * Graphics is an optional capability in Glk; not all libraries support + * graphics. This should not be a surprise. + * + * Most of the graphics commands in Glk deal with image resources. Your program + * does not have to worry about how images are stored. Everything is a resource, + * and a resource is referred to by an integer identifier. You may, for example, + * call a function to display image number 17. The format, loading, and + * displaying of that image is entirely up to the Glk library for the platform + * in question. + * + * Of course, it is also desirable to have a platform-independent way to store + * sounds and images. Blorb is the official resource-storage format of Glk. A + * Glk library does not have to understand Blorb, but it is more likely to + * understand Blorb than any other format. + * + * + * Glk does not specify the exact format of images, but Blorb does. Images in + * a Blorb archive must be PNG or JPEG files. More formats may be added if + * real-world experience shows it to be desirable. However, that is in the + * domain of the Blorb specification. The Glk spec, and Glk programming, will + * not change. + * + * + * At present, images can only be drawn in graphics windows and text buffer + * windows. In fact, a library may not implement both of these possibilities. + * You should test each with the %gestalt_DrawImage selector if you plan to use + * it. See Testing for + * Graphics Capabilities. + */ + +/** + * SECTION:glk-graphics-windows + * @short_description: Drawing graphics in graphics windows + * @include: libchimara/glk.h + * + * A graphics window is a rectangular canvas of pixels, upon which you can draw + * images. The contents are entirely under your control. You can draw as many + * images as you like, at any positions — overlapping if you like. If the + * window is resized, you are responsible for redrawing everything. See Graphics Windows. + * + * + * Note that graphics windows do not support a full set of object-drawing + * commands, nor can you draw text in them. That may be available in a future + * Glk extension. For now, it seems reasonable to limit the task to a single + * primitive, the drawing of a raster image. And then there's the ability to + * fill a rectangle with a solid color — a small extension, and + * hopefully no additional work for the library, since it can already clear + * with arbitrary background colors. In fact, if glk_window_fill_rect() did + * not exist, an author could invent it — by briefly setting the + * background color, erasing a rectangle, and restoring. + * + * + * If you call glk_image_draw() or glk_image_draw_scaled() in a graphics window, + * @val1 and @val2 are interpreted as X and Y coordinates. The image will be + * drawn with its upper left corner at this position. + * + * It is legitimate for part of the image to fall outside the window; the excess + * is not drawn. Note that these are signed arguments, so you can draw an image + * which falls outside the left or top edge of the window, as well as the right + * or bottom. + * + * There are a few other commands which apply to graphics windows. + */ + +/** + * SECTION:glk-graphics-text + * @short_description: Drawing graphics inside or beside text + * @include: libchimara/glk.h + * + * A text buffer is a linear text stream. You can draw images in-line with this + * text. If you are familiar with HTML, you already understand this model. You + * draw images with flags indicating alignment. The library takes care of + * scrolling, resizing, and reformatting text buffer windows. + * + * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer + * window, @val1 gives the image alignment. The @val2 argument is currently + * unused, and should always be zero. + */ + +/** + * SECTION:glk-graphics-testing + * @short_description: Checking whether the library supports graphics + * @include: libchimara/glk.h + * + * Before calling Glk graphics functions, you should use the gestalt selector + * %gestalt_Graphics. To test for additional capabilities, you can also use the + * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors. + */ + +/** + * SECTION:glk-creating-hyperlinks + * @short_description: Printing text as a hyperlink + * @include: libchimara/glk.h + * + * Some games may wish to mark up text in their windows with hyperlinks, which + * can be selected by the player — most likely by mouse click. Glk allows + * this in a manner similar to the way text styles are set. + * + * Hyperlinks are an optional capability in Glk. + */ + +/** + * SECTION:glk-accepting-hyperlinks + * @short_description: Generating and catching hyperlink navigation events + * @include: libchimara/glk.h + */ + +/** + * SECTION:glk-hyperlinks-testing + * @short_description: Checking whether the library supports hyperlinks + * @include: libchimara/glk.h + * + * Before calling Glk hyperlink functions, you should use the gestalt selectors + * %gestalt_Hyperlinks and %gestalt_HyperlinkInput. + */ + +/** + * SECTION:dispatch-interrogating + * @short_description: Finding out what functions the Glk library exports + * @include: libchimara/glk.h, libchimara/gi_dispa.h + * + * These are the ancilliary functions that let you enumerate. + */ + +/** + * SECTION:dispatch-dispatching + * @short_description: Dispatching the call to the Glk library + * @include: libchimara/glk.h, libchimara/gi_dispa.h + */ + +/** + * SECTION:dispatch-prototypes + * @short_description: Querying Glk function prototypes + * @include: libchimara/glk.h, libchimara/gi_dispa.h + * + * There are many possible ways to set up a #gluniversal_t array, and it's + * illegal to call gidispatch_call() with an array which doesn't match the + * function. Furthermore, some references are passed in, some passed out, and + * some both. How do you know how to handle the argument list? + * + * One possibility is to recognize each function selector, and set up the + * arguments appropriately. However, this entails writing special code for each + * Glk function; which is exactly what we don't want to do. + * + * Instead, you can call gidispatch_prototype(). + */ + +/** + * SECTION:dispatch-library-functions + * @short_description: Platform-dependent dispatch layer functions + * @include: libchimara/glk.h, libchimara/gi_dispa.h + * + * Ideally, the three layers — program, dispatch layer, Glk library + * — would be completely modular; each would refer only to the layers + * beneath it. Sadly, there are a few places where the library must notify the + * program that something has happened. Worse, these situations are only + * relevant to programs which use the dispatch layer, and then only some of + * those. + * + * Since C is uncomfortable with the concept of calling functions which may not + * exist, Glk handles this with call-back function pointers. The program can + * pass callbacks in to the library; if it does, the library will call them, and + * if not, the library doesn't try. + * + * These callbacks are optional, in the sense that the program may or may not + * set them. However, any library which wants to interoperate with the dispatch + * layer must allow the program to set them; it is the + * program's choice. The library does this by implementing + * set_registry functions — the functions to which the + * program passes its callbacks. + * + * + * Even though these callbacks and the functions to set them are declared in + * gi_dispa.h, they are not defined in + * gi_dispa.c. The dispatch layer merely coordinates + * them. The program defines the callback functions; the library calls them. + * + */ + +/** + * SECTION:blorb-program + * @short_description: How to use the Blorb layer in your program + * @include: libchimara/glk.h, libchimara/gi_blorb.h + * + * If you wish your program to load its resources from a Blorb file, you need to + * find and open that file in your startup code. (See Startup Options.) Each platform will + * have appropriate functions available for finding startup data. Be sure to + * open the file in binary mode, not text mode. Once you have opened the file as + * a Glk stream, pass it to giblorb_set_resource_map(). + * + * If you do not call giblorb_set_resource_map() in your startup code, or if it + * fails, the library is left to its own devices for finding resources. Some + * libraries may try to load resources from individual files — + * PIC1, PIC2, + * PIC3, and so on. (See the Blorb specification for more + * on this approach.) Other libraries will not have any other loading mechanism + * at all; no resources will be available. + */ + +/** + * SECTION:blorb-layer + * @short_description: The platform-independent functions in the Blorb layer + * @include: libchimara/glk.h, libchimara/gi_blorb.h + * + * These are the functions which are implemented in + * gi_blorb.c. They will be compiled into the library, but + * they are the same on every platform. In general, only the library needs to + * call these functions. The Glk program should allow the library to do all the + * resource handling. + */ + +/** + * SECTION:blorb-errors + * @short_description: Error codes returned by the Blorb layer functions + * @include: libchimara/glk.h, libchimara/gi_blorb.h + * + * All Blorb layer functions, including giblorb_set_resource_map(), return the + * following error codes. + */ + +/** + * SECTION:glkext-startup + * @short_description: Parsing startup options + * @include: libchimara/glk.h, libchimara/glkstart.h + * + * This section describes an extension to Glk for parsing command-line startup + * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and + * GlkTerm. + * + * When you compile a Glk program, you may 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. + * + * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]| + * + * 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. + */ + +/** + * SECTION:glkext-unix + * @short_description: Unix-specific functions + * @include: libchimara/glk.h, libchimara/glkstart.h + * + * This section describes an extension to Glk for various Unix functions. It was + * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm. + * + * 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. + */ + /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/ /** @@ -743,7 +1200,44 @@ * GLK_MODULE_UNICODE: * * If this preprocessor symbol is defined, so are all the Unicode functions and - * constants (see #gestalt_Unicode). If not, not. + * constants (see %gestalt_Unicode). If not, not. + */ + +/** + * GLK_MODULE_IMAGE: + * + * If you are writing a C program, there is an additional complication. A + * library which does not support graphics may not implement the graphics + * functions at all. Even if you put gestalt tests around your graphics calls, + * you may get link-time errors. If the glk.h file is so old that it does not declare + * the graphics functions and constants, you may even get compile-time errors. + * + * To avoid this, you can perform a preprocessor test for the existence of + * %GLK_MODULE_IMAGE. If this is defined, so are all the functions and constants + * described in this section. If not, not. + * + * + * To be extremely specific, there are two ways this can happen. If the + * glk.h file that comes with the + * library is too old to have the graphics declarations in it, it will of + * course lack %GLK_MODULE_IMAGE as well. If the glk.h file is recent, but the library is old, + * the definition of %GLK_MODULE_IMAGE should be removed from glk.h, to avoid link errors. This is not a + * great solution. A better one is for the library to implement the graphics + * functions as stubs that do nothing (or cause run-time errors). Since no + * program will call the stubs without testing %gestalt_Graphics, this is + * sufficient. + * + */ + +/** + * GLK_MODULE_HYPERLINKS: + * + * If you are writing a C program, you can perform a preprocessor test for the + * existence of %GLK_MODULE_HYPERLINKS. If this is defined, so are all the + * functions and constants described in this section. If not, not. */ /** @@ -771,7 +1265,7 @@ * gestalt_Version: * * For an example of the gestalt mechanism, consider the selector - * #gestalt_Version. If you do + * %gestalt_Version. If you do * |[ * #glui32 res; * res = #glk_gestalt(#gestalt_Version, 0); @@ -833,15 +1327,15 @@ * #glui32 res, len; * res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1); * ]| - * then res will be one of #gestalt_CharOutput_CannotPrint, - * #gestalt_CharOutput_ExactPrint, or #gestalt_CharOutput_ApproxPrint (see + * then res will be one of %gestalt_CharOutput_CannotPrint, + * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see * below.) * * In all cases, len (the #glui32 value pointed at by the third * argument) will be the number of actual glyphs which will be used to represent - * the character. In the case of #gestalt_CharOutput_ExactPrint, this will - * always be 1; for #gestalt_CharOutput_CannotPrint, it may be 0 (nothing - * printed) or higher; for #gestalt_CharOutput_ApproxPrint, it may be 1 or + * the character. In the case of %gestalt_CharOutput_ExactPrint, this will + * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing + * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or * higher. This information may be useful when printing text in a fixed-width * font. * @@ -851,7 +1345,7 @@ * third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead. * * - * This selector will always return #gestalt_CharOutput_CannotPrint if + * This selector will always return %gestalt_CharOutput_CannotPrint if * ch is an unprintable eight-bit character (0 to 9, 11 to 31, 127 * to 159.) * @@ -871,7 +1365,7 @@ * do not represent glyphs; and double-width characters, whose glyphs take up * two spaces in a fixed-width font. Future versions of this spec may * recognize these concepts by returning a len of 0 or 2 when - * #gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to + * %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to * a policy of simple stuff first. * */ @@ -879,7 +1373,7 @@ /** * gestalt_CharOutput_CannotPrint: * - * When the #gestalt_CharOutput selector returns this for a character, the + * When the %gestalt_CharOutput selector returns this for a character, the * character cannot be meaningfully printed. If you try, the player may see * nothing, or may see a placeholder. */ @@ -887,7 +1381,7 @@ /** * gestalt_CharOutput_ApproxPrint: * - * When the #gestalt_CharOutput selector returns this for a character, the + * When the %gestalt_CharOutput selector returns this for a character, the * library will print some approximation of the character. It will be more or * less right, but it may not be precise, and it may not be distinguishable from * other, similar characters. (Examples: @@ -901,10 +1395,100 @@ /** * gestalt_CharOutput_ExactPrint: * - * When the #gestalt_CharOutput selector returns this for a character, the + * When the %gestalt_CharOutput selector returns this for a character, the * character will be printed exactly as defined. */ +/** + * gestalt_MouseInput: + * + * You can test whether mouse input is supported with the %gestalt_MouseInput + * selector. + * |[ res = glk_gestalt(gestalt_MouseInput, windowtype); ]| + * This will return %TRUE (1) if windows of the given type support mouse input. + * If this returns %FALSE (0), it is still legal to call + * glk_request_mouse_event(), but it will have no effect, and you will never get + * mouse events. + */ + +/** + * gestalt_Timer: + * + * You can test whether the library supports timer events: + * |[ res = #glk_gestalt(#gestalt_Timer, 0); ]| + * This returns 1 if timer events are supported, and 0 if they are not. + */ + +/** + * gestalt_Graphics: + * + * Before calling Glk graphics functions, you should use the following gestalt + * selector: + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_Graphics, 0); + * ]| + * This returns 1 if the overall suite of graphics functions is available. This + * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(), + * glk_window_erase_rect(), glk_window_fill_rect(), + * glk_window_set_background_color(), and glk_window_flow_break(). It also + * includes the capability to create graphics windows. + * + * If this selector returns 0, you should not try to call these functions. They + * may have no effect, or they may cause a run-time error. If you try to create + * a graphics window, you will get %NULL. + */ + +/** + * gestalt_DrawImage: + * + * This selector returns 1 if images can be drawn in windows of the given type. + * If it returns 0, glk_image_draw() will fail and return %FALSE. You should + * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries + * may implement both, neither, or only one. + */ + +/** + * gestalt_Hyperlinks: + * + * You can test whether the library supports hyperlinks: + * |[ + * #glui32 res; + * res = #glk_gestalt(#gestalt_Hyperlinks, 0); + * ]| + * This returns 1 if the overall suite of hyperlinks functions is available. + * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(), + * glk_request_hyperlink_event(), glk_cancel_hyperlink_event(). + * + * If this selector returns 0, you should not try to call these functions. They + * may have no effect, or they may cause a run-time error. + */ + +/** + * gestalt_HyperlinkInput: + * + * You can test whether hyperlinks are supported with the + * %gestalt_HyperlinkInput selector: + * |[ res = #glk_gestalt(#gestalt_HyperlinkInput, windowtype); ]| + * This will return %TRUE (1) if windows of the given type support hyperlinks. + * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and + * glk_request_hyperlink_event(), but they will have no effect, and you will + * never get hyperlink events. + */ + +/** + * gestalt_GraphicsTransparency: + * + * This returns 1 if images with alpha channels can actually be drawn with the + * appropriate degree of transparency. If it returns 0, the alpha channel is + * ignored; fully transparent areas will be drawn in an implementation-defined + * color. + * + * The JPEG format does not support transparency or alpha channels; the PNG + * format does. + * + */ + /** * gestalt_Unicode: * @@ -938,7 +1522,7 @@ * To avoid this, you can perform a preprocessor test for the existence of * #GLK_MODULE_UNICODE. */ - + /** * evtype_None: * @@ -960,7 +1544,7 @@ * * If a window has a pending request for character input, and the player hits a * key in that window, glk_select() will return an event whose type is - * #evtype_CharInput. Once this happens, the request is complete; it is no + * %evtype_CharInput. Once this happens, the request is complete; it is no * longer pending. You must call glk_request_char_event() or * glk_request_char_event_uni() if you want another character from that window. * @@ -980,7 +1564,7 @@ * If a window has a pending request for line input, and the player hits * enter in that window (or whatever action is appropriate to * enter his input), glk_select() will return an event whose type is - * #evtype_LineInput. Once this happens, the request is complete; it is no + * %evtype_LineInput. Once this happens, the request is complete; it is no * longer pending. You must call glk_request_line_event() if you want another * line of text from that window. * @@ -1015,7 +1599,7 @@ * Some platforms allow the player to resize the Glk window during play. This * will naturally change the sizes of your windows. If this occurs, then * immediately after all the rearrangement, glk_select() will return an event - * whose type is #evtype_Arrange. You can use this notification to redisplay the + * whose type is %evtype_Arrange. You can use this notification to redisplay the * contents of a graphics or text grid window whose size has changed. * * @@ -1070,7 +1654,7 @@ * * On platforms that support graphics, it is possible that the contents of a * graphics window will be lost, and have to be redrawn from scratch. If this - * occurs, then glk_select() will return an event whose type is #evtype_Redraw. + * occurs, then glk_select() will return an event whose type is %evtype_Redraw. * * In the event structure, @win will be %NULL if all windows are affected. If * only some windows are affected, @win will refer to a window which contains @@ -1084,7 +1668,7 @@ * receive the redraw event. * * Redraw events can be returned by glk_select_poll(). But, like arrangement - * events, this is platform-dependent. See #evtype_Arrange. + * events, this is platform-dependent. See %evtype_Arrange. * * For more about redraw events and how they affect graphics windows, see Graphics Windows. @@ -1094,7 +1678,7 @@ * evtype_SoundNotify: * * On platforms that support sound, you can request to receive an - * #evtype_SoundNotify event when a sound finishes playing. See Playing Sounds. */ @@ -1102,7 +1686,7 @@ * evtype_Hyperlink: * * On platforms that support hyperlinks, you can request to receive an - * #evtype_Hyperlink event when the player selects a link. See Accepting Hyperlink * Events. */ @@ -1118,7 +1702,7 @@ * that spawned the event, if relevant, is in @win. The remaining fields contain * more information specific to the event. * - * The event types are described below. Note that #evtype_None is zero, and the + * The event types are described below. Note that %evtype_None is zero, and the * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF) * are reserved for implementation-defined events. */ @@ -1279,14 +1863,106 @@ * keycode_MAXVAL: * * This value is equal to the number of special keycodes. The last keycode is - * The last keycode is always - * + * always + * * (0x100000000 - keycode_MAXVAL) * (0x100000000 - keycode_MAXVAL) - * + * * . */ +/** + * style_Normal: + * + * The style of normal or body text. A new window or stream always starts with + * %style_Normal as the current style. + */ + +/** + * style_Emphasized: + * + * Text which is emphasized. + */ + +/** + * style_Preformatted: + * + * Text which has a particular arrangement of characters. + * + * This style, unlike the others, does have a standard appearance; it will + * always be a fixed-width font. This is a concession to practicality. Games + * often want to display maps or diagrams using character graphics, and this is + * the style for that. + * + */ + +/** + * style_Header: + * + * Text which introduces a large section. This is suitable for the title of an + * entire game, or a major division such as a chapter. + */ + +/** + * style_Subheader: + * + * Text which introduces a smaller section within a large section. + * + * In a Colossal-Cave-style game, this is suitable for the name of a room (when + * the player looks around.) + * + */ + +/** + * style_Alert: + * + * Text which warns of a dangerous condition, or one which the player should pay + * attention to. + */ + +/** + * style_Note: + * + * Text which notifies of an interesting condition. + * + * This is suitable for noting that the player's score has changed. + * + */ + +/** + * style_BlockQuote: + * + * Text which forms a quotation or otherwise abstracted text. + */ + +/** + * style_Input: + * + * Text which the player has entered. You should generally not use this style at + * all; the library uses it for text which is typed during a line-input request. + * One case when it is appropriate for you to use %style_Input is when you are + * simulating player input by reading commands from a text file. + */ + +/** + * style_User1: + * + * This style has no particular semantic meaning. You may define a meaning + * relevant to your own work, and use it as you see fit. + */ + +/** + * style_User2: + * + * Another style available for your use. + */ + +/** + * style_NUMSTYLES: + * + * The number of styles defined in this library. + */ + /** * stream_result_t: * @readcount: Number of characters read from the stream. @@ -1448,7 +2124,7 @@ * larger, the new bottom or right area is filled with blanks. * * - * You may wish to watch for #evtype_Arrange events, and clear-and-redraw your + * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your * text grid windows when you see them change size. * * @@ -1503,11 +2179,11 @@ * larger, the new bottom or right area is filled with the background color. * * - * You may wish to watch for #evtype_Arrange events, and clear-and-redraw your + * You may wish to watch for %evtype_Arrange events, and clear-and-redraw your * graphics windows when you see them change size. * * - * In some libraries, you can receive a graphics-redraw event (#evtype_Redraw) + * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw) * at any time. This signifies that the window in question has been cleared to * its background color, and must be redrawn. If you create any graphics * windows, you must handle these events. @@ -1580,8 +2256,8 @@ * winmethod_DirMask: * * Bitwise AND this value with a window splitting method argument to find - * whether the split is #winmethod_Left, #winmethod_Right, #winmethod_Above, or - * #winmethod_Below. + * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or + * %winmethod_Below. */ /** @@ -1602,7 +2278,7 @@ * winmethod_DivisionMask: * * Bitwise AND this value with a window splitting method argument to find - * whether the new window has #winmethod_Fixed or #winmethod_Proportional. + * whether the new window has %winmethod_Fixed or %winmethod_Proportional. */ /** @@ -1664,8 +2340,8 @@ * fileusage_TypeMask: * * Bitwise AND this value with a file usage argument to find whether the file - * type is #fileusage_SavedGame, #fileusage_Transcript, #fileusage_InputRecord, - * or #fileusage_Data. + * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord, + * or %fileusage_Data. */ /** @@ -1731,3 +2407,1042 @@ * this will move backwards to a position within the file. */ +/** + * stylehint_Indentation: + * + * How much to indent lines of text in the given style. May be a negative + * number, to shift the text out (left) instead of in (right). The exact metric + * isn't precisely specified; you can assume that +1 is the smallest indentation + * possible which is clearly visible to the player. + */ + +/** + * stylehint_ParaIndentation: + * + * How much to indent the first line of each paragraph. This is in addition to + * the indentation specified by %stylehint_Indentation. This too may be + * negative, and is measured in the same units as %stylehint_Indentation. + */ + +/** + * stylehint_Justification: + * + * The value of this hint must be one of the constants + * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification), + * %stylehint_just_Centered, or %stylehint_just_RightFlush. + */ + +/** + * stylehint_Size: + * + * How much to increase or decrease the font size. This is relative; 0 means the + * interpreter's default font size will be used, positive numbers increase it, + * and negative numbers decrease it. Again, +1 is the smallest size increase + * which is easily visible. + * + * The amount of this increase may not be constant. +1 might increase an + * 8-point font to 9-point, but a 16-point font to 18-point. + * + */ + +/** + * stylehint_Weight: + * + * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for + * normal weight, and -1 for light-weight fonts. + */ + +/** + * stylehint_Oblique: + * + * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal + * angle. + */ + +/** + * stylehint_Proportional: + * + * The value of this hint must be 1 for proportional-width fonts, or 0 for + * fixed-width. + */ + +/** + * stylehint_TextColor: + * + * The foreground color of the text. This is encoded in the 32-bit hint value: + * the top 8 bits must be zero, the next 8 bits are the red value, the next 8 + * bits are the green value, and the bottom 8 bits are the blue value. Color + * values range from 0 to 255. + * + * So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red. + * + */ + +/** + * stylehint_BackColor: + * + * The background color behind the text. This is encoded the same way as + * %stylehint_TextColor. + */ + +/** + * stylehint_ReverseColor: + * + * The value of this hint must be 0 for normal printing (%stylehint_TextColor on + * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on + * %stylehint_TextColor). + * + * Some libraries may support this hint but not the %stylehint_TextColor and + * %stylehint_BackColor hints. Other libraries may take the opposite tack; + * others may support both, or neither. + * + */ + +/** + * stylehint_NUMHINTS: + * + * The number of style hints defined in this library. + */ + +/** + * stylehint_just_LeftFlush: + * + * A value for %stylehint_Justification representing left-justified text. + */ + +/** + * stylehint_just_LeftRight: + * + * A value for %stylehint_Justification representing fully justified text. + */ + +/** + * stylehint_just_Centered: + * + * A value for %stylehint_Justification representing centered text. + */ + +/** + * stylehint_just_RightFlush: + * + * A value for %stylehint_Justification representing right-justified text. + */ + +/** + * imagealign_InlineUp: + * + * The image appears at the current point in the text, sticking up. That is, the + * bottom edge of the image is aligned with the baseline of the line of text. + */ + +/** + * imagealign_InlineDown: + * + * The image appears at the current point, and the top edge is aligned with the + * top of the line of text. + */ + +/** + * imagealign_InlineCenter: + * + * The image appears at the current point, and it is centered between the top + * and baseline of the line of text. If the image is taller than the line of + * text, it will stick up and down equally. + */ + +/*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/ + +/** + * gidispatch_count_classes: + * + * Returns the number of opaque object classes used by the library. You will + * need to know this if you want to keep track of opaque objects as they are + * created; see Opaque Object + * Registry. + * + * As of Glk API 0.7.0, there are four classes: windows, streams, filerefs, and + * sound channels (numbered 0, 1, 2, and 3 respectively.) + * + * Returns: Number of opaque object classes used by the library. + */ + +/** + * gidispatch_count_intconst: + * + * Returns the number of integer constants exported by the library. + * + * Returns: Number of integer constants exported by the library. + */ + +/** + * gidispatch_get_intconst: + * @index: Unique integer index of the integer constant. + * + * Returns a structure describing an integer constant which the library exports. + * These are, roughly, all the constants defined in the glk.h file. @index can range from 0 to + * N - 1N - + * 1, where N is the value returned by + * gidispatch_count_intconst(). + * + * Returns: A #gidispatch_intconst_t structure describing the integer constant. + */ + +/** + * gidispatch_intconst_t: + * @name: Symbolic name of the integer constant. + * @val: Value of the integer constant. + * + * This structure simply contains a string and a value. The string is a + * symbolic name of the value, and can be re-exported to anyone interested in + * using Glk constants. + */ + +/** + * gidispatch_count_functions: + * + * Returns the number of functions exported by the library. + * + * Returns: Number of functions exported by the library. + */ + +/** + * gidispatch_get_function: + * @index: Unique integer index of the function. + * + * Returns a structure describing a Glk function. @index can range from 0 to + * N - 1N - + * 1, where N is the value returned by + * gidispatch_count_functions(). + * + * Returns: A #gidispatch_function_t structure describing the function. + */ + +/** + * gidispatch_function_t: + * @id: Dispatch selector of the function. + * @fnptr: Pointer to the function. + * @name: Name of the function, without the glk_ prefix. + * + * The @id field is a selector — a numeric constant used to refer to the + * function in question. @name is the function name, as it is given in the + * glk.h file, but without the + * glk_ prefix. And @fnptr is the address of the + * function itself. + * + * + * This is included because it might be useful, but it is not recommended. To + * call an arbitrary Glk function, you should use gidispatch_call(). + * + * + * See Table of Selectors for + * the selector definitions. See Dispatching for more about calling Glk + * functions by selector. + */ + +/** + * gidispatch_get_function_by_id: + * @id: A selector. + * + * Returns a structure describing the Glk function with selector @id. If there + * is no such function in the library, this returns %NULL. + * + * Returns: a #gidispatch_function_t structure, or %NULL. + */ + +/** + * gidispatch_call: + * @funcnum: Selector of the function to call. + * @numargs: Length of @arglist. + * @arglist: List of arguments to pass to the function. + * + * @funcnum is the function number to invoke; see Table of Selectors. @arglist is + * the list of arguments, and @numargs is the length of the list. + * + * The arguments are all stored as #gluniversal_t objects. + * Basic Types + * Numeric arguments are passed in the obvious way — one argument per + * #gluniversal_t, with the @uint or @sint field set to the numeric value. + * Characters and strings are also passed in this way — #chars in + * the @uch, @sch, or @ch fields (depending on whether the #char is signed) and + * strings in the @charstr field. Opaque objects (windows, streams, etc) are + * passed in the @opaqueref field (which is void*, in order to + * handle all opaque pointer types.) + * + * However, pointers (other than C strings), arrays, and structures complicate + * life. So do return values. + * + * References + * A reference to a numeric type or object reference — that is, + * #glui32*, #winid_t*, and so on — takes + * one or two #gluniversal_t objects. The first is a flag + * indicating whether the reference argument is %NULL or not. The @ptrflag field + * of this #gluniversal_t should be %FALSE if the reference is %NULL, and %TRUE + * otherwise. If %FALSE, that is the end of the argument; you should not use a + * #gluniversal_t to explicitly store the %NULL reference. If the flag is %TRUE, + * you must then put a #gluniversal_t storing the base type of the reference. + * + * For example, consider a hypothetical function, with selector + * 0xABCD: + * |[ + * void glk_glomp(#glui32 num, #winid_t win, #glui32 *numref, #strid_t *strref); + * ]| + * ...and the calls: + * |[ + * #glui32 value; + * #winid_t mainwin; + * #strid_t gamefile; + * glk_glomp(5, mainwin, &value, &gamefile); + * ]| + * + * To perform this through gidispatch_call(), you would do the following: + * |[ + * #gluniversal_t arglist[6]; + * arglist[0].uint = 5; + * arglist[1].opaqueref = mainwin; + * arglist[2].ptrflag = TRUE; + * arglist[3].uint = value; + * arglist[4].ptrflag = TRUE; + * arglist[5].opaqueref = gamefile; + * #gidispatch_call(0xABCD, 6, arglist); + * value = arglist[3].uint; + * gamefile = arglist[5].opaqueref; + * ]| + * + * Note that you copy the value of the reference arguments into and out of + * @arglist. Of course, it may be that glk_glomp() only uses these as pass-out + * references or pass-in references; if so, you could skip copying in or out. + * + * For further examples: + * |[ + * glk_glomp(7, mainwin, NULL, NULL); + * ...or... + * #gluniversal_t arglist[4]; + * arglist[0].uint = 7; + * arglist[1].opaqueref = mainwin; + * arglist[2].ptrflag = FALSE; + * arglist[3].ptrflag = FALSE; + * #gidispatch_call(0xABCD, 4, arglist); + * ]| + * + * |[ + * glk_glomp(13, NULL, NULL, &gamefile); + * ...or... + * #gluniversal_t arglist[5]; + * arglist[0].uint = 13; + * arglist[1].opaqueref = NULL; + * arglist[2].ptrflag = FALSE; + * arglist[3].ptrflag = TRUE; + * arglist[4].opaqueref = gamefile; + * #gidispatch_call(0xABCD, 5, arglist); + * gamefile = arglist[4].opaqueref; + * ]| + * + * |[ + * glk_glomp(17, NULL, &value, NULL); + * ...or... + * #gluniversal_t arglist[5]; + * arglist[0].uint = 17; + * arglist[1].opaqueref = NULL; + * arglist[2].ptrflag = TRUE; + * arglist[3].uint = value; + * arglist[4].ptrflag = FALSE; + * #gidispatch_call(0xABCD, 5, arglist); + * value = arglist[3].uint; + * ]| + * + * As you see, the length of @arglist depends on how many of the reference + * arguments are %NULL. + * + * Structures + * A structure pointer is represented by a single @ptrflag, possibly followed by + * a sequence of #gluniversal_t objects (one for each field of the structure.) + * Again, if the structure pointer is non-%NULL, the @ptrflag should be %TRUE + * and be followed by values; if not, the @ptrflag should be %NULL and stands + * alone. + * + * For example, the function glk_select() can be invoked as follows: + * |[ + * #event_t ev; + * #gluniversal_t arglist[5]; + * arglist[0].ptrflag = TRUE; + * #gidispatch_call(0x00C0, 5, arglist); + * ev.type = arglist[1].uint; + * ev.win = arglist[2].opaqueref; + * ev.val1 = arglist[3].uint; + * ev.val2 = arglist[4].uint; + * ]| + * + * Since the structure passed to glk_select() is a pass-out reference (the entry + * values are ignored), you don't need to fill in arglist[1..4] + * before calling gidispatch_call(). + * + * + * Theoretically, you would invoke #glk_select(%NULL) by setting' + * arglist[0].ptrflag to %FALSE, and using a one-element @arglist + * instead of five-element. But it's illegal to pass %NULL to glk_select(). So + * you cannot actually do this. + * + * Arrays + * In the Glk API, an array argument is always followed by a numeric argument + * giving the array's length. These two C arguments are a single logical + * argument, which is represented by one or three + * #gluniversal_t objects. The first is a @ptrflag, indicating whether the + * argument is %NULL or not. The second is a pointer, stored in the @array + * field. The third is the array length, stored in the @uint field. And again, + * if the @ptrflag is %NULL, the following two are omitted. + * + * For example, the function glk_put_buffer() can be invoked as follows: + * |[ + * #char buf[64]; + * #glui32 len = 64; + * #glk_put_buffer(buf, len); + * ...or... + * #gluniversal_t arglist[3]; + * arglist[0].ptrflag = TRUE; + * arglist[1].array = buf; + * arglist[2].uint = len; + * #gidispatch_call(0x0084, 3, arglist); + * ]| + * + * Since you are passing a C char array to gidispatch_call(), the contents will + * be read directly from that. There is no need to copy data into @arglist, as + * you would for a basic type. + * + * If you are implementing a VM whose native representation of char arrays is + * more complex, you will have to do more work. You should allocate a C char + * array, copy your characters into it, make the call, and then free the array. + * + * + * glk_put_buffer() does not modify the array passed to it, so there is no + * need to copy the characters out. + * + * Return Values + * The return value of a function is not treated specially. It is simply + * considered to be a pass-out reference argument which may not be %NULL. It + * comes after all the other arguments of the function. + * + * For example, the function glk_window_get_rock() can be invoked as follows: + * |[ + * #glui32 rock; + * #winid_t win; + * rock = #glk_window_get_rock(win); + * ...or... + * #gluniversal_t arglist[3]; + * arglist[0].opaqueref = win; + * arglist[1].ptrflag = TRUE; + * #gidispatch_call(0x0021, 3, arglist); + * rock = arglist[2].uint; + * ]| + * + */ + +/** + * gluniversal_t: + * @uint: Stores a #glui32. + * @sint: Stores a #glsi32. + * @opaqueref: Stores a #winid_t, #strid_t, #frefid_t, or #schanid_t. + * @uch: Stores an #unsigned #char. + * @sch: Stores a #signed #char. + * @ch: Stores a #char with the default signedness. + * @charstr: Stores a %NULL-terminated string. + * @array: Stores a pointer to an array, and should be followed by another + * #gluniversal_t with the array length stored in the @uint member. + * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL, + * in which case it represents the entire argument. If %TRUE, should be followed + * by another #gluniversal_t with the pointer in its @opaqueref or @array field. + * + * This is a union, encompassing all the types that can be passed to Glk + * functions. + */ + +/** + * gidispatch_prototype: + * @funcnum: A selector for the function to be queried. + * + * This returns a string which encodes the proper argument list for the given + * function. If there is no such function in the library, this returns %NULL. + * + * The prototype string for the glk_glomp() function described above would be: + * "4IuQa&Iu&Qb:". The "4" is the number of + * arguments (including the return value, if there is one, which in this case + * there isn't.) "Iu" denotes an unsigned integer; + * "Qa" is an opaque object of class 0 (window). + * "&Iu" is a reference to an unsigned + * integer, and "&Qb" is a reference to a stream. The colon at + * the end terminates the argument list; the return value would follow it, if + * there was one. + * + * Note that the initial number ("4" in this case) is the number of + * logical arguments, not the number of #gluniversal_t objects which will be + * passed to gidispatch_call(). The glk_glomp() call uses anywhere from four to + * six #gluniversal_t objects, as demonstrated above. + * + * The basic type codes: + * + * + * Iu, Is + * Unsigned and signed 32-bit integer. + * + * + * Cn, Cu, Cs + * Character, #unsigned #char, and #signed #char. + * Of course Cn will be the same as either + * Cu or Cs, depending on the platform. For this + * reason, Glk avoids using it, but it is included here for completeness. + * + * + * + * + * S + * A C-style string (null-terminated array of #char). In Glk, + * strings are always treated as read-only and used immediately; the library + * does not retain a reference to a string between Glk calls. A Glk call that + * wants to use writable char arrays will use an array type + * ("#C"), not string ("S"). + * + * + * U + * A zero-terminated array of 32-bit integers. This is + * primarily intended as a Unicode equivalent of "S". Like + * "S" strings, "U" strings are read-only and used + * immediately. A Glk call that wants to use writable Unicode arrays will use + * an array type ("#Iu") instead of "U". + * + * + * + * F + * A floating-point value. Glk does not currently use + * floating-point values, but we might as well define a code for them. + * + * + * + * Qa, Qb, Qc... + * A reference to an opaque object. The second letter + * determines which class is involved. (The number of classes can be gleaned + * from gidispatch_count_classes(); see Interrogating the + * Interface). + * + * If Glk expands to have more than 26 classes, we'll think of something. + * + * + * + * Any type code can be prefixed with one or more of the following characters + * (order does not matter): + * + * + * & + * A reference to the type; or, if you like, a variable passed + * by reference. The reference is passed both in and out, so you must copy the + * value in before calling gidispatch_call() and copy it out afterward. + * + * + * + * < + * A reference which is pass-out only. The initial value is + * ignored, so you only need copy out the value after the call. + * + * + * + * > + * A reference which is pass-in only. + * + * This is not generally used for simple types, but is useful for structures + * and arrays. + * + * + * + * + + * Combined with "&", "<", or + * ">", indicates that a valid reference is mandatory; %NULL + * cannot be passed. + * + * Note that even though the @ptrflag #gluniversal_t for a "+" + * reference is always %TRUE, it cannot be omitted. + * + * + * + * : + * The colon separates the arguments from the return value, or + * terminates the string if there is no return value. Since return values are + * always non-%NULL pass-out references, you may treat ":" as + * equivalent to "<+". The colon is never combined with any + * other prefix character. + * + * + * [...] + * Combined with "&", "<", or + * ">", indicates a structure reference. Between the brackets + * is a complete argument list encoding string, including the number of + * arguments. + * + * For example, the prototype string for glk_select() is + * "1<+[4IuQaIuIu]:" — one argument, which is a + * pass-out non-%NULL reference to a structure, which contains four + * arguments. + * + * Currently, structures in Glk contain only basic types. + * + * + * + * # + * Combined with "&", "<", or + * ">", indicates an array reference. As described above, this + * encompasses up to three #gluniversal_t objects — @ptrflag, pointer, + * and integer length. + * + * Depending on the design of your program, you may wish to pass a pointer + * directly to your program's memory, or allocate an array and copy the + * contents in and out. See Arrays. + * + * + * + * ! + * Combined with "#", indicates that the + * array is retained by the library. The library will keep a reference to the + * array; the contents are undefined until further notice. You should not use + * or copy the contents of the array out after the call, even for + * "&#!" or "<#!" arrays. Instead, do + * it when the library releases the array. + * + * For example, glk_stream_open_memory() retains the array that you pass it, + * and releases it when the stream is closed. The library can notify you + * automatically when arrays are retained and released; see Retained Array + * Registry. + * + * + * + * + * Returns: A string which encodes the prototype of the specified Glk function. + */ + +/** + * gidisp_Class_Window: + * + * Represents a #winid_t opaque object. + */ + +/** + * gidisp_Class_Stream: + * + * Represents a #strid_t opaque object. + */ + +/** + * gidisp_Class_Fileref: + * + * Represents a #frefid_t opaque object. + */ + +/** + * gidisp_Class_Schannel: + * + * Represents a #schanid_t opaque object. + */ + +/** + * gidispatch_rock_t: + * @num: Space for storing an integer. + * @ptr: Space for storing a pointer. + * + * You can store any value you want in this object; return it from your object + * registry and retained array registry callbacks, and the library will stash it + * away. You can retrieve it with gidispatch_get_objrock(). + */ + +/*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/ + +/** + * giblorb_err_t: + * + * An integer type that can hold the Blorb error codes. + */ + +/** + * giblorb_err_None: + * + * No error. + */ + +/** + * giblorb_err_CompileTime: + * + * Something is compiled wrong in the Blorb layer. + */ + +/** + * giblorb_err_Alloc: + * + * Memory could not be allocated. + * Chimara + * + * The Blorb layer in the Chimara library should not return this error code; + * instead, the program aborts if memory allocation fails, in keeping with + * GLib practices. + * + */ + +/** + * giblorb_err_Read: + * + * Data could not be read from the file. + */ + +/** + * giblorb_err_NotAMap: + * + * The map parameter is invalid. + */ + +/** + * giblorb_err_Format: + * + * The Blorb file is corrupted or invalid. + */ + +/** + * giblorb_err_NotFound: + * + * The requested data could not be found. + */ + +/** + * giblorb_method_DontLoad: + * + * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or + * giblorb_load_resource() to obtain information about a chunk without actually + * loading it. + */ + +/** + * giblorb_method_Memory: + * + * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or + * giblorb_load_resource() to load a chunk into memory. + */ + +/** + * giblorb_method_DontLoad: + * + * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or + * giblorb_load_resource() to get the position in the Blorb file at which the + * chunk data starts. + */ + +/** + * giblorb_ID_Snd: + * + * Resource usage constant representing a sound file. + */ + +/** + * giblorb_ID_Exec: + * + * Resource usage constant representing an executable program. + */ + +/** + * giblorb_ID_Pict: + * + * Resource usage constant representing an image file. + */ + +/** + * giblorb_ID_Copyright: + * + * Resource usage constant representing the copyright message (date and holder, + * without the actual copyright symbol). There should only be one such chunk per + * file. + */ + +/** + * giblorb_ID_AUTH: + * + * Resource usage constant representing the name of the author or creator of the + * file. This could be a login name on multi-user systems, for example. There + * should only be one such chunk per file. + */ + +/** + * giblorb_ID_ANNO: + * + * Resource usage constant representing any textual annotation that the user or + * writing program sees fit to include. + */ + +/** + * giblorb_map_t: + * + * Holds the complete description of an open Blorb file. This type is opaque for + * normal interpreter use. + */ + +/** + * giblorb_result_t: + * + * Holds information about a chunk loaded from a Blorb file, and the method of + * accessing the chunk data. See giblorb_load_chunk_by_type() and + * giblorb_load_chunk_by_number(). + */ + +/** + * giblorb_create_map: + * @file: An input stream pointing to a Blorb file. + * @newmap: Return location for a Blorb resource map. + * + * Reads Blorb data out of a Glk stream. It does not load every resource at + * once; instead, it creates a map in memory which makes it easy to find + * resources. A pointer to the map is stored in @newmap. This is an opaque + * object; you pass it to the other Blorb-layer functions. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_destroy_map: + * @map: A Blorb resource map to deallocate. + * + * Deallocates @map and all associated memory. This does + * not close the original stream. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_load_chunk_by_type: + * @map: The Blorb resource map to load a chunk from. + * @method: The loading method to use, one of %giblorb_method_DontLoad, + * %giblorb_method_Memory, or %giblorb_method_FilePos. + * @res: Return location for the result. + * @chunktype: The type of chunk to load. + * @count: The chunk number of type @chunktype to load. + * + * Loads a chunk of a given type. The @count parameter distinguishes between + * chunks of the same type. If @count is zero, the first chunk of that type is + * loaded, and so on. + * + * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the + * form type, rather than FORM. + * + * This introduces a slight ambiguity — you cannot distiguish between a + * FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is + * almost certainly a mistake. + * + * + * The returned data is written into @res, according to @method. + * + * The chunknum field is filled in with the number of + * the chunk. (This value can then be passed to giblorb_load_chunk_by_number() + * or giblorb_unload_chunk().) The length field is + * filled in with the length of the chunk in bytes. The + * chunktype field is the chunk's type, which of + * course will be the type you asked for. + * + * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You + * can use this if you are only interested in whether a chunk exists, or in the + * chunknum and length + * parameters. + * + * If you specify %giblorb_method_FilePos, + * data.startpos is filled in with the file position + * of the chunk data. You can use glk_stream_set_position() to read the data + * from the stream. + * + * If you specify %giblorb_method_Memory, data.ptr is + * filled with a pointer to allocated memory containing the chunk data. This + * memory is owned by the map, not you. If you load the chunk more than once + * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one + * copy in memory. You should not deallocate this memory yourself; call + * giblorb_unload_chunk() instead. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_load_chunk_by_number: + * @map: The Blorb resource map to load a chunk from. + * @method: The loading method to use, one of %giblorb_method_DontLoad, + * %giblorb_method_Memory, or %giblorb_method_FilePos. + * @res: Return location for the result. + * @chunknum: The chunk number to load. + * + * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a + * given chunk number. The type of the chunk can be found in the + * chunktype field of #giblorb_result_t. You can get + * the chunk number from the chunknum field, after + * calling one of the other load functions. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_unload_chunk: + * @map: The Blorb resource map to unload a chunk from. + * @chunknum: The chunk number to unload. + * + * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk + * has never been loaded into memory, this has no effect. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_load_resource: + * @map: The Blorb resource map to load a resource from. + * @method: The loading method to use, one of %giblorb_method_DontLoad, + * %giblorb_method_Memory, or %giblorb_method_FilePos. + * @res: Return location for the result. + * @usage: The type of data resource to load. + * @resnum: The resource number to load. + * + * Loads a resource, given its usage and resource number. Currently, the three + * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and + * %giblorb_ID_Exec (executable program). See the Blorb specification for more + * information about the types of data that can be stored for these usages. + * + * Note that a resource number is not the same as a chunk number. The resource + * number is the sound or image number specified by a Glk program. Chunk number + * is arbitrary, since chunks in a Blorb file can be in any order. To find the + * chunk number of a given resource, call giblorb_load_resource() and look in + * res.chunknum. + * + * Returns: a Blorb error code. + */ + +/** + * giblorb_count_resources: + * @map: The Blorb resource map in which to count the resources. + * @usage: The type of data resource to count. + * @num: Return location for the number of chunks of @usage. + * @min: Return location for the lowest resource number of @usage. + * @max: Return location for the highest resource number of @usage. + * + * Counts the number of chunks with a given usage (image, sound, or executable.) + * The total number of chunks of that usage is stored in @num. The lowest and + * highest resource number of that usage are stored in @min and @max. You can + * leave any of the three pointers %NULL if you don't care about that + * information. + * + * Returns: a Blorb error code. + */ + +/*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/ + +/** + * glkunix_argumentlist_t: + * + * 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. + */ + +/** + * 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. + */ + +/** + * glkunix_arg_End: + * + * Terminates a list of #glkunix_argumentlist_t. + */ + +/** + * glkunix_arg_ValueFollows: + * + * Indicates an argument which must be followed by a value, as the next + * argument. + */ + +/** + * glkunix_arg_NoValue: + * + * Indicates an argument which occurs by itself, without a value. + */ + +/** + * glkunix_arg_ValueCanFollow: + * + * Indicates an argument which may be followed by a value, or may occur by + * itself. + */ + +/** + * glkunix_arg_NumberValue: + * + * Indicates an argument which must be followed by a numerical value, either as + * the next argument or tacked onto the end of this argument. + */