DM4 §43: Pictures, sounds, blurbs and Blorb

## §43 Pictures, sounds, blurbs and Blorb

> The blorb spell (safely protect a small object as though in a strong box).
> — Marc Blank and P. David Lebling, ‘Enchanter’

Pictures may, but need not, accompany a Version 6 game. They are not stored in the story file itself, and different interpreters make different arrangements for getting access to them. Some interpreters can only read low-resolution, low-colour-range images in the awkward format used by Infocom's graphical games. Others take pictures from a “Blorb file” which can hold high-resolution and riotously colourful images in a format called PNG. The story file neither knows nor cares which, and refers to pictures only by their numbers.

A Blorb file can also safely protect sound effects and even the story file itself, so that a game and its multi-media resources can be a single file. Blorb is a simple format largely devised by Andrew Plotkin (partly based on the same author's earlier “Pickle”); it has been fully implemented in Kevin Bracey's ‘Zip2000’ interpreter for Acorn RISC OS machines, and is also used by the new “glulx” format of story files.

A Perl script called perlBlorb, runnable on many models of computer, gathers together sounds and images and constructs Blorb files as needed, from a list of instructions called a “blurb file”. For instance:

    ! Example of a blurb file
    copyright "Angela M. Horns 1998"
    release 17
    palette 16 bit
    resolution 600x400
    storyfile "games/sherbet.z5"
    sound    creak  "sounds/creaking.snd"
    sound    wind   "sounds/wind.snd"
    picture  flag     "flag_1.jpg"      scale 3/1
    picture  pattern  "backdrop_1.jpg"

When run through perlBlorb, the above produces the text below:

    ! perlBlorb 1.0 [executing on 980124 at 15:31.33]
    Constant SOUND_creak = 3;
    Constant SOUND_wind = 4;
    Constant PICTURE_flag = 1;
    Constant PICTURE_pattern = 2;
    ! Completed: size 45684 bytes (2 pictures, 2 sounds)

This output text looks like Inform source code, and this is not an accident: the idea is that it can be used as an `Include` file to give sensible names to the sound and picture numbers, so that the rest of the code can include statements like this one:

    @sound_effect SOUND_creak 2 128 255;

(“start playing this effect at about half maximum volume, repeating it indefinitely”). An attractive alternative is to use a convenient class library, such as `"V6Lib.h"` by Jason Penney, to avoid messing about with assembly language.

You're free to specify the numbering yourself, and you need not give names for the pictures and sounds. A blurb command like:

    picture "backdrop.png"

gives this image the next picture number: i.e., the previous picture number plus 1, or just 1 if it's the first specified picture. On the other hand, a blurb command like:

    picture 100 "backdrop.png"

gives it picture number 100. The only restriction is that pictures must be given in increasing numerical order. The numbering of sounds is similar.

· · · · ·

▲ The full specification for the “blurb” language is as follows. With one exception (see palette below) each command occupies one and only one line of text. Lines are permitted to be empty or to contain only white space. Lines whose first non-white-space character is an exclamation mark are treated as comments, that is, ignored. (“White space” means spaces and tab characters.)

‹string› means any text within double-quotes, not containing either double-quote or new-line characters

‹number› means a decimal number in the range 0 to 32767

‹id› means either nothing at all, or a ‹number›, or a sequence of up to 20 letters, digits or underscore characters `_`

‹dim› indicates screen dimensions, and must take the form ‹number›`x`‹number›

‹ratio› is a fraction in the form ‹number›`/`‹number›. `0/0` is legal but otherwise both numbers must be positive

‹colour› is a colour expressed as six hexadecimal digits, as in some HTML tags: for instance `F5DEB3` is the colour of wheat, with red value `F5` (on a scale `00`, none, to `FF`, full), green value `DE` and blue value `B3`. Hexadecimal digits may be given in either upper or lower case.

With the exception of picture and sound, each type of command can only occur at most once in any blurb file. Commands can be used in any order or not at all: an empty “blurb” file results in a perfectly legal, if useless, Blorb file. The full set of commands is as follows:

`copyright` ‹string›

Adds this copyright declaration to the file. It would normally consist of the author's name and the date.

`release` ‹number›

Gives this release number to the file. This is the number returned by the opcode `@picture_data 0` within any game using the Blorb file, and might be used when printing out version information.

`palette 16 bit`
`palette 32 bit`
`palette {` ‹colour-1› … ‹colour-N› `}`

Blorb allows designers to signal to the interpreter that a particular colour-scheme is in use. The first two options simply suggest that the pictures are best displayed using at least 16-bit, or 32-bit, colours. The third option specifies colours used in the pictures in terms of red/green/blue levels, and the braces allow the sequence of colours to continue over many lines. At least one and at most 256 colours may be defined in this way. This is only a “clue” to the interpreter; see the Blorb specification for details.

`resolution` ‹dim›
`resolution` ‹dim›`min` ‹dim›
`resolution` ‹dim›`max` ‹dim›
`resolution` ‹dim›`min` ‹dim›`max` ‹dim›

Allows the designer to signal a preferred screen size, in real pixels, in case the interpreter should have any choice over this. The minimum and maximum values are the extreme values at which the designer thinks the game will be playable: they're optional, the default values being `0x0` and infinity by infinity.

`storyfile` ‹string›
`storyfile` ‹string›`include`

Tells perlBlorb the filename of the Z-code story file which these resources are being provided for. (There is no need to do this if you prefer not to.) Usually the Blorb file simply contains a note of the release number, serial code and checksum of the story file, which an interpreter can try to match at run-time to see if the Blorb file and story file go together. If the `include` option is used, however, the entire story file is embedded within the Blorb file, so that game and resources are all bound up in one single file.

`sound` ‹id› ‹string›
`sound` ‹id› ‹string›`repeat` ‹number›
`sound` ‹id› ‹string›`repeat forever`
`sound` ‹id› ‹string›`music`
`sound` ‹id› ‹string›`song`

Tells perlBlorb to take a sound sample from the named file and make it the sound effect with the given number. The file should be an AIFF file unless `music` is specified, in which case it should be a MOD file (roughly speaking a SoundTracker file); or unless `song` is specified, in which case it should be a song file (roughly, a SoundTracker file using other Blorb sound effects as note samples). Note that repeat information (the number of repeats to be played) is meaningful only with version 3 story files using sound effects, as only Infocom's ‘The Lurking Horror’ ever has.

`picture` ‹id› ‹string›
`picture` ‹id› ‹string›`scale` ‹ratio›
`picture` ‹id› ‹string›`scale min` ‹ratio›
`picture` ‹id› ‹string›`scale` ‹ratio›`min` ‹ratio›
and so on

Similarly for pictures: the named file must be a PNG-format image. Optionally, the designer can specify a scale factor at which the interpreter will display the image – or, alternatively, a range of acceptable scale factors, from which the interpreter may choose its own scale factor. (By default an image is not scaleable and an interpreter must display it pixel-for-pixel.) There are three optional scale factors given: the preferred scale factor, the minimum and the maximum allowed. The minimum and maximum each default to the preferred value if not given, and the default preferred scale factor is 1. Scale factors are expressed as fractions: so for instance,

    picture "flag/png" scale 3/1

means “always display three times its normal size”, whereas

    picture "backdrop/png" scale min 1/10 max 8/1

means “you can display this anywhere between one tenth normal size and eight times normal size, but if possible it ought to be just its normal size”.

• REFERENCES
The Perl script ‘perlBlorb’ is available from the Inform web-page. •The source code to Kevin Bracey's fully Blorb-compliant standard interpreter ‘Zip2000’ is public. •Andrew Plotkin has published generic C routines for handling Blorb files. •Numerous utility programs exist which will convert GIF or JPEG images to PNG format, or WAV and MPEG sounds to AIFF.