/**
* 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.
* 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 —
* <keycombo action="simul"><keycap function="command">command</keycap>
/**
* 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.
/**
* 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.
* <variablelist>
/**
* 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.
/**
* SECTION:glk-gestalt
* @short_description: Testing Glk's capabilities
- * @include: glk.h
+ * @include: libchimara/glk.h
*
* The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
* system by which the Glk API can be upgraded without making your life
/**
* 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 <link
* linkend="chimara-Character-Input-Events">Character Input Events</link>.
* action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
* </keycombo> code when the <keycap function="tab">tab</keycap> key is
* pressed. The Glk library, if it can recognize this at all, will generate a
- * <keysym>#keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
+ * <keysym>%keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
* Therefore, for these keyboards, no keyboard key will generate a <keycombo
* action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
* </keycombo> event (value 9.) The Glk library will probably map many of the
* legal. The idea is, however, that if your program asks the player to
* <quote><computeroutput>press the <keycap function="tab">tab</keycap>
* key</computeroutput></quote>, you should check for a
- * <keysym>#keycode_Tab</keysym> event as opposed to a <keycombo
+ * <keysym>%keycode_Tab</keysym> event as opposed to a <keycombo
* action="simul"><keycap function="control">control</keycap>
* <keycap>I</keycap></keycombo> event.
* </para></note>
* purposes of the interface. For example, the Mac Glk library reserves the
* <keycap function="tab">tab</keycap> key for switching between different Glk
* windows. Therefore, on the Mac, the library will never generate a
- * <keysym>#keycode_Tab</keysym> event or a <keycombo action="simul">
+ * <keysym>%keycode_Tab</keysym> event or a <keycombo action="simul">
* <keycap function="control">control</keycap><keycap>I</keycap></keycombo>
* event.
*
* function="control">control</keycap><keycap>J</keycap></keycombo>
* character, which is the only printable control character, is probably not
* typable. This is because, in most libraries, it will be converted to
- * <keysym>#keycode_Return</keysym>. Again, you should check for
- * <keysym>#keycode_Return</keysym> if your program asks the player to
+ * <keysym>%keycode_Return</keysym>. Again, you should check for
+ * <keysym>%keycode_Return</keysym> if your program asks the player to
* <quote><computeroutput>press the <keycap function="enter">return</keycap>
* key</computeroutput></quote>.
* </para></note>
* large problem.
* </para></note>
*
- * You can test for this by using the #gestalt_CharInput selector.
+ * You can test for this by using the %gestalt_CharInput selector.
*
* <note><para>
* 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 <keysym>#keycode_Home</keysym>
+ * available, and ask players to use it. If a <keysym>%keycode_Home</keysym>
* event can only be generated by typing <keycombo action="seq"><keycap
* function="escape">escape</keycap><keycombo action="simul"><keycap
* function="control">control</keycap><keycap>A</keycap></keycombo>
* when the game says <quote><computeroutput>Press the <keycap
* function="home">home</keycap> key to see the next
* hint.</computeroutput></quote> It is better for the library to say that it
- * cannot generate a <keysym>#keycode_Home</keysym> event; that way the game
+ * cannot generate a <keysym>%keycode_Home</keysym> event; that way the game
* can detect the situation and ask the user to type <keycap>H</keycap>
* instead.
* </para>
* (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 <keycap
* function="enter">return</keycap>, 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.
* </para></note>
*/
/**
* 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
/**
* 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().
/**
* 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.
*/
/**
* 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.
*/
/**
* 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
/**
* 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.
*/
/**
* SECTION:glk-events
* @short_description: Waiting for events
- * @include: glk.h
+ * @include: libchimara/glk.h
*
* As described in <link linkend="chimara-Your-Programs-Main-Function">Your
* Program's Main Function</link>, all player input is handed to your program by
/**
* 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.
+ * <note><para>So @val1 is the column, and @val2 is the row.</para></note>
+ * 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).
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
+ * <note><para>
+ * 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 <quote>double-click</quote>, <quote>right-click</quote>, or
+ * <quote>control-click</quote> in a window. The preferred term is <quote>to
+ * touch the window</quote>, or a spot in the window.
+ * </para></note>
+ * <note><para>
+ * Goofy, but preferred.
+ * </para></note>
+ */
+
+/**
+ * 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
/**
* 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
/**
* 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
/**
* 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
/**
* 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.
*
* </para></note>
*/
+/**
+ * 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><para>
+ * Note that every stream and window has its own idea of the <quote>current
+ * style.</quote> Sending a style command to one window or stream does not
+ * affect any others.
+ * </para></note>
+ * <note><para>
+ * Except for a window's echo stream; see <link
+ * linkend="chimara-Echo-Streams">Echo Streams</link>.
+ * </para></note>
+ *
+ * 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.
+ *
+ * <note><para>
+ * For example, %style_Header may well be centered text. If you print
+ * <quote>Welcome to Victim (a short interactive mystery)</quote>, and only the
+ * word <quote>Victim</quote> 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.
+ * </para></note>
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
+ */
+
+/**
+ * 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 <emphasis>not</emphasis> affect
+ * <emphasis>existing</emphasis> 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.
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
+ * 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 <emphasis>change</emphasis> 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.
+ * <note><para>
+ * This policy allows for the future definition of style hints without breaking
+ * old Glk libraries.
+ * </para></note>
+ */
+
+/**
+ * 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.
+ * <note><para>
+ * 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.
+ * </para></note>
+ */
+
/**
* SECTION:glk-stream-types
* @short_description: Window, memory, and file streams
- * @include: glk.h
+ * @include: libchimara/glk.h
*
* <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
* <para>
* 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
/**
* 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.
*/
/**
* 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 <link linkend="chimara-Opaque-Objects">Opaque
* 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
/**
* 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.
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
+ * 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 <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for
+ * Graphics Capabilities</link>.
+ */
+
+/**
+ * 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 <link
+ * linkend="wintype-Graphics">Graphics Windows</link>.
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
+ * 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 <emphasis>allow</emphasis> the program to set them; it is the
+ * program's choice. The library does this by implementing
+ * <code>set_registry functions</code> — the functions to which the
+ * program passes its callbacks.
+ *
+ * <note><para>
+ * Even though these callbacks and the functions to set them are declared in
+ * <filename class="headerfile">gi_dispa.h</filename>, they are not defined in
+ * <filename>gi_dispa.c</filename>. The dispatch layer merely coordinates
+ * them. The program defines the callback functions; the library calls them.
+ * </para></note>
+ */
+
+/**
+ * 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 <link
+ * linkend="chimara-Startup-Options">Startup Options</link>.) 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 —
+ * <filename>PIC1</filename>, <filename>PIC2</filename>,
+ * <filename>PIC3</filename>, 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
+ * <filename>gi_blorb.c</filename>. 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 <code>glkunix_arguments[]</code>. These
+ * set up various Unix-specific options used by the Glk library. There is a
+ * sample <quote><filename>glkstart.c</filename></quote> file included in this
+ * package; you should modify it to your needs.
+ *
+ * |[ extern #glkunix_argumentlist_t glkunix_arguments[]; ]|
+ *
+ * The <code>glkunix_arguments[]</code> 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 ----------------------------*/
/**
* 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 <filename
+ * class="headerfile">glk.h</filename> 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.
+ *
+ * <note><para>
+ * To be extremely specific, there are two ways this can happen. If the
+ * <filename class="headerfile">glk.h</filename> 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 <filename
+ * class="headerfile">glk.h</filename> file is recent, but the library is old,
+ * the definition of %GLK_MODULE_IMAGE should be removed from <filename
+ * class="headerfile">glk.h</filename>, 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.
+ * </para></note>
+ */
+
+/**
+ * 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.
*/
/**
* 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);
* #glui32 res, len;
* res = #glk_gestalt_ext(#gestalt_CharOutput, ch, &len, 1);
* ]|
- * then <code>res</code> will be one of #gestalt_CharOutput_CannotPrint,
- * #gestalt_CharOutput_ExactPrint, or #gestalt_CharOutput_ApproxPrint (see
+ * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
+ * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see
* below.)
*
* In all cases, <code>len</code> (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.
*
* third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
* </para></note>
*
- * This selector will always return #gestalt_CharOutput_CannotPrint if
+ * This selector will always return %gestalt_CharOutput_CannotPrint if
* <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127
* to 159.)
*
* 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 <code>len</code> 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 <quote>simple stuff first</quote>.
* </para></note>
*/
/**
* 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.
*/
/**
* 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:
/**
* 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.
+ * <note><para>
+ * The JPEG format does not support transparency or alpha channels; the PNG
+ * format does.
+ * </para></note>
+ */
+
/**
* gestalt_Unicode:
*
* To avoid this, you can perform a preprocessor test for the existence of
* #GLK_MODULE_UNICODE.
*/
-
+
/**
* evtype_None:
*
*
* 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.
*
* If a window has a pending request for line input, and the player hits
* <keycap>enter</keycap> 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.
*
* 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.
*
* <note><para>
*
* 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
* 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 <link
* linkend="chimara-Graphics-Windows">Graphics Windows</link>.
* evtype_SoundNotify:
*
* On platforms that support sound, you can request to receive an
- * #evtype_SoundNotify event when a sound finishes playing. See <link
+ * %evtype_SoundNotify event when a sound finishes playing. See <link
* linkend="chimara-Playing-Sounds">Playing Sounds</link>.
*/
* evtype_Hyperlink:
*
* On platforms that support hyperlinks, you can request to receive an
- * #evtype_Hyperlink event when the player selects a link. See <link
+ * %evtype_Hyperlink event when the player selects a link. See <link
* linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink
* Events</link>.
*/
* 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.
*/
* keycode_MAXVAL:
*
* This value is equal to the number of special keycodes. The last keycode is
- * The last keycode is always
- * <informalequation>
+ * always
+ * <inlineequation>
* <alt>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</alt>
* <mathphrase>(0x100000000 - <keysym>keycode_MAXVAL</keysym>)</mathphrase>
- * </informalequation>
+ * </inlineequation>
* .
*/
+/**
+ * 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.
+ * <note><para>
+ * 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.
+ * </para></note>
+ */
+
+/**
+ * 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.
+ * <note><para>
+ * In a Colossal-Cave-style game, this is suitable for the name of a room (when
+ * the player looks around.)
+ * </para></note>
+ */
+
+/**
+ * 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.
+ * <note><para>
+ * This is suitable for noting that the player's score has changed.
+ * </para></note>
+ */
+
+/**
+ * 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.
* larger, the new bottom or right area is filled with blanks.
*
* <note><para>
- * 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.
* </para></note>
*
* larger, the new bottom or right area is filled with the background color.
*
* <note><para>
- * 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.
* </para></note>
*
- * 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 <emphasis>must</emphasis> handle these events.
* 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.
*/
/**
* 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.
*/
/**
* 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.
*/
/**
* 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.
+ * <note><para>
+ * 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.
+ * </para></note>
+ */
+
+/**
+ * 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.
+ * <note><para>
+ * So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
+ * </para></note>
+ */
+
+/**
+ * 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).
+ * <note><para>
+ * 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.
+ * </para></note>
+ */
+
+/**
+ * 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 <link linkend="gidispatch-set-object-registry">Opaque Object
+ * Registry</link>.
+ *
+ * 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 <filename
+ * class="headerfile">glk.h</filename> file. @index can range from 0 to
+ * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
+ * 1</alt></inlineequation>, 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
+ * <inlineequation><mathphrase>N - 1</mathphrase><alt>N -
+ * 1</alt></inlineequation>, 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 <code>glk_</code> 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
+ * <filename class="headerfile">glk.h</filename> file, but without the
+ * <quote><code>glk_</code></quote> prefix. And @fnptr is the address of the
+ * function itself.
+ *
+ * <note><para>
+ * This is included because it might be useful, but it is not recommended. To
+ * call an arbitrary Glk function, you should use gidispatch_call().
+ * </para></note>
+ *
+ * See <link linkend="chimara-Table-of-Selectors">Table of Selectors</link> for
+ * the selector definitions. See <link
+ * linkend="chimara-Dispatching">Dispatching</link> 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 <link
+ * linkend="chimara-Table-of-Selectors">Table of Selectors</link>. @arglist is
+ * the list of arguments, and @numargs is the length of the list.
+ *
+ * The arguments are all stored as #gluniversal_t objects.
+ * </para><refsect3 id="chimara-Basic-Types"><title>Basic Types</title><para>
+ * 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 — #char<!---->s 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 <code>void*</code>, in order to
+ * handle all opaque pointer types.)
+ *
+ * However, pointers (other than C strings), arrays, and structures complicate
+ * life. So do return values.
+ * </para></refsect3>
+ * <refsect3 id="chimara-References"><title>References</title><para>
+ * A reference to a numeric type or object reference — that is,
+ * <code>#glui32*</code>, <code>#winid_t*</code>, and so on — takes
+ * <emphasis>one or two</emphasis> #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
+ * <code>0xABCD</code>:
+ * |[
+ * 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.
+ * </para></refsect3>
+ * <refsect3 id="chimara-Structures"><title>Structures</title><para>
+ * 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 <code>arglist[1..4]</code>
+ * before calling gidispatch_call().
+ *
+ * <note><para>
+ * Theoretically, you would invoke <code>#glk_select(%NULL)</code> by setting'
+ * <code>arglist[0].ptrflag</code> 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.
+ * </para></note></para></refsect3>
+ * <refsect3 id="chimara-Arrays"><title>Arrays</title><para>
+ * 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 <emphasis>one or three</emphasis>
+ * #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.
+ *
+ * <note><para>
+ * glk_put_buffer() does not modify the array passed to it, so there is no
+ * need to copy the characters out.
+ * </para></note></para></refsect3>
+ * <refsect3 id="chimara-Return-Values"><title>Return Values</title><para>
+ * 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;
+ * ]|
+ * </para></refsect3><para>
+ */
+
+/**
+ * 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:
+ * <code>"4IuQa&Iu&Qb:"</code>. The <code>"4"</code> is the number of
+ * arguments (including the return value, if there is one, which in this case
+ * there isn't.) <code>"Iu"</code> denotes an unsigned integer;
+ * <code>"Qa"</code> is an opaque object of class 0 (window).
+ * <code>"&Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
+ * integer, and <code>"&Qb"</code> 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 (<code>"4"</code> 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:
+ * <variablelist>
+ * <varlistentry>
+ * <term><code>Iu, Is</code></term>
+ * <listitem><para>Unsigned and signed 32-bit integer.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>Cn, Cu, Cs</code></term>
+ * <listitem><para>Character, #unsigned #char, and #signed #char.</para>
+ * <note><para>Of course <code>Cn</code> will be the same as either
+ * <code>Cu</code> or <code>Cs</code>, depending on the platform. For this
+ * reason, Glk avoids using it, but it is included here for completeness.
+ * </para></note>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>S</code></term>
+ * <listitem><para>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
+ * (<code>"#C"</code>), not string (<code>"S"</code>).</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>U</code></term>
+ * <listitem><para>A zero-terminated array of 32-bit integers. This is
+ * primarily intended as a Unicode equivalent of <code>"S"</code>. Like
+ * <code>"S"</code> strings, <code>"U"</code> strings are read-only and used
+ * immediately. A Glk call that wants to use writable Unicode arrays will use
+ * an array type (<code>"#Iu"</code>) instead of <code>"U"</code>.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>F</code></term>
+ * <listitem><para>A floating-point value. Glk does not currently use
+ * floating-point values, but we might as well define a code for them.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>Qa, Qb, Qc...</code></term>
+ * <listitem><para>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 <link
+ * linkend="chimara-Interrogating-the-Interface">Interrogating the
+ * Interface</link>).</para>
+ * <note><para>
+ * If Glk expands to have more than 26 classes, we'll think of something.
+ * </para></note></listitem>
+ * </varlistentry>
+ * </variablelist>
+ * Any type code can be prefixed with one or more of the following characters
+ * (order does not matter):
+ * <variablelist>
+ * <varlistentry>
+ * <term><code>&</code></term>
+ * <listitem><para>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.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code><</code></term>
+ * <listitem><para>A reference which is pass-out only. The initial value is
+ * ignored, so you only need copy out the value after the call.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>></code></term>
+ * <listitem><para>A reference which is pass-in only.</para>
+ * <note><para>
+ * This is not generally used for simple types, but is useful for structures
+ * and arrays.
+ * </para></note></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>+</code></term>
+ * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
+ * <code>">"</code>, indicates that a valid reference is mandatory; %NULL
+ * cannot be passed.</para>
+ * <note><para>
+ * Note that even though the @ptrflag #gluniversal_t for a <code>"+"</code>
+ * reference is always %TRUE, it cannot be omitted.
+ * </para></note></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>:</code></term>
+ * <listitem><para>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 <code>":"</code> as
+ * equivalent to <code>"<+"</code>. The colon is never combined with any
+ * other prefix character.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>[...]</code></term>
+ * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
+ * <code>">"</code>, indicates a structure reference. Between the brackets
+ * is a complete argument list encoding string, including the number of
+ * arguments.</para>
+ * <note><para>
+ * For example, the prototype string for glk_select() is
+ * <code>"1<+[4IuQaIuIu]:"</code> — one argument, which is a
+ * pass-out non-%NULL reference to a structure, which contains four
+ * arguments.
+ * </para></note>
+ * <para>Currently, structures in Glk contain only basic types.</para>
+ * </listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>#</code></term>
+ * <listitem><para>Combined with <code>"&"</code>, <code>"<"</code>, or
+ * <code>">"</code>, indicates an array reference. As described above, this
+ * encompasses up to three #gluniversal_t objects — @ptrflag, pointer,
+ * and integer length.</para>
+ * <note><para>
+ * 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 <link linkend="chimara-Arrays">Arrays</link>.
+ * </para></note></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term><code>!</code></term>
+ * <listitem><para>Combined with <code>"#"</code>, 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
+ * <code>"&#!"</code> or <code>"<#!"</code> arrays. Instead, do
+ * it when the library releases the array.</para>
+ * <note><para>
+ * 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 <link
+ * linkend="gidispatch-set-retained-registry">Retained Array
+ * Registry</link>.
+ * </para></note></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * 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.
+ * <note><title>Chimara</title>
+ * <para>
+ * 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.
+ * </para></note>
+ */
+
+/**
+ * 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
+ * <emphasis>not</emphasis> 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.
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
+ * The returned data is written into @res, according to @method.
+ *
+ * The <structfield>chunknum</structfield> 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 <structfield>length</structfield> field is
+ * filled in with the length of the chunk in bytes. The
+ * <structfield>chunktype</structfield> 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
+ * <structfield>chunknum</structfield> and <structfield>length</structfield>
+ * parameters.
+ *
+ * If you specify %giblorb_method_FilePos,
+ * <structfield>data.startpos</structfield> 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, <structfield>data.ptr</structfield> 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
+ * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
+ * the chunk number from the <structfield>chunknum</structfield> 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
+ * <structfield>res.chunknum</structfield>.
+ *
+ * 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:
+ *
+ * <variablelist>
+ * <varlistentry>
+ * <term>%glkunix_arg_NoValue</term>
+ * <listitem><para>The argument appears by itself.</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_ValueFollows</term>
+ * <listitem><para>The argument must be followed by another argument (the
+ * value).</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_ValueCanFollow</term>
+ * <listitem><para>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.)</para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_NumberValue</term>
+ * <listitem><para>The argument must be followed by a number, which may be the
+ * next argument or part of this one. (That is, either <quote><code>-width
+ * 20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
+ * </para></listitem>
+ * </varlistentry>
+ * <varlistentry>
+ * <term>%glkunix_arg_End</term>
+ * <listitem><para>The <code>glkunix_arguments[]</code> array must be
+ * terminated with an entry containing this value.</para></listitem>
+ * </varlistentry>
+ * </variablelist>
+ *
+ * To accept arbitrary arguments which lack dashes, specify a name of
+ * <code>""</code> 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 <quote><code>thingfile -goo -wob8 -bom -hum
+ * song</code></quote>.
+ *
+ * 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 <code>(argc, argv)</code> list, which contain
+ * the arguments you requested from the command line. In deference to custom,
+ * <code>argv[0]</code> 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.
+ */
projects / rodin / chimara.git / blobdiff