Added underscore to prevent marshaller functions from being exported in library
[rodin/chimara.git] / docs / reference / glk-sound-resources.sgml
1 <?xml version="1.0"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4 ]>
5 <refentry id="chimara-Sound-Resources">
6 <refmeta>
7 <refentrytitle>Sound Resources</refentrytitle>
8 <manvolnum>3</manvolnum>
9 <refmiscinfo>CHIMARA Library</refmiscinfo>
10 </refmeta>
11 <refnamediv>
12 <refname>Sound Resources</refname>
13 <refpurpose>Sound in Glk</refpurpose>
14 </refnamediv>
15 <refsect1>
16 <title>Description</title>
17 <para>
18 As with graphics, so with sound. Sounds, however, obviously don't appear in windows. To play a sound in Glk, you must first create a sound channel to hold it. This is an entirely new class of opaque objects; there are <code>create</code> and <code>destroy</code> and <code>iterate</code> and <code>get_rock</code> functions for channels, just as there are for windows and streams and filerefs.
19 </para><para>
20 A channel can be playing exactly one sound at a time. If you want to play more than one sound simultaneously, you need more than one sound channel. On the other hand, a single sound can be played on several channels at the same time, or overlapping itself.
21 </para><para>
22 Sound is an optional capability in Glk.
23 </para><para>
24 As with images, sounds are kept in resources, and your program does not have to worry about the formatting or storage. A resource is referred to by an integer identifier.
25 </para><para>
26 A resource can theoretically contain any kind of sound data, of any length. A resource can even be infinitely long.
27 <note><para>This would be represented by some sound encoding with a built-in repeat-forever flag &mdash; but that is among the details which are hidden from you.
28 </para></note>
29 A resource can also contain two or more channels of sound (stereo data). Do not confuse such in-sound channels with Glk sound channels. A single Glk sound channel suffices to play any sound, even stereo sounds.
30 </para>
31 <note><para>
32 Again, Blorb is the official resource-storage format of Glk. Sounds in Blorb files can be encoded as AIFF, MOD, or MOD song data. See the Blorb specification for details.
33 </para></note>
34 </refsect1>
35 </refentry>