libchimara/schannel.c

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