From: Philip Chimento Date: Fri, 30 Apr 2010 01:33:24 +0000 (+0000) Subject: Documented all planned Glk API functions X-Git-Url: https://git.stderr.nl/gitweb?p=rodin%2Fchimara.git;a=commitdiff_plain;h=7e3ce2d0110b47a67b04a457d1ea215ce1bf1078 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 ac9181d..1c393a6 100644 --- 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-sound-resources.sgml \ glk-porting.sgml \ dispatch.sgml \ blorb.sgml \ diff --git a/docs/reference/chimara-docs.sgml b/docs/reference/chimara-docs.sgml index eebc66c..1cec326 100644 --- a/docs/reference/chimara-docs.sgml +++ b/docs/reference/chimara-docs.sgml @@ -6,11 +6,7 @@ Chimara Reference Manual - - for Chimara &version;. The latest version of this documentation can be - found on-line at http://[SERVER]/chimara/. - + for Chimara &version; @@ -107,14 +103,15 @@ - + Hyperlinks @@ -150,6 +147,7 @@ Glk Extensions + diff --git a/docs/reference/chimara-sections.txt b/docs/reference/chimara-sections.txt index 3756d5a..7f4075d 100644 --- a/docs/reference/chimara-sections.txt +++ b/docs/reference/chimara-sections.txt @@ -95,21 +95,16 @@ schanid_t The Gestalt System glk_gestalt_ext glk_gestalt - + gestalt_Version - gestalt_Unicode GLK_MODULE_UNICODE - gestalt_CharOutput gestalt_CharOutput_CannotPrint gestalt_CharOutput_ApproxPrint gestalt_CharOutput_ExactPrint - gestalt_LineInput - gestalt_CharInput - gestalt_MouseInput gestalt_Timer gestalt_Graphics @@ -151,6 +146,7 @@ keycode_Func9 keycode_Func10 keycode_Func11 keycode_Func12 + keycode_MAXVAL @@ -172,11 +168,12 @@ winmethod_Left winmethod_Right winmethod_Above winmethod_Below -winmethod_DirMask winmethod_Fixed winmethod_Proportional -winmethod_DivisionMask glk_window_close + +winmethod_DirMask +winmethod_DivisionMask
@@ -342,6 +339,7 @@ style_BlockQuote style_Input style_User1 style_User2 + style_NUMSTYLES
@@ -361,11 +359,12 @@ stylehint_Proportional stylehint_TextColor stylehint_BackColor stylehint_ReverseColor -stylehint_NUMHINTS stylehint_just_LeftFlush stylehint_just_LeftRight stylehint_just_Centered stylehint_just_RightFlush + +stylehint_NUMHINTS
@@ -398,9 +397,10 @@ fileusage_Data fileusage_SavedGame fileusage_Transcript fileusage_InputRecord -fileusage_TypeMask fileusage_TextMode fileusage_BinaryMode + +fileusage_TypeMask
@@ -619,5 +619,5 @@ glkunix_set_base_file
glkext-garglk Gargoyle Extensions -garglk_set_reverse_video +garglk_set_reversevideo
\ No newline at end of file diff --git a/libchimara/doc.c b/libchimara/doc.c index 2e61ee4..3fd18ca 100644 --- 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. + * + * The two margin 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 text 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. */ - + +/** + * 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 @@ -1232,6 +1279,21 @@ * sufficient. * */ + +/** + * 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 glk.h 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: @@ -1262,6 +1324,13 @@ * members. */ +/** + * schanid_t: + * + * Opaque structure representing a sound channel. It has no user-accessible + * members. + */ + /** * gestalt_Version: * @@ -1448,7 +1517,50 @@ * 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: * @@ -1477,6 +1589,21 @@ * 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. + * + * Music sound resources means MOD songs — 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. + * + */ + /** * gestalt_GraphicsTransparency: * @@ -1860,18 +1987,6 @@ * Represents the F12 key. */ -/** - * keycode_MAXVAL: - * - * This value is equal to the number of special keycodes. The last keycode is - * always - * - * (0x100000000 - keycode_MAXVAL) - * (0x100000000 - keycode_MAXVAL) - * - * . - */ - /** * style_Normal: * @@ -1957,12 +2072,6 @@ * * Another style available for your use. */ - -/** - * style_NUMSTYLES: - * - * The number of styles defined in this library. - */ /** * 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. */ - -/** - * 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: @@ -2275,13 +2376,6 @@ * 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: * @@ -2498,12 +2592,6 @@ * others may support both, or neither. * */ - -/** - * stylehint_NUMHINTS: - * - * The number of style hints defined in this library. - */ /** * 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. */ + +/** + * 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 — that is, it will be + * left-indented for as many lines as it takes to pass the image. + * + * Margin images are not implemented yet. + */ + +/** + * imagealign_MarginRight: + * + * The image appears in the right margin, and subsequent text will flow around + * it on the left. + * + * Margin images are not implemented yet. + */ /*---------- 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 diff --git a/libchimara/graphics.c b/libchimara/graphics.c index abcab4a..c87a148 100644 --- 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_flow_break: + * @win: A window. + * + * You may wish to break 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. + * + * 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. + * + * 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. + * + * + * This function is not implemented yet. + * + */ 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 ***/ diff --git a/libchimara/schannel.c b/libchimara/schannel.c index 918dbfa..c991148 100644 --- a/libchimara/schannel.c +++ b/libchimara/schannel.c @@ -1,51 +1,218 @@ #include #include +/** + * 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. + * + * This function is not implemented yet. + * + * Returns: A new sound channel, or %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). + * + * This function is not implemented yet. + */ 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 Iterating + * Through Opaque Objects. + * + * As that section describes, the order in which channels are returned is + * arbitrary. + * + * This function is not implemented yet. + * + * Returns: the next sound channel, or %NULL if there are no more. + */ schanid_t glk_schannel_iterate(schanid_t chan, glui32 *rockptr) { + VALID_SCHANNEL_OR_NULL(chan, return NULL); return NULL; } +/** + * glk_schannel_get_rock: + * @chan: A sound channel. + * + * Retrieves the channel's rock value. See Rocks. + * + * This function is not implemented yet. + * + * Returns: A rock value. + */ glui32 glk_schannel_get_rock(schanid_t chan) { + VALID_SCHANNEL(chan, 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. + * + * 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. + * + * + * This function is not implemented yet. + * + * Returns: 1 on success, 0 on failure. + */ glui32 glk_schannel_play(schanid_t chan, glui32 snd) { + VALID_SCHANNEL(chan, 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. glk_schannel_play(chan, snd) is exactly equivalent to + * glk_schannel_play_ext(chan, snd, 1, 0). + * + * 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 Testing for Sound + * Capabilities. + * + * This function is not implemented yet. + * + * Returns: 1 on success, 0 on failure. + */ glui32 glk_schannel_play_ext(schanid_t chan, glui32 snd, glui32 repeats, glui32 notify) { + VALID_SCHANNEL(chan, 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. + * + * This function is not implemented yet. + */ 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%. + * + * 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 Testing for Sound + * Capabilities. + * + * This function is not implemented yet. + */ 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. + * + * This function is not implemented yet. + */ +void +glk_sound_load_hint(glui32 snd, glui32 flag) { }