docs/reference/blorb.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-The-Blorb-Layer">
   6 <refmeta>
   7 <refentrytitle>The Blorb Layer</refentrytitle>
   8 <manvolnum>3</manvolnum>
   9 <refmiscinfo>CHIMARA Library</refmiscinfo>
  10 </refmeta>
  11 <refnamediv>
  12 <refname>The Blorb Layer</refname>
  13 <refpurpose>Loading resources from a Blorb file</refpurpose>
  14 </refnamediv>
  15 <refsect1>
  16 <title>Description</title>
  17 <para>
  18 The material described in this section is not part of the Glk API per se. It is an external layer which allows the library to load resources (images and sounds) from a file specified by your program. The Blorb file format is a standard IF resource archive.
  19 </para>
  20 <para>
  21 The Glk spec does not require that resources be stored in a Blorb file. It says only that the library knows how to load them and use them, when you so request. However, Blorb is the recommended way to supply portable resources. Most Glk libraries will support Blorb, using the interface defined in this section.
  22 </para>
  23 <para>
  24 The quick summary: resources are identified by type (image, sound, etc) and by an index number.
  25 <note><para>
  26 But not by name.
  27 This is for historical reasons; Infocom's Z-machine architecture used this scheme.
  28 </para></note>
  29 </para>
  30 <para>
  31 For the complete Blorb specification and tools for Blorb file manipulation, see:
  32 <ulink role="online-location" url="http://www.eblong.com/zarf/blorb/">http://www.eblong.com/zarf/blorb/</ulink>
  33 </para>
  34 <refsect2 id="chimara-How-This-Works">
  35 <title>How This Works</title>
  36 <para>
  37 The Blorb layer is implemented in a C source file, <filename>gi_blorb.c</filename>, and its header, <filename class="headerfile">gi_blorb.h</filename>. This code is (mostly) platform-independent &mdash; it is identical in every library, just as the <filename class="headerfile">glk.h</filename> header file is identical in every library. Each library author who wants to support Blorb should download the <filename>gi_blorb.c</filename> and <filename class="headerfile">gi_blorb.h</filename> files from the Glk web site, and compile them unchanged into the library.
  38 </para>
  39 <para>
  40 Most of the functions defined in <filename class="headerfile">gi_blorb.h</filename> are intended for the library. If you are writing a Glk program, you can ignore them all, except for <link linkend="giblorb-set-resource-map"><function>giblorb_set_resource_map()</function></link>; see <link linkend="chimara-What-the-Program-Does">What the Program Does</link>. If you are implementing a Glk library, you can use this API to find and load resource data.
  41 </para>
  42 </refsect2>
  43 </refsect1>
  44 </refentry>