glk-window-arrangement.sgml \
glk-display-style.sgml \
glk-other-events.sgml \
+ glk-sound-resources.sgml \
glk-porting.sgml \
dispatch.sgml \
blorb.sgml \
<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>
</chapter>
<!-- Chapter 8. Sound -->
-<!-- <chapter>
+ <chapter>
<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>
--->
+
<!-- Chapter 9. Hyperlinks -->
<chapter>
<title>Hyperlinks</title>
<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>
<TITLE>The Gestalt System</TITLE>
glk_gestalt_ext
glk_gestalt
-<SUBSECTION The Version Number>
+<SUBSECTION Constants>
gestalt_Version
-<SUBSECTION Testing for Unicode Capabilities>
gestalt_Unicode
GLK_MODULE_UNICODE
-<SUBSECTION Output>
gestalt_CharOutput
gestalt_CharOutput_CannotPrint
gestalt_CharOutput_ApproxPrint
gestalt_CharOutput_ExactPrint
-<SUBSECTION Line Input>
gestalt_LineInput
-<SUBSECTION Character Input>
gestalt_CharInput
-<SUBSECTION Constants>
gestalt_MouseInput
gestalt_Timer
gestalt_Graphics
keycode_Func10
keycode_Func11
keycode_Func12
+<SUBSECTION Private>
keycode_MAXVAL
</SECTION>
winmethod_Right
winmethod_Above
winmethod_Below
-winmethod_DirMask
winmethod_Fixed
winmethod_Proportional
-winmethod_DivisionMask
glk_window_close
+<SUBSECTION Private>
+winmethod_DirMask
+winmethod_DivisionMask
</SECTION>
<SECTION>
style_Input
style_User1
style_User2
+<SUBSECTION Private>
style_NUMSTYLES
</SECTION>
stylehint_TextColor
stylehint_BackColor
stylehint_ReverseColor
-stylehint_NUMHINTS
stylehint_just_LeftFlush
stylehint_just_LeftRight
stylehint_just_Centered
stylehint_just_RightFlush
+<SUBSECTION Private>
+stylehint_NUMHINTS
</SECTION>
<SECTION>
fileusage_SavedGame
fileusage_Transcript
fileusage_InputRecord
-fileusage_TypeMask
fileusage_TextMode
fileusage_BinaryMode
+<SUBSECTION Private>
+fileusage_TypeMask
</SECTION>
<SECTION>
<SECTION>
<FILE>glkext-garglk</FILE>
<TITLE>Gargoyle Extensions</TITLE>
-garglk_set_reverse_video
+garglk_set_reversevideo
</SECTION>
\ No newline at end of file
* 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.
*/
/**
* %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
* 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:
* members.
*/
+/**
+ * schanid_t:
+ *
+ * Opaque structure representing a sound channel. It has no user-accessible
+ * members.
+ */
+
/**
* gestalt_Version:
*
* 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:
*
* 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 — 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:
*
* 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:
*
*
* Another style available for your use.
*/
-
-/**
- * style_NUMSTYLES:
- *
- * The number of styles defined in this library.
- */
/**
* stream_result_t:
* 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:
* 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:
*
* others may support both, or neither.
* </para></note>
*/
-
-/**
- * stylehint_NUMHINTS:
- *
- * The number of style hints defined in this library.
- */
/**
* stylehint_just_LeftFlush:
* 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.
+ *
+ * <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 ------------------*/
*/
/**
- * 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
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)
{
+ VALID_WINDOW(win, return);
}
/*** Called when the graphics window is resized. Resize the backing pixmap if necessary ***/
#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;
}
+/**
+ * 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)
{
+ 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)
{
+ VALID_SCHANNEL_OR_NULL(chan, 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)
{
+ 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.
+ * <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)
{
+ 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. <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)
{
+ 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.
+ *
+ * <warning><para>This function is not implemented yet.</para></warning>
+ */
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 <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)
{
+ 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)
{
}
projects / rodin / chimara.git / commitdiff