X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fdoc.c;h=c45859f7b5cb7e8535ed8aa3807158cc0d7bdad1;hb=cbb35cca2d0a87a664e5d72fe71dce45c3030823;hp=fa4dc5a8d29a8f3ad77a067a3370604ad521e087;hpb=d8bf5493f36c47b989dcb8950fee1ad496850260;p=projects%2Fchimara%2Fchimara.git diff --git a/libchimara/doc.c b/libchimara/doc.c index fa4dc5a..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.2, so this selector will return - * 0x00000702. + * 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: *