programming/blorb/blorb-infocom-extension.txt

Blorb extensions for Infocom graphics                        version 0.1
-------------------------------------

Author: Kevin Bracey (kevin@bracey-griffith.freeserve.co.uk)


This document specifies an extension to Blorb 1.1 to handle the original
graphics of the four Infocom V6 games.

The aim is to make it possible to convert the Infocom graphics to Blorb
without any loss of functionality. That way V6 interpreters only need to
handle Blorb with some minor extensions, rather than having to cope with two
totally different resource formats.

Conversion of the TLH and Sherlock sounds to Blorb was straightforward, and
these have been uploaded to the IF Archive. The only remaining issue is the
correct frequency for one of the TLH sounds.

For the graphics, the consensus is that the optimal versions are the IBM MCGA
(MG1) versions.

The MG1 graphics are designed for a 320x200 resolution screen, and use a
maximum of 14 colours per image. An extra transparent colour is also
supported. The games will readily scale themselves to different resolutions,
sizes and screen sizes proportions.

There are three peculiar features to the MG1 graphics.

    1) Images with zero height and/or width (in Zork Zero and Arthur)
    2) Images with no palette (in Zork Zero and Arthur)
    3) Images with no data (in Zork Zero, Shogun, and Arthur)

The first two cannot represented in Blorb 1.1, as PNG and JPEGs must have
both width and height >= 1, and PNGs must have a palette. Item 3 can be dealt
with (inefficiently) by having a totally transparent PNG.

To handle these features, this specification add two extensions to Blorb.
Support for these extensions by interpreters is optional, and their use is
strongly discouraged for any purpose other than conversions of Infocom
graphics.


* Rectangles

A third of picture is a rectangle. A rectangle has only size, but no
contents. A rectangle exists for the purposes of @picture_data, and
@erase_picture, but its use in @draw_picture or @picture_table is an error.
Indeed, the IBM Infocom interpreter crashes if asked to plot an image with
no data. 

A rectangle is described by a "Rect" chunk:

      4 bytes   "Rect"    chunk ID
      4 bytes   8         chunk size
      4 bytes   px        picture width
      4 bytes   py        picture height

Rectangles are used by Zork Zero, Shogun and Arthur. Either or both of the
width and height may be zero.


* The Adaptive Palette Chunk

This chunk contains a list of pictures that change their colours according to
the pictures plotted before - these will be known as adaptive-palette
pictures.

        4 bytes       'APal'       chunk ID
        4 bytes       num*4        chunk length
        num*4 bytes   ...          adaptive palette entries
        
Each entry is 4 bytes, of the form:

        4 bytes       number       picture resource number

If this chunk is present:

   * All pictures in the Blorb file will be PNGs or Rects.
   * All PNGs will be indexed-colour (colour type 3).
   * All PNGs will use only colour indices 2-15.
   * All PNGs will have no more than 16 entries in their PLTE chunk.
   * PNGs may have a tRNS chunk marking colour 0 only as fully transparent,
     in which case colour index 0 may also be used. No other forms of the
     tRNS chunk are valid.

However, the following rules still apply from the PNG standard:

   * Any bit depth of PNG is valid (1,2,4 or 8 bits per pixel).
   * The PLTE chunk is required by the PNG standard, and it must have
     sufficient entries to cover every colour used in the PNG, even in
     adaptive-palette pictures.
   * The PLTE chunk may not have more entries than can be represented
     by the PNG's bit depth.
   * The PNGs may have gAMA, cHRM and sRGB or iCCP chunks describing the
     colour space. Interpreters should make every effort to support at least
     gAMA. For the Infocom graphics at least, cHRM, sRGB and iCCP are
     probably beyond the call of duty.

These restrictions, though intricate, serve to make the interpreter's life
easier at the expense of constraining the creator. The constraints are
natural given the form of the original Infocom graphics.

The interpreter should keep track of the "Current Palette". This will be a
14-entry table, covering colour indices 2-16. For ease of implementation,
this will probably be a 16-entry table, whose first two entries are not
significant.

Whenever a picture *not* listed in the APal chunk is plotted, its palette (as
derived from its PLTE, gAMA, cHRM and sRGB/iCCP chunks) should be copied into
the Current Palette. If its palette has fewer than 16 entries, then only
those entries of the Current Palette are changed. (Possible interpreter
implementation: transform the PNG's PLTE chunk according to the gAMA, cHRM,
sRGB chunks, then copy it into your Current Palette which is always in the
screen colour-space. With libpng, use png_get_PLTE, after calling
png_update_info).

Whenever a picture listed in the APal chunk is plotted, its palette should be
ignored, and it should be plotted with the Current Palette. (Possible
interpreter implementation: strip out the PLTE, gAMA, cHRM and sRGB/iCCP
chunks from the PNG, and insert the Current Palette as its PLTE. Or with
libpng, use png_set_PLTE before reading the data).

Behaviour is undefined if any adaptive-palette pictures are plotted before
a non-adaptive picture has been plotted.

If picture caching (through @picture_data or otherwise) is implemented,
special attention may need to be paid to ensure that adaptive images that are
cached are still appropriate for the Current Palette when plotted. It would
appear that the Zork Zero does reset the cache after a palette change, but
this has not been exhaustively investigated.

Alternatively, for the full retro-gaming experience, the pictures can be
handled in the same way as the Amiga and IBM MCGA interpreters, as follows:
Use a 16-colour screen mode. Copy non-adaptive pictures' palette (apart from
the first two entries) into the screen palette when plotted. Use colour
indices 0 and 1 for the window background and text respectively. This mimics
the IBM MGA and Amiga display, where drawing a picture can change the colours
of graphics already on the screen, but it is not the preferred rendering.

Shogun and Journey do not use any adaptive-palette images, but on some
platforms the effect of pictures already on the screen changing colour is
visible. To give an interpreter the ability to do this if desired, and to
signal that optimisations may be possible because of the limited nature of
the graphics, the Blorb files for Shogun and Journey contain an empty APal
chunk.