glk_schannel_play ()

glui32
glk_schannel_play (schanid_t chan,
                   glui32 snd);

Begins playing the given sound on the channel. If the channel was already playing a sound (even the same one), the old sound is stopped (with no notification event.

This returns 1 if the sound actually started playing, and 0 if there was any problem.

glk_schannel_play_ext ()

glui32
glk_schannel_play_ext (schanid_t chan,
                       glui32 snd,
                       glui32 repeats,
                       glui32 notify);

This works the same as glk_schannel_play(), but lets you specify additional options. glk_schannel_play(chan, snd) is exactly equivalent to glk_schannel_play_ext(chan, snd, 1, 0).

The repeats value is the number of times the sound should be repeated. A repeat value of -1 (or rather 0xFFFFFFFF) means that the sound should repeat forever. A repeat value of 0 means that the sound will not be played at all; nothing happens. (Although a previous sound on the channel will be stopped, and the function will return 1.)

The notify value should be nonzero in order to request a sound notification event. If you do this, when the sound is completed, you will get an event with type evtype_SoundNotify. The window will be NULL, val1 will be the sound's resource id, and val2 will be the nonzero value you passed as notify .

If you request sound notification, and the repeat value is greater than one, you will get the event only after the last repetition. If the repeat value is 0 or -1, you will never get a notification event at all. Similarly, if the sound is stopped or interrupted, or if the channel is destroyed while the sound is playing, there will be no notification event.

Not all libraries support sound notification. You should test the gestalt_Sound2 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.

glk_schannel_play_multi ()

glui32
glk_schannel_play_multi (schanid_t *chanarray,
                         glui32 chancount,
                         glui32 *sndarray,
                         glui32 soundcount,
                         glui32 notify);

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 given as two arrays, which must be the same length. The notify argument applies to all the sounds; the repeats value for all the sounds is 1.

All the sounds will begin at exactly the same time.

This returns the number of sounds that began playing correctly. (This will be a number from 0 to soundcount .)

glk_schannel_stop ()

void
glk_schannel_stop (schanid_t chan);

Stops any sound playing in the channel. No notification event is generated, even if you requested one. If no sound is playing, this has no effect.

glk_schannel_pause ()

void
glk_schannel_pause (schanid_t chan);

Pause any sound playing in the channel. This does not generate any notification events. If the channel is already paused, this does nothing.

New sounds started in a paused channel are paused immediately.

A volume change in progress is not paused, and may proceed to completion, generating a notification if appropriate.

glk_schannel_unpause ()

void
glk_schannel_unpause (schanid_t chan);

Unpause the channel. Any paused sounds begin playing where they left off. If the channel is not already paused, this does nothing.

glk_schannel_set_volume ()

void
glk_schannel_set_volume (schanid_t chan,
                         glui32 vol);

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.

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.

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 Testing for Sound Capabilities.

glk_schannel_set_volume_ext ()

void
glk_schannel_set_volume_ext (schanid_t chan,
                             glui32 vol,
                             glui32 duration,
                             glui32 notify);

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.

If the duration is zero, the change is immediate. Otherwise, the change begins immediately, and occurs smoothly over the next duration milliseconds.

The notify value should be nonzero in order to request a volume notification event. If you do this, when the volume change is completed, you will get an 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 .

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 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 Capabilities".

glk_sound_load_hint ()

void
glk_sound_load_hint (glui32 snd,
                     glui32 flag);

This gives the library a hint about whether the given sound should be loaded or not. If the flag is nonzero, the library may preload the sound or do other initialization, so that glk_schannel_play() will be faster. If the flag is zero, the library may release memory or other resources associated with the sound. Calling this function is always optional, and it has no effect on what the library actually plays.