X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=c45859f7b5cb7e8535ed8aa3807158cc0d7bdad1;hb=9ee259d9a29d83d79d912d1716b4044c63e90343;hp=a510e77342272965347c8588f0b06376316d11f8;hpb=1517709438931d163e561b67991af15ec1d358c5;p=projects%2Fchimara%2Fchimara.git
diff --git a/libchimara/doc.c b/libchimara/doc.c
index a510e77..c45859f 100644
--- a/libchimara/doc.c
+++ b/libchimara/doc.c
@@ -586,6 +586,28 @@
* A stream is opened with a particular file mode, see the
* filemode_ constants below.
*
+ *
+ * In the stdio library, using fopen(), %filemode_Write would be mode
+ * "w"; %filemode_Read would be mode "r";
+ * %filemode_ReadWrite would be mode "r+". Confusingly,
+ * %filemode_WriteAppend cannot be mode "a", because the stdio
+ * spec says that when you open a file with mode "a", then
+ * fseek() doesn't work. So we have to use mode "r+" for
+ * appending. Then we run into the other stdio problem,
+ * which is that "r+" never creates a new file. So
+ * %filemode_WriteAppend has to first open the file with
+ * "a", close it, reopen with "r+", and then
+ * fseek() to the end of the file. For %filemode_ReadWrite, the process is
+ * the same, except without the fseek() — we begin at the beginning of
+ * the file.
+ *
+ *
+ * We must also obey an obscure geas of ANSI C "r+" files: you
+ * can't switch from reading to writing without doing an fseek() in between.
+ * Switching from writing to reading has the same restriction, except that an
+ * fflush() also works.
+ *
+ *
* For information on opening streams, see the discussion of each specific type
* of stream in The Types of
* Streams. Remember that it is always possible that opening a stream
@@ -778,7 +800,7 @@
/**
* SECTION:glk-stream-types
- * @short_description: Window, memory, and file streams
+ * @short_description: Window, memory, file, and resource streams
*
* Window Streams
*
@@ -841,6 +863,30 @@
* linkend="chimara-File-References">File References.
*
*
+ * Resource Streams
+ *
+ * You can open a stream which reads from (but not writes to) a resource file.
+ *
+ *
+ * Typically this is embedded in a Blorb file, as Blorb is the official
+ * resource-storage format of Glk. A Blorb file can contain images and sounds,
+ * but it can also contain raw data files, which are accessed by
+ * glk_stream_open_resource() and glk_stream_open_resource_uni(). A data file
+ * is identified by number, not by a filename. The Blorb usage field will be
+ * 'Data'. The chunk type will be %giblorb_ID_TEXT for text
+ * resources, %giblorb_ID_BINA for binary resources.
+ *
+ *
+ *
+ * If the running program is not associated with a Blorb file, the library may
+ * look for data files as actual files instead. These would be named
+ * DATA1, DATA2, etc, with a suffix
+ * distinguishing text and binary files. See Other Resource
+ * Arrangements in the Blorb spec:
+ *
+ *
+ *
*/
/**
@@ -1313,7 +1359,7 @@
*/
/**
- * GLK_MODULE_SOUND:
+ * GLK_MODULE_SOUND2:
*
* If you are writing a C program, there is an additional complication. A
* library which does not support sound may not implement the sound functions at
@@ -1323,9 +1369,17 @@
* even get compile-time errors.
*
* To avoid this, you can perform a preprocessor test for the existence of
- * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants
+ * %GLK_MODULE_SOUND2. If this is defined, so are all the functions and constants
* described in this section. If not, not.
- */
+ */
+
+/**
+ * GLK_MODULE_SOUND:
+ *
+ * You can perform a preprocessor test for the existence of %GLK_MODULE_SOUND.
+ * If this is defined, so are all the functions and constants described in this
+ * section. If not, not.
+ */
/**
* GLK_MODULE_HYPERLINKS:
@@ -1410,8 +1464,8 @@
* So the version number 78.2.11 would be encoded as 0x004E020B.
*
*
- * The current Glk specification version is 0.7.3, so this selector will return
- * 0x00000703.
+ * The current Glk specification version is 0.7.4, so this selector will return
+ * 0x00000704.
*
* |[
* glui32 res;
@@ -1612,6 +1666,8 @@
*
* If this selector returns 0, you should not try to call these functions. They
* may have no effect, or they may cause a run-time error.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
@@ -1619,24 +1675,22 @@
*
* You can test whether the library supports setting the volume of sound
* channels:
- * |[
- * glui32 res;
- * res = glk_gestalt(gestalt_SoundVolume, 0);
- * ]|
+ * |[ res = glk_gestalt(gestalt_SoundVolume, 0); ]|
* This selector returns 1 if the glk_schannel_set_volume() function works. If
* it returns zero, glk_schannel_set_volume() has no effect.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
* gestalt_SoundNotify:
*
* You can test whether the library supports sound notification events:
- * |[
- * glui32 res;
- * res = glk_gestalt(gestalt_SoundNotify, 0);
- * ]|
+ * |[ res = glk_gestalt(gestalt_SoundNotify, 0); ]|
* This selector returns 1 if the library supports sound notification events. If
* it returns zero, you will never get such events.
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
@@ -1680,6 +1734,8 @@
* course, an ugly hack. It is a concession to the current state of the Glk
* libraries, some of which can handle AIFF but not MOD sounds.
*
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
@@ -1802,6 +1858,18 @@
*
*/
+/**
+ * gestalt_ResourceStream:
+ *
+ * |[
+ * res = glk_gestalt(gestalt_ResourceStream, 0);
+ * ]|
+ *
+ * This returns 1 if the glk_stream_open_resource() and
+ * glk_stream_open_resource_uni() functions are available. If it returns 0, you
+ * should not call them.
+ */
+
/**
* evtype_None:
*
@@ -1963,6 +2031,8 @@
/**
* evtype_SoundNotify:
*
+ * The completion of a sound being played in a sound channel.
+ *
* On platforms that support sound, you can request to receive an
* %evtype_SoundNotify event when a sound finishes playing. See Playing Sounds.
@@ -1970,6 +2040,8 @@
/**
* evtype_Hyperlink:
+ *
+ * The selection of a hyperlink in a window.
*
* On platforms that support hyperlinks, you can request to receive an
* %evtype_Hyperlink event when the player selects a link. See .
*/
+/**
+ * evtype_VolumeNotify:
+ *
+ * The completion of a gradual volume change in a sound channel.
+ *
+ * On platforms that support sound, you can request to receive an
+ * %evtype_VolumeNotify event when a gradual volume change completes. See Playing Sounds.
+ */
+
/**
* event_t:
* @type: the event type
@@ -2601,7 +2683,7 @@
* linefeed-plus-carriage-return combinations; Latin-1 characters may be
* converted to native character codes. When reading a file in text mode, native
* line breaks will be converted back to newline (0x0A) characters, and native
- * character codes may be converted to Latin-1.
+ * character codes may be converted to Latin-1 or UTF-8.
*
*
* Line breaks will always be converted; other conversions are more
@@ -3574,6 +3656,12 @@
* Resource usage constant representing an image file.
*/
+/**
+ * giblorb_ID_Data:
+ *
+ * Resource usage constant representing a data file.
+ */
+
/**
* giblorb_ID_Copyright:
*
@@ -3596,7 +3684,19 @@
* Resource usage constant representing any textual annotation that the user or
* writing program sees fit to include.
*/
-
+
+/**
+ * giblorb_ID_TEXT:
+ *
+ * Resource usage constant representing a text data file.
+ */
+
+/**
+ * giblorb_ID_BINA:
+ *
+ * Resource usage constant representing a binary data file.
+ */
+
/**
* giblorb_map_t:
*