From: Philip Chimento Date: Wed, 18 Jan 2012 16:18:51 +0000 (+0100) Subject: Bring documentation up to date with API 0.7.3 X-Git-Tag: v0.9~44 X-Git-Url: https://git.stderr.nl/gitweb?p=projects%2Fchimara%2Fchimara.git;a=commitdiff_plain;h=90090906ff9ca843e5dac0d26342f5bf85bab4f2 Bring documentation up to date with API 0.7.3 --- diff --git a/docs/reference/glk-sound-resources.sgml b/docs/reference/glk-sound-resources.sgml index aaf4fd4..8576203 100644 --- a/docs/reference/glk-sound-resources.sgml +++ b/docs/reference/glk-sound-resources.sgml @@ -29,7 +29,7 @@ A resource can theoretically contain any kind of sound data, of any length. A re A resource can also contain two or more channels of sound (stereo data). Do not confuse such in-sound channels with Glk sound channels. A single Glk sound channel suffices to play any sound, even stereo sounds. -Again, Blorb is the official resource-storage format of Glk. Sounds in Blorb files can be encoded as AIFF, MOD, or MOD song data. See the Blorb specification for details. +Again, Blorb is the official resource-storage format of Glk. Sounds in Blorb files can be encoded as Ogg, AIFF, or MOD. See the Blorb specification for details. - \ No newline at end of file + diff --git a/libchimara/doc.c b/libchimara/doc.c index a510e77..277245c 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 @@ -1313,7 +1335,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 +1345,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: @@ -1612,6 +1642,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 +1651,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 +1710,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. */ /** @@ -1963,6 +1995,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 +2004,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 +2647,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 diff --git a/libchimara/schannel.c b/libchimara/schannel.c index d176d7d..617adc1 100644 --- a/libchimara/schannel.c +++ b/libchimara/schannel.c @@ -172,6 +172,23 @@ finally: * Remember that it is possible that the library will be unable to create a new * channel, in which case glk_schannel_create() will return %NULL. * + * When you create a channel using glk_schannel_create(), it has full volume, + * represented by the value 0x10000. Half volume would be 0x8000, three-quarters + * volume would be 0xC000, and so on. A volume of zero represents silence. + * + * You can overdrive the volume of a channel by setting a volume greater than + * 0x10000. However, this is not recommended; the library may be unable to + * increase the volume past full, or the sound may become distorted. You should + * always create sound resources with the maximum volume you will need, and then + * reduce the volume when appropriate using the channel-volume calls. + * + * + * Mathematically, these volume changes should be taken as linear + * multiplication of a waveform represented as linear samples. As I + * understand it, linear PCM encodes the sound pressure, and therefore a + * volume of 0x8000 should represent a 6 dB drop. + * + * * Returns: A new sound channel, or %NULL. */ schanid_t @@ -185,11 +202,14 @@ glk_schannel_create(glui32 rock) * @rock: The rock value to give the new sound channel. * @volume: Integer representing the volume; 0x10000 is 100%. * - * [DRAFT SPEC] - * * The glk_schannel_create_ext() call lets you create a channel with the volume * already set at a given level. * + * Not all libraries support glk_schannel_create_ext(). You should test the + * %gestalt_Sound2 selector before you rely on it; see Testing for Sound + * Capabilities. + * * Returns: A new sound channel, or %NULL. */ schanid_t @@ -402,9 +422,14 @@ glk_schannel_play(schanid_t chan, glui32 snd) * sound is playing, there will be no notification event. * * Not all libraries support sound notification. You should test the - * %gestalt_SoundNotify selector before you rely on it; see Testing for Sound * Capabilities. + * + * Note that you can play a sound on a channel whose volume is zero. This has + * no audible result, unless you later change the volume; but it produces + * notifications as usual. You can also play a sound on a paused channel; the + * sound is paused immediately, and does not progress. * * Returns: 1 on success, 0 on failure. */ @@ -482,8 +507,6 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify) * @sndarray: Array of sound resource numbers. * @soundcount: Length of @sndarray, must be equal to @chanarray. * @notify: If nonzero, request a notification when each sound finishes. - * - * [DRAFT SPEC] * * This works the same as glk_schannel_play_ext(), except that you can specify * more than one sound. The channel references and sound resource numbers are @@ -496,6 +519,11 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify) * a number from 0 to @soundcount.) * * + * If the @notify argument is nonzero, you will get a separate sound + * notification event as each sound finishes. They will all have the same + * @val2 value. + * + * * Note that you have to supply @chancount and @soundcount as separate * arguments, even though they are required to be the same. This is an awkward * consequence of the way array arguments are dispatched in Glulx. @@ -610,9 +638,7 @@ glk_schannel_stop(schanid_t chan) /** * glk_schannel_pause: * @chan: Channel to pause. - * - * [DRAFT SPEC] - * + * * Pause any sound playing in the channel. This does not generate any * notification events. If the channel is already paused, this does nothing. * @@ -649,11 +675,16 @@ glk_schannel_pause(schanid_t chan) /** * glk_schannel_unpause: * @chan: Channel to unpause. - * - * [DRAFT SPEC] * * Unpause the channel. Any paused sounds begin playing where they left off. If * the channel is not already paused, this does nothing. + * + * + * This means, for example, that you can pause a channel that is currently + * not playing any sounds. If you then add a sound to the channel, it will + * not start playing; it will be paused at its beginning. If you later + * unpaise the channel, the sound will commence. + * */ void glk_schannel_unpause(schanid_t chan) @@ -685,19 +716,20 @@ glk_schannel_unpause(schanid_t chan) * @chan: Channel to set the volume of. * @vol: Integer representing the volume; 0x10000 is 100%. * - * Sets the volume in the channel. When you create a channel, it has full - * volume, represented by the value 0x10000. Half volume would be 0x8000, - * three-quarters volume would be 0xC000, and so on. A volume of zero represents - * silence, although the sound is still considered to be playing. + * Sets the volume in the channel, from 0 (silence) to 0x10000 (full volume). + * Again, you can overdrive the volume by setting a value greater than 0x10000, + * but this is not recommended. * - * You can call this function between sounds, or while a sound is playing. The - * effect is immediate. + * The glk_schannel_set_volume() function does not include duration and notify + * values. Both are assumed to be zero: immediate change, no notification. + * + * You can call this function between sounds, or while a sound is playing. + * However, a zero-duration change while a sound is playing may produce + * unpleasant clicks. * - * You can overdrive the volume of a channel by setting a volume greater than - * 0x10000. However, this is not recommended; the library may be unable to - * increase the volume past full, or the sound may become distorted. You should - * always create sound resources with the maximum volume you will need, and then - * call glk_schannel_set_volume() to reduce the volume when appropriate. + * At most one volume change can be occurring on a sound channel at any time. + * If you call this function while a previous volume change is in progress, the + * previous change is interrupted. * * Not all libraries support this function. You should test the * %gestalt_SoundVolume selector before you rely on it; see * - * After the first split, the new pair window (O1, which covers the whole - * screen) knows that its first child (A) is above the second, and gets 50% of - * its own area. (A is the key window for this split, but a proportional split - * doesn't care about key windows.) + * The initial window is A. After the first split, the new pair window (O1, + * which covers the whole screen) knows that its new child (B) is below A, and + * gets 50% of its own area. (B is the key window for this split, but a + * proportional split doesn't care about key windows.) * - * After the second split, all this remains true; O1 knows that its first child - * gets 50% of its space, and A is O1's key window. But now O1's first child is - * O2 instead of A. The newer pair window (O2) knows that its first child (C) - * is above the second, and gets a fixed size of two rows. (As measured in C's - * font, because C is O2's key window.) + * After the second split, all this remains true; O1 knows + * that its first child gets 50% of its space, and B is O1's key window. But + * now O1's first child is O2 instead of A. The newer pair window (O2) knows + * that its first child (C) is above the second, and gets a fixed size of two + * rows. (As measured in C's font, because C is O2's key window.) * * If we split C, now, the resulting pair will still be two C-font rows high * — that is, tall enough for two lines of whatever font C displays. For