From: Philip Chimento Date: Thu, 7 Jul 2011 22:08:51 +0000 (+0200) Subject: Added draft docs for new functions and gestalt selectors X-Git-Tag: v0.9~47^2~7 X-Git-Url: https://git.stderr.nl/gitweb?a=commitdiff_plain;h=9b633ba807c15f0120cbb8c23a40dbf7cabd4d68;p=projects%2Fchimara%2Fchimara.git Added draft docs for new functions and gestalt selectors --- diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml index 43dbffa..c98d874 100644 --- a/docs/reference/chimara-docs.sgml +++ b/docs/reference/chimara-docs.sgml @@ -105,7 +105,7 @@ - + Sound diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index 6952d18..74e9e6a 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -130,6 +130,7 @@ gestalt_MouseInput gestalt_Timer gestalt_Graphics gestalt_DrawImage +gestalt_Sound2 gestalt_Sound gestalt_SoundVolume gestalt_SoundNotify @@ -494,6 +495,7 @@ GLK_MODULE_IMAGE glk-sound-channels Creating and Destroying Sound Channels glk_schannel_create +glk_schannel_create_ext glk_schannel_destroy @@ -502,8 +504,12 @@ glk_schannel_destroy Playing Sounds glk_schannel_play glk_schannel_play_ext +glk_schannel_play_multi glk_schannel_stop +glk_schannel_pause +glk_schannel_unpause glk_schannel_set_volume +glk_schannel_set_volume_ext glk_sound_load_hint @@ -518,6 +524,7 @@ glk_schannel_get_rock glk-sound-testing Testing for Sound Capabilities GLK_MODULE_SOUND +GLK_MODULE_SOUND2
diff --git a/libchimara/doc.c b/libchimara/doc.c index 4b0a273..f058e27 100644 --- a/libchimara/doc.c +++ b/libchimara/doc.c @@ -1045,10 +1045,15 @@ * SECTION:glk-sound-testing * @short_description: Checking whether the library supports sound * - * 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. + * Before calling Glk sound functions, you should use the %gestalt_Sound2 + * selector. + * + * Earlier versions of the Glk spec defined separate selectors for various + * optional capabilities. This has proven to be an unnecessarily confusing + * strategy, and is no longer used. The %gestalt_Sound, %gestalt_SoundMusic, + * %gestalt_SoundVolume, and %gestalt_SoundNotify selectors still exist, but you + * should not need to test them; the %gestalt_Sound2 selector covers all of + * them. */ /** @@ -1577,10 +1582,24 @@ * may implement both, neither, or only one. */ +/** + * gestalt_Sound2: + * + * You can test whether the library supports sound: + * |[ + * glui32 res; + * res = glk_gestalt(gestalt_Sound2, 0); + * ]| + * This returns 1 if the overall suite of sound functions is available. This + * includes all the functions defined in this chapter. It also includes the + * capabilities described below under %gestalt_SoundMusic, %gestalt_SoundVolume, + * and %gestalt_SoundNotify. + */ + /** * gestalt_Sound: * - * You can test whether the library supports sound: * |[ * glui32 res; * res = glk_gestalt(gestalt_Sound, 0); @@ -1592,7 +1611,7 @@ * 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. + * may have no effect, or they may cause a run-time error. */ /** @@ -1605,7 +1624,7 @@ * 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. + * it returns zero, glk_schannel_set_volume() has no effect. */ /** @@ -1617,7 +1636,7 @@ * 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. + * it returns zero, you will never get such events. */ /** diff --git a/libchimara/schannel.c b/libchimara/schannel.c index 38561dc..1005778 100644 --- a/libchimara/schannel.c +++ b/libchimara/schannel.c @@ -476,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] *