X-Git-Url: https://git.stderr.nl/gitweb?p=rodin%2Fchimara.git;a=blobdiff_plain;f=libchimara%2Fdoc.c;h=3fd18ca0f55778eb8c719b9a28fc5bcc2bd337b8;hp=2e61ee457d310601d0ce202a606244e1c48966c0;hb=7e3ce2d0110b47a67b04a457d1ea215ce1bf1078;hpb=c6e78c57fc1b323ec055bfe48c7430515be27d1c 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