X-Git-Url: https://git.stderr.nl/gitweb?a=blobdiff_plain;f=libchimara%2Fschannel.c;h=b64470db222addbcf9a30c9595f9309676e1ce14;hb=1e0dc5378f314f555e3b923c6d95f5017abd528b;hp=d176d7d87caf7ef04aa878340aea32943863b2a1;hpb=8f5765dbc7691ac4b6b68b65ba40e7d815507c3a;p=projects%2Fchimara%2Fchimara.git
diff --git a/libchimara/schannel.c b/libchimara/schannel.c
index d176d7d..b64470d 100644
--- a/libchimara/schannel.c
+++ b/libchimara/schannel.c
@@ -15,7 +15,7 @@
#define VOLUME_TIMER_RESOLUTION 1.0 /* In milliseconds */
-extern GPrivate *glk_data_key;
+extern GPrivate glk_data_key;
#ifdef GSTREAMER_SOUND
/* Stop any currently playing sound on this channel, and remove any
@@ -25,6 +25,11 @@ clean_up_after_playing_sound(schanid_t chan)
{
if(!gst_element_set_state(chan->pipeline, GST_STATE_NULL))
WARNING_S(_("Could not set GstElement state to"), "NULL");
+ if(chan->source)
+ {
+ gst_bin_remove(GST_BIN(chan->pipeline), chan->source);
+ chan->source = NULL;
+ }
if(chan->demux)
{
gst_bin_remove(GST_BIN(chan->pipeline), chan->demux);
@@ -172,6 +177,23 @@ finally:
* 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.
+ *
+ *
+ * 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.
+ *
+ *
* Returns: A new sound channel, or %NULL.
*/
schanid_t
@@ -185,18 +207,21 @@ glk_schannel_create(glui32 rock)
* @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 Testing for Sound
+ * Capabilities.
+ *
* Returns: A new sound channel, or %NULL.
*/
schanid_t
glk_schannel_create_ext(glui32 rock, glui32 volume)
{
#ifdef GSTREAMER_SOUND
- ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+ ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
schanid_t s = g_new0(struct glk_schannel_struct, 1);
s->magic = MAGIC_SCHANNEL;
@@ -223,12 +248,11 @@ glk_schannel_create_ext(glui32 rock, glui32 volume)
gst_object_unref(bus);
/* Create GStreamer elements to put in the pipeline */
- s->source = gst_element_factory_make("giostreamsrc", NULL);
s->typefind = gst_element_factory_make("typefind", NULL);
s->convert = gst_element_factory_make("audioconvert", NULL);
s->filter = gst_element_factory_make("volume", NULL);
s->sink = gst_element_factory_make("autoaudiosink", NULL);
- if(!s->source || !s->typefind || !s->convert || !s->filter || !s->sink) {
+ if(!s->typefind || !s->convert || !s->filter || !s->sink) {
WARNING(_("Could not create one or more GStreamer elements"));
goto fail;
}
@@ -238,9 +262,10 @@ glk_schannel_create_ext(glui32 rock, glui32 volume)
/* Put the elements in the pipeline and link as many together as we can
without knowing the type of the audio stream */
- gst_bin_add_many(GST_BIN(s->pipeline), s->source, s->typefind, s->convert, s->filter, s->sink, NULL);
- /* Link elements: Source -> typefinder -> ??? -> Converter -> Volume filter -> Sink */
- if(!gst_element_link(s->source, s->typefind) || !gst_element_link_many(s->convert, s->filter, s->sink, NULL)) {
+ gst_bin_add_many(GST_BIN(s->pipeline), s->typefind, s->convert, s->filter, s->sink, NULL);
+
+ /* Link elements: ??? -> Converter -> Volume filter -> Sink */
+ if(!gst_element_link_many(s->convert, s->filter, s->sink, NULL)) {
WARNING(_("Could not link GStreamer elements"));
goto fail;
}
@@ -269,7 +294,7 @@ glk_schannel_destroy(schanid_t chan)
VALID_SCHANNEL(chan, return);
#ifdef GSTREAMER_SOUND
- ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+ ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
if(!gst_element_set_state(chan->pipeline, GST_STATE_NULL))
WARNING_S(_("Could not set GstElement state to"), "NULL");
@@ -311,7 +336,7 @@ glk_schannel_iterate(schanid_t chan, glui32 *rockptr)
VALID_SCHANNEL_OR_NULL(chan, return NULL);
#ifdef GSTREAMER_SOUND
- ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+ ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
GList *retnode;
if(chan == NULL)
@@ -402,9 +427,14 @@ glk_schannel_play(schanid_t chan, glui32 snd)
* 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 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.
*
* Returns: 1 on success, 0 on failure.
*/
@@ -413,7 +443,7 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
{
VALID_SCHANNEL(chan, return 0);
#ifdef GSTREAMER_SOUND
- ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+ ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
GInputStream *stream;
/* Stop the previous sound */
@@ -458,15 +488,24 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
stream = g_memory_input_stream_new_from_data(resource.data.ptr, resource.length, NULL);
}
+ chan->source = gst_element_factory_make("giostreamsrc", NULL);
+ g_object_set(chan->source, "stream", stream, NULL);
+ g_object_unref(stream); /* Now owned by GStreamer element */
+ gst_bin_add(GST_BIN(chan->pipeline), chan->source);
+ if(!gst_element_link(chan->source, chan->typefind)) {
+ WARNING(_("Could not link GStreamer elements"));
+ clean_up_after_playing_sound(chan);
+ return 0;
+ }
+
chan->repeats = repeats;
chan->resource = snd;
chan->notify = notify;
- g_object_set(chan->source, "stream", stream, NULL);
- g_object_unref(stream); /* Now owned by GStreamer element */
/* Play the sound; unless the channel is paused, then pause it instead */
if(!gst_element_set_state(chan->pipeline, chan->paused? GST_STATE_PAUSED : GST_STATE_PLAYING)) {
WARNING_S(_("Could not set GstElement state to"), chan->paused? "PAUSED" : "PLAYING");
+ clean_up_after_playing_sound(chan);
return 0;
}
return 1;
@@ -482,8 +521,6 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
* @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
@@ -496,6 +533,11 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
* a number from 0 to @soundcount.)
*
*
+ * 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.
+ *
+ *
* 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.
@@ -515,7 +557,7 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
VALID_SCHANNEL(chanarray[count], return 0);
#ifdef GSTREAMER_SOUND
- ChimaraGlkPrivate *glk_data = g_private_get(glk_data_key);
+ ChimaraGlkPrivate *glk_data = g_private_get(&glk_data_key);
GInputStream *stream;
if(!glk_data->resource_map && !glk_data->resource_load_callback) {
@@ -563,11 +605,18 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
stream = g_memory_input_stream_new_from_data(resource.data.ptr, resource.length, NULL);
}
+ chanarray[count]->source = gst_element_factory_make("giostreamsrc", NULL);
+ g_object_set(chanarray[count]->source, "stream", stream, NULL);
+ g_object_unref(stream); /* Now owned by GStreamer element */
+ gst_bin_add(GST_BIN(chanarray[count]->pipeline), chanarray[count]->source);
+ if(!gst_element_link(chanarray[count]->source, chanarray[count]->typefind)) {
+ WARNING(_("Could not link GStreamer elements"));
+ clean_up_after_playing_sound(chanarray[count]);
+ }
+
chanarray[count]->repeats = 1;
chanarray[count]->resource = sndarray[count];
chanarray[count]->notify = notify;
- g_object_set(chanarray[count]->source, "stream", stream, NULL);
- g_object_unref(stream); /* Now owned by GStreamer element */
}
/* Start all the sounds as close to each other as possible. */
@@ -580,6 +629,7 @@ glk_schannel_play_multi(schanid_t *chanarray, glui32 chancount, glui32 *sndarray
if(!gst_element_set_state(chanarray[count]->pipeline, chanarray[count]->paused? GST_STATE_PAUSED : GST_STATE_PLAYING)) {
WARNING_S(_("Could not set GstElement state to"), chanarray[count]->paused? "PAUSED" : "PLAYING");
skiparray[count] = TRUE;
+ clean_up_after_playing_sound(chanarray[count]);
continue;
}
successes++;
@@ -610,9 +660,7 @@ glk_schannel_stop(schanid_t chan)
/**
* 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.
*
@@ -649,11 +697,16 @@ glk_schannel_pause(schanid_t chan)
/**
* 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.
+ *
+ *
+ * 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.
+ *
*/
void
glk_schannel_unpause(schanid_t chan)
@@ -685,19 +738,20 @@ 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.
+ *
+ * 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. The
- * effect is immediate.
+ * 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