Sync new GStreamer element to parent state
[projects/chimara/chimara.git] / libchimara / doc.c
1 /*
2  * doc.c - Contains the short and long descriptions of all the documentation
3  *         sections in the Glk spec, as well as the GtkDoc comments for symbols
4  *         defined only in glk.h.
5  */
6
7 /**
8  * SECTION:glk-exiting
9  * @short_description: How to terminate a Glk program cleanly
10  *
11  * A Glk program usually ends when the end of the glk_main() function is 
12  * reached. You can also terminate it earlier.
13  */ 
14
15 /**
16  * SECTION:glk-interrupt
17  * @short_description: Specifying an interrupt handler for cleaning up critical
18  * resources
19  *
20  * Most platforms have some provision for interrupting a program —
21  * <keycombo action="simul"><keycap function="command">command</keycap>
22  * <keycap>period</keycap></keycombo> on the Macintosh, <keycombo 
23  * action="simul"><keycap function="control">control</keycap><keycap>C</keycap>
24  * </keycombo> in Unix, possibly a window manager item, or other possibilities.
25  * This can happen at any time, including while execution is nested inside one 
26  * of your own functions, or inside a Glk library function.
27  *
28  * If you need to clean up critical resources, you can specify an interrupt
29  * handler function.
30  */
31
32 /**
33  * SECTION:glk-tick
34  * @short_description: Yielding time to the operating system
35  *
36  * Many platforms have some annoying thing that has to be done every so often,
37  * or the gnurrs come from the voodvork out and eat your computer.
38  * 
39  * Well, not really. But you should call glk_tick() every so often, just in
40  * case. It may be necessary to yield time to other applications in a
41  * cooperative-multitasking OS, or to check for player interrupts in an infinite
42  * loop.
43  */
44
45 /**
46  * SECTION:glk-types
47  * @short_description: Basic types used in Glk
48  *
49  * For simplicity, all the arguments used in Glk calls are of a very few types.
50  * <variablelist>
51  *  <varlistentry>
52  *    <term>32-bit unsigned integer</term>
53  *    <listitem><para>Unsigned integers are used wherever possible, which is
54  *    nearly everywhere. This type is called #glui32.</para></listitem>
55  *  </varlistentry>
56  *  <varlistentry>
57  *    <term>32-bit signed integer</term>
58  *    <listitem><para>This type is called #glsi32. Rarely used.</para>
59  *    </listitem>
60  *  </varlistentry>
61  *  <varlistentry>
62  *    <term>References to library objects</term>
63  *    <listitem><para>These are pointers to opaque C structures; each library
64  *    will use different structures, so you can not and should not try to
65  *    manipulate their contents. See <link 
66  *    linkend="chimara-Opaque-Objects">Opaque Objects</link>.</para></listitem>
67  *  </varlistentry>
68  *  <varlistentry>
69  *    <term>Pointer to one of the above types</term>
70  *    <listitem><para>Pointer to a structure which consists entirely of the
71  *    above types.</para></listitem>
72  *  </varlistentry>
73  *  <varlistentry>
74  *    <term><type>unsigned char</type></term> 
75  *    <listitem><para>This is used only for Latin-1 text characters; see 
76  *    <link linkend="chimara-Character-Encoding">Character Encoding</link>.
77  *    </para></listitem>
78  *  </varlistentry>
79  *  <varlistentry>
80  *    <term>Pointer to <type>char</type></term> 
81  *    <listitem><para>Sometimes this means a null-terminated string; sometimes
82  *    an unterminated buffer, with length as a separate #glui32 argument. The
83  *    documentation says which.</para></listitem>
84  *  </varlistentry>
85  *  <varlistentry>
86  *    <term>Pointer to <type>void</type></term> 
87  *    <listitem><para>When nothing else will do.</para></listitem>
88  *  </varlistentry>
89  * </variablelist>
90  */
91
92 /**
93  * SECTION:glk-opaque-objects
94  * @short_description: Complex objects in Glk
95  *
96  * Glk keeps track of a few classes of special objects. These are opaque to your
97  * program; you always refer to them using pointers to opaque C structures.
98  * 
99  * Currently, these classes are:
100  * <variablelist>
101  *  <varlistentry>
102  *    <term>Windows</term>
103  *    <listitem><para>Screen panels, used to input or output information.
104  *    </para></listitem>
105  *  </varlistentry>
106  *  <varlistentry>
107  *    <term>Streams</term>
108  *    <listitem><para>Data streams, to which you can input or output text.
109  *    </para>
110  *    <note><para>There are file streams and window streams, since you can
111  *    output data to windows or files.</para></note>
112  *    </listitem>
113  *  </varlistentry>
114  *  <varlistentry>
115  *    <term>File references</term>
116  *    <listitem><para>Pointers to files in permanent storage.</para>
117  *    <note><para>In Unix a file reference is a pathname; on the Mac, an
118  *    <type>FSSpec</type>. Actually there's a little more information included,
119  *    such as file type and whether it is a text or binary file.</para></note>
120  *    </listitem>
121  *  </varlistentry>
122  *  <varlistentry>
123  *    <term>Sound channels</term>
124  *    <listitem><para>Audio output channels.</para>
125  *    <note><para>Not all Glk libraries support sound.</para></note>
126  *    </listitem>
127  *  </varlistentry>
128  * </variablelist>
129  *
130  * <note><para>
131  * Note that there may be more object classes in future versions of the Glk API.
132  * </para></note>
133  * 
134  * When you create one of these objects, it is always possible that the creation
135  * will fail (due to lack of memory, or some other OS error.) When this happens,
136  * the allocation function will return %NULL instead of a valid pointer. You
137  * should always test for this possibility.
138  * 
139  * %NULL is never the identifier of any object (window, stream, file reference,
140  * or sound channel). The value %NULL is often used to indicate <quote>no
141  * object</quote> or <quote>nothing</quote>, but it is not a valid reference. If
142  * a Glk function takes an object reference as an argument, it is illegal to
143  * pass in %NULL unless the function definition says otherwise.
144  * 
145  * The <filename class="headerfile">glk.h</filename> file defines types
146  * #winid_t, #strid_t, #frefid_t, #schanid_t to store references. These are
147  * pointers to struct #glk_window_struct, #glk_stream_struct, 
148  * #glk_fileref_struct, and #glk_schannel_struct respectively. It is, of course,
149  * illegal to pass one kind of pointer to a function which expects another.
150  * 
151  * <note><para>
152  * This is how you deal with opaque objects from a C program. If you are using
153  * Glk through a virtual machine, matters will probably be different. Opaque
154  * objects may be represented as integers, or as VM objects of some sort.
155  * </para></note></para>
156  * <para>
157  * <refsect2 id="chimara-Rocks"><!-- Indeed it does. -->
158  * <title>Rocks</title>
159  * <para>
160  * Every one of these objects (window, stream, file reference, or sound channel)
161  * has a <quote>rock</quote> value. This is simply a 32-bit integer value which
162  * you provide, for your own purposes, when you create the object.
163  * </para>
164  * <note><para>The library &mdash; so to speak &mdash; stuffs this value under a
165  * rock for safe-keeping, and gives it back to you when you ask for it.
166  * </para></note>
167  * <note><para>If you don't know what to use the rocks for, provide 0 and forget
168  * about it.</para></note>
169  * </refsect2>
170  * <refsect2 id="chimara-Iterating-Through-Opaque-Objects">
171  * <title>Iteration Through Opaque Objects</title>
172  * <para>
173  * For each class of opaque objects, there is an iterate function, which you can
174  * use to obtain a list of all existing objects of that class. It takes the form
175  * |[
176  * CLASSid_t glk_CLASS_iterate(CLASSid_t obj, glui32 *rockptr);
177  * ]|
178  * ...where <code><replaceable>CLASS</replaceable></code> represents one of the
179  * opaque object classes. 
180  * </para>
181  * <note><para>
182  *   So, at the current time, these are the functions glk_window_iterate(),
183  *   glk_stream_iterate(), glk_fileref_iterate(), and glk_schannel_iterate().  
184  *   There may be more classes in future versions of the spec; they all behave
185  *   the same.
186  * </para></note>
187  * <para>
188  * Calling <code>glk_<replaceable>CLASS</replaceable>_iterate(%NULL, r)</code>
189  * returns the first object; calling 
190  * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> returns
191  * the next object, until there aren't any more, at which time it returns %NULL.
192  * </para>
193  * <para>
194  * The @rockptr argument is a pointer to a location; whenever  
195  * <code>glk_<replaceable>CLASS</replaceable>_iterate()</code> returns an
196  * object, the object's rock is stored in the location <code>(*@rockptr)</code>.
197  * If you don't want the rocks to be returned, you may set @rockptr to %NULL.
198  * </para>
199  * <para>
200  * You usually use this as follows:
201  * |[
202  * obj = glk_CLASS_iterate(NULL, NULL);
203  * while (obj) {
204  *    /* ...do something with obj... *<!-- -->/
205  *    obj = glk_CLASS_iterate(obj, NULL);
206  * }
207  * ]|
208  * </para>
209  * <para>
210  * If you create or destroy objects inside this loop, obviously, the results are
211  * unpredictable. However it is always legal to call 
212  * <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> as long as
213  * @obj is a valid object id, or %NULL.
214  * </para>
215  * <para>
216  * The order in which objects are returned is entirely arbitrary. The library
217  * may even rearrange the order every time you create or destroy an object of
218  * the given class. As long as you do not create or destroy any object, the rule
219  * is that <code>glk_<replaceable>CLASS</replaceable>_iterate(obj, r)</code> has
220  * a fixed result, and iterating through the results as above will list every
221  * object exactly once. 
222  * </para>
223  * </refsect2>
224  */
225
226 /**
227  * SECTION:glk-gestalt
228  * @short_description: Testing Glk's capabilities
229  *
230  * The <quote>gestalt</quote> mechanism (cheerfully stolen from the Mac OS) is a
231  * system by which the Glk API can be upgraded without making your life
232  * impossible. New capabilities (graphics, sound, or so on) can be added without
233  * changing the basic specification. The system also allows for 
234  * <quote>optional</quote> capabilities &mdash; those which not all Glk library
235  * implementations will support &mdash; and allows you to check for their
236  * presence without trying to infer them from a version number.
237  * 
238  * The basic idea is that you can request information about the capabilities of
239  * the API, by calling the gestalt functions.
240  */
241
242 /**
243  * SECTION:glk-character-input
244  * @short_description: Waiting for a single keystroke
245  *
246  * You can request that the player hit a single key. See <link 
247  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
248  * 
249  * If you use the basic text API, the character code which is returned can be
250  * any value from 0 to 255. The printable character codes have already been
251  * described. The remaining codes are typically control codes: <keycombo  
252  * action="simul"><keycap function="control">control</keycap>
253  * <keycap>A</keycap></keycombo> to <keycombo action="simul"><keycap 
254  * function="control">control</keycap><keycap>Z</keycap></keycombo> and a few
255  * others.
256  * 
257  * There are also a number of special codes, representing special keyboard
258  * keys, which can be returned from a char-input event. These are represented
259  * as 32-bit integers, starting with 4294967295 (0xFFFFFFFF) and working down.
260  * The special key codes are defined in the <filename 
261  * class="headerfile">glk.h</filename> file. They include one code for <keycap
262  * function="enter">return</keycap> or <keycap function="enter">enter</keycap>,
263  * one for <keycap function="delete">delete</keycap> or <keycap
264  * function="backspace">backspace</keycap>, twelve function keys, and one code
265  * for any key which has no Latin-1 or special code. The full list of key codes
266  * is included below.
267  * 
268  * Various implementations of Glk will vary widely in which characters the
269  * player can enter. The most obvious limitation is that some characters are
270  * mapped to others. For example, most keyboards return a <keycombo
271  * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
272  * </keycombo> code when the <keycap function="tab">tab</keycap> key is
273  * pressed. The Glk library, if it can recognize this at all, will generate a
274  * <keysym>%keycode_Tab</keysym> event (value 0xFFFFFFF7) when this occurs.
275  * Therefore, for these keyboards, no keyboard key will generate a <keycombo
276  * action="simul"><keycap function="control">control</keycap><keycap>I</keycap>
277  * </keycombo> event (value 9.) The Glk library will probably map many of the
278  * control codes to the other special keycodes.
279  * 
280  * <note><para>
281  *   On the other hand, the library may be very clever and discriminate between
282  *   <keycap>tab</keycap> and <keycombo action="simul"><keycap
283  *   function="control">control</keycap><keycap>I</keycap></keycombo>. This is
284  *   legal. The idea is, however, that if your program asks the player to
285  *   <quote><computeroutput>press the <keycap function="tab">tab</keycap>
286  *   key</computeroutput></quote>, you should check for a 
287  *   <keysym>%keycode_Tab</keysym> event as opposed to a <keycombo 
288  *   action="simul"><keycap function="control">control</keycap>
289  *   <keycap>I</keycap></keycombo> event.
290  * </para></note>
291  * 
292  * Some characters may not be enterable simply because they do not exist.
293  * 
294  * <note><para>
295  *   Not all keyboards have a <keycap function="home">home</keycap> or <keycap
296  *   function="end">end</keycap> key. A pen-based platform may not recognize
297  *   any control characters at all.
298  * </para></note>
299  * 
300  * Some characters may not be enterable because they are reserved for the
301  * purposes of the interface. For example, the Mac Glk library reserves the 
302  * <keycap function="tab">tab</keycap> key for switching between different Glk
303  * windows. Therefore, on the Mac, the library will never generate a
304  * <keysym>%keycode_Tab</keysym> event or a <keycombo action="simul">
305  * <keycap function="control">control</keycap><keycap>I</keycap></keycombo>
306  * event.
307  * 
308  * <note><para>
309  *   Note that the linefeed or <keycombo action="simul"><keycap  
310  *   function="control">control</keycap><keycap>J</keycap></keycombo> 
311  *   character, which is the only printable control character, is probably not
312  *   typable. This is because, in most libraries, it will be converted to
313  *   <keysym>%keycode_Return</keysym>. Again, you should check for
314  *   <keysym>%keycode_Return</keysym> if your program asks the player to 
315  *   <quote><computeroutput>press the <keycap function="enter">return</keycap>
316  *   key</computeroutput></quote>.
317  * </para></note>
318  * 
319  * <note><para>
320  *   The <keycap function="delete">delete</keycap> and <keycap
321  *   function="backspace">backspace</keycap> keys are merged into a single
322  *   keycode because they have such an astonishing history of being confused in
323  *   the first place... this spec formally waives any desire to define the
324  *   difference. Of course, a library is free to distinguish <keycap
325  *   function="delete">delete</keycap> and <keycap
326  *   function="backspace">backspace</keycap> during line input. This is when it
327  *   matters most; conflating the two during character input should not be a
328  *   large problem.
329  * </para></note>
330  *
331  * You can test for this by using the %gestalt_CharInput selector.
332  * 
333  * <note><para>
334  *   Glk porters take note: it is not a goal to be able to generate every
335  *   single possible key event. If the library says that it can generate a
336  *   particular keycode, then game programmers will assume that it is
337  *   available, and ask players to use it. If a <keysym>%keycode_Home</keysym>
338  *   event can only be generated by typing <keycombo action="seq"><keycap
339  *   function="escape">escape</keycap><keycombo action="simul"><keycap
340  *   function="control">control</keycap><keycap>A</keycap></keycombo>
341  *   </keycombo>, and the player does not know this, the player will be lost
342  *   when the game says <quote><computeroutput>Press the <keycap
343  *   function="home">home</keycap> key to see the next 
344  *   hint.</computeroutput></quote> It is better for the library to say that it
345  *   cannot generate a <keysym>%keycode_Home</keysym> event; that way the game
346  *   can detect the situation and ask the user to type <keycap>H</keycap>
347  *   instead.
348  * </para>
349  * <para>
350  *   Of course, it is better not to rely on obscure keys in any case. The arrow
351  *   keys and <keycap function="enter">return</keycap> are nearly certain to be
352  *   available; the others are of gradually decreasing reliability, and you
353  *   (the game programmer) should not depend on them. You must be certain to
354  *   check for the ones you want to use, including the arrow keys and <keycap
355  *   function="enter">return</keycap>, and be prepared to use different keys in
356  *   your interface if %gestalt_CharInput says they are not available.
357  * </para></note>
358  */
359
360 /**
361  * SECTION:glk-case
362  * @short_description: Changing the case of strings
363  *
364  * Glk has functions to manipulate the case of both Latin-1 and Unicode strings.
365  * One Latin-1 lowercase character corresponds to one uppercase character, and
366  * vice versa, so the Latin-1 functions act on single characters. The Unicode
367  * functions act on whole strings, since the length of the string may change.
368  */
369
370 /**
371  * SECTION:glk-normalize
372  * @short_description: Combining characters
373  *
374  * Comparing Unicode strings is difficult, because there can be several ways to
375  * represent a piece of text as a Unicode string. For example, the one-character
376  * string <quote>&egrave;</quote> (an accented <quote>e</quote>) will be
377  * displayed the same as the two-character string containing <quote>e</quote>
378  * followed by Unicode character 0x0300 (COMBINING GRAVE ACCENT). These strings
379  * should be considered equal.
380  *
381  * Therefore, a Glk program that accepts line input should convert its text to a
382  * normalized form before parsing it. These functions offer those conversions.
383  * The algorithms are defined by the Unicode spec (chapter 3.7) and <ulink
384  * url="http://www.unicode.org/reports/tr15/">Unicode Standard Annex
385  * &num;15</ulink>.
386  */
387
388 /**
389  * SECTION:glk-window-opening
390  * @short_description: Creating new windows and closing them
391  *
392  * You can open a new window using glk_window_open() and close it again using
393  * glk_window_close().
394  */
395
396 /**
397  * SECTION:glk-window-constraints
398  * @short_description: Manipulating the size of a window
399  *
400  * There are library functions to change and to measure the size of a window.
401  */
402
403 /**
404  * SECTION:glk-window-types
405  * @short_description: Blank, pair, text grid, text buffer, and graphics windows
406  * 
407  * A technical description of all the window types, and exactly how they behave.
408  */
409
410 /**
411  * SECTION:glk-echo-streams
412  * @short_description: Creating a copy of a window's output
413  *
414  * Every window has an associated window stream; you print to the window by
415  * printing to this stream. However, it is possible to attach a second stream to
416  * a window. Any text printed to the window is also echoed to this second
417  * stream, which is called the window's <quote>echo stream.</quote>
418  * 
419  * Effectively, any call to glk_put_char() (or the other output commands) which
420  * is directed to the window's window stream, is replicated to the window's echo
421  * stream. This also goes for the style commands such as glk_set_style().
422  * 
423  * Note that the echoing is one-way. You can still print text directly to the
424  * echo stream, and it will go wherever the stream is bound, but it does not
425  * back up and appear in the window. 
426  *
427  * An echo stream can be of any type, even another window's window stream.
428  * 
429  * <note><para>
430  *   This would be somewhat silly, since it would mean that any text printed to
431  *   the window would be duplicated in another window. More commonly, you would
432  *   set a window's echo stream to be a file stream, in order to create a
433  *   transcript file from that window.
434  * </para></note>
435  *
436  * A window can only have one echo stream. But a single stream can be the echo
437  * stream of any number of windows, sequentially or simultaneously.
438  *
439  * If a window is closed, its echo stream remains open; it is not automatically
440  * closed. 
441  *
442  * <note><para>
443  *   Do not confuse the window's window stream with its echo stream. The window
444  *   stream is <quote>owned</quote> by the window, and dies with it. The echo
445  *   stream is merely temporarily associated with the window.
446  * </para></note>
447  * 
448  * If a stream is closed, and it is the echo stream of one or more windows,
449  * those windows are reset to not echo anymore. (So then calling
450  * glk_window_get_echo_stream() on them will return %NULL.) 
451  */
452
453 /**
454  * SECTION:glk-window-other
455  * @short_description: Miscellaneous functions for windows
456  *
457  * This section contains functions for windows that don't fit anywhere else.
458  */
459
460 /**
461  * SECTION:glk-events
462  * @short_description: Waiting for events
463  *
464  * As described in <link linkend="chimara-Your-Programs-Main-Function">Your
465  * Program's Main Function</link>, all player input is handed to your program by
466  * the glk_select() call, in the form of events. You should write at least one
467  * event loop to retrieve these events.
468  */
469
470 /**
471  * SECTION:glk-character-input-events
472  * @short_description: Events representing a single keystroke
473  *
474  * You can request character input from text buffer and text grid windows. See 
475  * %evtype_CharInput. There are separate functions for requesting Latin-1 input
476  * and Unicode input; see %gestalt_Unicode.
477  */
478
479 /**
480  * SECTION:glk-line-input-events
481  * @short_description: Events representing a line of user input
482  *
483  * You can request line input from text buffer and text grid windows. See
484  * %evtype_LineInput. There are separate functions for requesting Latin-1 input
485  * and Unicode input; see %gestalt_Unicode.
486  */
487
488 /**
489  * SECTION:glk-mouse-events
490  * @short_description: Events representing a mouse click
491  *
492  * On some platforms, Glk can recognize when the mouse (or other pointer) is 
493  * used to select a spot in a window. You can request mouse input only in text 
494  * grid windows and graphics windows.
495  * 
496  * A window can have mouse input and character/line input pending at the same
497  * time.
498  * 
499  * If the player clicks in a window which has a mouse input event pending,
500  * glk_select() will return an event whose type is %evtype_MouseInput. Again,
501  * once this happens, the request is complete, and you must request another if
502  * you want further mouse input.
503  * 
504  * In the event structure, @win tells what window the event came from.
505  * 
506  * In a text grid window, the @val1 and @val2 fields are the x and y coordinates
507  * of the character that was clicked on. 
508  * <note><para>So @val1 is the column, and @val2 is the row.</para></note>
509  * The top leftmost character is considered to be (0,0).
510  * 
511  * In a graphics window, they are the x and y coordinates of the pixel that was
512  * clicked on. Again, the top left corner of the window is (0,0).
513  * 
514  * <note><para>
515  *   Most mouse-based idioms define standard functions for mouse hits in text
516  *   windows &mdash; typically selecting or copying text. It is up to the
517  *   library to separate this from Glk mouse input. The library may choose to
518  *   select text when it is clicked normally, and cause Glk mouse events when
519  *   text is control-clicked. Or the other way around. Or it may be the
520  *   difference between clicking and double-clicking. Or the library may
521  *   reserve a particular mouse button, on a multi-button mouse. It may even
522  *   specify a keyboard key to be the "mouse button", referring to wherever the
523  *   mouse cursor is when the key is hit. Or some even more esoteric positioning
524  *   system. You need only know that the user can do it, or not.
525  * </para></note> 
526  * <note><para>
527  *   However, since different platforms will handle this issue differently, you
528  *   should be careful how you instruct the player in your program. Do not tell
529  *   the player to <quote>double-click</quote>, <quote>right-click</quote>, or
530  *   <quote>control-click</quote> in a window. The preferred term is <quote>to
531  *   touch the window</quote>, or a spot in the window.
532  * </para></note>
533  * <note><para>
534  *   Goofy, but preferred.
535  * </para></note>
536  */
537
538 /**
539  * SECTION:glk-timer-events
540  * @short_description: Events sent at fixed intervals
541  *
542  * You can request that an event be sent at fixed intervals, regardless of what
543  * the player does. Unlike input events, timer events can be tested for with
544  * glk_select_poll() as well as glk_select().
545  *
546  * It is possible that the library does not support timer events. You can check
547  * this with the %gestalt_Timer selector.
548  */
549  
550 /**
551  * SECTION:glk-streams
552  * @short_description: Input and output abstractions
553  *
554  * All character output in Glk is done through streams. Every window has an
555  * output stream associated with it. You can also write to files on disk; every
556  * open file is represented by an output stream as well.
557  *
558  * There are also input streams; these are used for reading from files on disk.
559  * It is possible for a stream to be both an input and an output stream. 
560  *
561  * <note><para>
562  *   Player input is done through line and character input events, not streams.
563  *   This is a small inelegance in theory. In practice, player input is slow and
564  *   things can interrupt it, whereas file input is immediate. If a network
565  *   extension to Glk were proposed, it would probably use events and not
566  *   streams, since network communication is not immediate.
567  * </para></note>
568  *
569  * It is also possible to create a stream that reads or writes to a buffer in
570  * memory.
571  * 
572  * Finally, there may be platform-specific types of streams, which are created
573  * before your program starts running. 
574  *
575  * <note><para>
576  *   For example, a program running under Unix may have access to standard input
577  *   as a stream, even though there is no Glk call to explicitly open standard
578  *   input. On the Mac, data in a Mac resource may be available through a
579  *   resource-reading stream.
580  * </para></note>
581  *
582  * You do not need to worry about the origin of such streams; just read or write
583  * them as usual. For information about how platform-specific streams come to
584  * be, see <link linkend="chimara-Startup-Options">Startup Options</link>.
585  * 
586  * A stream is opened with a particular file mode, see the 
587  * <code>filemode_</code> constants below.
588  *
589  * <note><para>
590  *   In the stdio library, using fopen(), %filemode_Write would be mode
591  *   <code>"w"</code>; %filemode_Read would be mode <code>"r"</code>;
592  *   %filemode_ReadWrite would be mode <code>"r+"</code>. Confusingly,
593  *   %filemode_WriteAppend cannot be mode <code>"a"</code>, because the stdio
594  *   spec says that when you open a file with mode <code>"a"</code>, then
595  *   fseek() doesn't work. So we have to use mode <code>"r+"</code> for
596  *   appending. Then we run into the <emphasis>other</emphasis> stdio problem,
597  *   which is that <code>"r+"</code> never creates a new file. So
598  *   %filemode_WriteAppend has to <emphasis>first</emphasis> open the file with
599  *   <code>"a"</code>, close it, reopen with <code>"r+"</code>, and then
600  *   fseek() to the end of the file. For %filemode_ReadWrite, the process is
601  *   the same, except without the fseek() &mdash; we begin at the beginning of
602  *   the file.
603  * </para></note>
604  * <note><para>
605  *   We must also obey an obscure geas of ANSI C <code>"r+"</code> files: you
606  *   can't switch from reading to writing without doing an fseek() in between.
607  *   Switching from writing to reading has the same restriction, except that an
608  *   fflush() also works.
609  * </para></note>
610  *
611  * For information on opening streams, see the discussion of each specific type
612  * of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
613  * Streams</link>. Remember that it is always possible that opening a stream
614  * will fail, in which case the creation function will return %NULL.
615  * 
616  * Each stream remembers two character counts, the number of characters printed
617  * to and read from that stream. The write-count is exactly one per 
618  * glk_put_char() call; it is figured before any platform-dependent character
619  * cookery. 
620  *
621  * <note><para>
622  *   For example, if a newline character is converted to 
623  *   linefeed-plus-carriage-return, the stream's count still only goes up by
624  *   one; similarly if an accented character is displayed as two characters.
625  * </para></note>
626  * 
627  * The read-count is exactly one per glk_get_char_stream() call, as long as the
628  * call returns an actual character (as opposed to an end-of-file token.) 
629  *
630  * Glk has a notion of the <quote>current (output) stream</quote>. If you print
631  * text without specifying a stream, it goes to the current output stream. The
632  * current output stream may be %NULL, meaning that there isn't one. It is
633  * illegal to print text to stream %NULL, or to print to the current stream when
634  * there isn't one.
635  *
636  * If the stream which is the current stream is closed, the current stream
637  * becomes %NULL. 
638  */
639  
640 /**
641  * SECTION:glk-print
642  * @short_description: Printing to streams
643  *
644  * You can print Latin-1 and Unicode characters, null-terminated strings, or
645  * buffers to any stream. The characters will be converted into the appropriate
646  * format for that stream.
647  */
648  
649 /**
650  * SECTION:glk-read
651  * @short_description: Reading from streams
652  *
653  * You can read Latin-1 or Unicode characters, buffers, or whole lines from any
654  * stream. The characters will be converted into the form in which you request
655  * them.
656  */
657  
658 /**
659  * SECTION:glk-closing-streams
660  * @short_description: Closing streams and retrieving their character counts
661  *
662  * When you close a Glk stream, you have the opportunity to examine the
663  * character counts &mdash; the number of characters written to or read from the
664  * stream.
665  */
666
667 /**
668  * SECTION:glk-stream-positions
669  * @short_description: Moving the read/write mark
670  *
671  * You can set the position of the read/write mark in a stream.
672  *
673  * <note><para>
674  *   Which makes one wonder why they're called <quote>streams</quote> in the
675  *   first place. Oh well.
676  * </para></note>
677  */
678
679 /**
680  * SECTION:glk-styles
681  * @short_description: Changing the appearance of printed text
682  *
683  * You can send style-changing commands to an output stream. After a style
684  * change, new text which is printed to that stream will be given the new style,
685  * whatever that means for the stream in question. For a window stream, the text
686  * will appear in that style. For a memory stream, style changes have no effect.
687  * For a file stream, if the machine supports styled text files, the styles may
688  * be written to the file; more likely the style changes will have no effect.
689  * 
690  * Styles are exclusive. A character is shown with exactly one style, not a 
691  * subset of the possible styles.
692  *
693  * <note><para>
694  *  Note that every stream and window has its own idea of the <quote>current 
695  *  style.</quote> Sending a style command to one window or stream does not
696  *  affect any others.
697  * </para></note>
698  * <note><para>
699  *  Except for a window's echo stream; see <link 
700  *  linkend="chimara-Echo-Streams">Echo Streams</link>.
701  * </para></note>
702  * 
703  * The styles are intended to distinguish meaning and use, not formatting. There
704  * is no standard definition of what each style will look like. That is left up
705  * to the Glk library, which will choose an appearance appropriate for the
706  * platform's interface and the player's preferences.
707  * 
708  * There are currently eleven styles defined. More may be defined in the future.
709  * 
710  * Styles may be distinguished on screen by font, size, color, indentation,
711  * justification, and other attributes. Note that some attributes (notably
712  * justification and indentation) apply to entire paragraphs. If possible and
713  * relevant, you should apply a style to an entire paragraph &mdash; call 
714  * glk_set_style() immediately after printing the newline at the beginning of
715  * the text, and do the same at the end.
716  * 
717  * <note><para>
718  *  For example, %style_Header may well be centered text. If you print 
719  *  <quote>Welcome to Victim (a short interactive mystery)</quote>, and only the
720  *  word <quote>Victim</quote> is in the %style_Header, the center-justification
721  *  attribute will be lost. Similarly, a block quote is usually indented on both
722  *  sides, but indentation is only meaningful when applied to an entire line or
723  *  paragraph, so block quotes should take up an entire paragraph. Contrariwise,
724  *  %style_Emphasized need not be used on an entire paragraph. It is often used
725  *  for single emphasized words in normal text, so you can expect that it will
726  *  appear properly that way; it will be displayed in italics or underlining, 
727  *  not center-justified or indented.
728  * </para></note> 
729  * 
730  * <note><para>
731  *  Yes, this is all a matter of mutual agreement between game authors and game
732  *  players. It's not fixed by this specification. That's natural language for
733  *  you.
734  * </para></note>
735  */
736
737 /**
738  * SECTION:glk-stylehints
739  * @short_description: Setting style hints
740  *
741  * There are no guarantees of how styles will look, but you can make 
742  * suggestions.
743  *
744  * Initially, no hints are set for any window type or style. Note that having no
745  * hint set is not the same as setting a hint with value 0.
746  * 
747  * These functions do <emphasis>not</emphasis> affect 
748  * <emphasis>existing</emphasis> windows. They affect the windows which you
749  * create subsequently. If you want to set hints for all your game windows, call
750  * glk_stylehint_set() before you start creating windows. If you want different
751  * hints for different windows, change the hints before creating each window.
752  * 
753  * <note><para>
754  *  This policy makes life easier for the interpreter. It knows everything about
755  *  a particular window's appearance when the window is created, and it doesn't
756  *  have to change it while the window exists.
757  * </para></note>
758  * 
759  * Hints are hints. The interpreter may ignore them, or give the player a choice
760  * about whether to accept them. Also, it is never necessary to set hints. You
761  * don't have to suggest that %style_Preformatted be fixed-width, or 
762  * %style_Emphasized be boldface or italic; they will have appropriate defaults.
763  * Hints are for situations when you want to <emphasis>change</emphasis> the 
764  * appearance of a style from what it would ordinarily be. The most common case
765  * when this is appropriate is for the styles %style_User1 and %style_User2.
766  * 
767  * There are currently ten style hints defined. More may be defined in the 
768  * future. 
769  * 
770  * Again, when passing a style hint to a Glk function, any value is actually 
771  * legal. If the interpreter does not recognize the stylehint value, it will 
772  * ignore it. 
773  * <note><para>
774  *  This policy allows for the future definition of style hints without breaking
775  *  old Glk libraries.
776  * </para></note> 
777  */
778
779 /**
780  * SECTION:glk-style-measure
781  * @short_description: Finding out how the library displays your style hints
782  *
783  * You can suggest the appearance of a window's style before the window is
784  * created; after the window is created, you can test the style's actual
785  * appearance. These functions do not test the style hints; they test the
786  * attribute of the style as it appears to the player.
787  *
788  * Note that although you cannot change the appearance of a window's styles
789  * after the window is created, the library can. A platform may support dynamic
790  * preferences, which allow the player to change text formatting while your
791  * program is running.
792  * <note><para>
793  *   Changes that affect window size (such as font size changes) will be
794  *   signalled by an %evtype_Arrange event. However, more subtle changes (such
795  *   as text color differences) are not signalled. If you test the appearance of
796  *   styles at the beginning of your program, you must keep in mind the
797  *   possibility that the player will change them later.
798  * </para></note>
799  */
800
801 /**
802  * SECTION:glk-stream-types
803  * @short_description: Window, memory, file, and resource streams
804  *
805  * <refsect2 id="chimara-Window-Streams"><title>Window Streams</title>
806  * <para>
807  * Every window has an output stream associated with it. This is created
808  * automatically, with %filemode_Write, when you open the window. You get it
809  * with glk_window_get_stream(). Window streams always have rock value 0.
810  * 
811  * A window stream cannot be closed with glk_stream_close(). It is closed
812  * automatically when you close its window with glk_window_close().
813  * 
814  * Only printable characters (including newline) may be printed to a window
815  * stream. See <link linkend="chimara-Character-Encoding">Character 
816  * Encoding</link>.
817  * </para>
818  * </refsect2>
819  * <refsect2 id="chimara-Memory-Streams"><title>Memory Streams</title>
820  * <para>
821  * You can open a stream which reads from or writes to a space in memory. See
822  * glk_stream_open_memory() and glk_stream_open_memory_uni(). When opening a
823  * memory stream, you specify a buffer to which the stream's output will be
824  * written, and its length @buflen.
825  *
826  * When outputting, if more than @buflen characters are written to the stream,
827  * all of them beyond the buffer length will be thrown away, so as not to
828  * overwrite the buffer. (The character count of the stream will still be
829  * maintained correctly. That is, it will count the number of characters written
830  * into the stream, not the number that fit into the buffer.)
831  *
832  * If the buffer is %NULL, or for that matter if @buflen is zero, then 
833  * <emphasis>everything</emphasis> written to the stream is thrown away. This
834  * may be useful if you are interested in the character count.
835  *
836  * When inputting, if more than @buflen characters are read from the stream, the
837  * stream will start returning -1 (signalling end-of-file.) If the buffer is 
838  * %NULL, the stream will always return end-of-file.
839  *
840  * The data is written to the buffer exactly as it was passed to the printing
841  * functions (glk_put_char(), etc.); input functions will read the data exactly
842  * as it exists in memory. No platform-dependent cookery will be done on it.
843  *
844  * <note><para>
845  *   You can write a disk file in text mode, but a memory stream is effectively
846  *   always in binary mode.
847  * </para></note>
848  * 
849  * Whether reading or writing, the contents of the buffer are undefined until
850  * the stream is closed. The library may store the data there as it is written,
851  * or deposit it all in a lump when the stream is closed. It is illegal to
852  * change the contents of the buffer while the stream is open.
853  * </para>
854  * </refsect2>
855  * <refsect2 id="chimara-File-Streams"><title>File Streams</title>
856  * <para>
857  * You can open a stream which reads from or writes to a disk file. See 
858  * glk_stream_open_file() and glk_stream_open_file_uni().
859  *
860  * The file may be written in text or binary mode; this is determined by the
861  * file reference you open the stream with. Similarly, platform-dependent
862  * attributes such as file type are determined by the file reference. See <link
863  * linkend="chimara-File-References">File References</link>.
864  * </para>
865  * </refsect2>
866  * <refsect2 id="chimara-Resource-Streams"><title>Resource Streams</title>
867  * <para>
868  * You can open a stream which reads from (but not writes to) a resource file.
869  *
870  * <note><para>
871  *   Typically this is embedded in a Blorb file, as Blorb is the official
872  *   resource-storage format of Glk. A Blorb file can contain images and sounds,
873  *   but it can also contain raw data files, which are accessed by
874  *   glk_stream_open_resource() and glk_stream_open_resource_uni(). A data file
875  *   is identified by number, not by a filename. The Blorb usage field will be
876  *   <code>'Data'</code>. The chunk type will be %giblorb_ID_TEXT for text
877  *   resources, %giblorb_ID_BINA for binary resources.
878  * </para></note>
879  *
880  * <note><para>
881  *   If the running program is not associated with a Blorb file, the library may
882  *   look for data files as actual files instead. These would be named
883  *   <filename>DATA1</filename>, <filename>DATA2</filename>, etc, with a suffix
884  *   distinguishing text and binary files. See <quote>Other Resource
885  *   Arrangements</quote> in the Blorb spec: <ulink
886  *   url="http://eblong.com/zarf/blorb/"></ulink>
887  * </para></note>
888  * </para>
889  * </refsect2>
890  */
891  
892 /**
893  * SECTION:glk-stream-other
894  * @short_description: Miscellaneous functions for streams
895  *
896  * This section includes functions for streams that don't fit anywhere else.
897  */
898
899 /**
900  * SECTION:glk-fileref
901  * @short_description: A platform-independent way to refer to disk files
902  *
903  * You deal with disk files using file references. Each fileref is an opaque C
904  * structure pointer; see <link linkend="chimara-Opaque-Objects">Opaque 
905  * Objects</link>.
906  * 
907  * A file reference contains platform-specific information about the name and
908  * location of the file, and possibly its type, if the platform has a notion of
909  * file type. It also includes a flag indication whether the file is a text file
910  * or binary file. 
911  *
912  * <note><para>
913  *   Note that this is different from the standard C I/O library, in which you
914  *   specify text or binary mode when the file is opened.
915  * </para></note>
916  * 
917  * A fileref does not have to refer to a file which actually exists. You can
918  * create a fileref for a nonexistent file, and then open it in write mode to
919  * create a new file.
920  * 
921  * You always provide a usage argument when you create a fileref. The usage
922  * indicates the file type and the mode (text or binary.) It must be the
923  * logical-or of a file-type constant and a mode constant. These values are used
924  * when you create a new file, and also to filter file lists when the player is
925  * selecting a file to load.
926  * 
927  * In general, you should use text mode if the player expects to read the file
928  * with a platform-native text editor; you should use binary mode if the file is
929  * to be read back by your program, or if the data must be stored exactly. Text
930  * mode is appropriate for %fileusage_Transcript; binary mode is appropriate for
931  * %fileusage_SavedGame and probably for %fileusage_InputRecord. %fileusage_Data
932  * files may be text or binary, depending on what you use them for. 
933  */
934  
935 /**
936  * SECTION:glk-fileref-types
937  * @short_description: Four different ways to create a file reference
938  *
939  * There are four different functions for creating a fileref, depending on how
940  * you wish to specify it. Remember that it is always possible that a fileref
941  * creation will fail and return %NULL.
942  */
943  
944 /**
945  * SECTION:glk-fileref-other
946  * @short_description: Miscellaneous functions for file references
947  *
948  * This section includes functions for file references that don't fit anywhere
949  * else.
950  */
951
952 /**
953  * SECTION:glk-image-resources
954  * @short_description: Graphics in Glk
955  *
956  * In accordance with this modern age, Glk provides for a modicum of graphical
957  * flair. It does not attempt to be a complete graphical toolkit. Those already
958  * exist. Glk strikes the usual uncomfortable balance between power, 
959  * portability, and ease of implementation: commands for arranging pre-supplied
960  * images on the screen and intermixed with text.
961  * 
962  * Graphics is an optional capability in Glk; not all libraries support 
963  * graphics. This should not be a surprise.
964  * 
965  * Most of the graphics commands in Glk deal with image resources. Your program
966  * does not have to worry about how images are stored. Everything is a resource,
967  * and a resource is referred to by an integer identifier. You may, for example,
968  * call a function to display image number 17. The format, loading, and 
969  * displaying of that image is entirely up to the Glk library for the platform
970  * in question.
971  * 
972  * Of course, it is also desirable to have a platform-independent way to store
973  * sounds and images. Blorb is the official resource-storage format of Glk. A
974  * Glk library does not have to understand Blorb, but it is more likely to
975  * understand Blorb than any other format.
976  *
977  * <note><para>
978  *   Glk does not specify the exact format of images, but Blorb does. Images in 
979  *   a Blorb archive must be PNG or JPEG files. More formats may be added if 
980  *   real-world experience shows it to be desirable. However, that is in the 
981  *   domain of the Blorb specification. The Glk spec, and Glk programming, will
982  *   not change.
983  * </para></note>
984  * 
985  * At present, images can only be drawn in graphics windows and text buffer 
986  * windows. In fact, a library may not implement both of these possibilities.
987  * You should test each with the %gestalt_DrawImage selector if you plan to use
988  * it. See <link linkend="chimara-Testing-for-Graphics-Capabilities">Testing for
989  * Graphics Capabilities</link>. 
990  */
991
992 /**
993  * SECTION:glk-graphics-windows
994  * @short_description: Drawing graphics in graphics windows
995  *
996  * A graphics window is a rectangular canvas of pixels, upon which you can draw
997  * images. The contents are entirely under your control. You can draw as many
998  * images as you like, at any positions &mdash; overlapping if you like. If the
999  * window is resized, you are responsible for redrawing everything. See <link
1000  * linkend="wintype-Graphics">Graphics Windows</link>.
1001  * 
1002  * <note><para>
1003  *   Note that graphics windows do not support a full set of object-drawing 
1004  *   commands, nor can you draw text in them. That may be available in a future 
1005  *   Glk extension. For now, it seems reasonable to limit the task to a single 
1006  *   primitive, the drawing of a raster image. And then there's the ability to
1007  *   fill a rectangle with a solid color &mdash; a small extension, and 
1008  *   hopefully no additional work for the library, since it can already clear 
1009  *   with arbitrary background colors. In fact, if glk_window_fill_rect() did 
1010  *   not exist, an author could invent it &mdash; by briefly setting the
1011  *   background color, erasing a rectangle, and restoring.
1012  * </para></note>
1013  * 
1014  * If you call glk_image_draw() or glk_image_draw_scaled() in a graphics window,
1015  * @val1 and @val2 are interpreted as X and Y coordinates. The image will be 
1016  * drawn with its upper left corner at this position.
1017  * 
1018  * It is legitimate for part of the image to fall outside the window; the excess
1019  * is not drawn. Note that these are signed arguments, so you can draw an image
1020  * which falls outside the left or top edge of the window, as well as the right
1021  * or bottom.
1022  * 
1023  * There are a few other commands which apply to graphics windows.
1024  */
1025
1026 /**
1027  * SECTION:glk-graphics-text
1028  * @short_description: Drawing graphics inside or beside text
1029  *
1030  * A text buffer is a linear text stream. You can draw images in-line with this
1031  * text. If you are familiar with HTML, you already understand this model. You
1032  * draw images with flags indicating alignment. The library takes care of
1033  * scrolling, resizing, and reformatting text buffer windows.
1034  *
1035  * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
1036  * window, @val1 gives the image alignment. The @val2 argument is currently
1037  * unused, and should always be zero.
1038  *
1039  * The two <quote>margin</quote> alignments require some care. To allow proper 
1040  * positioning, images using %imagealign_MarginLeft and %imagealign_MarginRight 
1041  * must be placed at the beginning of a line. That is, you may only call 
1042  * glk_image_draw() (with these two alignments) in a window, if you have just 
1043  * printed a newline to the window's stream, or if the window is entirely empty.
1044  * If you margin-align an image in a line where text has already appeared, no 
1045  * image will appear at all.
1046  * 
1047  * Inline-aligned images count as <quote>text</quote> for the purpose of this 
1048  * rule.
1049  * 
1050  * You may have images in both margins at the same time.
1051  * 
1052  * It is also legal to have more than one image in the same margin (left or 
1053  * right.) However, this is not recommended. It is difficult to predict how text
1054  * will wrap in that situation, and libraries may err on the side of 
1055  * conservatism. 
1056  */
1057
1058 /**
1059  * SECTION:glk-graphics-testing
1060  * @short_description: Checking whether the library supports graphics
1061  *
1062  * Before calling Glk graphics functions, you should use the gestalt selector
1063  * %gestalt_Graphics. To test for additional capabilities, you can also use the
1064  * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors.
1065  */
1066
1067 /**
1068  * SECTION:glk-sound-channels
1069  * @short_description: Creating new sound channels and closing them
1070  *
1071  * Sounds in Glk are played through sound channels. Sound channels are another
1072  * type of opaque object, like windows, streams, and file references.
1073  */
1074
1075 /**
1076  * SECTION:glk-playing-sounds
1077  * @short_description: Producing noise
1078  *
1079  * These functions play the actual sounds through the sound channels.
1080  */
1081
1082 /**
1083  * SECTION:glk-sound-other
1084  * @short_description: Miscellaneous functions for sound channels
1085  *
1086  * This section includes functions for sound channels that don't fit anywhere
1087  * else.
1088  */
1089
1090 /**
1091  * SECTION:glk-sound-testing
1092  * @short_description: Checking whether the library supports sound
1093  *
1094  * Before calling Glk sound functions, you should use the %gestalt_Sound2
1095  * selector.
1096  *
1097  * Earlier versions of the Glk spec defined separate selectors for various
1098  * optional capabilities. This has proven to be an unnecessarily confusing
1099  * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic,
1100  * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you
1101  * should not need to test them; the %gestalt_Sound2 selector covers all of
1102  * them.
1103  */
1104
1105 /**
1106  * SECTION:glk-creating-hyperlinks
1107  * @short_description: Printing text as a hyperlink
1108  *
1109  * Some games may wish to mark up text in their windows with hyperlinks, which
1110  * can be selected by the player &mdash; most likely by mouse click. Glk allows
1111  * this in a manner similar to the way text styles are set.
1112  *
1113  * Hyperlinks are an optional capability in Glk.
1114  */
1115
1116 /**
1117  * SECTION:glk-accepting-hyperlinks
1118  * @short_description: Generating and catching hyperlink navigation events
1119  *
1120  * When you request a hyperlink event in a window, you will receive a hyperlink
1121  * event when the player clicks on a hyperlink.
1122  */
1123
1124 /**
1125  * SECTION:glk-hyperlinks-testing
1126  * @short_description: Checking whether the library supports hyperlinks
1127  *
1128  * Before calling Glk hyperlink functions, you should use the gestalt selectors
1129  * %gestalt_Hyperlinks and %gestalt_HyperlinkInput.
1130  */
1131
1132 /**
1133  * SECTION:glk-clock
1134  * @short_description: Getting the current time from the system clock
1135  *
1136  * You can get the current time, either as a Unix timestamp (seconds since 1970)
1137  * or as a broken-out structure of time elements (year, month, day, hour,
1138  * minute, second).
1139  *
1140  * The system clock is not guaranteed to line up with timer events (see <link 
1141  * linkend="chimara-Timer-Events">Timer Events</link>). Timer events may be
1142  * delivered late according to the system clock.
1143  */
1144
1145 /**
1146  * SECTION:glk-clock-conversions
1147  * @short_description: Converting from timestamps to date structures and back
1148  *
1149  * This section describes functions for converting timestamps to more
1150  * human-readable date structures and back.
1151  */
1152
1153 /**
1154  * SECTION:glk-clock-testing
1155  * @short_description: Checking whether the library supports the clock functions
1156  *
1157  * Before calling Glk date and time functions, you should use the
1158  * %gestalt_DateTime selector.
1159  */
1160  
1161 /**
1162  * SECTION:dispatch-interrogating
1163  * @short_description: Finding out what functions the Glk library exports
1164  *
1165  * These are the ancilliary functions that let you enumerate.
1166  */
1167  
1168 /**
1169  * SECTION:dispatch-dispatching
1170  * @short_description: Dispatching the call to the Glk library
1171  *
1172  * The function gidispatch_call() invokes a function from the Glk library.
1173  */
1174  
1175 /**
1176  * SECTION:dispatch-prototypes
1177  * @short_description: Querying Glk function prototypes
1178  *
1179  * There are many possible ways to set up a #gluniversal_t array, and it's
1180  * illegal to call gidispatch_call() with an array which doesn't match the
1181  * function. Furthermore, some references are passed in, some passed out, and
1182  * some both. How do you know how to handle the argument list?
1183  * 
1184  * One possibility is to recognize each function selector, and set up the
1185  * arguments appropriately. However, this entails writing special code for each
1186  * Glk function; which is exactly what we don't want to do.
1187  * 
1188  * Instead, you can call gidispatch_prototype(). 
1189  */
1190
1191 /**
1192  * SECTION:dispatch-library-functions
1193  * @short_description: Platform-dependent dispatch layer functions
1194  *
1195  * Ideally, the three layers &mdash; program, dispatch layer, Glk library
1196  * &mdash; would be completely modular; each would refer only to the layers
1197  * beneath it. Sadly, there are a few places where the library must notify the
1198  * program that something has happened. Worse, these situations are only
1199  * relevant to programs which use the dispatch layer, and then only some of
1200  * those.
1201  * 
1202  * Since C is uncomfortable with the concept of calling functions which may not
1203  * exist, Glk handles this with call-back function pointers. The program can
1204  * pass callbacks in to the library; if it does, the library will call them, and
1205  * if not, the library doesn't try.
1206  * 
1207  * These callbacks are optional, in the sense that the program may or may not
1208  * set them. However, any library which wants to interoperate with the dispatch
1209  * layer must <emphasis>allow</emphasis> the program to set them; it is the
1210  * program's choice. The library does this by implementing
1211  * <code>set_registry functions</code> &mdash; the functions to which the
1212  * program passes its callbacks.
1213  * 
1214  * <note><para>
1215  *   Even though these callbacks and the functions to set them are declared in
1216  *   <filename class="headerfile">gi_dispa.h</filename>, they are not defined in
1217  *   <filename>gi_dispa.c</filename>. The dispatch layer merely coordinates
1218  *   them. The program defines the callback functions; the library calls them.
1219  * </para></note>
1220  */
1221
1222 /** 
1223  * SECTION:blorb-program
1224  * @short_description: How to use the Blorb layer in your program
1225  *
1226  * If you wish your program to load its resources from a Blorb file, you need to
1227  * find and open that file in your startup code. (See <link 
1228  * linkend="chimara-Startup-Options">Startup Options</link>.) Each platform will
1229  * have appropriate functions available for finding startup data. Be sure to
1230  * open the file in binary mode, not text mode. Once you have opened the file as
1231  * a Glk stream, pass it to giblorb_set_resource_map().
1232  *
1233  * If you do not call giblorb_set_resource_map() in your startup code, or if it
1234  * fails, the library is left to its own devices for finding resources. Some
1235  * libraries may try to load resources from individual files &mdash; 
1236  * <filename>PIC1</filename>, <filename>PIC2</filename>, 
1237  * <filename>PIC3</filename>, and so on. (See the Blorb specification for more 
1238  * on this approach.) Other libraries will not have any other loading mechanism
1239  * at all; no resources will be available. 
1240  */
1241
1242 /**
1243  * SECTION:blorb-layer
1244  * @short_description: The platform-independent functions in the Blorb layer
1245  *
1246  * These are the functions which are implemented in 
1247  * <filename>gi_blorb.c</filename>. They will be compiled into the library, but
1248  * they are the same on every platform. In general, only the library needs to
1249  * call these functions. The Glk program should allow the library to do all the
1250  * resource handling.
1251  */ 
1252  
1253 /** 
1254  * SECTION:blorb-errors
1255  * @short_description: Error codes returned by the Blorb layer functions
1256  *
1257  * All Blorb layer functions, including giblorb_set_resource_map(), return the
1258  * following error codes.
1259  */
1260
1261 /**
1262  * SECTION:glkext-startup
1263  * @short_description: Parsing startup options
1264  *
1265  * This section describes an extension to Glk for parsing command-line startup
1266  * options. It was written by Andrew Plotkin for the Glk libraries CheapGlk and
1267  * GlkTerm. 
1268  *
1269  * When you compile a Glk program, you may define a function called 
1270  * <function>glkunix_startup_code&lpar;&rpar;</function>, and an array 
1271  * <code>glkunix_arguments[]</code>. These set up various Unix-specific options
1272  * used by the Glk library. There is a sample 
1273  * <quote><filename>glkstart.c</filename></quote> file included in this package;
1274  * you should modify it to your needs.
1275  * 
1276  * |[ extern glkunix_argumentlist_t glkunix_arguments[]; ]|
1277  *  
1278  * The <code>glkunix_arguments[]</code> array is a list of command-line 
1279  * arguments that your program can accept. The library will sort these out of 
1280  * the command line and pass them on to your code.
1281  */
1282
1283 /**
1284  * SECTION:glkext-unix
1285  * @short_description: Unix-specific functions
1286  *
1287  * This section describes an extension to Glk for various Unix functions. It was
1288  * written by Andrew Plotkin for the Glk libraries CheapGlk and GlkTerm.
1289  *
1290  * You can put other startup code in glkunix_startup_code(). This should
1291  * generally be limited to finding and opening data files. There are a few Unix
1292  * Glk library functions which are convenient for this purpose.
1293  */
1294
1295 /**
1296  * SECTION:glkext-garglk
1297  * @short_description: Gargoyle extensions to Glk
1298  *
1299  * This section describes various extensions to Glk that were written for the
1300  * popular interpreter <ulink 
1301  * url="http://www.ccxvii.net/gargoyle/">Gargoyle</ulink> by Tor Andersson (now 
1302  * maintained by Ben Cressey).
1303  *
1304  * These functions mostly serve to close the gap between Glk's input/output
1305  * capabilities and what some interpreters expect. For example, 
1306  * garglk_set_zcolors() displays the colors defined in the Z-machine standard,
1307  * and garglk_set_story_name() can be used to give the host program a hint
1308  * about what to display in the title bar of its window.
1309  */ 
1310  
1311 /*---------------- TYPES AND CONSTANTS FROM GLK.H ----------------------------*/
1312
1313 /**
1314  * glui32:
1315  *
1316  * A 32-bit unsigned integer type, used wherever possible in Glk.
1317  */
1318  
1319 /**
1320  * glsi32:
1321  *
1322  * A 32-bit signed integer type, rarely used.
1323  */
1324
1325 /**
1326  * GLK_MODULE_UNICODE:
1327  *
1328  * If this preprocessor symbol is defined, so are the core Unicode functions and
1329  * constants (see %gestalt_Unicode). If not, not.
1330  */
1331
1332 /**
1333  * GLK_MODULE_IMAGE:
1334  *
1335  * If you are writing a C program, there is an additional complication. A
1336  * library which does not support graphics may not implement the graphics
1337  * functions at all. Even if you put gestalt tests around your graphics calls,
1338  * you may get link-time errors. If the <filename
1339  * class="headerfile">glk.h</filename> file is so old that it does not declare
1340  * the graphics functions and constants, you may even get compile-time errors.
1341  *
1342  * To avoid this, you can perform a preprocessor test for the existence of
1343  * %GLK_MODULE_IMAGE. If this is defined, so are all the functions and constants
1344  * described in this section. If not, not.
1345  *
1346  * <note><para>
1347  *   To be extremely specific, there are two ways this can happen. If the 
1348  *   <filename class="headerfile">glk.h</filename> file that comes with the
1349  *   library is too old to have the graphics declarations in it, it will of
1350  *   course lack %GLK_MODULE_IMAGE as well. If the <filename 
1351  *   class="headerfile">glk.h</filename> file is recent, but the library is old,
1352  *   the definition of %GLK_MODULE_IMAGE should be removed from <filename 
1353  *   class="headerfile">glk.h</filename>, to avoid link errors. This is not a
1354  *   great solution. A better one is for the library to implement the graphics
1355  *   functions as stubs that do nothing (or cause run-time errors). Since no
1356  *   program will call the stubs without testing %gestalt_Graphics, this is
1357  *   sufficient.
1358  * </para></note>
1359  */
1360
1361 /**
1362  * GLK_MODULE_SOUND2:
1363  *
1364  * If you are writing a C program, there is an additional complication. A 
1365  * library which does not support sound may not implement the sound functions at
1366  * all. Even if you put gestalt tests around your sound calls, you may get 
1367  * link-time errors. If the <filename class="headerfile">glk.h</filename> file 
1368  * is so old that it does not declare the sound functions and constants, you may
1369  * even get compile-time errors.
1370  * 
1371  * To avoid this, you can perform a preprocessor test for the existence of
1372  * %GLK_MODULE_SOUND2. If this is defined, so are all the functions and constants
1373  * described in this section. If not, not.
1374  */
1375
1376 /**
1377  * GLK_MODULE_SOUND:
1378  *
1379  * You can perform a preprocessor test for the existence of %GLK_MODULE_SOUND.
1380  * If this is defined, so are all the functions and constants described in this
1381  * section. If not, not.
1382  */
1383  
1384 /**
1385  * GLK_MODULE_HYPERLINKS:
1386  * 
1387  * If you are writing a C program, you can perform a preprocessor test for the
1388  * existence of %GLK_MODULE_HYPERLINKS. If this is defined, so are all the
1389  * functions and constants described in this section. If not, not.
1390  */
1391
1392 /**
1393  * GLK_MODULE_UNICODE_NORM:
1394  *
1395  * If this preprocessor symbol is defined, so are the Unicode normalization
1396  * functions (see %gestalt_UnicodeNorm). If not, not.
1397  */
1398
1399 /**
1400  * GLK_MODULE_DATETIME:
1401  *
1402  * If you are writing a C program, you can perform a preprocessor test for the
1403  * existence of %GLK_MODULE_DATETIME. If this is defined, so are all the
1404  * functions and data types described in this section.
1405  */
1406
1407 /**
1408  * GLK_MODULE_LINE_ECHO:
1409  *
1410  * If this preprocessor symbol is defined, so is glk_set_echo_line_event(). If
1411  * not, not.
1412  */
1413
1414 /**
1415  * GLK_MODULE_LINE_TERMINATORS:
1416  *
1417  * If this preprocessor symbol is defined, so is
1418  * glk_set_terminators_line_event(). If not, not.
1419  */
1420
1421 /**
1422  * winid_t:
1423  *
1424  * Opaque structure representing a Glk window. It has no user-accessible 
1425  * members.
1426  */
1427  
1428 /**
1429  * strid_t:
1430  *
1431  * Opaque structure representing an input or output stream. It has no
1432  * user-accessible members.
1433  */
1434  
1435 /**
1436  * frefid_t:
1437  * 
1438  * Opaque structure representing a file reference. It has no user-accessible
1439  * members.
1440  */
1441
1442 /**
1443  * schanid_t:
1444  * 
1445  * Opaque structure representing a sound channel. It has no user-accessible
1446  * members.
1447  */
1448   
1449 /**
1450  * gestalt_Version:
1451  *
1452  * For an example of the gestalt mechanism, consider the selector
1453  * %gestalt_Version. If you do
1454  * |[
1455  * glui32 res;
1456  * res = glk_gestalt(gestalt_Version, 0);
1457  * ]|
1458  * <code>res</code> will be set to a 32-bit number which encodes the version of
1459  * the Glk spec which the library implements. The upper 16 bits stores the major
1460  * version number; the next 8 bits stores the minor version number; the low 8 
1461  * bits stores an even more minor version number, if any.
1462  *
1463  * <note><para>
1464  *   So the version number 78.2.11 would be encoded as 0x004E020B.
1465  * </para></note>
1466  *
1467  * The current Glk specification version is 0.7.4, so this selector will return
1468  * 0x00000704.
1469  *
1470  * |[
1471  * glui32 res;
1472  * res = glk_gestalt_ext(gestalt_Version, 0, NULL, 0);
1473  * ]|
1474  * does exactly the same thing. Note that, in either case, the second argument 
1475  * is not used; so you should always pass 0 to avoid future surprises.
1476  */
1477
1478 /**
1479  * gestalt_CharInput:
1480  *
1481  * If you set <code>ch</code> to a character code, or a special code (from
1482  * 0xFFFFFFFF down), and call
1483  * |[
1484  * glui32 res;
1485  * res = glk_gestalt(gestalt_CharInput, ch);
1486  * ]|
1487  * then <code>res</code> will be %TRUE (1) if that character can be typed by
1488  * the player in character input, and %FALSE (0) if not. See <link
1489  * linkend="chimara-Character-Input">Character Input</link>.
1490  */
1491
1492 /**
1493  * gestalt_LineInput:
1494  *
1495  * If you set <code>ch</code> to a character code, and call
1496  * |[
1497  * glui32 res;
1498  * res = glk_gestalt(gestalt_LineInput, ch);
1499  * ]|
1500  * then <code>res</code> will be %TRUE (1) if that character can be typed by the
1501  * player in line input, and %FALSE (0) if not. Note that if <code>ch</code> is 
1502  * a nonprintable Latin-1 character (0 to 31, 127 to 159), then this is 
1503  * guaranteed to return %FALSE. See <link linkend="chimara-Line-Input">Line
1504  * Input</link>.
1505  */
1506
1507 /**
1508  * gestalt_CharOutput:
1509  *
1510  * If you set <code>ch</code> to a character code (Latin-1 or higher), and call
1511  * |[
1512  * glui32 res, len;
1513  * res = glk_gestalt_ext(gestalt_CharOutput, ch, &amp;len, 1);
1514  * ]|
1515  * then <code>res</code> will be one of %gestalt_CharOutput_CannotPrint,
1516  * %gestalt_CharOutput_ExactPrint, or %gestalt_CharOutput_ApproxPrint (see 
1517  * below.)
1518  * 
1519  * In all cases, <code>len</code> (the #glui32 value pointed at by the third
1520  * argument) will be the number of actual glyphs which will be used to represent
1521  * the character. In the case of %gestalt_CharOutput_ExactPrint, this will 
1522  * always be 1; for %gestalt_CharOutput_CannotPrint, it may be 0 (nothing 
1523  * printed) or higher; for %gestalt_CharOutput_ApproxPrint, it may be 1 or 
1524  * higher. This information may be useful when printing text in a fixed-width 
1525  * font.
1526  *
1527  * <note><para>
1528  *   As described in <link linkend="chimara-Other-API-Conventions">Other API
1529  *   Conventions</link>, you may skip this information by passing %NULL as the
1530  *   third argument in glk_gestalt_ext(), or by calling glk_gestalt() instead.
1531  * </para></note>
1532  *
1533  * This selector will always return %gestalt_CharOutput_CannotPrint if 
1534  * <code>ch</code> is an unprintable eight-bit character (0 to 9, 11 to 31, 127 
1535  * to 159.)
1536  *
1537  * <note><para>
1538  *   Make sure you do not get confused by signed byte values. If you set a
1539  *   <quote><type>signed char</type></quote> variable <code>ch</code> to 0xFE,
1540  *   the small-thorn character (&thorn;), it will wind up as -2. (The same is
1541  *   true of a <quote><type>char</type></quote> variable, if your compiler
1542  *   treats <quote><type>char</type></quote> as signed!) If you then call
1543  *   |[ res = glk_gestalt(gestalt_CharOutput, ch); ]|
1544  *   then (by the definition of C/C++) <code>ch</code> will be sign-extended to
1545  *   0xFFFFFFFE, which is not a legitimate character, even in Unicode. You
1546  *   should write
1547  *   |[ res = glk_gestalt(gestalt_CharOutput, (unsigned char)ch); ]|
1548  *   instead.
1549  * </para></note>
1550  * <note><para>
1551  *   Unicode includes the concept of non-spacing or combining characters, which 
1552  *   do not represent glyphs; and double-width characters, whose glyphs take up
1553  *   two spaces in a fixed-width font. Future versions of this spec may 
1554  *   recognize these concepts by returning a <code>len</code> of 0 or 2 when
1555  *   %gestalt_CharOutput_ExactPrint is used. For the moment, we are adhering to 
1556  *   a policy of <quote>simple stuff first</quote>.
1557  * </para></note>
1558  */
1559  
1560 /**
1561  * gestalt_CharOutput_CannotPrint:
1562  *
1563  * When the %gestalt_CharOutput selector returns this for a character, the
1564  * character cannot be meaningfully printed. If you try, the player may see
1565  * nothing, or may see a placeholder.
1566  */
1567
1568 /**
1569  * gestalt_CharOutput_ApproxPrint:
1570  *
1571  * When the %gestalt_CharOutput selector returns this for a character, the 
1572  * library will print some approximation of the character. It will be more or 
1573  * less right, but it may not be precise, and it may not be distinguishable from
1574  * other, similar characters. (Examples: 
1575  * <quote><computeroutput>ae</computeroutput></quote> for the one-character
1576  * <quote>&aelig;</quote> ligature, 
1577  * <quote><computeroutput>e</computeroutput></quote> for 
1578  * <quote>&egrave;</quote>, <quote><computeroutput>|</computeroutput></quote> 
1579  * for a broken vertical bar (&brvbar;).)
1580  */
1581  
1582 /**
1583  * gestalt_CharOutput_ExactPrint:
1584  *
1585  * When the %gestalt_CharOutput selector returns this for a character, the
1586  * character will be printed exactly as defined.
1587  */
1588
1589 /**
1590  * gestalt_MouseInput:
1591  *
1592  * You can test whether mouse input is supported with the %gestalt_MouseInput 
1593  * selector.
1594  * |[ res = glk_gestalt(gestalt_MouseInput, windowtype); ]|
1595  * This will return %TRUE (1) if windows of the given type support mouse input.
1596  * If this returns %FALSE (0), it is still legal to call
1597  * glk_request_mouse_event(), but it will have no effect, and you will never get
1598  * mouse events.
1599  */ 
1600  
1601 /**
1602  * gestalt_Timer:
1603  *
1604  * You can test whether the library supports timer events:
1605  * |[ res = glk_gestalt(gestalt_Timer, 0); ]|
1606  * This returns %TRUE (1) if timer events are supported, and %FALSE (0) if they 
1607  * are not.
1608  */
1609
1610 /**
1611  * gestalt_Graphics:
1612  * 
1613  * Before calling Glk graphics functions, you should use the following gestalt
1614  * selector:
1615  * |[
1616  * glui32 res;
1617  * res = glk_gestalt(gestalt_Graphics, 0);
1618  * ]|
1619  * This returns 1 if the overall suite of graphics functions is available. This
1620  * includes glk_image_draw(), glk_image_draw_scaled(), glk_image_get_info(),
1621  * glk_window_erase_rect(), glk_window_fill_rect(),
1622  * glk_window_set_background_color(), and glk_window_flow_break(). It also
1623  * includes the capability to create graphics windows.
1624  * 
1625  * If this selector returns 0, you should not try to call these functions. They
1626  * may have no effect, or they may cause a run-time error. If you try to create
1627  * a graphics window, you will get %NULL. 
1628  */
1629
1630 /**
1631  * gestalt_DrawImage:
1632  * 
1633  * This selector returns 1 if images can be drawn in windows of the given type. 
1634  * If it returns 0, glk_image_draw() will fail and return %FALSE (0). You should 
1635  * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries 
1636  * may implement both, neither, or only one.  
1637  */
1638
1639 /**
1640  * gestalt_Sound2:
1641  *
1642  * You can test whether the library supports sound:
1643  * |[
1644  * glui32 res;
1645  * res = glk_gestalt(gestalt_Sound2, 0);
1646  * ]|
1647  * This returns 1 if the overall suite of sound functions is available. This
1648  * includes all the functions defined in <link
1649  * linkend="chimara-glk-spec-sound">this chapter</link>. It also includes the
1650  * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume,
1651  * and %gestalt_SoundNotify.
1652  */
1653
1654 /**
1655  * gestalt_Sound:
1656  *
1657  * |[
1658  * glui32 res;
1659  * res = glk_gestalt(gestalt_Sound, 0);
1660  * ]|
1661  * This returns 1 if the overall suite of sound functions is available. This 
1662  * includes glk_schannel_create(), glk_schannel_destroy(), 
1663  * glk_schannel_iterate(), glk_schannel_get_rock(), glk_schannel_play(),
1664  * glk_schannel_play_ext(), glk_schannel_stop(), glk_schannel_set_volume(), and
1665  * glk_sound_load_hint().
1666  *
1667  * If this selector returns 0, you should not try to call these functions. They 
1668  * may have no effect, or they may cause a run-time error.
1669  *
1670  * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1671  */
1672
1673 /**
1674  * gestalt_SoundVolume:
1675  *
1676  * You can test whether the library supports setting the volume of sound 
1677  * channels: 
1678  * |[ res = glk_gestalt(gestalt_SoundVolume, 0); ]|
1679  * This selector returns 1 if the glk_schannel_set_volume() function works. If 
1680  * it returns zero, glk_schannel_set_volume() has no effect.
1681  *
1682  * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1683  */
1684
1685 /**
1686  * gestalt_SoundNotify:
1687  *
1688  * You can test whether the library supports sound notification events:
1689  * |[ res = glk_gestalt(gestalt_SoundNotify, 0); ]| 
1690  * This selector returns 1 if the library supports sound notification events. If
1691  * it returns zero, you will never get such events.
1692  *
1693  * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1694  */
1695
1696 /**
1697  * gestalt_Hyperlinks:
1698  *
1699  * You can test whether the library supports hyperlinks:
1700  * |[ 
1701  * glui32 res;
1702  * res = glk_gestalt(gestalt_Hyperlinks, 0); 
1703  * ]|
1704  * This returns 1 if the overall suite of hyperlinks functions is available.
1705  * This includes glk_set_hyperlink(), glk_set_hyperlink_stream(),
1706  * glk_request_hyperlink_event(), glk_cancel_hyperlink_event().
1707  *
1708  * If this selector returns 0, you should not try to call these functions. They
1709  * may have no effect, or they may cause a run-time error.
1710  */
1711
1712 /**
1713  * gestalt_HyperlinkInput:
1714  *
1715  * You can test whether hyperlinks are supported with the 
1716  * %gestalt_HyperlinkInput selector:
1717  * |[ res = glk_gestalt(gestalt_HyperlinkInput, windowtype); ]|
1718  * This will return %TRUE (1) if windows of the given type support hyperlinks.
1719  * If this returns %FALSE (0), it is still legal to call glk_set_hyperlink() and
1720  * glk_request_hyperlink_event(), but they will have no effect, and you will
1721  * never get hyperlink events.
1722  */
1723
1724 /** 
1725  * gestalt_SoundMusic:
1726  *
1727  * You can test whether music resources are supported:
1728  * |[ res = glk_gestalt(gestalt_SoundMusic, 0); ]|
1729  * This returns 1 if the library is capable of playing music sound resources. If 
1730  * it returns 0, only sampled sounds can be played.
1731  * <note><para>
1732  *   <quote>Music sound resources</quote> means MOD songs &mdash; the only music
1733  *   format that Blorb currently supports. The presence of this selector is, of 
1734  *   course, an ugly hack. It is a concession to the current state of the Glk 
1735  *   libraries, some of which can handle AIFF but not MOD sounds.
1736  * </para></note>
1737  *
1738  * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
1739  */ 
1740   
1741 /**
1742  * gestalt_GraphicsTransparency:
1743  *
1744  * This returns 1 if images with alpha channels can actually be drawn with the
1745  * appropriate degree of transparency. If it returns 0, the alpha channel is
1746  * ignored; fully transparent areas will be drawn in an implementation-defined
1747  * color.
1748  * <note><para>
1749  *   The JPEG format does not support transparency or alpha channels; the PNG 
1750  *   format does.
1751  * </para></note>
1752  */
1753
1754 /**
1755  * gestalt_Unicode:
1756  *
1757  * The basic text functions will be available in every Glk library. The Unicode
1758  * functions may or may not be available. Before calling them, you should use
1759  * the %gestalt_Unicode and %gestalt_UnicodeNorm gestalt selectors.
1760  *
1761  * |[
1762  * glui32 res;
1763  * res = glk_gestalt(gestalt_Unicode, 0);
1764  * ]|
1765  * This returns 1 if the core Unicode functions are available. If it returns 0,
1766  * you should not try to call them. They may print nothing, print gibberish, or
1767  * cause a run-time error. The Unicode functions include
1768  * glk_buffer_to_lower_case_uni(), glk_buffer_to_upper_case_uni(),  
1769  * glk_buffer_to_title_case_uni(), glk_put_char_uni(), glk_put_string_uni(),
1770  * glk_put_buffer_uni(), glk_put_char_stream_uni(), glk_put_string_stream_uni(),
1771  * glk_put_buffer_stream_uni(), glk_get_char_stream_uni(),
1772  * glk_get_buffer_stream_uni(), glk_get_line_stream_uni(),
1773  * glk_request_char_event_uni(), glk_request_line_event_uni(),
1774  * glk_stream_open_file_uni(), glk_stream_open_memory_uni().
1775  * 
1776  * If you are writing a C program, there is an additional complication. A
1777  * library which does not support Unicode may not implement the Unicode
1778  * functions at all. Even if you put gestalt tests around your Unicode calls,
1779  * you may get link-time errors. If the 
1780  * <filename class="headerfile">glk.h</filename> file is so old that it does not
1781  * declare the Unicode functions and constants, you may even get compile-time
1782  * errors.
1783  * 
1784  * To avoid this, you can perform a preprocessor test for the existence of
1785  * %GLK_MODULE_UNICODE.
1786  */
1787
1788 /**
1789  * gestalt_UnicodeNorm:
1790  *
1791  * |[
1792  * glui32 res;
1793  * res = glk_gestalt(gestalt_UnicodeNorm, 0);
1794  * ]|
1795  * This code returns 1 if the Unicode normalization functions are available. If
1796  * it returns 0, you should not try to call them. The Unicode normalization
1797  * functions include glk_buffer_canon_decompose_uni() and
1798  * glk_buffer_canon_normalize_uni().
1799  *
1800  * The equivalent preprocessor test for these functions is
1801  * %GLK_MODULE_UNICODE_NORM.
1802  */
1803
1804 /**
1805  * gestalt_LineInputEcho:
1806  *
1807  * |[
1808  * res = glk_gestalt(gestalt_LineInputEcho, 0);
1809  * ]|
1810  *
1811  * This returns 1 if glk_set_echo_line_event() is supported, and 0 if it is not.
1812  * <note><para>
1813  *   Remember that if it is not supported, the behavior is always the default,
1814  *   which is line echoing <emphasis>enabled</emphasis>.
1815  * </para></note>
1816  */
1817
1818 /**
1819  * gestalt_LineTerminators:
1820  *
1821  * |[
1822  * res = glk_gestalt(gestalt_LineTerminators, 0);
1823  * ]|
1824  *
1825  * This returns 1 if glk_set_terminators_line_event() is supported, and 0 if it
1826  * is not.
1827  */
1828
1829 /**
1830  * gestalt_LineTerminatorKey:
1831  *
1832  * |[
1833  * res = glk_gestalt(gestalt_LineTerminatorKey, ch);
1834  * ]|
1835  *
1836  * This returns 1 if the keycode @ch can be passed to
1837  * glk_set_terminators_line_event(). If it returns 0, that keycode will be
1838  * ignored as a line terminator. Printable characters and %keycode_Return will
1839  * always return 0.
1840  */
1841
1842 /**
1843  * gestalt_DateTime:
1844  *
1845  * |[
1846  * res = glk_gestalt(gestalt_DateTime, 0);
1847  * ]|
1848  *
1849  * This returns 1 if the overall suite of system clock functions, as described
1850  * in <link linkend="chimara-The-System-Clock">this chapter</link>, is
1851  * available.
1852  *
1853  * If this selector returns 0, you should not try to call these functions. They
1854  * may have no effect, or they may cause a run-time error.
1855  *
1856  * <note><para>
1857  *   Glk timer events are covered by a different selector. See %gestalt_Timer.
1858  * </para></note>
1859  */
1860
1861 /**
1862  * gestalt_ResourceStream:
1863  *
1864  * |[
1865  * res = glk_gestalt(gestalt_ResourceStream, 0);
1866  * ]|
1867  *
1868  * This returns 1 if the glk_stream_open_resource() and
1869  * glk_stream_open_resource_uni() functions are available. If it returns 0, you
1870  * should not call them.
1871  */
1872
1873 /**
1874  * evtype_None:
1875  *
1876  * No event. This is a placeholder, and glk_select() never returns it.
1877  */
1878
1879 /**
1880  * evtype_Timer:
1881  *
1882  * An event that repeats at fixed intervals. See <link 
1883  * linkend="chimara-Timer-Events">Timer Events</link>.
1884  */
1885  
1886 /**
1887  * evtype_CharInput:
1888  *
1889  * A keystroke event in a window. See <link 
1890  * linkend="chimara-Character-Input-Events">Character Input Events</link>.
1891  *
1892  * If a window has a pending request for character input, and the player hits a
1893  * key in that window, glk_select() will return an event whose type is
1894  * %evtype_CharInput. Once this happens, the request is complete; it is no 
1895  * longer pending. You must call glk_request_char_event() or
1896  * glk_request_char_event_uni() if you want another character from that window.
1897  * 
1898  * In the event structure, @win tells what window the event came from. @val1 
1899  * tells what character was entered; this will be a character code, or a special
1900  * keycode. (See <link linkend="chimara-Character-Input">Character 
1901  * Input</link>.) If you called glk_request_char_event(), @val1 will be in 
1902  * 0..255, or else a special keycode. In any case, @val2 will be 0.
1903  */
1904
1905 /**
1906  * evtype_LineInput:
1907  *
1908  * A full line of input completed in a window. See <link 
1909  * linkend="chimara-Line-Input-Events">Line Input Events</link>.
1910  *
1911  * If a window has a pending request for line input, the player can generally
1912  * hit the <keycap>enter</keycap> key (in that window) to complete line input.
1913  * The details will depend on the platform's native user interface.
1914  *
1915  * When line input is completed, glk_select() will return an event whose type is
1916  * %evtype_LineInput. Once this happens, the request is complete; it is no
1917  * longer pending. You must call glk_request_line_event() if you want another
1918  * line of text from that window.
1919  *
1920  * In the event structure, @win tells what window the event came from. @val1
1921  * tells how many characters were entered. @val2 will be 0 unless input was
1922  * ended by a special terminator key, in which case @val2 will be the keycode
1923  * (one of the values passed to glk_set_terminators_line_event()).
1924  *
1925  * The characters themselves are stored in the buffer specified in the original
1926  * glk_request_line_event() or glk_request_line_event_uni() call.
1927  *
1928  * <note><para>
1929  *   There is no null terminator or newline stored in the buffer.
1930  * </para></note>
1931  * 
1932  * It is illegal to print anything to a window which has line input pending. 
1933  *
1934  * <note><para>
1935  *   This is because the window may be displaying and editing the player's 
1936  *   input, and printing anything would make life unnecessarily complicated for
1937  *   the library.
1938  * </para></note>
1939  */
1940
1941 /**
1942  * evtype_MouseInput:
1943  *
1944  * A mouse click in a window. See <link 
1945  * linkend="chimara-Mouse-Input-Events">Mouse Input Events</link>.
1946  */
1947  
1948 /**
1949  * evtype_Arrange:
1950  *
1951  * An event signalling that the sizes of some windows have changed. 
1952  * 
1953  * Some platforms allow the player to resize the Glk window during play. This 
1954  * will naturally change the sizes of your windows. If this occurs, then
1955  * immediately after all the rearrangement, glk_select() will return an event
1956  * whose type is %evtype_Arrange. You can use this notification to redisplay the
1957  * contents of a graphics or text grid window whose size has changed.
1958  *
1959  * <note><para>
1960  *   The display of a text buffer window is entirely up to the library, so you
1961  *   don't need to worry about those.
1962  * </para></note>
1963  * 
1964  * In the event structure, @win will be %NULL if all windows are affected. If 
1965  * only some windows are affected, @win will refer to a window which contains 
1966  * all the affected windows. @val1 and @val2 will be 0.
1967  *
1968  * <note><para>
1969  *   You can always play it safe, ignore @win, and redraw every graphics and 
1970  *   text grid window.
1971  * </para></note>
1972  *
1973  * An arrangement event is guaranteed to occur whenever the player causes any
1974  * window to change size, as measured by its own metric. 
1975  *
1976  * <note><para>
1977  *   Size changes caused by you &mdash; for example, if you open, close, or 
1978  *   resize a window &mdash; do not trigger arrangement events. You must be 
1979  *   aware of the effects of your window management, and redraw the windows that
1980  *   you affect.
1981  * </para></note>
1982  * 
1983  * <note><para>
1984  *   It is possible that several different player actions can cause windows to
1985  *   change size. For example, if the player changes the screen resolution, an
1986  *   arrangement event might be triggered. This might also happen if the player
1987  *   changes his display font to a different size; the windows would then be
1988  *   different <quote>sizes</quote> in the metric of rows and columns, which is
1989  *   the important metric and the only one you have access to.
1990  * </para></note>
1991  * 
1992  * Arrangement events, like timer events, can be returned by glk_select_poll().
1993  * But this will not occur on all platforms. You must be ready to receive an
1994  * arrangement event when you call glk_select_poll(), but it is possible that it
1995  * will not arrive until the next time you call glk_select(). 
1996  *
1997  * <note><para>
1998  *   This is because on some platforms, window resizing is handled as part of
1999  *   player input; on others, it can be triggered by an external process such as 
2000  *   a window manager.
2001  * </para></note>
2002  */
2003
2004 /**
2005  * evtype_Redraw:
2006  *
2007  * An event signalling that graphics windows must be redrawn.
2008  *
2009  * On platforms that support graphics, it is possible that the contents of a
2010  * graphics window will be lost, and have to be redrawn from scratch. If this
2011  * occurs, then glk_select() will return an event whose type is %evtype_Redraw.
2012  *
2013  * In the event structure, @win will be %NULL if all windows are affected. If 
2014  * only some windows are affected, @win will refer to a window which contains 
2015  * all the affected windows. @val1 and @val2 will be 0.
2016  *
2017  * <note><para>
2018  *   You can always play it safe, ignore @win, and redraw every graphics window.
2019  * </para></note>
2020  *
2021  * Affected windows are already cleared to their background color when you 
2022  * receive the redraw event.
2023  * 
2024  * Redraw events can be returned by glk_select_poll(). But, like arrangement
2025  * events, this is platform-dependent. See %evtype_Arrange.
2026  *
2027  * For more about redraw events and how they affect graphics windows, see <link
2028  * linkend="wintype-Graphics">Graphics Windows</link>.
2029  */
2030
2031 /**
2032  * evtype_SoundNotify:
2033  *
2034  * The completion of a sound being played in a sound channel.
2035  *
2036  * On platforms that support sound, you can request to receive an 
2037  * %evtype_SoundNotify event when a sound finishes playing. See <link
2038  * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
2039  */
2040  
2041 /**
2042  * evtype_Hyperlink:
2043  *
2044  * The selection of a hyperlink in a window.
2045  * 
2046  * On platforms that support hyperlinks, you can request to receive an
2047  * %evtype_Hyperlink event when the player selects a link. See <link
2048  * linkend="chimara-Accepting-Hyperlink-Events">Accepting Hyperlink 
2049  * Events</link>.
2050  */
2051
2052 /**
2053  * evtype_VolumeNotify:
2054  *
2055  * The completion of a gradual volume change in a sound channel.
2056  *
2057  * On platforms that support sound, you can request to receive an
2058  * %evtype_VolumeNotify event when a gradual volume change completes. See <link
2059  * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
2060  */
2061
2062 /**
2063  * event_t:
2064  * @type: the event type
2065  * @win: the window that spawned the event, or %NULL
2066  * @val1: information, the meaning of which depends on the type of event
2067  * @val2: more information, the meaning of which depends on the type of event
2068  *
2069  * The event structure is self-explanatory. @type is the event type. The window
2070  * that spawned the event, if relevant, is in @win. The remaining fields contain
2071  * more information specific to the event.
2072  *
2073  * The event types are described below. Note that %evtype_None is zero, and the
2074  * other values are positive. Negative event types (0x80000000 to 0xFFFFFFFF) 
2075  * are reserved for implementation-defined events. 
2076  */
2077
2078 /**
2079  * keycode_Unknown:
2080  *
2081  * Represents any key that has no Latin-1 or special code.
2082  */
2083
2084 /**
2085  * keycode_Left:
2086  *
2087  * Represents the <keycap function="left">left arrow</keycap> key.
2088  */
2089  
2090 /**
2091  * keycode_Right:
2092  *
2093  * Represents the <keycap function="right">right arrow</keycap> key.
2094  */
2095  
2096 /**
2097  * keycode_Up:
2098  *
2099  * Represents the <keycap function="up">up arrow</keycap> key.
2100  */
2101  
2102 /**
2103  * keycode_Down:
2104  *
2105  * Represents the <keycap function="down">down arrow</keycap> key.
2106  */
2107  
2108 /**
2109  * keycode_Return:
2110  *
2111  * Represents the <keycap function="enter">return</keycap> or <keycap 
2112  * function="enter">enter</keycap> keys.
2113  */
2114
2115 /**
2116  * keycode_Delete:
2117  *
2118  * Represents the <keycap function="delete">delete</keycap> or <keycap
2119  * function="backspace">backspace</keycap> keys.
2120  */
2121  
2122 /**
2123  * keycode_Escape:
2124  *
2125  * Represents the <keycap function="escape">escape</keycap> key.
2126  */
2127  
2128 /**
2129  * keycode_Tab:
2130  *
2131  * Represents the <keycap function="tab">tab</keycap> key.
2132  */
2133
2134 /**
2135  * keycode_PageUp:
2136  *
2137  * Represents the <keycap function="pageup">page up</keycap> key.
2138  */
2139
2140 /**
2141  * keycode_PageDown:
2142  *
2143  * Represents the <keycap function="pagedown">page down</keycap> key.
2144  */
2145
2146 /**
2147  * keycode_Home:
2148  *
2149  * Represents the <keycap function="home">home</keycap> key.
2150  */
2151  
2152 /**
2153  * keycode_End:
2154  *
2155  * Represents the <keycap function="end">end</keycap> key.
2156  */
2157
2158 /**
2159  * keycode_Func1:
2160  *
2161  * Represents the <keycap>F1</keycap> key.
2162  */
2163  
2164 /**
2165  * keycode_Func2:
2166  *
2167  * Represents the <keycap>F2</keycap> key.
2168  */
2169
2170 /**
2171  * keycode_Func3:
2172  *
2173  * Represents the <keycap>F3</keycap> key.
2174  */
2175
2176 /**
2177  * keycode_Func4:
2178  *
2179  * Represents the <keycap>F4</keycap> key.
2180  */
2181
2182 /**
2183  * keycode_Func5:
2184  *
2185  * Represents the <keycap>F5</keycap> key.
2186  */
2187  
2188 /**
2189  * keycode_Func6:
2190  *
2191  * Represents the <keycap>F6</keycap> key.
2192  */
2193
2194 /**
2195  * keycode_Func7:
2196  *
2197  * Represents the <keycap>F7</keycap> key.
2198  */
2199
2200 /**
2201  * keycode_Func8:
2202  *
2203  * Represents the <keycap>F8</keycap> key.
2204  */
2205
2206 /**
2207  * keycode_Func9:
2208  *
2209  * Represents the <keycap>F9</keycap> key.
2210  */
2211
2212 /**
2213  * keycode_Func10:
2214  *
2215  * Represents the <keycap>F10</keycap> key.
2216  */
2217
2218 /**
2219  * keycode_Func11:
2220  *
2221  * Represents the <keycap>F11</keycap> key.
2222  */
2223
2224 /**
2225  * keycode_Func12:
2226  *
2227  * Represents the <keycap>F12</keycap> key.
2228  */
2229
2230 /**
2231  * style_Normal: 
2232  *
2233  * The style of normal or body text. A new window or stream always starts with
2234  * %style_Normal as the current style.
2235  */
2236
2237 /**
2238  * style_Emphasized: 
2239  *
2240  * Text which is emphasized.
2241  */
2242
2243 /**
2244  * style_Preformatted: 
2245  *
2246  * Text which has a particular arrangement of characters.
2247  * <note><para>
2248  *  This style, unlike the others, does have a standard appearance; it will 
2249  *  always be a fixed-width font. This is a concession to practicality. Games 
2250  *  often want to display maps or diagrams using character graphics, and this is
2251  *  the style for that.
2252  * </para></note>
2253  */
2254  
2255 /**
2256  * style_Header: 
2257  * 
2258  * Text which introduces a large section. This is suitable for the title of an 
2259  * entire game, or a major division such as a chapter.
2260  */
2261
2262 /**
2263  * style_Subheader: 
2264  * 
2265  * Text which introduces a smaller section within a large section. 
2266  * <note><para>
2267  *  In a Colossal-Cave-style game, this is suitable for the name of a room (when
2268  *  the player looks around.)
2269  * </para></note>
2270  */
2271
2272 /**
2273  * style_Alert: 
2274  *
2275  * Text which warns of a dangerous condition, or one which the player should pay
2276  * attention to.
2277  */
2278
2279 /**
2280  * style_Note: 
2281  *
2282  * Text which notifies of an interesting condition.
2283  * <note><para>
2284  *  This is suitable for noting that the player's score has changed.
2285  * </para></note>
2286  */
2287
2288 /**
2289  * style_BlockQuote: 
2290  *
2291  * Text which forms a quotation or otherwise abstracted text.
2292  */
2293
2294 /**
2295  * style_Input: 
2296  *
2297  * Text which the player has entered. You should generally not use this style at
2298  * all; the library uses it for text which is typed during a line-input request.
2299  * One case when it is appropriate for you to use %style_Input is when you are 
2300  * simulating player input by reading commands from a text file.
2301  */
2302
2303 /**
2304  * style_User1: 
2305  * 
2306  * This style has no particular semantic meaning. You may define a meaning 
2307  * relevant to your own work, and use it as you see fit.
2308  */
2309
2310 /**
2311  * style_User2: 
2312  *
2313  * Another style available for your use. 
2314  */
2315
2316 /**
2317  * stream_result_t:
2318  * @readcount: Number of characters read from the stream.
2319  * @writecount: Number of characters printed to the stream, including ones that
2320  * were thrown away.
2321  *
2322  * If you are interested in the character counts of a stream (see <link
2323  * linkend="chimara-Streams">Streams</link>), then you can pass a pointer to
2324  * #stream_result_t as an argument of glk_stream_close() or glk_window_close().
2325  * The structure will be filled with the stream's final character counts.
2326  */
2327
2328 /**
2329  * wintype_AllTypes:
2330  *
2331  * A constant representing all window types, which may be used as the @wintype
2332  * argument in glk_stylehint_set().
2333  */
2334
2335 /** 
2336  * wintype_Pair:
2337  * 
2338  * A pair window is completely filled by the two windows it contains. It
2339  * supports no input and no output, and it has no size.
2340  * 
2341  * You cannot directly create a pair window; one is automatically created
2342  * every time you split a window with glk_window_open(). Pair windows are
2343  * always created with a rock value of 0.
2344  * 
2345  * You can close a pair window with glk_window_close(); this also closes every
2346  * window contained within the pair window.
2347  * 
2348  * It is legal to split a pair window when you call glk_window_open().
2349  */
2350  
2351 /**
2352  * wintype_Blank:
2353  * 
2354  * A blank window is always blank. It supports no input and no output. (You
2355  * can call glk_window_get_stream() on it, as you can with any window, but
2356  * printing to the resulting stream has no effect.) A blank window has no
2357  * size; glk_window_get_size() will return (0,0), and it is illegal to set a
2358  * window split with a fixed size in the measurement system of a blank window.
2359  * 
2360  * <note><para>
2361  *   A blank window is not the same as there being no windows. When Glk starts
2362  *   up, there are no windows at all, not even a window of the blank type.
2363  * </para></note>
2364  */
2365  
2366 /**
2367  * wintype_TextBuffer: 
2368  *
2369  * A text buffer window contains a linear stream of text. It supports output;
2370  * when you print to it, the new text is added to the end. There is no way for
2371  * you to affect text which has already been printed. There are no guarantees
2372  * about how much text the window keeps; old text may be stored forever, so
2373  * that the user can scroll back to it, or it may be thrown away as soon as it
2374  * scrolls out of the window. 
2375  * 
2376  * <note><para>
2377  *   Therefore, there may or may not be a player-controllable scroll bar or
2378  *   other scrolling widget.
2379  * </para></note>
2380  * 
2381  * The display of the text in a text buffer is up to the library. Lines will
2382  * probably not be broken in the middles of words &mdash; but if they are, the
2383  * library is not doing anything illegal, only ugly. Text selection and copying
2384  * to a clipboard, if available, are handled however is best on the player's
2385  * machine. Paragraphs (as defined by newline characters in the output) may be
2386  * indented. 
2387  * 
2388  * <note><para>
2389  *   You should not, in general, fake this by printing spaces before each
2390  *   paragraph of prose text. Let the library and player preferences handle
2391  *   that. Special cases (like indented lists) are of course up to you.
2392  * </para></note>
2393  * 
2394  * When a text buffer is cleared (with glk_window_clear()), the library will do
2395  * something appropriate; the details may vary. It may clear the window, with
2396  * later text appearing at the top &mdash; or the bottom. It may simply print
2397  * enough blank lines to scroll the current text out of the window. It may
2398  * display a distinctive page-break symbol or divider.
2399  * 
2400  * The size of a text buffer window is necessarily imprecise. Calling
2401  * glk_window_get_size() will return the number of rows and columns that would
2402  * be available <emphasis>if</emphasis> the window was filled with 
2403  * <quote>0</quote> (zero) characters in the <quote>normal</quote> font.
2404  * However, the window may use a non-fixed-width font, so that number of
2405  * characters in a line could vary. The window might even support 
2406  * variable-height text (say, if the player is using large text for emphasis);
2407  * that would make the number of lines in the window vary as well.
2408  * 
2409  * Similarly, when you set a fixed-size split in the measurement system of a
2410  * text buffer, you are setting a window which can handle a fixed number of rows
2411  * (or columns) of <quote>0</quote> characters. The number of rows (or
2412  * characters) that will actually be displayed depends on font variances.
2413  * 
2414  * A text buffer window supports both character and line input, but not mouse
2415  * input.
2416  * 
2417  * In character input, there will be some visible signal that the window is
2418  * waiting for a keystroke. (Typically, a cursor at the end of the text.) When
2419  * the player hits a key in that window, an event is generated, but the key is
2420  * <emphasis>not</emphasis> printed in the window.
2421  * 
2422  * In line input, again, there will be some visible signal. It is most common
2423  * for the player to compose input in the window itself, at the end of the text.
2424  * (This is how IF story input usually looks.) But it's not strictly required.
2425  * An alternative approach is the way MUD clients usually work: there is a
2426  * dedicated one-line input window, outside of Glk's window space, and the user
2427  * composes input there.
2428  * 
2429  * <note><para>
2430  *   If this approach is used, there will still be some way to handle input from
2431  *   two windows at once. It is the library's responsibility to make this
2432  *   available to the player. You only need request line input and  wait for the
2433  *   result.
2434  * </para></note>
2435  * 
2436  * By default, when the player finishes his line of input, the library will
2437  * display the input text at the end of the buffer text (if it wasn't there
2438  * already.) It will be followed by a newline, so that the next text you print
2439  * will start a new line (paragraph) after the input.
2440  * 
2441  * If you call glk_cancel_line_event(), the same thing happens; whatever text
2442  * the user was composing is visible at the end of the buffer text, followed by
2443  * a newline.
2444  *
2445  * However, this default behavior can be changed with the
2446  * glk_set_echo_line_event() call. If the default echoing is disabled, the
2447  * library will <emphasis>not</emphasis> display the input text (plus newline)
2448  * after input is either completed or cancelled. The buffer will end with
2449  * whatever prompt you displayed before requesting input. If you want the
2450  * traditional input behavior, it is then your responsibility to print the text,
2451  * using the Input text style, followed by a newline (in the original style).
2452  */
2453  
2454 /**
2455  * wintype_TextGrid: 
2456  * 
2457  * A text grid contains a rectangular array of characters, in a fixed-width
2458  * font. Its size is the number of columns and rows of the array.
2459  * 
2460  * A text grid window supports output. It maintains knowledge of an output
2461  * cursor position. When the window is opened, it is filled with blanks (space
2462  * characters), and the output cursor starts in the top left corner &mdash;
2463  * character (0,0). If the window is cleared with glk_window_clear(), the window
2464  * is filled with blanks again, and the cursor returns to the top left corner.
2465  * 
2466  * When you print, the characters of the output are laid into the array in
2467  * order, left to right and top to bottom. When the cursor reaches the end of a
2468  * line, or if a newline (0x0A) is printed, the cursor goes to the beginning of
2469  * the next line. The library makes <emphasis>no</emphasis> attempt to wrap
2470  * lines at word breaks. If the cursor reaches the end of the last line, further
2471  * printing has no effect on the window until the cursor is moved.
2472  * 
2473  * <note><para>
2474  *   Note that printing fancy characters may cause the cursor to advance more
2475  *   than one position per character. (For example, the <quote>&aelig;</quote>
2476  *   ligature may print as two characters.) See <link 
2477  *   linkend="chimara-Output">Output</link>, for how to test this situation.
2478  * </para></note>
2479  * 
2480  * You can set the cursor position with glk_window_move_cursor().
2481  * 
2482  * When a text grid window is resized smaller, the bottom or right area is
2483  * thrown away, but the remaining area stays unchanged. When it is resized
2484  * larger, the new bottom or right area is filled with blanks.
2485  * 
2486  * <note><para>
2487  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
2488  *   text grid windows when you see them change size.
2489  * </para></note>
2490  * 
2491  * Text grid window support character and line input, as well as mouse input (if
2492  * a mouse is available.)
2493  * 
2494  * Mouse input returns the position of the character that was touched, from
2495  * (0,0) to 
2496  * <inlineequation>
2497  *   <alt>(width-1,height-1)</alt>
2498  *   <mathphrase>(width - 1, height - 1)</mathphrase>
2499  * </inlineequation>
2500  * .
2501  * 
2502  * Character input is as described in the previous section.
2503  * 
2504  * Line input is slightly different; it is guaranteed to take place in the
2505  * window, at the output cursor position. The player can compose input only to
2506  * the right edge of the window; therefore, the maximum input length is
2507  * <inlineequation>
2508  *   <alt>(windowwidth - 1 - cursorposition)</alt>
2509  *   <mathphrase>(windowwidth - 1 - cursorposition)</mathphrase>
2510  * </inlineequation>
2511  * . If the maxlen argument of glk_request_line_event() is smaller than this,
2512  * the library will not allow the input cursor to go more than maxlen characters
2513  * past its start point. 
2514  * 
2515  * <note><para>
2516  *   This allows you to enter text in a fixed-width field, without the player
2517  *   being able to overwrite other parts of the window.
2518  * </para></note>
2519  * 
2520  * When the player finishes his line of input, it will remain visible in the
2521  * window, and the output cursor will be positioned at the beginning of the 
2522  * <emphasis>next</emphasis> row. Again, if you glk_cancel_line_event(), the
2523  * same thing happens. The glk_set_echo_line_event() call has no effect in grid
2524  * windows.
2525  */
2526  
2527 /**
2528  * wintype_Graphics: 
2529  * 
2530  * A graphics window contains a rectangular array of pixels. Its size is the
2531  * number of columns and rows of the array.
2532  * 
2533  * Each graphics window has a background color, which is initially white. You
2534  * can change this; see <link 
2535  * linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics 
2536  * Windows</link>.
2537  * 
2538  * When a graphics window is resized smaller, the bottom or right area is
2539  * thrown away, but the remaining area stays unchanged. When it is resized
2540  * larger, the new bottom or right area is filled with the background color.
2541  * 
2542  * <note><para>
2543  *   You may wish to watch for %evtype_Arrange events, and clear-and-redraw your
2544  *   graphics windows when you see them change size.
2545  * </para></note>
2546  * 
2547  * In some libraries, you can receive a graphics-redraw event (%evtype_Redraw)
2548  * at any time. This signifies that the window in question has been cleared to
2549  * its background color, and must be redrawn. If you create any graphics
2550  * windows, you <emphasis>must</emphasis> handle these events.
2551  * 
2552  * <note><para>
2553  *   Redraw events can be triggered when a Glk window is uncovered or made
2554  *   visible by the platform's window manager. On the other hand, some Glk
2555  *   libraries handle these problem automatically &mdash; for example, with a
2556  *   backing store &mdash; and do not send you redraw events. On the third hand,
2557  *   the backing store may be discarded if memory is low, or for other reasons
2558  *   &mdash; perhaps the screen's color depth has changed. So redraw events are
2559  *   always a possibility, even in clever libraries. This is why you must be
2560  *   prepared to handle them.
2561  * 
2562  *   However, you will not receive a redraw event when you create a graphics
2563  *   window. It is assumed that you will do the initial drawing of your own
2564  *   accord. You also do not get redraw events when a graphics window is
2565  *   enlarged. If you ordered the enlargement, you already know about it; if the
2566  *   player is responsible, you receive a window-arrangement event, which covers
2567  *   the situation.
2568  * </para></note>
2569  * 
2570  * For a description of the drawing functions that apply to graphics windows,
2571  * see <link linkend="chimara-Graphics-in-Graphics-Windows">Graphics in Graphics
2572  * Windows</link>.
2573  * 
2574  * Graphics windows support no text input or output.
2575  * 
2576  * Not all libraries support graphics windows. You can test whether Glk graphics
2577  * are available using the gestalt system. In a C program, you can also test
2578  * whether the graphics functions are defined at compile-time. See <link 
2579  * linkend="chimara-Testing-for-Graphics-Capabilities">Testing for Graphics
2580  * Capabilities</link>. 
2581  *
2582  * <note><para>
2583  *   As with all windows, you should also test for %NULL when you create a
2584  *   graphics window.
2585  * </para></note>
2586  */
2587  
2588 /**
2589  * winmethod_Left:
2590  *
2591  * When calling glk_window_open() with this @method, the new window will be 
2592  * to the left of the old one which was split.
2593  */
2594
2595 /**
2596  * winmethod_Right:
2597  *
2598  * When calling glk_window_open() with this @method, the new window will be 
2599  * to the right of the old one which was split.
2600  */
2601
2602 /**
2603  * winmethod_Above:
2604  *
2605  * When calling glk_window_open() with this @method, the new window will be 
2606  * above the old one which was split.
2607  */
2608  
2609 /**
2610  * winmethod_Below:
2611  *
2612  * When calling glk_window_open() with this @method, the new window will be 
2613  * below the old one which was split.
2614  */
2615  
2616 /**
2617  * winmethod_Fixed:
2618  *
2619  * When calling glk_window_open() with this @method, the new window will be 
2620  * a fixed size. (See glk_window_open()).
2621  */
2622
2623 /**
2624  * winmethod_Proportional:
2625  *
2626  * When calling glk_window_open() with this @method, the new window will be 
2627  * a given proportion of the old window's size. (See glk_window_open()).
2628  */
2629
2630 /**
2631  * winmethod_Border:
2632  *
2633  * When calling glk_window_open() with this @method, it specifies that there
2634  * should be a visible window border between the new window and its sibling.
2635  * (This is a hint to the library.)
2636  *
2637  * <note><title>Chimara</title><para>
2638  *   There will only be a visible border if the #ChimaraGlk:spacing property
2639  *   is nonzero. Setting #ChimaraGlk:spacing to zero disables all borders on Glk
2640  *   windows.
2641  * </para></note>
2642  */
2643
2644 /**
2645  * winmethod_NoBorder:
2646  *
2647  * When calling glk_window_open() with this @method, it specifies that there
2648  * should not be a visible window border between the new window and its sibling.
2649  * (This is a hint to the library; you might specify NoBorder between two
2650  * graphics windows that should form a single image.)
2651  */
2652
2653 /** 
2654  * fileusage_Data: 
2655  *
2656  * Any other kind of file (preferences, statistics, arbitrary data.) 
2657  */
2658
2659 /**
2660  * fileusage_SavedGame: 
2661  * 
2662  * A file which stores game state.
2663  */
2664
2665 /**
2666  * fileusage_Transcript: 
2667  * 
2668  * A file which contains a stream of text from the game (often an echo stream
2669  * from a window.)
2670  */
2671  
2672 /** 
2673  * fileusage_InputRecord: 
2674  * 
2675  * A file which records player input.
2676  */
2677
2678 /** 
2679  * fileusage_TextMode: 
2680  *
2681  * The file contents will be transformed to a platform-native text file as they
2682  * are written out. Newlines may be converted to linefeeds or 
2683  * linefeed-plus-carriage-return combinations; Latin-1 characters may be
2684  * converted to native character codes. When reading a file in text mode, native
2685  * line breaks will be converted back to newline (0x0A) characters, and native
2686  * character codes may be converted to Latin-1 or UTF-8. 
2687  *
2688  * <note><para>
2689  *   Line breaks will always be converted; other conversions are more
2690  *   questionable. If you write out a file in text mode, and then read it back
2691  *   in text mode, high-bit characters (128 to 255) may be transformed or lost.
2692  * </para></note>
2693  * <note><title>Chimara</title>
2694  * <para>
2695  * Text mode files in Chimara are in UTF-8, which is GTK+'s native file
2696  * encoding.
2697  * </para></note>
2698  */
2699
2700 /**
2701  * fileusage_BinaryMode: 
2702  *
2703  * The file contents will be stored exactly as they are written, and read back
2704  * in the same way. The resulting file may not be viewable on platform-native
2705  * text file viewers.
2706  */
2707
2708 /**
2709  * fileusage_TypeMask:
2710  *
2711  * Bitwise AND this value with a file usage argument to find whether the file
2712  * type is %fileusage_SavedGame, %fileusage_Transcript, %fileusage_InputRecord,
2713  * or %fileusage_Data.
2714  */
2715
2716 /**
2717  * filemode_Write: 
2718  *
2719  * An output stream.
2720  *
2721  * <note><para>
2722  *   Corresponds to mode <code>"w"</code> in the stdio library, using fopen().
2723  * </para></note>
2724  */
2725
2726 /** 
2727  * filemode_Read: 
2728  *
2729  * An input stream.
2730  *
2731  * <note><para>
2732  *   Corresponds to mode <code>"r"</code> in the stdio library, using fopen().
2733  * </para></note>
2734  */
2735
2736 /**
2737  * filemode_ReadWrite: 
2738  *
2739  * Both an input and an output stream.
2740  *
2741  * <note><para>
2742  *   Corresponds to mode <code>"r+"</code> in the stdio library, using fopen().
2743  * </para></note>
2744  */
2745
2746 /**
2747  * filemode_WriteAppend: 
2748  *
2749  * An output stream, but the data will added to the end of whatever already
2750  * existed in the destination, instead of replacing it. 
2751  *
2752  * <note><para>
2753  *   Confusingly, %filemode_WriteAppend cannot be mode <code>"a"</code>, because
2754  *   the stdio spec says that when you open a file with mode <code>"a"</code>,
2755  *   then fseek() doesn't work. So we have to use mode <code>"r+"</code> for
2756  *   appending. Then we run into the <emphasis>other</emphasis> stdio problem,
2757  *   which is that <code>"r+"</code> never creates a new file. So
2758  *   %filemode_WriteAppend has to <emphasis>first</emphasis> open the file with
2759  *   <code>"a"</code>, close it, reopen with <code>"r+"</code>, and then fseek()
2760  *   to the end of the file. For %filemode_ReadWrite, the process is the same,
2761  *   except without the fseek() &mdash; we begin at the beginning of the file.
2762  * </para></note>
2763  */
2764  
2765 /**
2766  * seekmode_Start:
2767  *
2768  * In glk_stream_set_position(), signifies that @pos is counted in characters
2769  * after the beginning of the file.
2770  */
2771  
2772 /**
2773  * seekmode_Current: 
2774  *
2775  * In glk_stream_set_position(), signifies that @pos is counted in characters
2776  * after the current position (moving backwards if @pos is negative.)
2777  */
2778
2779 /** 
2780  * seekmode_End: 
2781  *
2782  * In glk_stream_set_position(), signifies that @pos is counted in characters
2783  * after the end of the file. (@pos should always be zero or negative, so that
2784  * this will move backwards to a  position within the file.
2785  */
2786
2787 /**
2788  * stylehint_Indentation: 
2789  *
2790  * How much to indent lines of text in the given style. May be a negative 
2791  * number, to shift the text out (left) instead of in (right). The exact metric
2792  * isn't precisely specified; you can assume that +1 is the smallest indentation
2793  * possible which is clearly visible to the player.
2794  */
2795
2796 /**
2797  * stylehint_ParaIndentation: 
2798  *
2799  * How much to indent the first line of each paragraph. This is in addition to 
2800  * the indentation specified by %stylehint_Indentation. This too may be 
2801  * negative, and is measured in the same units as %stylehint_Indentation.
2802  */
2803
2804 /**
2805  * stylehint_Justification: 
2806  *
2807  * The value of this hint must be one of the constants 
2808  * %stylehint_just_LeftFlush, %stylehint_just_LeftRight (full justification), 
2809  * %stylehint_just_Centered, or %stylehint_just_RightFlush.
2810  */
2811
2812 /** 
2813  * stylehint_Size: 
2814  *
2815  * How much to increase or decrease the font size. This is relative; 0 means the
2816  * interpreter's default font size will be used, positive numbers increase it, 
2817  * and negative numbers decrease it. Again, +1 is the smallest size increase 
2818  * which is easily visible. 
2819  * <note><para>
2820  *  The amount of this increase may not be constant. +1 might increase an 
2821  *  8-point font to 9-point, but a 16-point font to 18-point.
2822  * </para></note>
2823  */
2824
2825 /**
2826  * stylehint_Weight: 
2827  *
2828  * The value of this hint must be 1 for heavy-weight fonts (boldface), 0 for 
2829  * normal weight, and -1 for light-weight fonts.
2830  */
2831
2832 /**
2833  * stylehint_Oblique: 
2834  *
2835  * The value of this hint must be 1 for oblique fonts (italic), or 0 for normal
2836  * angle.
2837  */
2838  
2839 /** 
2840  * stylehint_Proportional: 
2841  * 
2842  * The value of this hint must be 1 for proportional-width fonts, or 0 for 
2843  * fixed-width.
2844  */
2845
2846 /**
2847  * stylehint_TextColor: 
2848  * 
2849  * The foreground color of the text. This is encoded in the 32-bit hint value: 
2850  * the top 8 bits must be zero, the next 8 bits are the red value, the next 8 
2851  * bits are the green value, and the bottom 8 bits are the blue value. Color 
2852  * values range from 0 to 255. 
2853  * <note><para>
2854  *   So 0x00000000 is black, 0x00FFFFFF is white, and 0x00FF0000 is bright red.
2855  * </para></note>
2856  */
2857  
2858 /** 
2859  * stylehint_BackColor: 
2860  *
2861  * The background color behind the text. This is encoded the same way as 
2862  * %stylehint_TextColor.
2863  */
2864  
2865 /** 
2866  * stylehint_ReverseColor: 
2867  *
2868  * The value of this hint must be 0 for normal printing (%stylehint_TextColor on 
2869  * %stylehint_BackColor), or 1 for reverse printing (%stylehint_BackColor on 
2870  * %stylehint_TextColor). 
2871  * <note><para>
2872  *  Some libraries may support this hint but not the %stylehint_TextColor and 
2873  *  %stylehint_BackColor hints. Other libraries may take the opposite tack; 
2874  *  others may support both, or neither.
2875  * </para></note>
2876  */
2877  
2878 /**
2879  * stylehint_just_LeftFlush:
2880  *
2881  * A value for %stylehint_Justification representing left-justified text.
2882  */ 
2883  
2884 /**
2885  * stylehint_just_LeftRight:
2886  *
2887  * A value for %stylehint_Justification representing fully justified text.
2888  */ 
2889  
2890 /**
2891  * stylehint_just_Centered:
2892  *
2893  * A value for %stylehint_Justification representing centered text.
2894  */ 
2895  
2896 /**
2897  * stylehint_just_RightFlush:
2898  *
2899  * A value for %stylehint_Justification representing right-justified text.
2900  */
2901
2902 /**
2903  * imagealign_InlineUp:
2904  *
2905  * The image appears at the current point in the text, sticking up. That is, the
2906  * bottom edge of the image is aligned with the baseline of the line of text.
2907  */
2908
2909 /**
2910  * imagealign_InlineDown:
2911  *
2912  * The image appears at the current point, and the top edge is aligned with the
2913  * top of the line of text.
2914  */
2915
2916 /**
2917  * imagealign_InlineCenter:
2918  *
2919  * The image appears at the current point, and it is centered between the top
2920  * and baseline of the line of text. If the image is taller than the line of
2921  * text, it will stick up and down equally.
2922  */
2923
2924 /**
2925  * imagealign_MarginLeft:
2926  * 
2927  * The image appears in the left margin. Subsequent text will be displayed to
2928  * the right of the image, and will flow around it &mdash; that is, it will be
2929  * left-indented for as many lines as it takes to pass the image.
2930  *
2931  * <warning><para>Margin images are not implemented yet.</para></warning>
2932  */
2933
2934 /**
2935  * imagealign_MarginRight:
2936  *
2937  * The image appears in the right margin, and subsequent text will flow around
2938  * it on the left.
2939  *
2940  * <warning><para>Margin images are not implemented yet.</para></warning>
2941  */
2942
2943 /**
2944  * glkdate_t:
2945  * @year: The full (four-digit) year
2946  * @month: The month number, ranging from 1-12, 1 is January
2947  * @day: The day of the month, ranging from 1-31
2948  * @weekday: The day of the week, ranging from 0-6, 0 is Sunday
2949  * @hour: The hour of the day, ranging from 0-23
2950  * @minute: The minute of the hour, ranging from 0-59
2951  * @second: The second of the minute, ranging from 0-59; may be 60 during a leap
2952  * second
2953  * @microsec: The fraction of the second in microseconds, ranging from 0-999999
2954  *
2955  * This structure represents a human-readable date in a specific timezone.
2956  */
2957
2958 /**
2959  * glktimeval_t:
2960  * @high_sec: The most significant 32 bits of the timestamp in seconds.
2961  * @low_sec: The least significant 32 bits of the timestamp in seconds.
2962  * @microsec: The fraction of the timestamp, in microseconds, ranging from
2963  * 0-999999.
2964  *
2965  * This structure represents the Unix timestamp, i.e. the number of seconds
2966  * since January 1, 1970.
2967  */
2968  
2969 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
2970
2971 /**
2972  * gidispatch_count_classes:
2973  * 
2974  * Returns the number of opaque object classes used by the library. You will
2975  * need to know this if you want to keep track of opaque objects as they are
2976  * created; see <link linkend="gidispatch-set-object-registry">Opaque Object
2977  * Registry</link>.
2978  * 
2979  * As of Glk API 0.7.0, there are four classes: windows, streams, filerefs, and
2980  * sound channels (numbered 0, 1, 2, and 3 respectively.)
2981  *
2982  * Returns: Number of opaque object classes used by the library.
2983  */
2984
2985 /**
2986  * gidispatch_get_class:
2987  * @index: Unique integer index of the class.
2988  *
2989  * Returns a structure describing an opaque class that the library exports.
2990  * @index can range from 0 to <inlineequation><mathphrase>N -
2991  * 1</mathphrase><alt>N - 1</alt></inlineequation>, where N is the value
2992  * returned by gidispatch_count_classes().
2993  *
2994  * Returns: A #gidispatch_intconst_t structure describing the class.
2995  */
2996
2997 /**
2998  * gidispatch_count_intconst:
2999  *
3000  * Returns the number of integer constants exported by the library.
3001  *
3002  * Returns: Number of integer constants exported by the library.
3003  */
3004  
3005 /**
3006  * gidispatch_get_intconst:
3007  * @index: Unique integer index of the integer constant.
3008  *
3009  * Returns a structure describing an integer constant which the library exports.
3010  * These are, roughly, all the constants defined in the <filename
3011  * class="headerfile">glk.h</filename> file. @index can range from 0 to
3012  * <inlineequation><mathphrase>N - 1</mathphrase><alt>N - 
3013  * 1</alt></inlineequation>, where N is the value returned by 
3014  * gidispatch_count_intconst().
3015  *
3016  * Returns: A #gidispatch_intconst_t structure describing the integer constant.
3017  */
3018
3019 /**
3020  * gidispatch_intconst_t:
3021  * @name: Symbolic name of the integer constant.
3022  * @val: Value of the integer constant.
3023  *
3024  * This structure simply contains a string and a value. The string is a
3025  * symbolic name of the value, and can be re-exported to anyone interested in
3026  * using Glk constants.
3027  *
3028  * <note><para>
3029  *   In the current <filename>gi_dispa.c</filename> library, these structures
3030  *   are static and immutable, and will never be deallocated. However, it is
3031  *   safer to assume that the structure may be reused in future
3032  *   gidispatch_get_intconst() calls.
3033  * </para></note>
3034  */
3035  
3036 /**
3037  * gidispatch_count_functions:
3038  *
3039  * Returns the number of functions exported by the library.
3040  *
3041  * Returns: Number of functions exported by the library.
3042  */
3043  
3044 /**
3045  * gidispatch_get_function:
3046  * @index: Unique integer index of the function.
3047  *
3048  * Returns a structure describing a Glk function. @index can range from 0 to
3049  * <inlineequation><mathphrase>N - 1</mathphrase><alt>N - 
3050  * 1</alt></inlineequation>, where N is the value returned by 
3051  * gidispatch_count_functions().
3052  *
3053  * <note><para>
3054  *   Again, it is safest to assume that the structure is only valid until the
3055  *   next gidispatch_get_function() or gidispatch_get_function_by_id() call.
3056  * </para></note>
3057  *
3058  * Returns: A #gidispatch_function_t structure describing the function.
3059  */
3060  
3061 /**
3062  * gidispatch_function_t:
3063  * @id: Dispatch selector of the function.
3064  * @fnptr: Pointer to the function.
3065  * @name: Name of the function, without the <code>glk_</code> prefix.
3066  *
3067  * The @id field is a selector &mdash; a numeric constant used to refer to the
3068  * function in question. @name is the function name, as it is given in the
3069  * <filename class="headerfile">glk.h</filename> file, but without the 
3070  * <quote><code>glk_</code></quote> prefix. And @fnptr is the address of the
3071  * function itself.
3072  *
3073  * <note><para>
3074  *   This is included because it might be useful, but it is not recommended. To
3075  *   call an arbitrary Glk function, you should use gidispatch_call().
3076  * </para></note>
3077  *
3078  * See <link linkend="chimara-Table-of-Selectors">Table of Selectors</link> for
3079  * the selector definitions. See <link 
3080  * linkend="chimara-Dispatching">Dispatching</link> for more about calling Glk
3081  * functions by selector.
3082  */
3083  
3084 /**
3085  * gidispatch_get_function_by_id:
3086  * @id: A selector.
3087  *
3088  * Returns a structure describing the Glk function with selector @id. If there 
3089  * is no such function in the library, this returns %NULL.
3090  *
3091  * <note><para>
3092  *   Again, it is safest to assume that the structure is only valid until the
3093  *   next gidispatch_get_function() or gidispatch_get_function_by_id() call.
3094  * </para></note>
3095  *
3096  * Returns: a #gidispatch_function_t structure, or %NULL.
3097  */
3098  
3099 /**
3100  * gidispatch_call:
3101  * @funcnum: Selector of the function to call.
3102  * @numargs: Length of @arglist.
3103  * @arglist: List of arguments to pass to the function.
3104  *
3105  * @funcnum is the function number to invoke; see <link 
3106  * linkend="chimara-Table-of-Selectors">Table of Selectors</link>. @arglist is
3107  * the list of arguments, and @numargs is the length of the list.
3108  * 
3109  * The arguments are all stored as #gluniversal_t objects. 
3110  * </para><refsect3 id="chimara-Basic-Dispatch-Types"><title>Basic Dispatch
3111  * Types</title><para>
3112  * Numeric arguments are passed in the obvious way &mdash; one argument per
3113  * #gluniversal_t, with the @uint or @sint field set to the numeric value.
3114  * Characters and strings are also passed in this way &mdash; #char<!---->s in
3115  * the @uch, @sch, or @ch fields (depending on whether the #char is signed) and
3116  * strings in the @charstr field. Opaque objects (windows, streams, etc) are
3117  * passed in the @opaqueref field (which is <code>void*</code>, in order to
3118  * handle all opaque pointer types.)
3119  * 
3120  * However, pointers (other than C strings), arrays, and structures complicate
3121  * life. So do return values.
3122  * </para></refsect3>
3123  * <refsect3 id="chimara-References"><title>References</title><para>
3124  * A reference to a numeric type or object reference &mdash; that is,
3125  * <code>#glui32*</code>, <code>#winid_t*</code>, and so on &mdash; takes
3126  * <emphasis>one or two</emphasis> #gluniversal_t objects. The first is a flag
3127  * indicating whether the reference argument is %NULL or not. The @ptrflag field
3128  * of this #gluniversal_t should be %FALSE (0) if the reference is %NULL, and
3129  * %TRUE (1) otherwise. If %FALSE, that is the end of the argument; you should
3130  * not use a #gluniversal_t to explicitly store the %NULL reference. If the flag
3131  * is %TRUE, you must then put a #gluniversal_t storing the base type of the
3132  * reference.
3133  *
3134  * For example, consider a hypothetical function, with selector 
3135  * <code>0xABCD</code>:
3136  * |[ 
3137  * void glk_glomp(glui32 num, winid_t win, glui32 *numref, strid_t *strref);
3138  * ]|
3139  * ...and the calls:
3140  * |[
3141  * glui32 value;
3142  * winid_t mainwin;
3143  * strid_t gamefile;
3144  * glk_glomp(5, mainwin, &value, &gamefile);
3145  * ]|
3146  *
3147  * To perform this through gidispatch_call(), you would do the following:
3148  * |[
3149  * gluniversal_t arglist[6];
3150  * arglist[0].uint = 5;
3151  * arglist[1].opaqueref = mainwin;
3152  * arglist[2].ptrflag = TRUE;
3153  * arglist[3].uint = value;
3154  * arglist[4].ptrflag = TRUE;
3155  * arglist[5].opaqueref = gamefile;
3156  * gidispatch_call(0xABCD, 6, arglist);
3157  * value = arglist[3].uint;
3158  * gamefile = arglist[5].opaqueref;
3159  * ]|
3160  * 
3161  * Note that you copy the value of the reference arguments into and out of
3162  * @arglist. Of course, it may be that 
3163  * <function>glk_glomp&lpar;&rpar;</function> only uses these as pass-out
3164  * references or pass-in references; if so, you could skip copying in or out.
3165  *
3166  * For further examples:
3167  * |[
3168  * glk_glomp(7, mainwin, NULL, NULL);
3169  * ...or...
3170  * gluniversal_t arglist[4];
3171  * arglist[0].uint = 7;
3172  * arglist[1].opaqueref = mainwin;
3173  * arglist[2].ptrflag = FALSE;
3174  * arglist[3].ptrflag = FALSE;
3175  * gidispatch_call(0xABCD, 4, arglist);
3176  * ]|
3177  *
3178  * |[
3179  * glk_glomp(13, NULL, NULL, &gamefile);
3180  * ...or...
3181  * gluniversal_t arglist[5];
3182  * arglist[0].uint = 13;
3183  * arglist[1].opaqueref = NULL;
3184  * arglist[2].ptrflag = FALSE;
3185  * arglist[3].ptrflag = TRUE;
3186  * arglist[4].opaqueref = gamefile;
3187  * gidispatch_call(0xABCD, 5, arglist);
3188  * gamefile = arglist[4].opaqueref;
3189  * ]|
3190  *
3191  * |[
3192  * glk_glomp(17, NULL, &value, NULL);
3193  * ...or...
3194  * gluniversal_t arglist[5];
3195  * arglist[0].uint = 17;
3196  * arglist[1].opaqueref = NULL;
3197  * arglist[2].ptrflag = TRUE;
3198  * arglist[3].uint = value;
3199  * arglist[4].ptrflag = FALSE;
3200  * gidispatch_call(0xABCD, 5, arglist);
3201  * value = arglist[3].uint;
3202  * ]|
3203  * 
3204  * As you see, the length of @arglist depends on how many of the reference
3205  * arguments are %NULL.
3206  * </para></refsect3>
3207  * <refsect3 id="chimara-Structures"><title>Structures</title><para>
3208  * A structure pointer is represented by a single @ptrflag, possibly followed by
3209  * a sequence of #gluniversal_t objects (one for each field of the structure.)
3210  * Again, if the structure pointer is non-%NULL, the @ptrflag should be %TRUE
3211  * and be followed by values; if not, the @ptrflag should be %NULL and stands
3212  * alone.
3213  * 
3214  * For example, the function glk_select() can be invoked as follows:
3215  * |[
3216  * event_t ev;
3217  * gluniversal_t arglist[5];
3218  * arglist[0].ptrflag = TRUE;
3219  * gidispatch_call(0x00C0, 5, arglist);
3220  * ev.type = arglist[1].uint;
3221  * ev.win = arglist[2].opaqueref;
3222  * ev.val1 = arglist[3].uint;
3223  * ev.val2 = arglist[4].uint;
3224  * ]|
3225  * 
3226  * Since the structure passed to glk_select() is a pass-out reference (the entry
3227  * values are ignored), you don't need to fill in <code>arglist[1..4]</code>
3228  * before calling gidispatch_call().
3229  * 
3230  * <note><para>
3231  *   Theoretically, you would invoke <code>#glk_select(%NULL)</code> by setting'
3232  *   <code>arglist[0].ptrflag</code> to %FALSE, and using a one-element @arglist
3233  *   instead of five-element. But it's illegal to pass %NULL to glk_select(). So
3234  *   you cannot actually do this.
3235  * </para></note></para></refsect3>
3236  * <refsect3 id="chimara-Arrays"><title>Arrays</title><para>
3237  * In the Glk API, an array argument is always followed by a numeric argument
3238  * giving the array's length. These two C arguments are a single logical
3239  * argument, which is represented by <emphasis>one or three</emphasis>
3240  * #gluniversal_t objects. The first is a @ptrflag, indicating whether the
3241  * argument is %NULL or not. The second is a pointer, stored in the @array
3242  * field. The third is the array length, stored in the @uint field. And again,
3243  * if the @ptrflag is %NULL, the following two are omitted.
3244  * 
3245  * For example, the function glk_put_buffer() can be invoked as follows:
3246  * |[
3247  * char buf[64];
3248  * glui32 len = 64;
3249  * glk_put_buffer(buf, len);
3250  * ...or...
3251  * gluniversal_t arglist[3];
3252  * arglist[0].ptrflag = TRUE;
3253  * arglist[1].array = buf;
3254  * arglist[2].uint = len;
3255  * gidispatch_call(0x0084, 3, arglist);
3256  * ]|
3257  * 
3258  * Since you are passing a C char array to gidispatch_call(), the contents will
3259  * be read directly from that. There is no need to copy data into @arglist, as
3260  * you would for a basic type.
3261  * 
3262  * If you are implementing a VM whose native representation of char arrays is
3263  * more complex, you will have to do more work. You should allocate a C char
3264  * array, copy your characters into it, make the call, and then free the array.
3265  *
3266  * <note><para>
3267  *   glk_put_buffer() does not modify the array passed to it, so there is no
3268  *   need to copy the characters out.
3269  * </para></note></para></refsect3>
3270  * <refsect3 id="chimara-Return-Values"><title>Return Values</title><para>
3271  * The return value of a function is not treated specially. It is simply
3272  * considered to be a pass-out reference argument which may not be %NULL. It
3273  * comes after all the other arguments of the function.
3274  * 
3275  * For example, the function glk_window_get_rock() can be invoked as follows:
3276  * |[
3277  * glui32 rock;
3278  * winid_t win;
3279  * rock = glk_window_get_rock(win);
3280  * ...or...
3281  * gluniversal_t arglist[3];
3282  * arglist[0].opaqueref = win;
3283  * arglist[1].ptrflag = TRUE;
3284  * gidispatch_call(0x0021, 3, arglist);
3285  * rock = arglist[2].uint;
3286  * ]|
3287  * </para></refsect3><para>
3288  */
3289
3290 /**
3291  * gluniversal_t:
3292  * @uint: Stores a #glui32.
3293  * @sint: Stores a #glsi32.
3294  * @opaqueref: Stores a #winid_t, #strid_t, #frefid_t, or #schanid_t.
3295  * @uch: Stores an #unsigned #char.
3296  * @sch: Stores a #signed #char.
3297  * @ch: Stores a #char with the default signedness.
3298  * @charstr: Stores a null-terminated string.
3299  * @unicharstr: Stores a zero-terminated string of #glui32 values representing
3300  * Unicode characters.
3301  * @array: Stores a pointer to an array, and should be followed by another 
3302  * #gluniversal_t with the array length stored in the @uint member.
3303  * @ptrflag: If %FALSE, represents an opaque reference or array that is %NULL,
3304  * in which case it represents the entire argument. If %TRUE, should be followed
3305  * by another #gluniversal_t with the pointer in its @opaqueref or @array field.
3306  *
3307  * This is a union, encompassing all the types that can be passed to Glk
3308  * functions.
3309  */
3310  
3311 /**
3312  * gidispatch_prototype:
3313  * @funcnum: A selector for the function to be queried.
3314  *
3315  * This returns a string which encodes the proper argument list for the given
3316  * function. If there is no such function in the library, this returns %NULL.
3317  * 
3318  * The prototype string for the <function>glk_glomp&lpar;&rpar;</function> 
3319  * function described above would be: <code>"4IuQa&amp;Iu&amp;Qb:"</code>. The 
3320  * <code>"4"</code> is the number of arguments (including the return value, if 
3321  * there is one, which in this case there isn't.) <code>"Iu"</code> denotes an 
3322  * unsigned integer; <code>"Qa"</code> is an opaque object of class 0 (window).
3323  * <code>"&amp;Iu"</code> is a <emphasis>reference</emphasis> to an unsigned
3324  * integer, and <code>"&amp;Qb"</code> is a reference to a stream. The colon at
3325  * the end terminates the argument list; the return value would follow it, if
3326  * there was one.
3327  * 
3328  * Note that the initial number (<code>"4"</code> in this case) is the number of
3329  * logical arguments, not the number of #gluniversal_t objects which will be
3330  * passed to gidispatch_call(). The <function>glk_glomp&lpar;&rpar;</function> 
3331  * call uses anywhere from four to six #gluniversal_t objects, as demonstrated 
3332  * above.
3333  * 
3334  * The basic type codes:
3335  * <variablelist>
3336  * <varlistentry>
3337  *   <term><code>Iu, Is</code></term>
3338  *   <listitem><para>Unsigned and signed 32-bit integer.</para></listitem>
3339  * </varlistentry>
3340  * <varlistentry>
3341  *   <term><code>Cn, Cu, Cs</code></term>
3342  *   <listitem><para>Character, #unsigned #char, and #signed #char.</para>
3343  *     <note><para>Of course <code>Cn</code> will be the same as either 
3344  *     <code>Cu</code> or <code>Cs</code>, depending on the platform. For this
3345  *     reason, Glk avoids using it, but it is included here for completeness.
3346  *     </para></note>
3347  *   </listitem>
3348  * </varlistentry>
3349  * <varlistentry>
3350  *   <term><code>S</code></term>
3351  *   <listitem><para>A C-style string (null-terminated array of #char). In Glk,
3352  *   strings are always treated as read-only and used immediately; the library
3353  *   does not retain a reference to a string between Glk calls. A Glk call that
3354  *   wants to use writable char arrays will use an array type 
3355  *   (<code>"&num;C"</code>), not string (<code>"S"</code>).</para></listitem>
3356  * </varlistentry>
3357  * <varlistentry>
3358  *   <term><code>U</code></term>
3359  *   <listitem><para>A zero-terminated array of 32-bit integers. This is
3360  *   primarily intended as a Unicode equivalent of <code>"S"</code>. Like 
3361  *   <code>"S"</code> strings, <code>"U"</code> strings are read-only and used
3362  *   immediately. A Glk call that wants to use writable Unicode arrays will use
3363  *   an array type (<code>"&num;Iu"</code>) instead of <code>"U"</code>.</para>
3364  *   </listitem>
3365  * </varlistentry>
3366  * <varlistentry>
3367  *   <term><code>F</code></term>
3368  *   <listitem><para>A floating-point value. Glk does not currently use
3369  *   floating-point values, but we might as well define a code for them.</para>
3370  *   </listitem>
3371  * </varlistentry>
3372  * <varlistentry>
3373  *   <term><code>Qa, Qb, Qc...</code></term>
3374  *   <listitem><para>A reference to an opaque object. The second letter
3375  *   determines which class is involved. (The number of classes can be gleaned
3376  *   from gidispatch_count_classes(); see <link 
3377  *   linkend="chimara-Interrogating-the-Interface">Interrogating the
3378  *   Interface</link>).</para>
3379  *   <note><para>
3380  *     If Glk expands to have more than 26 classes, we'll think of something.
3381  *   </para></note></listitem>
3382  * </varlistentry>
3383  * </variablelist>
3384  * Any type code can be prefixed with one or more of the following characters:
3385  * <variablelist>
3386  * <varlistentry>
3387  *   <term><code>&amp;</code></term>
3388  *   <listitem><para>A reference to the type; or, if you like, a variable passed
3389  *   by reference. The reference is passed both in and out, so you must copy the
3390  *   value in before calling gidispatch_call() and copy it out afterward.</para>
3391  *   </listitem>
3392  * </varlistentry>
3393  * <varlistentry>
3394  *   <term><code>&lt;</code></term>
3395  *   <listitem><para>A reference which is pass-out only. The initial value is
3396  *   ignored, so you only need copy out the value after the call.</para>
3397  *   </listitem>
3398  * </varlistentry>
3399  * <varlistentry>
3400  *   <term><code>&gt;</code></term>
3401  *   <listitem><para>A reference which is pass-in only.</para>
3402  *   <note><para>
3403  *     This is not generally used for simple types, but is useful for structures
3404  *     and arrays.
3405  *   </para></note></listitem>
3406  * </varlistentry>
3407  * <varlistentry>
3408  *   <term><code>+</code></term>
3409  *   <listitem><para>Combined with <code>"&"</code>, <code>"&lt;"</code>, or 
3410  *   <code>"&gt;"</code>, indicates that a valid reference is mandatory; %NULL
3411  *   cannot be passed.</para>
3412  *   <note><para>
3413  *     Note that even though the @ptrflag #gluniversal_t for a <code>"+"</code>
3414  *     reference is always %TRUE, it cannot be omitted.
3415  *   </para></note></listitem>
3416  * </varlistentry>
3417  * <varlistentry>
3418  *   <term><code>:</code></term>
3419  *   <listitem><para>The colon separates the arguments from the return value, or
3420  *   terminates the string if there is no return value. Since return values are
3421  *   always non-%NULL pass-out references, you may treat <code>":"</code> as
3422  *   equivalent to <code>"&lt;+"</code>. The colon is never combined with any
3423  *   other prefix character.</para></listitem>
3424  * </varlistentry>
3425  * <varlistentry>
3426  *   <term><code>[...]</code></term>
3427  *   <listitem><para>Combined with <code>"&amp;"</code>, <code>"&lt;"</code>, or 
3428  *   <code>"&gt;"</code>, indicates a structure reference. Between the brackets
3429  *   is a complete argument list encoding string, including the number of
3430  *   arguments.</para>
3431  *   <note><para>
3432  *     For example, the prototype string for glk_select() is
3433  *     <code>"1&lt;+[4IuQaIuIu]:"</code> &mdash; one argument, which is a
3434  *     pass-out non-%NULL reference to a structure, which contains four
3435  *     arguments.
3436  *   </para></note>
3437  *   <para>Currently, structures in Glk contain only basic types.</para>
3438  *   </listitem>
3439  * </varlistentry>
3440  * <varlistentry>
3441  *   <term><code>&num;</code></term>
3442  *   <listitem><para>Combined with <code>"&amp;"</code>, <code>"&lt;"</code>, or 
3443  *   <code>"&gt;"</code>, indicates an array reference. As described above, this
3444  *   encompasses up to three #gluniversal_t objects &mdash; @ptrflag, pointer,
3445  *   and integer length.</para>
3446  *   <note><para>
3447  *     Depending on the design of your program, you may wish to pass a pointer
3448  *     directly to your program's memory, or allocate an array and copy the
3449  *     contents in and out. See <link linkend="chimara-Arrays">Arrays</link>.
3450  *   </para></note></listitem>
3451  * </varlistentry>
3452  * <varlistentry>
3453  *   <term><code>!</code></term>
3454  *   <listitem><para>Combined with <code>"&num;"</code>, indicates that the
3455  *   array is retained by the library. The library will keep a reference to the
3456  *   array; the contents are undefined until further notice. You should not use
3457  *   or copy the contents of the array out after the call, even for 
3458  *   <code>"&amp;&num;!"</code> or <code>"&lt;&num;!"</code> arrays. Instead, do
3459  *   it when the library releases the array.</para>
3460  *   <note><para>
3461  *     For example, glk_stream_open_memory() retains the array that you pass it,
3462  *     and releases it when the stream is closed. The library can notify you
3463  *     automatically when arrays are retained and released; see <link
3464  *     linkend="gidispatch-set-retained-registry">Retained Array
3465  *     Registry</link>.
3466  *   </para></note></listitem>
3467  * </varlistentry>
3468  * </variablelist>
3469  *
3470  * The order of these characters and prefixes is not completely arbitrary. Here
3471  * is a formal grammar for the prototype strings.
3472  *
3473  * <note><para>Thanks to Neil Cerutti for working this out.</para></note>
3474  *
3475  * <productionset>
3476  * <production id="prototype">
3477  *   <lhs>prototype</lhs>
3478  *   <rhs>ArgCount [ <nonterminal def="&num;arg_list">arg_list</nonterminal> ]
3479  *     ':' [ <nonterminal def="&num;arg">arg</nonterminal> ] EOL</rhs>
3480  * </production>
3481  * <production id="arg_list">
3482  *   <lhs>arg_list</lhs>
3483  *   <rhs><nonterminal def="&num;arg">arg</nonterminal> { <nonterminal
3484  *     def="&num;arg">arg</nonterminal> }</rhs>
3485  * </production>
3486  * <production id="arg">
3487  *   <lhs>arg</lhs>
3488  *   <rhs>TypeName | <nonterminal def="&num;ref_type">ref_type</nonterminal>
3489  *   </rhs>
3490  * </production>
3491  * <production id="ref_type">
3492  *   <lhs>ref_type</lhs>
3493  *   <rhs>RefType [ '+' ] <nonterminal
3494  *     def="&num;target_type">target_type</nonterminal></rhs>
3495  * </production>
3496  * <production id="target_type">
3497  *   <lhs>target_type</lhs>
3498  *   <rhs>TypeName | <nonterminal def="&num;array">array</nonterminal> |
3499  *     <nonterminal def="&num;struct">struct</nonterminal></rhs>
3500  * </production>
3501  * <production id="array">
3502  *   <lhs>array</lhs>
3503  *   <rhs>'&num;' [ '!' ] TypeName</rhs>
3504  * </production>
3505  * <production id="struct">
3506  *   <lhs>struct</lhs>
3507  *   <rhs>'[' ArgCount [ <nonterminal def="&num;arg_list">arg_list</nonterminal>
3508  *     ] ']'</rhs>
3509  * </production>
3510  * </productionset>
3511  * <constraintdef id="TypeName">
3512  *   <para>TypeName is <code>I[us]<!---->|C[nus]<!---->|S|U|F|Q[a-z]</code>
3513  *   </para>
3514  * </constraintdef>
3515  * <constraintdef id="ArgCount">
3516  *   <para>ArgCount is <code>\d+</code></para>
3517  * </constraintdef>
3518  * <constraintdef id="RefType">
3519  *   <para>RefType is <code>&amp;|&lt;|&gt;</code></para>
3520  * </constraintdef>
3521  * <constraintdef id="EOL">
3522  *   <para>EOL is end of input</para>
3523  * </constraintdef>
3524  *
3525  * Returns: A string which encodes the prototype of the specified Glk function.
3526  */
3527
3528 /**
3529  * gidisp_Class_Window:
3530  *
3531  * Represents a #winid_t opaque object.
3532  */
3533  
3534 /**
3535  * gidisp_Class_Stream:
3536  *
3537  * Represents a #strid_t opaque object.
3538  */
3539  
3540 /**
3541  * gidisp_Class_Fileref:
3542  *
3543  * Represents a #frefid_t opaque object.
3544  */
3545
3546 /**
3547  * gidisp_Class_Schannel:
3548  * 
3549  * Represents a #schanid_t opaque object.
3550  */
3551
3552 /**
3553  * gidispatch_rock_t:
3554  * @num: Space for storing an integer.
3555  * @ptr: Space for storing a pointer.
3556  *
3557  * You can store any value you want in this object; return it from your object
3558  * registry and retained array registry callbacks, and the library will stash it
3559  * away. You can retrieve it with gidispatch_get_objrock().
3560  */ 
3561
3562 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_BLORB.H ------------------*/
3563  
3564 /**
3565  * giblorb_err_t: 
3566  *
3567  * An integer type that can hold the Blorb error codes.
3568  */ 
3569  
3570 /**
3571  * giblorb_err_None:
3572  *
3573  * No error.
3574  */
3575  
3576 /**
3577  * giblorb_err_CompileTime: 
3578  *
3579  * Something is compiled wrong in the Blorb layer.
3580  */
3581  
3582 /**
3583  * giblorb_err_Alloc: 
3584  *
3585  * Memory could not be allocated.
3586  * <note><title>Chimara</title>
3587  * <para>
3588  *  The Blorb layer in the Chimara library should not return this error code;
3589  *  instead, the program aborts if memory allocation fails, in keeping with
3590  *  GLib practices.
3591  * </para></note> 
3592  */
3593  
3594 /**
3595  * giblorb_err_Read: 
3596  *
3597  * Data could not be read from the file.
3598  */
3599
3600 /** 
3601  * giblorb_err_NotAMap:
3602  *
3603  * The map parameter is invalid.
3604  */
3605
3606 /** 
3607  * giblorb_err_Format:
3608  *
3609  * The Blorb file is corrupted or invalid.
3610  */
3611  
3612 /**
3613  * giblorb_err_NotFound:
3614  *
3615  * The requested data could not be found.
3616  */
3617
3618 /**
3619  * giblorb_method_DontLoad:
3620  *
3621  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3622  * giblorb_load_resource() to obtain information about a chunk without actually
3623  * loading it.
3624  */
3625
3626 /**
3627  * giblorb_method_Memory:
3628  *
3629  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3630  * giblorb_load_resource() to load a chunk into memory.
3631  */
3632
3633 /**
3634  * giblorb_method_FilePos:
3635  *
3636  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
3637  * giblorb_load_resource() to get the position in the Blorb file at which the
3638  * chunk data starts.
3639  */
3640
3641 /**
3642  * giblorb_ID_Snd:
3643  *
3644  * Resource usage constant representing a sound file.
3645  */
3646
3647 /**
3648  * giblorb_ID_Exec:
3649  *
3650  * Resource usage constant representing an executable program.
3651  */
3652  
3653 /**
3654  * giblorb_ID_Pict:
3655  *
3656  * Resource usage constant representing an image file.
3657  */
3658
3659 /**
3660  * giblorb_ID_Data:
3661  *
3662  * Resource usage constant representing a data file.
3663  */
3664
3665 /**
3666  * giblorb_ID_Copyright:
3667  *
3668  * Resource usage constant representing the copyright message (date and holder, 
3669  * without the actual copyright symbol). There should only be one such chunk per
3670  * file.
3671  */
3672
3673 /**
3674  * giblorb_ID_AUTH:
3675  *
3676  * Resource usage constant representing the name of the author or creator of the
3677  * file. This could be a login name on multi-user systems, for example. There
3678  * should only be one such chunk per file.
3679  */
3680  
3681 /**
3682  * giblorb_ID_ANNO:
3683  *
3684  * Resource usage constant representing any textual annotation that the user or 
3685  * writing program sees fit to include.
3686  */ 
3687
3688 /**
3689  * giblorb_ID_TEXT:
3690  *
3691  * Resource usage constant representing a text data file.
3692  */
3693
3694 /**
3695  * giblorb_ID_BINA:
3696  *
3697  * Resource usage constant representing a binary data file.
3698  */
3699
3700 /**
3701  * giblorb_map_t:
3702  *
3703  * Holds the complete description of an open Blorb file. This type is opaque for
3704  * normal interpreter use.
3705  */
3706  
3707 /**
3708  * giblorb_result_t:
3709  * @chunknum: The chunk number (for use in giblorb_unload_chunk(), etc.)
3710  * @length: The length of the data
3711  * @chunktype: The type of the chunk.
3712  *
3713  * Holds information about a chunk loaded from a Blorb file, and the method of
3714  * accessing the chunk data. @data is a union of @ptr, a pointer to the data (if
3715  * you used %giblorb_method_Memory) and @startpos, the position in the file (if
3716  * you used %giblorb_method_FilePos). See giblorb_load_chunk_by_type() and
3717  * giblorb_load_chunk_by_number(). 
3718  */
3719  
3720 /**
3721  * giblorb_create_map:
3722  * @file: An input stream pointing to a Blorb file.
3723  * @newmap: Return location for a Blorb resource map.
3724  *
3725  * Reads Blorb data out of a Glk stream. It does not load every resource at 
3726  * once; instead, it creates a map in memory which makes it easy to find 
3727  * resources. A pointer to the map is stored in @newmap. This is an opaque 
3728  * object; you pass it to the other Blorb-layer functions.
3729  *
3730  * Returns: a Blorb error code. 
3731  */
3732  
3733 /**
3734  * giblorb_destroy_map: 
3735  * @map: A Blorb resource map to deallocate.
3736  *
3737  * Deallocates @map and all associated memory. This does 
3738  * <emphasis>not</emphasis> close the original stream.
3739  *
3740  * Returns: a Blorb error code. 
3741  */
3742
3743 /**
3744  * giblorb_load_chunk_by_type:
3745  * @map: The Blorb resource map to load a chunk from.
3746  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
3747  * %giblorb_method_Memory, or %giblorb_method_FilePos.
3748  * @res: Return location for the result.
3749  * @chunktype: The type of chunk to load.
3750  * @count: The chunk number of type @chunktype to load.
3751  *
3752  * Loads a chunk of a given type. The @count parameter distinguishes between 
3753  * chunks of the same type. If @count is zero, the first chunk of that type is 
3754  * loaded, and so on.
3755  * 
3756  * To load a chunk of an IFF FORM type (such as AIFF), you should pass in the 
3757  * form type, rather than FORM.
3758  * <note><para>
3759  *  This introduces a slight ambiguity &mdash; you cannot distiguish between a 
3760  *  FORM AIFF chunk and a non-FORM chunk of type AIFF. However, the latter is 
3761  *  almost certainly a mistake.
3762  * </para></note> 
3763  * 
3764  * The returned data is written into @res, according to @method.
3765  * 
3766  * The <structfield>chunknum</structfield> field is filled in with the number of
3767  * the chunk. (This value can then be passed to giblorb_load_chunk_by_number() 
3768  * or giblorb_unload_chunk().) The <structfield>length</structfield> field is 
3769  * filled in with the length of the chunk in bytes. The 
3770  * <structfield>chunktype</structfield> field is the chunk's type, which of 
3771  * course will be the type you asked for.
3772  * 
3773  * If you specify %giblorb_method_DontLoad, no data is actually loaded in. You
3774  * can use this if you are only interested in whether a chunk exists, or in the
3775  * <structfield>chunknum</structfield> and <structfield>length</structfield> 
3776  * parameters.
3777  * 
3778  * If you specify %giblorb_method_FilePos, 
3779  * <structfield>data.startpos</structfield> is filled in with the file position
3780  * of the chunk data. You can use glk_stream_set_position() to read the data 
3781  * from the stream.
3782  * 
3783  * If you specify %giblorb_method_Memory, <structfield>data.ptr</structfield> is
3784  * filled with a pointer to allocated memory containing the chunk data. This 
3785  * memory is owned by the map, not you. If you load the chunk more than once 
3786  * with %giblorb_method_Memory, the Blorb layer is smart enough to keep just one
3787  * copy in memory. You should not deallocate this memory yourself; call 
3788  * giblorb_unload_chunk() instead.
3789  *
3790  * Returns: a Blorb error code.
3791  */
3792
3793 /** 
3794  * giblorb_load_chunk_by_number:
3795  * @map: The Blorb resource map to load a chunk from.
3796  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
3797  * %giblorb_method_Memory, or %giblorb_method_FilePos.
3798  * @res: Return location for the result.
3799  * @chunknum: The chunk number to load.
3800  *
3801  * This is similar to giblorb_load_chunk_by_type(), but it loads a chunk with a
3802  * given chunk number. The type of the chunk can be found in the 
3803  * <structfield>chunktype</structfield> field of #giblorb_result_t. You can get
3804  * the chunk number from the <structfield>chunknum</structfield> field, after 
3805  * calling one of the other load functions.
3806  *
3807  * Returns: a Blorb error code. 
3808  */
3809
3810 /**
3811  * giblorb_unload_chunk:
3812  * @map: The Blorb resource map to unload a chunk from.
3813  * @chunknum: The chunk number to unload.
3814  *
3815  * Frees the chunk data allocated by %giblorb_method_Memory. If the given chunk
3816  * has never been loaded into memory, this has no effect. 
3817  *
3818  * Returns: a Blorb error code.
3819  */
3820
3821 /**
3822  * giblorb_load_resource:
3823  * @map: The Blorb resource map to load a resource from.
3824  * @method: The loading method to use, one of %giblorb_method_DontLoad, 
3825  * %giblorb_method_Memory, or %giblorb_method_FilePos.
3826  * @res: Return location for the result.
3827  * @usage: The type of data resource to load.
3828  * @resnum: The resource number to load.
3829  *
3830  * Loads a resource, given its usage and resource number. Currently, the three
3831  * usage values are %giblorb_ID_Pict (images), %giblorb_ID_Snd (sounds), and
3832  * %giblorb_ID_Exec (executable program). See the Blorb specification for more
3833  * information about the types of data that can be stored for these usages.
3834  * 
3835  * Note that a resource number is not the same as a chunk number. The resource
3836  * number is the sound or image number specified by a Glk program. Chunk number
3837  * is arbitrary, since chunks in a Blorb file can be in any order. To find the
3838  * chunk number of a given resource, call giblorb_load_resource() and look in
3839  * <structfield>res.chunknum</structfield>.
3840  *
3841  * Returns: a Blorb error code.
3842  */
3843
3844 /**
3845  * giblorb_count_resources:
3846  * @map: The Blorb resource map in which to count the resources.
3847  * @usage: The type of data resource to count.
3848  * @num: Return location for the number of chunks of @usage.
3849  * @min: Return location for the lowest resource number of @usage.
3850  * @max: Return location for the highest resource number of @usage.
3851  *
3852  * Counts the number of chunks with a given usage (image, sound, or executable.)
3853  * The total number of chunks of that usage is stored in @num. The lowest and 
3854  * highest resource number of that usage are stored in @min and @max. You can
3855  * leave any of the three pointers %NULL if you don't care about that
3856  * information. 
3857  *
3858  * Returns: a Blorb error code.
3859  */
3860
3861 /*--------------------TYPES AND CONSTANTS FROM GLKSTART.H---------------------*/
3862
3863 /**
3864  * glkunix_argumentlist_t:
3865  * @name: the option as it would appear on the command line (including the 
3866  * leading dash, if any.) 
3867  * @desc: a description of the argument; this is used when the library is 
3868  * printing a list of options.
3869  * @argtype: one of the <code>glkunix_arg_</code> constants.
3870  * 
3871  * <variablelist>
3872  * <varlistentry>
3873  *  <term>%glkunix_arg_NoValue</term>
3874  *  <listitem><para>The argument appears by itself.</para></listitem>
3875  * </varlistentry>
3876  * <varlistentry>
3877  *  <term>%glkunix_arg_ValueFollows</term>
3878  *  <listitem><para>The argument must be followed by another argument (the 
3879  *  value).</para></listitem>
3880  * </varlistentry>
3881  * <varlistentry>
3882  *  <term>%glkunix_arg_ValueCanFollow</term> 
3883  *  <listitem><para>The argument may be followed by a value, optionally. (If the
3884  *  next argument starts with a dash, it is taken to be a new argument, not the 
3885  *  value of this one.)</para></listitem>
3886  * </varlistentry>
3887  * <varlistentry>
3888  *  <term>%glkunix_arg_NumberValue</term>
3889  *  <listitem><para>The argument must be followed by a number, which may be the 
3890  *  next argument or part of this one. (That is, either <quote><code>-width 
3891  *  20</code></quote> or <quote><code>-width20</code></quote> will be accepted.)
3892  *  </para></listitem>
3893  * </varlistentry>
3894  * <varlistentry> 
3895  *  <term>%glkunix_arg_End</term>
3896  *  <listitem><para>The <code>glkunix_arguments[]</code> array must be 
3897  *  terminated with an entry containing this value.</para></listitem>
3898  * </varlistentry>
3899  * </variablelist>
3900  * 
3901  * To accept arbitrary arguments which lack dashes, specify a name of 
3902  * <code>""</code> and an argtype of %glkunix_arg_ValueFollows.
3903  *
3904  * If you don't care about command-line arguments, you must still define an
3905  * empty arguments list, as follows:
3906  * |[
3907  * glkunix_argumentlist_t glkunix_arguments[] = {
3908  *     { NULL, glkunix_arg_End, NULL }
3909  * };
3910  * ]|
3911  * 
3912  * Here is a more complete sample list:
3913  * |[
3914  * glkunix_argumentlist_t glkunix_arguments[] = {
3915  *     { "", glkunix_arg_ValueFollows, "filename: The game file to load." },
3916  *     { "-hum", glkunix_arg_ValueFollows, "-hum NUM: Hum some NUM." },
3917  *     { "-bom", glkunix_arg_ValueCanFollow, "-bom [ NUM ]: Do a bom (on
3918  *       the NUM, if given)." },
3919  *     { "-goo", glkunix_arg_NoValue, "-goo: Find goo." },
3920  *     { "-wob", glkunix_arg_NumberValue, "-wob NUM: Wob NUM times." },
3921  *     { NULL, glkunix_arg_End, NULL }
3922  * };
3923  * ]|
3924  * This would match the arguments <quote><code>thingfile -goo -wob8 -bom -hum 
3925  * song</code></quote>.
3926  *
3927  * After the library parses the command line, it does various occult rituals of
3928  * initialization, and then calls glkunix_startup_code().
3929  *
3930  * |[ int glkunix_startup_code(glkunix_startup_t *data); ]|
3931  *
3932  * This should return %TRUE if everything initializes properly. If it returns
3933  * %FALSE, the library will shut down without ever calling your glk_main() 
3934  * function.
3935  */
3936
3937 /**
3938  * glkunix_startup_t: 
3939  * @argc: The number of arguments in @argv.
3940  * @argv: Strings representing command line arguments.
3941  * 
3942  * The fields are a standard Unix <code>(argc, argv)</code> list, which contain
3943  * the arguments you requested from the command line. In deference to custom,
3944  * <code>argv[0]</code> is always the program name.
3945  */
3946
3947 /**
3948  * glkunix_arg_End:
3949  *
3950  * Terminates a list of #glkunix_argumentlist_t.
3951  */
3952  
3953 /**
3954  * glkunix_arg_ValueFollows:
3955  *
3956  * Indicates an argument which must be followed by a value, as the next 
3957  * argument.
3958  */
3959
3960 /** 
3961  * glkunix_arg_NoValue:
3962  *
3963  * Indicates an argument which occurs by itself, without a value.
3964  */
3965  
3966 /**
3967  * glkunix_arg_ValueCanFollow:
3968  *
3969  * Indicates an argument which may be followed by a value, or may occur by 
3970  * itself.
3971  */
3972  
3973 /**
3974  * glkunix_arg_NumberValue:
3975  *
3976  * Indicates an argument which must be followed by a numerical value, either as 
3977  * the next argument or tacked onto the end of this argument.
3978  */