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>