* A stream is opened with a particular file mode, see the
* <code>filemode_</code> constants below.
*
+ * <note><para>
+ * In the stdio library, using fopen(), %filemode_Write would be mode
+ * <code>"w"</code>; %filemode_Read would be mode <code>"r"</code>;
+ * %filemode_ReadWrite would be mode <code>"r+"</code>. Confusingly,
+ * %filemode_WriteAppend cannot be mode <code>"a"</code>, because the stdio
+ * spec says that when you open a file with mode <code>"a"</code>, then
+ * fseek() doesn't work. So we have to use mode <code>"r+"</code> for
+ * appending. Then we run into the <emphasis>other</emphasis> stdio problem,
+ * which is that <code>"r+"</code> never creates a new file. So
+ * %filemode_WriteAppend has to <emphasis>first</emphasis> open the file with
+ * <code>"a"</code>, close it, reopen with <code>"r+"</code>, 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.
+ * </para></note>
+ * <note><para>
+ * We must also obey an obscure geas of ANSI C <code>"r+"</code> 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.
+ * </para></note>
+ *
* For information on opening streams, see the discussion of each specific type
* of stream in <link linkend="chimara-The-Types-of-Streams">The Types of
* Streams</link>. Remember that it is always possible that opening a stream
*/
/**
- * 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
* 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:
*
* 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.
*/
/**
*
* 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.
*/
/**
* 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.
* </para></note>
+ *
+ * This selector is guaranteed to return 1 if %gestalt_Sound2 does.
*/
/**
/**
* 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 <link
* linkend="chimara-Playing-Sounds">Playing Sounds</link>.
/**
* 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 <link
* Events</link>.
*/
+/**
+ * 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 <link
+ * linkend="chimara-Playing-Sounds">Playing Sounds</link>.
+ */
+
/**
* event_t:
* @type: the event type
* 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.
*
* <note><para>
* Line breaks will always be converted; other conversions are more
* 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.
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
+ *
* Returns: A new sound channel, or %NULL.
*/
schanid_t
* @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 <link
+ * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound
+ * Capabilities</link>.
+ *
* Returns: A new sound channel, or %NULL.
*/
schanid_t
* 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 <link
+ * %gestalt_Sound2 selector before you rely on it; see <link
* linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound
* Capabilities</link>.
+ *
+ * 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.
*/
* @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
* a number from 0 to @soundcount.)
*
* <note><para>
+ * 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.
+ * </para></note>
+ * <note><para>
* 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.
/**
* 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.
*
/**
* 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.
+ *
+ * <note><para>
+ * 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.
+ * </para></note>
*/
void
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 <link
* @vol: Integer representing the volume; 0x10000 is 100%.
* @duration: Length of volume change in milliseconds, or 0 for immediate.
* @notify: If nonzero, requests a notification when the volume change finishes.
- *
- * [DRAFT SPEC]
- *
+ *
* 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.
* event with type #evtype_VolumeNotify. The window will be %NULL, @val1 will be
* zero, and @val2 will be the nonzero value you passed as @notify.
*
- * The glk_schannel_set_volume() does not include @duration and @notify values.
- * Both are assumed to be zero: immediate change, no notification.
- *
- * You can call these functions between sounds, or while a sound is playing.
+ * 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.
*
* At most one volume change can be occurring on a sound channel at any time. If
- * you call one of these functions while a previous volume change is in
- * progress, the previous change is interrupted. The beginning point of the new
- * volume change should be wherever the previous volume change was interrupted
- * (rather than the previous change's beginning or ending point).
+ * you call this function while a previous volume change is in progress, the
+ * previous change is interrupted. The beginning point of the new volume change
+ * should be wherever the previous volume change was interrupted (rather than
+ * the previous change's beginning or ending point).
*
* Not all libraries support these functions. You should test the appropriate
* gestalt selectors before you rely on them; see "Testing for Sound
* A C
* </literallayout></textobject></mediaobject></entry>
* </row></tbody></tgroup></informaltable>
- * 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 <emphasis>second</emphasis> 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
projects / projects / chimara / chimara.git / commitdiff