Added draft docs for new functions and gestalt selectors

[projects/chimara/chimara.git] / libchimara / schannel.c

diff --git a/libchimara/schannel.c b/libchimara/schannel.c
index 373a9afa65aa9aa3a3e54b7ea733b25dbe827817..10057789ed052d556f40e052c6b619c70b97125b 100644 (file)
--- a/libchimara/schannel.c
+++ b/libchimara/schannel.c
@@ -463,8 +463,9 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
        g_object_set(chan->source, "stream", stream, NULL);
        g_object_unref(stream); /* Now owned by GStreamer element */
        
-       if(!gst_element_set_state(chan->pipeline, GST_STATE_PLAYING)) {
-               WARNING_S(_("Could not set GstElement state to"), "PLAYING");
+       /* 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");
                return 0;
        }
        return 1;
@@ -475,11 +476,11 @@ glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
 
 /**
  * glk_schannel_play_multi:
- * @chanarray:
- * @chancount:
- * @sndarray:
- * @soundcount:
- * @notify:
+ * @chanarray: Array of #schanid_t structures.
+ * @chancount: Length of @chanarray.
+ * @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]
  *
@@ -553,6 +554,10 @@ glk_schannel_pause(schanid_t chan)
 
        if(chan->paused)
                return; /* Silently do nothing */
+
+       /* Mark the channel as paused even if there is no sound playing yet */
+       chan->paused = TRUE;
+
        GstState state;
        if(gst_element_get_state(chan->pipeline, &state, NULL, GST_CLOCK_TIME_NONE) != GST_STATE_CHANGE_SUCCESS) {
                WARNING(_("Could not get GstElement state"));
@@ -565,7 +570,6 @@ glk_schannel_pause(schanid_t chan)
                WARNING_S(_("Could not set GstElement state to"), "PAUSED");
                return;
        }
-       chan->paused = TRUE;
 }
 
 /**
@@ -585,6 +589,9 @@ glk_schannel_unpause(schanid_t chan)
        if(!chan->paused)
                return; /* Silently do nothing */
 
+       /* Mark the channel as not paused in any case */
+       chan->paused = FALSE;
+
        GstState state;
        if(gst_element_get_state(chan->pipeline, &state, NULL, GST_CLOCK_TIME_NONE) != GST_STATE_CHANGE_SUCCESS) {
                WARNING(_("Could not get GstElement state"));
@@ -597,7 +604,6 @@ glk_schannel_unpause(schanid_t chan)
                WARNING_S(_("Could not set GstElement state to"), "PLAYING");
                return;
        }
-       chan->paused = FALSE;
 }
 
 /**
@@ -669,7 +675,7 @@ glk_schannel_set_volume(schanid_t chan, glui32 vol)
  * 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 thse functions. You should test the appropriate
+ * Not all libraries support these functions. You should test the appropriate
  * gestalt selectors before you rely on them; see "Testing for Sound
  * Capabilities".
  */