Documented all planned Glk API functions

git-svn-id: http://lassie.dyndns-server.com/svn/gargoyle-gtk@247 ddfedd41-794f-dd11-ae45-00112f111e67

diff --git a/docs/reference/Makefile.am b/docs/reference/Makefile.am
index ac9181d8b6a0352bbbf85263a36efa4d001b56f4..1c393a685eea48ecd091fd1309cb0c33e150149c 100644 (file)
--- a/docs/reference/Makefile.am
+++ b/docs/reference/Makefile.am
@@ -92,6 +92,7 @@ content_files = version.xml \
        glk-window-arrangement.sgml \
        glk-display-style.sgml \
        glk-other-events.sgml \
        glk-window-arrangement.sgml \
        glk-display-style.sgml \
        glk-other-events.sgml \

+       glk-sound-resources.sgml \

        glk-porting.sgml \
        dispatch.sgml \
        blorb.sgml \
        glk-porting.sgml \
        dispatch.sgml \
        blorb.sgml \

diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml
index eebc66cd09ccc9e3ec3eeb8a33a4ce53f4a2eea1..1cec326a3a6d75878fc42c5c9072fa298b0939d8 100644 (file)
--- a/docs/reference/chimara-docs.sgml
+++ b/docs/reference/chimara-docs.sgml
@@ -6,11 +6,7 @@
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>Chimara Reference Manual</title>
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>Chimara Reference Manual</title>

-    <releaseinfo>
-      for Chimara &version;. The latest version of this documentation can be 
-      found on-line at <ulink role="online-location" 
-      url="http://[SERVER]/chimara/index.html">http://[SERVER]/chimara/</ulink>.
-    </releaseinfo>
+    <releaseinfo>for Chimara &version;</releaseinfo>

   </bookinfo>
 
   <reference>
   </bookinfo>
 
   <reference>


@@ -107,14 +103,15 @@
     </chapter>
     
     <!-- Chapter 8. Sound -->
     </chapter>
     
     <!-- Chapter 8. Sound -->

-<!--    <chapter>
+    <chapter>

       <title>Sound</title>
       <title>Sound</title>

+      <xi:include href="glk-sound-resources.sgml"/>

       <xi:include href="xml/glk-sound-channels.xml"/>
       <xi:include href="xml/glk-playing-sounds.xml"/>
       <xi:include href="xml/glk-sound-other.xml"/>
       <xi:include href="xml/glk-sound-testing.xml"/>
     </chapter>
       <xi:include href="xml/glk-sound-channels.xml"/>
       <xi:include href="xml/glk-playing-sounds.xml"/>
       <xi:include href="xml/glk-sound-other.xml"/>
       <xi:include href="xml/glk-sound-testing.xml"/>
     </chapter>

--->    
+    

     <!-- Chapter 9. Hyperlinks -->
     <chapter>
       <title>Hyperlinks</title>
     <!-- Chapter 9. Hyperlinks -->
     <chapter>
       <title>Hyperlinks</title>


@@ -150,6 +147,7 @@
      <title>Glk Extensions</title>
      <xi:include href="xml/glkext-startup.xml"/>
      <xi:include href="xml/glkext-unix.xml"/>
      <title>Glk Extensions</title>
      <xi:include href="xml/glkext-startup.xml"/>
      <xi:include href="xml/glkext-unix.xml"/>

+     <xi:include href="xml/glkext-garglk.xml"/>

     </appendix>
   </reference>
 </book>
     </appendix>
   </reference>
 </book>

diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt
index 3756d5a077245bbfe6e45352744a8184cfd9501f..7f4075dd393fc26208c685c75c36f6eda38ed741 100644 (file)
--- a/docs/reference/chimara-sections.txt
+++ b/docs/reference/chimara-sections.txt
@@ -95,21 +95,16 @@ schanid_t
 <TITLE>The Gestalt System</TITLE>
 glk_gestalt_ext
 glk_gestalt
 <TITLE>The Gestalt System</TITLE>
 glk_gestalt_ext
 glk_gestalt

-<SUBSECTION The Version Number>
+<SUBSECTION Constants>

 gestalt_Version
 gestalt_Version

-<SUBSECTION Testing for Unicode Capabilities>

 gestalt_Unicode
 GLK_MODULE_UNICODE
 gestalt_Unicode
 GLK_MODULE_UNICODE

-<SUBSECTION Output>

 gestalt_CharOutput
 gestalt_CharOutput_CannotPrint
 gestalt_CharOutput_ApproxPrint
 gestalt_CharOutput_ExactPrint
 gestalt_CharOutput
 gestalt_CharOutput_CannotPrint
 gestalt_CharOutput_ApproxPrint
 gestalt_CharOutput_ExactPrint

-<SUBSECTION Line Input>

 gestalt_LineInput
 gestalt_LineInput

-<SUBSECTION Character Input>

 gestalt_CharInput
 gestalt_CharInput

-<SUBSECTION Constants>

 gestalt_MouseInput
 gestalt_Timer
 gestalt_Graphics
 gestalt_MouseInput
 gestalt_Timer
 gestalt_Graphics


@@ -151,6 +146,7 @@ keycode_Func9
 keycode_Func10
 keycode_Func11
 keycode_Func12
 keycode_Func10
 keycode_Func11
 keycode_Func12

+<SUBSECTION Private>

 keycode_MAXVAL
 </SECTION>
 
 keycode_MAXVAL
 </SECTION>
 


@@ -172,11 +168,12 @@ winmethod_Left
 winmethod_Right
 winmethod_Above
 winmethod_Below
 winmethod_Right
 winmethod_Above
 winmethod_Below

-winmethod_DirMask

 winmethod_Fixed
 winmethod_Proportional
 winmethod_Fixed
 winmethod_Proportional

-winmethod_DivisionMask

 glk_window_close
 glk_window_close

+<SUBSECTION Private>
+winmethod_DirMask
+winmethod_DivisionMask

 </SECTION>
 
 <SECTION>
 </SECTION>
 
 <SECTION>


@@ -342,6 +339,7 @@ style_BlockQuote
 style_Input
 style_User1
 style_User2
 style_Input
 style_User1
 style_User2

+<SUBSECTION Private>

 style_NUMSTYLES
 </SECTION>
 
 style_NUMSTYLES
 </SECTION>
 


@@ -361,11 +359,12 @@ stylehint_Proportional
 stylehint_TextColor
 stylehint_BackColor
 stylehint_ReverseColor
 stylehint_TextColor
 stylehint_BackColor
 stylehint_ReverseColor

-stylehint_NUMHINTS

 stylehint_just_LeftFlush
 stylehint_just_LeftRight
 stylehint_just_Centered
 stylehint_just_RightFlush
 stylehint_just_LeftFlush
 stylehint_just_LeftRight
 stylehint_just_Centered
 stylehint_just_RightFlush

+<SUBSECTION Private>
+stylehint_NUMHINTS

 </SECTION>
 
 <SECTION>
 </SECTION>
 
 <SECTION>


@@ -398,9 +397,10 @@ fileusage_Data
 fileusage_SavedGame
 fileusage_Transcript
 fileusage_InputRecord
 fileusage_SavedGame
 fileusage_Transcript
 fileusage_InputRecord

-fileusage_TypeMask

 fileusage_TextMode
 fileusage_BinaryMode
 fileusage_TextMode
 fileusage_BinaryMode

+<SUBSECTION Private>
+fileusage_TypeMask

 </SECTION>
 
 <SECTION>
 </SECTION>
 
 <SECTION>


@@ -619,5 +619,5 @@ glkunix_set_base_file
 <SECTION>
 <FILE>glkext-garglk</FILE>
 <TITLE>Gargoyle Extensions</TITLE>
 <SECTION>
 <FILE>glkext-garglk</FILE>
 <TITLE>Gargoyle Extensions</TITLE>

-garglk_set_reverse_video
+garglk_set_reversevideo

 </SECTION>
\ No newline at end of file
 </SECTION>
\ No newline at end of file

diff --git a/libchimara/doc.c b/libchimara/doc.c
index 2e61ee457d310601d0ce202a606244e1c48966c0..3fd18ca0f55778eb8c719b9a28fc5bcc2bd337b8 100644 (file)
--- a/libchimara/doc.c
+++ b/libchimara/doc.c
@@ -1003,6 +1003,24 @@
  * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
  * window, @val1 gives the image alignment. The @val2 argument is currently
  * unused, and should always be zero.
  * If you call glk_image_draw() or glk_image_draw_scaled() in a text buffer
  * window, @val1 gives the image alignment. The @val2 argument is currently
  * unused, and should always be zero.

+ *
+ * The two <quote>margin</quote> alignments require some care. To allow proper 
+ * positioning, images using %imagealign_MarginLeft and %imagealign_MarginRight 
+ * must be placed at the beginning of a line. That is, you may only call 
+ * glk_image_draw() (with these two alignments) in a window, if you have just 
+ * printed a newline to the window's stream, or if the window is entirely empty.
+ * If you margin-align an image in a line where text has already appeared, no 
+ * image will appear at all.
+ * 
+ * Inline-aligned images count as <quote>text</quote> for the purpose of this 
+ * rule.
+ * 
+ * You may have images in both margins at the same time.
+ * 
+ * It is also legal to have more than one image in the same margin (left or 
+ * right.) However, this is not recommended. It is difficult to predict how text
+ * will wrap in that situation, and libraries may err on the side of 
+ * conservatism. 

  */
 
 /**
  */
 
 /**


@@ -1014,7 +1032,36 @@
  * %gestalt_Graphics. To test for additional capabilities, you can also use the
  * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors.
  */
  * %gestalt_Graphics. To test for additional capabilities, you can also use the
  * %gestalt_DrawImage and %gestalt_GraphicsTransparency selectors.
  */

- 
+
+/**
+ * SECTION:glk-sound-channels
+ * @short_description: Creating new sound channels and closing them
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-playing-sounds
+ * @short_description: Producing noise
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-sound-other
+ * @short_description: Miscellaneous functions for sound channels
+ * @include: libchimara/glk.h
+ */
+
+/**
+ * SECTION:glk-sound-testing
+ * @short_description: Checking whether the library supports sound
+ * @include: libchimara/glk.h
+ *
+ * Before calling Glk sound functions, you should use the %gestalt_Sound
+ * selector. To test for additional capabilities, you can use the 
+ * %gestalt_SoundMusic, %gestalt_SoundVolume, and %gestalt_SoundNotify 
+ * selectors.
+ */
+

 /**
  * SECTION:glk-creating-hyperlinks
  * @short_description: Printing text as a hyperlink
 /**
  * SECTION:glk-creating-hyperlinks
  * @short_description: Printing text as a hyperlink


@@ -1232,6 +1279,21 @@
  *   sufficient.
  * </para></note>
  */
  *   sufficient.
  * </para></note>
  */

+
+/**
+ * GLK_MODULE_SOUND:
+ *
+ * If you are writing a C program, there is an additional complication. A 
+ * library which does not support sound may not implement the sound functions at
+ * all. Even if you put gestalt tests around your sound calls, you may get 
+ * link-time errors. If the <filename class="headerfile">glk.h</filename> file 
+ * is so old that it does not declare the sound functions and constants, you may
+ * even get compile-time errors.
+ * 
+ * To avoid this, you can perform a preprocessor test for the existence of
+ * %GLK_MODULE_SOUND. If this is defined, so are all the functions and constants
+ * described in this section. If not, not.
+ */ 

  
 /**
  * GLK_MODULE_HYPERLINKS:
  
 /**
  * GLK_MODULE_HYPERLINKS:


@@ -1262,6 +1324,13 @@
  * members.
  */
 
  * members.
  */
 

+/**
+ * schanid_t:
+ * 
+ * Opaque structure representing a sound channel. It has no user-accessible
+ * members.
+ */
+  

 /**
  * gestalt_Version:
  *
 /**
  * gestalt_Version:
  *


@@ -1448,7 +1517,50 @@
  * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries 
  * may implement both, neither, or only one.  
  */
  * test %wintype_Graphics and %wintype_TextBuffer separately, since libraries 
  * may implement both, neither, or only one.  
  */

- 
+
+/**
+ * gestalt_Sound:
+ *
+ * You can test whether the library supports sound: 
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_Sound, 0);
+ * ]|
+ * This returns 1 if the overall suite of sound functions is available. This 
+ * includes glk_schannel_create(), glk_schannel_destroy(), 
+ * glk_schannel_iterate(), glk_schannel_get_rock(), glk_schannel_play(),
+ * glk_schannel_play_ext(), glk_schannel_stop(), glk_schannel_set_volume(), and
+ * glk_sound_load_hint().
+ *
+ * If this selector returns 0, you should not try to call these functions. They 
+ * may have no effect, or they may cause a run-time error. 
+ */
+
+/**
+ * gestalt_SoundVolume:
+ *
+ * You can test whether the library supports setting the volume of sound 
+ * channels: 
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_SoundVolume, 0);
+ * ]|
+ * This selector returns 1 if the glk_schannel_set_volume() function works. If 
+ * it returns zero, glk_schannel_set_volume() has no effect.     
+ */
+
+/**
+ * gestalt_SoundNotify:
+ *
+ * You can test whether the library supports sound notification events:
+ * |[
+ * glui32 res;
+ * res = glk_gestalt(gestalt_SoundNotify, 0);
+ * ]| 
+ * This selector returns 1 if the library supports sound notification events. If
+ * it returns zero, you will never get such events. 
+ */
+

 /**
  * gestalt_Hyperlinks:
  *
 /**
  * gestalt_Hyperlinks:
  *


@@ -1477,6 +1589,21 @@
  * never get hyperlink events.
  */
 
  * never get hyperlink events.
  */
 

+/** 
+ * gestalt_SoundMusic:
+ *
+ * You can test whether music resources are supported:
+ * |[ res = glk_gestalt(gestalt_SoundMusic, 0); ]|
+ * This returns 1 if the library is capable of playing music sound resources. If 
+ * it returns 0, only sampled sounds can be played.
+ * <note><para>
+ *   <quote>Music sound resources</quote> means MOD songs &mdash; the only music
+ *   format that Blorb currently supports. The presence of this selector is, of 
+ *   course, an ugly hack. It is a concession to the current state of the Glk 
+ *   libraries, some of which can handle AIFF but not MOD sounds.
+ * </para></note>
+ */ 
+  

 /**
  * gestalt_GraphicsTransparency:
  *
 /**
  * gestalt_GraphicsTransparency:
  *


@@ -1860,18 +1987,6 @@
  * Represents the <keycap>F12</keycap> key.
  */
 
  * Represents the <keycap>F12</keycap> key.
  */
 

-/**
- * keycode_MAXVAL:
- *
- * This value is equal to the number of special keycodes. The last keycode is
- * always 
- * <inlineequation>
- *   <alt>(0x100000000 - <code><keysym>keycode_MAXVAL</keysym></code>)</alt>
- *   <mathphrase>(0x100000000 - <code><keysym>keycode_MAXVAL</keysym></code>)</mathphrase>
- * </inlineequation>
- * .
- */
-

 /**
  * style_Normal: 
  *
 /**
  * style_Normal: 
  *


@@ -1957,12 +2072,6 @@
  *
  * Another style available for your use. 
  */
  *
  * Another style available for your use. 
  */

- 
-/**
- * style_NUMSTYLES:
- * 
- * The number of styles defined in this library.
- */

 
 /**
  * stream_result_t:
 
 /**
  * stream_result_t:


@@ -2252,14 +2361,6 @@
  * When calling glk_window_open() with this @method, the new window will be 
  * below the old one which was split.
  */
  * When calling glk_window_open() with this @method, the new window will be 
  * below the old one which was split.
  */

-
-/**
- * winmethod_DirMask:
- *
- * Bitwise AND this value with a window splitting method argument to find
- * whether the split is %winmethod_Left, %winmethod_Right, %winmethod_Above, or
- * %winmethod_Below.
- */

  
 /**
  * winmethod_Fixed:
  
 /**
  * winmethod_Fixed:


@@ -2275,13 +2376,6 @@
  * a given proportion of the old window's size. (See glk_window_open()).
  */
  
  * a given proportion of the old window's size. (See glk_window_open()).
  */
  

-/**
- * winmethod_DivisionMask:
- *
- * Bitwise AND this value with a window splitting method argument to find
- * whether the new window has %winmethod_Fixed or %winmethod_Proportional.
- */
- 

 /** 
  * fileusage_Data: 
  *
 /** 
  * fileusage_Data: 
  *


@@ -2498,12 +2592,6 @@
  *  others may support both, or neither.
  * </para></note>
  */
  *  others may support both, or neither.
  * </para></note>
  */

-
-/**
- * stylehint_NUMHINTS:
- *
- * The number of style hints defined in this library.
- */ 

  
 /**
  * stylehint_just_LeftFlush:
  
 /**
  * stylehint_just_LeftFlush:


@@ -2550,6 +2638,25 @@
  * and baseline of the line of text. If the image is taller than the line of
  * text, it will stick up and down equally.
  */
  * and baseline of the line of text. If the image is taller than the line of
  * text, it will stick up and down equally.
  */

+
+/**
+ * imagealign_MarginLeft:
+ * 
+ * The image appears in the left margin. Subsequent text will be displayed to
+ * the right of the image, and will flow around it &mdash; that is, it will be
+ * left-indented for as many lines as it takes to pass the image.
+ *
+ * <warning><para>Margin images are not implemented yet.</para></warning>
+ */
+
+/**
+ * imagealign_MarginRight:
+ *
+ * The image appears in the right margin, and subsequent text will flow around
+ * it on the left.
+ *
+ * <warning><para>Margin images are not implemented yet.</para></warning>
+ */

  
 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
 
  
 /*---------- TYPES, FUNCTIONS AND CONSTANTS FROM GI_DISPA.H ------------------*/
 


@@ -3131,7 +3238,7 @@
  */
 
 /**
  */
 
 /**

- * giblorb_method_DontLoad:
+ * giblorb_method_FilePos:

  *
  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
  * giblorb_load_resource() to get the position in the Blorb file at which the
  *
  * Pass this to giblorb_load_chunk_by_type(), giblorb_load_chunk_by_number(), or
  * giblorb_load_resource() to get the position in the Blorb file at which the

diff --git a/libchimara/graphics.c b/libchimara/graphics.c
index abcab4a4a07e58344d54754c28d17ed5b6ef1078..c87a148390aa0dc05fdd17a7114ac1ca6aa883e4 100644 (file)
--- a/libchimara/graphics.c
+++ b/libchimara/graphics.c
@@ -481,8 +481,46 @@ glk_window_erase_rect(winid_t win, glsi32 left, glsi32 top, glui32 width, glui32
        glk_window_fill_rect(win, win->background_color, left, top, width, height);
 }
 
        glk_window_fill_rect(win, win->background_color, left, top, width, height);
 }
 

+/**
+ * glk_window_flow_break:
+ * @win: A window.
+ *
+ * You may wish to <quote>break</quote> the stream of text down below the 
+ * current margin image. Since lines of text can be in any font and size, you 
+ * cannot do this by counting newlines. Instead, use this function.
+ *
+ * If the current point in the text is indented around a margin-aligned image, 
+ * this acts like the correct number of newlines to start a new line below the 
+ * image. (If there are several margin-aligned images, it goes below all of 
+ * them.) If the current point is not beside a margin-aligned image, this call 
+ * has no effect.
+ *
+ * When a text buffer window is resized, a flow-break behaves cleverly; it may 
+ * become active or inactive as necessary. You can consider this function to 
+ * insert an invisible mark in the text stream. The mark works out how many 
+ * newlines it needs to be whenever the text is formatted for display.
+ * 
+ * An example of the use of glk_window_flow_break(): If you display a 
+ * left-margin image at the start of every line, they can stack up in a strange 
+ * diagonal way that eventually squeezes all the text off the screen. 
+ * <note><para>
+ *   If you can't picture this, draw some diagrams. Make the margin images more 
+ *   than one line tall, so that each line starts already indented around the 
+ *   last image.
+ * </para></note>
+ * To avoid this problem, call glk_window_flow_break() immediately before 
+ * glk_image_draw() for every margin-aligned image.
+ * 
+ * In all windows other than text buffers, glk_window_flow_break() has no 
+ * effect. 
+ *
+ * <warning><para>
+ *   This function is not implemented yet.
+ * </para></warning>
+ */

 void glk_window_flow_break(winid_t win)
 {
 void glk_window_flow_break(winid_t win)
 {

+       VALID_WINDOW(win, return);

 }
 
 /*** Called when the graphics window is resized. Resize the backing pixmap if necessary ***/
 }
 
 /*** Called when the graphics window is resized. Resize the backing pixmap if necessary ***/

diff --git a/libchimara/schannel.c b/libchimara/schannel.c
index 918dbfa871937bba77b5bc33c756cf01a7bea81f..c9911480b988aae8af9772ee95fd1b17f0dc3e8d 100644 (file)
--- a/libchimara/schannel.c
+++ b/libchimara/schannel.c
@@ -1,51 +1,218 @@
 #include <glib.h>
 #include <libchimara/glk.h>
 
 #include <glib.h>
 #include <libchimara/glk.h>
 

+/**
+ * glk_schannel_create:
+ * @rock: The rock value to give the new sound channel.
+ *
+ * This creates a sound channel, about as you'd expect.
+ *
+ * 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.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ *
+ * Returns: A new sound channel, or %NULL.
+ */

 schanid_t 
 glk_schannel_create(glui32 rock)
 {
        return NULL;
 }
 
 schanid_t 
 glk_schannel_create(glui32 rock)
 {
        return NULL;
 }
 

+/**
+ * glk_schannel_destroy:
+ * @chan: The sound channel to destroy.
+ *
+ * Destroys the channel. If the channel is playing a sound, the sound stops 
+ * immediately (with no notification event).
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ */

 void 
 glk_schannel_destroy(schanid_t chan)
 {
 void 
 glk_schannel_destroy(schanid_t chan)
 {

+       VALID_SCHANNEL(chan, return);

 }
 
 }
 

+/**
+ * glk_schannel_iterate:
+ * @chan: A sound channel, or %NULL.
+ * @rockptr: Return location for the next sound channel's rock, or %NULL.
+ *
+ * This function can be used to iterate through the list of all open channels.
+ * See <link linkend="chimara-Iterating-Through-Opaque-Objects">Iterating 
+ * Through Opaque Objects</link>.
+ *
+ * As that section describes, the order in which channels are returned is 
+ * arbitrary.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ *
+ * Returns: the next sound channel, or %NULL if there are no more.
+ */

 schanid_t 
 glk_schannel_iterate(schanid_t chan, glui32 *rockptr)
 {
 schanid_t 
 glk_schannel_iterate(schanid_t chan, glui32 *rockptr)
 {

+       VALID_SCHANNEL_OR_NULL(chan, return NULL);

        return NULL;
 }
 
        return NULL;
 }
 

+/**
+ * glk_schannel_get_rock:
+ * @chan: A sound channel.
+ * 
+ * Retrieves the channel's rock value. See <link 
+ * linkend="chimara-Rocks">Rocks</link>.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ *
+ * Returns: A rock value.
+ */

 glui32 
 glk_schannel_get_rock(schanid_t chan)
 {
 glui32 
 glk_schannel_get_rock(schanid_t chan)
 {

+       VALID_SCHANNEL(chan, return 0);

        return 0;
 }
 
        return 0;
 }
 

+/**
+ * glk_schannel_play:
+ * @chan: Channel to play the sound in.
+ * @snd: Resource number of the sound to play.
+ *
+ * Begins playing the given sound on the channel. If the channel was already
+ * playing a sound (even the same one), the old sound is stopped (with no
+ * notification event.
+ *
+ * This returns 1 if the sound actually started playing, and 0 if there was any
+ * problem.
+ * <note><para>
+ *   The most obvious problem is if there is no sound resource with the given
+ *   identifier. But other problems can occur. For example, the MOD-playing 
+ *   facility in a library might be unable to handle two MODs at the same time,
+ *   in which case playing a MOD resource would fail if one was already playing.
+ * </para></note>
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ *
+ * Returns: 1 on success, 0 on failure.
+ */

 glui32 
 glk_schannel_play(schanid_t chan, glui32 snd)
 {
 glui32 
 glk_schannel_play(schanid_t chan, glui32 snd)
 {

+       VALID_SCHANNEL(chan, return 0);

        return 0;
 }
 
        return 0;
 }
 

+/**
+ * glk_schannel_play_ext:
+ * @chan: Channel to play the sound in.
+ * @snd: Resource number of the sound to play.
+ * @repeats: Number of times to repeat the sound.
+ * @notify: If nonzero, requests a notification when the sound is finished.
+ *
+ * This works the same as glk_schannel_play(), but lets you specify additional 
+ * options. <code>glk_schannel_play(chan, snd)</code> is exactly equivalent to 
+ * <code>glk_schannel_play_ext(chan, snd, 1, 0)</code>.
+ * 
+ * The @repeats value is the number of times the sound should be repeated. A 
+ * repeat value of -1 (or rather 0xFFFFFFFF) means that the sound should repeat 
+ * forever. A repeat value of 0 means that the sound will not be played at all; 
+ * nothing happens. (Although a previous sound on the channel will be stopped, 
+ * and the function will return 1.)
+ * 
+ * The @notify value should be nonzero in order to request a sound notification
+ * event. If you do this, when the sound is completed, you will get an event 
+ * with type %evtype_SoundNotify. The @window will be %NULL, @val1 will be the 
+ * sound's resource id, and @val2 will be the nonzero value you passed as 
+ * @notify.
+ * 
+ * If you request sound notification, and the repeat value is greater than one, 
+ * you will get the event only after the last repetition. If the repeat value is
+ * 0 or -1, you will never get a notification event at all. Similarly, if the 
+ * sound is stopped or interrupted, or if the channel is destroyed while the 
+ * 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 <link
+ * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound 
+ * Capabilities</link>.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ * 
+ * Returns: 1 on success, 0 on failure.
+ */

 glui32 
 glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
 {
 glui32 
 glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify)
 {

+       VALID_SCHANNEL(chan, return 0);

        return 0;
 }
 
        return 0;
 }
 

+/**
+ * glk_schannel_stop:
+ * @chan: Channel to silence.
+ *
+ * Stops any sound playing in the channel. No notification event is generated,
+ * even if you requested one. If no sound is playing, this has no effect.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ */

 void 
 glk_schannel_stop(schanid_t chan)
 {
 void 
 glk_schannel_stop(schanid_t chan)
 {

+       VALID_SCHANNEL(chan, return);

 }
 
 }
 

+/**
+ * glk_schannel_set_volume:
+ * @chan: Channel to set the volume of.
+ * @vol: Integer representing the volume; 0x10000 is 100&percnt;.
+ *
+ * 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.
+ *
+ * You can call this function between sounds, or while a sound is playing. The 
+ * effect is immediate.
+ * 
+ * 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.
+ *
+ * Not all libraries support this function. You should test the
+ * %gestalt_SoundVolume selector before you rely on it; see <link
+ * linkend="chimara-Testing-for-Sound-Capabilities">Testing for Sound
+ * Capabilities</link>.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ */

 void 
 glk_schannel_set_volume(schanid_t chan, glui32 vol)
 {
 void 
 glk_schannel_set_volume(schanid_t chan, glui32 vol)
 {

+       VALID_SCHANNEL(chan, return);

 }
 
 }
 

-void glk_sound_load_hint(glui32 snd, glui32 flag)
+/**
+ * glk_sound_load_hint:
+ * @snd: Resource number of a sound.
+ * @flag: Nonzero to tell the library to load the sound, zero to tell the
+ * library to unload it.
+ *
+ * This gives the library a hint about whether the given sound should be loaded
+ * or not. If the @flag is nonzero, the library may preload the sound or do
+ * other initialization, so that glk_schannel_play() will be faster. If the
+ * @flag is zero, the library may release memory or other resources associated
+ * with the sound. Calling this function is always optional, and it has no
+ * effect on what the library actually plays.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ */
+void 
+glk_sound_load_hint(glui32 snd, glui32 flag)

 {
 }
 {
 }