libchimara/schannel.c

   1 #include <glib.h>
   2 #include <libchimara/glk.h>
   3
   4 /**
   5  * glk_schannel_create:
   6  * @rock: The rock value to give the new sound channel.
   7  *
   8  * This creates a sound channel, about as you'd expect.
   9  *
  10  * Remember that it is possible that the library will be unable to create a new
  11  * channel, in which case glk_schannel_create() will return %NULL.
  12  *
  13  * <warning><para>This function is not implemented yet.</para></warning>
  14  *
  15  * Returns: A new sound channel, or %NULL.
  16  */
  17 schanid_t
  18 glk_schannel_create(glui32 rock)
  19 {
  20         return NULL;
  21 }
  22
  23 /**
  24  * glk_schannel_destroy:
  25  * @chan: The sound channel to destroy.
  26  *
  27  * Destroys the channel. If the channel is playing a sound, the sound stops
  28  * immediately (with no notification event).
  29  *
  30  * <warning><para>This function is not implemented yet.</para></warning>
  31  */
  32 void
  33 glk_schannel_destroy(schanid_t chan)
  34 {
  35         VALID_SCHANNEL(chan, return);
  36 }
  37
  38 /**
  39  * glk_schannel_iterate:
  40  * @chan: A sound channel, or %NULL.
  41  * @rockptr: Return location for the next sound channel's rock, or %NULL.
  42  *
  43  * This function can be used to iterate through the list of all open channels.
  44  * See <link linkend="chimara-Iterating-Through-Opaque-Objects">Iterating
  45  * Through Opaque Objects</link>.
  46  *
  47  * As that section describes, the order in which channels are returned is
  48  * arbitrary.
  49  *
  50  * <warning><para>This function is not implemented yet.</para></warning>
  51  *
  52  * Returns: the next sound channel, or %NULL if there are no more.
  53  */
  54 schanid_t
  55 glk_schannel_iterate(schanid_t chan, glui32 *rockptr)
  56 {
  57         VALID_SCHANNEL_OR_NULL(chan, return NULL);
  58         return NULL;
  59 }
  60
  61 /**
  62  * glk_schannel_get_rock:
  63  * @chan: A sound channel.
  64  *
  65  * Retrieves the channel's rock value. See <link
  66  * linkend="chimara-Rocks">Rocks</link>.
  67  *
  68  * <warning><para>This function is not implemented yet.</para></warning>
  69  *
  70  * Returns: A rock value.
  71  */
  72 glui32
  73 glk_schannel_get_rock(schanid_t chan)
  74 {
  75         VALID_SCHANNEL(chan, return 0);
  76         return 0;
  77 }
  78
  79 /**
  80  * glk_schannel_play:
  81  * @chan: Channel to play the sound in.
  82  * @snd: Resource number of the sound to play.
  83  *
  84  * Begins playing the given sound on the channel. If the channel was already
  85  * playing a sound (even the same one), the old sound is stopped (with no
  86  * notification event.
  87  *
  88  * This returns 1 if the sound actually started playing, and 0 if there was any
  89  * problem.
  90  * <note><para>
  91  *   The most obvious problem is if there is no sound resource with the given
  92  *   identifier. But other problems can occur. For example, the MOD-playing
  93  *   facility in a library might be unable to handle two MODs at the same time,
  94  *   in which case playing a MOD resource would fail if one was already playing.
  95  * </para></note>
  96  *
  97  * <warning><para>This function is not implemented yet.</para></warning>
  98  *
  99  * Returns: 1 on success, 0 on failure.
 100  */
 101 glui32
 102 glk_schannel_play(schanid_t chan, glui32 snd)
 103 {
 104         VALID_SCHANNEL(chan, return 0);
 105         return 0;
 106 }
 107
 108 /**
 109  * glk_schannel_play_ext:
 110  * @chan: Channel to play the sound in.
 111  * @snd: Resource number of the sound to play.
 112  * @repeats: Number of times to repeat the sound.
 113  * @notify: If nonzero, requests a notification when the sound is finished.
 114  *
 115  * This works the same as glk_schannel_play(), but lets you specify additional
 116  * options. <code>glk_schannel_play(chan, snd)</code> is exactly equivalent to
 117  * <code>glk_schannel_play_ext(chan, snd, 1, 0)</code>.
 118  *
 119  * The @repeats value is the number of times the sound should be repeated. A
 120  * repeat value of -1 (or rather 0xFFFFFFFF) means that the sound should repeat
 121  * forever. A repeat value of 0 means that the sound will not be played at all;
 122  * nothing happens. (Although a previous sound on the channel will be stopped,
 123  * and the function will return 1.)
 124  *
 125  * The @notify value should be nonzero in order to request a sound notification
 126  * event. If you do this, when the sound is completed, you will get an event
 127  * with type %evtype_SoundNotify. The @window will be %NULL, @val1 will be the
 128  * sound's resource id, and @val2 will be the nonzero value you passed as
 129  * @notify.
 130  *
 131  * If you request sound notification, and the repeat value is greater than one,
 132  * you will get the event only after the last repetition. If the repeat value is
 133  * 0 or -1, you will never get a notification event at all. Similarly, if the
 134  * sound is stopped or interrupted, or if the channel is destroyed while the
 135  * sound is playing, there will be no notification event.
 136  *
 137  * Not all libraries support sound notification. You should test the
 138  * %gestalt_SoundNotify selector before you rely on it; see <link
 139  * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound
 140  * Capabilities</link>.
 141  *
 142  * <warning><para>This function is not implemented yet.</para></warning>
 143  *
 144  * Returns: 1 on success, 0 on failure.
 145  */
 146 glui32
 147 glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
 148 {
 149         VALID_SCHANNEL(chan, return 0);
 150         return 0;
 151 }
 152
 153 /**
 154  * glk_schannel_stop:
 155  * @chan: Channel to silence.
 156  *
 157  * Stops any sound playing in the channel. No notification event is generated,
 158  * even if you requested one. If no sound is playing, this has no effect.
 159  *
 160  * <warning><para>This function is not implemented yet.</para></warning>
 161  */
 162 void
 163 glk_schannel_stop(schanid_t chan)
 164 {
 165         VALID_SCHANNEL(chan, return);
 166 }
 167
 168 /**
 169  * glk_schannel_set_volume:
 170  * @chan: Channel to set the volume of.
 171  * @vol: Integer representing the volume; 0x10000 is 100&percnt;.
 172  *
 173  * Sets the volume in the channel. When you create a channel, it has full
 174  * volume, represented by the value 0x10000. Half volume would be 0x8000,
 175  * three-quarters volume would be 0xC000, and so on. A volume of zero represents
 176  * silence, although the sound is still considered to be playing.
 177  *
 178  * You can call this function between sounds, or while a sound is playing. The
 179  * effect is immediate.
 180  *
 181  * You can overdrive the volume of a channel by setting a volume greater than
 182  * 0x10000. However, this is not recommended; the library may be unable to
 183  * increase the volume past full, or the sound may become distorted. You should
 184  * always create sound resources with the maximum volume you will need, and then
 185  * call glk_schannel_set_volume() to reduce the volume when appropriate.
 186  *
 187  * Not all libraries support this function. You should test the
 188  * %gestalt_SoundVolume selector before you rely on it; see <link
 189  * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound
 190  * Capabilities</link>.
 191  *
 192  * <warning><para>This function is not implemented yet.</para></warning>
 193  */
 194 void
 195 glk_schannel_set_volume(schanid_t chan, glui32 vol)
 196 {
 197         VALID_SCHANNEL(chan, return);
 198 }
 199
 200 /**
 201  * glk_sound_load_hint:
 202  * @snd: Resource number of a sound.
 203  * @flag: Nonzero to tell the library to load the sound, zero to tell the
 204  * library to unload it.
 205  *
 206  * This gives the library a hint about whether the given sound should be loaded
 207  * or not. If the @flag is nonzero, the library may preload the sound or do
 208  * other initialization, so that glk_schannel_play() will be faster. If the
 209  * @flag is zero, the library may release memory or other resources associated
 210  * with the sound. Calling this function is always optional, and it has no
 211  * effect on what the library actually plays.
 212  *
 213  * <warning><para>This function is not implemented yet.</para></warning>
 214  */
 215 void
 216 glk_sound_load_hint(glui32 snd, glui32 flag)
 217 {
 218 }