Implemented garglk_set_program_name(), garglk_set_program_info(), garglk_set_story_name()
[rodin/chimara.git] / 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 }