Documentation for the Inform-Blorb frontend, Blorb Resource Compiler, and
Blorb Packager by L. Ross Raszewski, Version .3b + bpal

New in this version: bpal Palette Resource Editor. see section 4

The Inform-Blorb system was designed to make it easy to generate blorb files
for inform source code.  The first section of the document describes the
frontend.  Casual users will only need to read this section.
The remaining sections describe in detail the individual tools which make up
this package.

Questions, Bugs, concerns, donations, etc, may be sent to the author:
rraszews@hotmail.com

This program is copyright (c) 2000 by L. Ross Raszewski, but is freely
distributable and usable for all non-commercial applications (contact the
author if you wish to use it for a commerical product.)

iblorbb.zip contains MS-DOS executables for this sytem
iblorbs.zip contains source code for this system

0. The resource control file (.res) format
 The resource control file tells the system what resources you want to
 include in the zcode file.  Each resource line has this format:

 TYPE IDENT FILE

 For example, to add "C:\MyPic.png" to the resources for this story, with the
 inform name of "White_House", the line would be:

 PICTURE White_House C:\MyPic.png

 You can also add other blorb resoruces to this file:
 CODE File
  Tells the resource manager that you want to include the specified
  Z-Code or Glulx file in the blorb-file for this program (If the
  code is included in the blorb, you need only distribute one file
  for your users to get both the game itself and its picture/sound data,
  however, users without a blorb-capable interpreter will not be able to
  play the game)
 COPYRIGHT Text
  The copyright information for the resource file
 AUTHOR Text
  The name of the resource file's author
 NOTE Text
  Any other information you want to include about the resources.
 RELEASE Number
  The release number of this blorb file
 PALETTE file
  Include the pallette from the specified file, which is in blorb palette
  format.
 RESOLUTION file
  Include the resolution table from the specified file, which is in blorb
  resolution format.
 HIGHCOLOR
  Include directions to use a 16-bit palette
 TRUECOLOR
  include directions to use a 32-bit palette
  You can also put comments in the file by startign a line with
  an exclamation point (!)

This is a sample of a resource file:

PICTURE White_House C:\MyPic.png
SOUND Theme_Song C:\Music\theme.mod
SOUND Bang C:\Music\Bang.aif
PICTURE Plover_Egg C:\Pictures\Nature\plover.jpg
AUTHOR L. Ross Raszewski
COPYRIGHT (c) 2000
NOTE The Picture of the white house is a screencap from ZGI.
TRUECOLOR
RELEASE 1
To use the resources in your game, you include the .h file created by
the system. In the above example, for example, you could do this:

Include "Foo.bli"; ! Created by frontend
Include "Sound";   ! Shameless self promotion
...

PlaySound(Theme_Song);



1. Using the Frontend
 Download and install an inform compiler
 Place the programs "front", "blc", and "bres" in your executable
 search path (That is, the current directory, or one of the directories
 listed by typing "PATH" from a DOS prompt, or "echo $path" from a
 *nix shell)
 The Front-end program must be invoked with at least one argument, but you
 will almost certainyl want more.
 > front foo
 will run the front-end with front.res as the resource definitions file, and
 will produce foo.h and foo.blb.  (and a complaint from inform)
 All other parameters to front will be passed on to inform.  


 To compile "foo.z5" and "foo.blb" from "foo.inf", using resource file
 "foo.res", showing inform's compilation statistics, do this:

 > front foo foo.inf foo.z5 -s

Frontend assumes that bres, blc, and inform are all present, named thus, and
in the search path.  If there is a file in the current directory called
"infb.rc", it will be consulted first.

An infb.rc file containing these lines:

INFORM  infrmw32
BRES    c:\inform\bres

Will cause front to use "c:\inform\bres" for the resource compiler, and
"infrmw32" as the inform compiler (you can also use this to make your
favorite inform switches the default)



2. Bres: the Blorb Resource Compiler
The format of a bres input file is discussed in section 0.
Bres takes a .res file, and produces two additional files, a BLC
control file, and an inform file (the default extension, .bli,
was chosen to decrease the likilhood of accidentally writing over
one's own source).

Typing bres with no arguments will explain its various invocations

3. BLC: the Blorb Packager
BLC generates a blorb (.blb) file, based on the contents of a blorb
control file (.blc), which is usually produced by bres, but can also be
made by hand.

Each line in a BLC control file describes one chunk of the blorb file, and
has the following format:

Use Number Type Text

Use is the type of resource usage: Pict, Snd, or Exec.  If the chunk is
    not a resource, this should be 0, 1, or 2
    a Use of 0 tells blc that the chunk data is a newline-terminated string
    which follows the chunk type
    a use of 1 tells blc that the chunk data is a 2-byte integer whose
    which appears printed out after the chunk type 
    a Use of 2 tells blc that the chunk data is in a file whose name is a
    newline terminated string which follows the chunk type
Number is the resource number for the chunk, or any number if it is
    not a resource.
Type is the chunk type: JPEG, PNG, FORM (Aiff), MOD, ZCOD, GLUL, ANNO, (c),
    etc.
Text: For a resource, this is the name of the file to be included as this
    chunk's data.  For other chunks, this is the literal text of the chunk,
    which ends at the first newline.

A sample BLC file (based on the example .res file above):

Pict 1 PNG C:\MyPic.png
Snd 3 MOD C:\Music\theme.mod
Snd 4 FORM C:\Music\Bang.aif
Pict 2 JPEG C:\Pictures\Nature\plover.jpg
0 0 AUTH L. Ross Raszewski
0 0 (c) (c) 2000
0 0 ANNO The Picture of the white house is a screencap from ZGI.
1 0 RelN 123
2 0 Plte C:\pictures\nat_pal.plt


4. BPal: The Blorb Palette Editor
BPal is a versatile tool for the creation and manipulation of blorb palette
chunks. The format produced by bpal is identical to the blorb Plte chunk data
segment.  Palettes generated by bpal can be included in a bres resource or
BLC control file as explained above.

BPal's interface is a simple command-line interpreter. The following
functions can be performed:

l      -> load a palette file into bpal for manipulation
i      -> extract the palette from a PNG image if possible
m      -> merge a palette file into the current palette. Entries are
          not duplicated, and the user is warned if some entries were not
          copied due to space limitations (a palette can have no more than
          256 colors according to the blorb standard)
v      -> Toggle output of bpal; in verbose mode, bpal prints confirmation
          messages for most operations. In quiet mode, bpal prints messages
          only on severe errors.
s      -> Save the current palette to a file
a      -> Add a specific RGB color entry to the palette
e      -> Change the value of an entry in the palette
o      -> Organize palette entries by color
d      -> Remove an entry from the palette
c      -> clear the palette
h      -> command summary
q      -> quit

Probably the most useful thing to do with bpal is to extract the palette
from a PNG image; after constructing an image with the optimal palette for
the game (via some graphic manipulation tool), the PNG palette of this image
can be extracted for use in a blorb file.
(One ancient technique for ensuring that images looked correct on an 8-bit
display was to paste all the images from a game onto a single image, and let
the imaging tool construct the optimal palette. This image's palette could
then be used by the production as the palette for the entire game.
Such a method can be used with the images for a blorb file, and
the resulting PNG palette should represent the colors which the
interpreter should render)

To build foo.plt from the palette of image foo.png:

>bpal
bpal: Blorb Palette Editor (Feb  4 2000)
Version .1b by L. Ross Raszewski
Starting command interpreter...
type 'h' for command summary

i foo.png                                       ( import foo.png )
o                                               ( optional; sort the palette )
s foo.plt                                       ( save the palette )
q





Version History:
.1b: First release
.2b: Fixed spurious constant definition for bres CODE directive, added
     makefile, various code cleaning and commenting
.3b: Various code cleaning, added support for RelN, Plte and Reso chunks
.3b+: added bpal version 1.0
