LUMENA.TXT

LUMENA.TXT


Remove Frame

                      LUMENA FILE STRUCTURE

LUMENA file structures are described for those who want to inspect
or edit image file values. For example, if you intend to load a
non-standard image file, you might need to read its header to
extract information required by loadalien.

The LUMENA image file format, as of LUMENA/Vista v.3.4, is based
on the Truevision TGA file format, v.2.0. The format is type 2 for
unmapped data and type 10 for run-length encoded RGB data. The
structures for headers and other file areas in these formats differ
from those in earlier-version TGA and LUMENA image files.

Note, however, that LUMENA high-resolution files (.BPX files) still
use the earlier LUMENA format.

Three file formats are described below: TGA v.2.0, TGA prior to
v.2.0, and LUMENA .PIX or .BPX.

TGA File Format, v.2.0

Decimal
Byte        Number
Offset      of
Into File   Bytes       Contents

                              HEADER

0:          1    Number of bytes in image ID field
1:          1    Color map type: 0 = no map, 1 = map
2:          1    Image type: 2 = standard, 0A = run-length encoded
3:          5    Color map specification
8:          2    X-origin of image
10:         2    Y-origin of image
12:         2    Image width
14:         2    Image height
16:         1    Pixel depth
17:         1    Image descriptor

               IMAGE/COLOR MAP DATA (Image Field)
18:     varies   255 bytes, max

                           IMAGE DATA

varies  varies   Start of image data

                         DEVELOPER AREA

varies

                         EXTENSION AREA

        2        Extension size
       41        Author name
      324        Author comments
       12        Date and time stamp
       41        Job name or ID
        6        Job time
       41        Software ID
        3        Software version
        4        Key color
        4        Pixel aspect ratio
        4        Gamma value
        4        Color correction offset
        4        Stamp offset
        4        Scan line offset
        1        Attributes type
      varies     Scan line table
      varies     Start of postage stamp data
      2048       Color correction table

                         TGA FILE FOOTER

        4        Extension area offset
        4        Developer directory offset
       16        Signature
        1        Reserved character
        1         Binary terminator

Typical Header of a LUMENA/Vista TGA File, v.2.0

Byte
Offset
(In Hex)

0000:0000 00 00 02 00 00 00 00 00 00 00 00 00 00 02 E2 01
0000:00101 20 08 ------- (image ID field begins here) ---

LUMENA .PIX and .BPX File Format

Decimal
Byte        Number
Offset      of
Into File   Bytes       Contents

LUMENA      LUMENA
16   32     16    32    HEADER

 0:   0:     1     1    number of bytes in descriptor
 1:   1:     1     1    pix with stamp = 1, pix w/o stamp = 0,
                        bigpix = 0
 2:   2:     1     1    standard file 2, run-length encoded file
                        = 0A, compressed file = 8E
 3:   3:     2     2    stamp width in pixels
 5:   5:     2     2    stamp size in pixels
 7:   7:     1     1    number of bits per pixel in stamp
                        (including alpha (mask) bits)
 8:   8:     2     2    origin of lower left X coordinate
10:  10:     2     2    origin of lower left Y coordinate
12:  12:     2     2    image width in pixels
14:  14:     2     2    image height in pixels
16:  16:     1     1    number of bits per pixel (including alpha
                        (mask) bits)
17:  17:     1     1    number of alpha (mask) bits per pixel

LUMENA      LUMENA
16   32     16    32    DESCRIPTOR

18:  18:     2     2    magic word for LUMENA internal routine (use
                        8E)
20:  20:     2     4    mask for red bits
22:  24:     2     4    mask for green bits
24:  28:     2     4    mask for blue bits
26:  32:     2     2    image aspect ratio, X component
28:  34:     2     2    image aspect ratio, Y component
30:  36:     2     4    background color (black = 0)
32:  40:    40    40    40 bytes reserved for comment
72:  80:     varies     start of stamp data (followed immediately
                        by image data)

NOTE: All values are to be entered in HEX.

Typical Header of a LUMENA/16 .PIX File

Byte
Offset
(In Hex)

0000;0000  36 01 02 40  00 00 0F 10  00 00 00 00  00 02 E2 01
0000:0010  10 01 8E 00  00 7C E0 03  1F 00 1A 03  00 04 00 00
0000:0020  54 69 6D 65  00 41 72 74  73 20 49 6E  63 20 45 2E
0000:0030  56 2E 41 2E  20 66 69 6C  65 00 00 00  00 00 00 00
0000:0040	 00 00 00 00  00 00 00 00  (Stamp begins here)

Typical Header of a LUMENA/32 .PIX File

Byte
Offset
(In Hex)

0000:0000  3e 01 02 40  00 00 0F 20  00 00 00 00  00 02 E2 01
0000:0010  20 08 8E 00  00 00 FF 00  00 FF 00 00  FF 00 00 00
0000:0020  11 00 14 00  FF FF FF 00  54 69 6D 65  00 41 72 74
0000:0030  73 20 49 6E  63 20 45 2E  56 2E 41 2E  20 66 69 6C
0000:0040  65 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00
0000:0050  (Stamp begins here)

Typical Header of a LUMENA/16 .BPX File

Byte
Offset
(In Hex)

0000:0000  36 00 02 00  00 00 00 00  00 00 00 00  00 04 C4 03
0000:0010  10 01 8E 00  00 7C E0 03  1F 00 11 00  14 00 00 00
0000:0020  54 69 6D 65  20 41 72 74  73 20 4C 75  6D 65 6E 61
0000:0030  20 66 69 6C  65 2E 00 6C  65 00 00 00  00 00 00 00
0000:0040  00 00 00 00  00 00 00 00  (Image begins here)

Typical Header of a LUMENA/32 .BPX File

Byte
Offset
(In Hex)

0000:0000  3e 00 02 00  00 00 00 00  00 00 00 00  00 04 8B 03
0000:0010  20 08 8E 00  00 00 FF 00  00 FF 00 00  FF 00 00 00
0000:0020  11 00 14 00  FF FF FF 00  54 69 6D 65  00 41 72 74
0000:0030  73 20 49 6E  63 20 45 2E  56 2E 41 2E  20 66 69 6C
0000:0040  65 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00
0000:0050  (Image begins here)

Earlier TGA Header Structure (prior to v.2.0)

The Truevision TGA file header format described below is the basis
for the Time Arts .PIX and .BPX header. A TGA header can be edited
to emulate the Time Arts header.

Earlier TGA Header Structure

Decimal
Byte        Number
Offset      of
Into File   Bytes       Contents

0:          1     number of characters in identification field
1:          1     color map type
2:          1     image type (2 = standard file; 0A = run-length
                  encoded; 8E = compressed)
3:          5     color map specification
8:          2     origin of lower left X coordinate
10:         2     origin of lower left Y coordinate
12:         2     image width in pixels
14:         2     image height in pixels
16:         1     number of bits per pixel (including alpha (mask)
                  bits)
17:         1     number of alpha (mask) bits per pixel
13:     variable  identification field

Typical Header of a .TGA File

Byte
Offset
(In Hex)

0000:0000 00 01 02 00 00 00 01 10 00 00 00 00 00 02 E2 01
0000:0010 10 00 (Identification field or image begins here)

Header Sizes

LUMENA/16 or /32 .TGA Image = 18 bytes
LUMENA/16 .BPX Image = 18 [header] + 54 [descriptor] = 72 bytes
LUMENA/32 .BPX Image = 18 [header] + 62 [descriptor] = 80 bytes

* The stamp width and height = 1/8 of image file proportions.
Bigpic files do not have stamps.

File Format For Lumena .CEL File

Decimal
Byte        Number
Offset      of
Into File   Bytes       Contents

0:          2    Width of cell
3:          2    Height of cell
4:      variable Cell data ... (followed by next width, height,
                 cell data, etc.)

The formula to determine where next cell file will begin is:

     width x height x depth (2 for 16 bits, or 4 for 32 bits)
     of previous cell


            VECTOR FILE FORMAT (as written by LUMENA)

The vector file is written by a set of calls to POLYSTORE (poly,
handle). Each call writes the data for one character. The following
gets written:

Offset        Description

0         |   P polygon flag     (char)
1         |   image pixel height (integer)
3         |   font dam height     (integer)            H
5         |   x-offset            (integer)            E
7         |   y-offset            (integer)            A
9         |   frameb->xsize       (integer)            D
11        |   frameb->ysize       (integer)            E
13        |   red                 (unsigned char)      R
14        |   green               (unsigned char)
15        |   blue                (unsigned char)

M    O    |   o   start of outline (char)
U    U    |       . point          (char)               D
L    T    |       x                (integer)            A
T    L    |       y                (integer)            T
I    I    |       .                                     A
P    N    |       x
L    E    |       y
E    S    |       (and so on)

          |   e  end of polygon   (char)


Comments:

frameb->xsize & frameb->ysize are not really helpful. These are
designed for distinguishing a bigpic from a regular size image. A
bigpic would use a different scaling factor than a non bigpic.
However, this is already handled at creation time when the user
set the font size. He will set it differently depending on whether
he is using a bigpic or a regular image. Also, these are global
values so they should not be duplicated within each polygon.

I'm planning to use this space for storing:

     Polygon angle       (100ths of a degree)
     Italic angle        (100ths of a degree)
     Shadow offset x     (pixels)
     Shadow offset y     (pixels)

struct tiffhead   /* structure for our TIFF Version 5.0 header */

Int order;                 /* byte order in file = II for Intel */
Int version;               /* TIFF magic number is always 42 */
long offset1;              /* offset of 1st sub directory */
int tags;                  /* number of entries in directory */
struct tag NewSubfileType; /* tag254 = 0 */
struct tag ImageWidth;     /* tag256 = pixels/line */
struct tag ImageLength;    /* tag257 = lines/image */
struct tag BitsPerSample;  /* tag258 = 8 or offset to rbits */
struct tag Compression;    /* tag259 = 1 for none, 5 for LZW */
struct tag Photometric;    /* tag262 = 1 for grey, 2 for rgb */
struct tag StripOffsets;   /* tag273 = offset of strip offsets */
struct tag SamplesPerPixel;  /* tag277 = 1 for grey, 3 for rgb */
struct tag RowsPerStrip;   /* tag278 = 1 */
struct tag StripByteCounts;/* tag279 = offset of byte count table*/
struct tag XResolution;    /* tag282 = offset of xresi */
struct tag YResolution;    /* tag283 = offset of yresi */
struct tag PlanarConfiguration; /* tag284 = 1 for rgbrgbrgb ... */
struct tag ResolutionUnit; /* tag296 = 1 for undefined */
struct tag Predictor;      /* tag3l7 = 1 for none, 2 for LZW */
long offsetn;              /* offset of next subdirectory = 0 */
long xres1,xres2, yres1,yres2;  /* x & y aspect */
short rbits,gbits,bbits; /* bits per pixel of red, green, blue */

Note: rbits, gbits, and bbits are not present if SamplesPerPixel
      = 1.
      All file offset fields are filled in at run time.
      Here are the default values we start with:

struct tiffhead ctiff =   /* an actual tiff file header */
{                         /* with our defaults in place */
0X4949,42;BL,159
254,3,1L,0L,           256,3,1L,512L,
257,3,1L,482L,         258,3,1L,0L,
259,3,1L;1L,           262,3,1L,1L,
273,4,482L,0L,         277,3,1L,3L,
278,3,1L,1L,           279,3,482L,0L,
282,5,1L,0L,           283,5,1L,0L,
284,3,1L,1L,           296,3,1L,1L,
317,3,1L,1L,
0L,                    /* mark end of header */
1L,1L,1L,1L            /* the aspect rationals */
8,8,8                  /* BitsPerSample for color */
};

/* Format of a Lumena/16/32 version 2.40 greyscale TIFF file

offset      contents     comment

0   */    0x4949,     /* byte order in file is usually Intel
2   */    42,         /* this has "deep philosophical significance"
4   */    8L,         /* offset of first sub directory
8   */    8,          /* 8 tags in first subdirectory
10  */ 255,3;1L,1L;   /* SubfileType = full resolution data
22  */ 256,3,1L,512L, /* ImageWidth can change
34  */ 257,3,1L,482L, /* ImageLength can change
46  */ 258,3,1L,8L,   /* BitsPerSample is 9 for greyscale data
58  */ 262,3,1L,1L,   /* PhotometricInterpretation = black to white
70  */ 273,3,1L,126L, /* StripOffsets = offset where image starts
82  */ 282,5,1L,110L, /* XResolution offset of xresi and xres2
94  */ 283,5,1L,11BL, /* Yresolution offset of yresi and yres2
106 */ 0L,            /* offset of next subdirectery(there is none)
110 */ 150L,1L,       /* xresi = system aspect times 150, xres2=1
118 */ 150L,1L        /* yresi=150, yres2=1. These never change.

126 Image data starts here, consisting of one byte per pixel
    stored in horizonal lines scanned left to right, top to
    bottom.  */

                    TIME ARTS FILE STRUCTURE
             for Lumena/16/32 and ColorScheme 1 & 2

Time Arts is using the AT&T Targa file formats, types 2 and 10,
for unmapped and run-length encoded RGB data, respectively. The
detailed header struct is shown below, and the stamp description,
which is placed after the descriptor, is noted at the bottom. The
"stamp" is a small version of the entire image that is used in
previewing. It is stored immediately following the descriptor data,
in the same place a map would have been put in a mapped image. We
are using this same format for high-resolution (bigpic) image files
but without a stamp.

Decimal
Byte        Number
Offset      of
Into File   Bytes       Contents

LUMENA      LUMENA
16    32    16    32
                       * * * HEADER * * *

 0:    0:   1     1     number of bytes in descriptor
 1:    1:   1     1     pix with stamp=1 pix w/o stamp=0 bigpix=0
 2:    2:   1     1     standard file=2 run-length encoded file=0A
                          compressed file=8E
 3:    3:   2     2     stamp width in pixels
 5:    5:   2     2     stamp size in pixels
 7:    7:   1     1     number of bits per pixel in stamp
                          [including alpha (mask) bits]
 8:    8:   2     2     origin of lower left X coordinate
10:   10:   2     2     origin of lower left Y coordinate
12:   12:   2     2     image width in pixels
14:   14:   2     2     image height in pixels
16:   16:   1     1     number of bits per pixel [including alpha
                          (mask) bits]
17:   17:   1     1     number of alpha (mask) bits per pixel


                     * * * DESCRIPTOR * * *

18:   18:   2     2     magic word for Lumena internal routine (use
                          8E)
20:   20:   2     4     mask for red bits
22:   24:   2     4     mask for green bits
24:   28:   2     4     mask for blue bits
26:   32:   2     2     image aspect ratio-X coordinate | Note:
                                                        | These two
28:   34:   2     2     image aspect ratio-Y coordinate | values
                                                        | together
                                                        | indicate
                                                        | a ratio.
30:   36:   2     4     background color (black=0)
32:   40:  40    40     40 bytes (reserved for comment)
72:   80:               start of stamp data (followed immediately
                          by image data)

NOTE: All values are to be entered in HEX.
      Assuming an image size of 512 x 482:
      Lumena/16 header size, bytes = 18 [header] + 54 [descriptor]
                                        + (64x60x2) [stamp] = 7752
      Lumena/32 header size, bytes = 18 [header] + 62 [descriptor]
                                        + (64x60x4) [stamp] = 15440
      Stamp width and height = 1/8 of image file proportions.

Lumena /8
File Formats


Image files ( .PIC )

Image files contain the entire contents of the frame buffer i.e.
all pixel values at the time the SAVE command was issued. The frame
buffer contents are not encoded in any way, and there is no header
record. The first 512 bytes of the file contain the top line of
pixels , left to right, with the next 512 bytes containing the next
line of pixels, and so on. 512 lines are saved. PIC files do not
contain any color map information.

Bytes            Contents
0      - 511     Line 511 (top of screen) pixel 0-511 values.
512    - 1023    Line 510 pixel values.
261633 - 262144  Line 0 (bottom of frame buffer--not visible).


Map files  ( .MAP )

Map files contain the contents of the current color map at the time
they were created. They are automatically created when an image is
saved, or can be saved by themselves through the MAPS menu. The
file consists of 768 bytes. The first 256 bytes contain the red
color component of the 256 entries in the color map, starting with
the first entry. The next 256 bytes contain the green color
component, and the next 256 bytes contain the blue component.

Bytes	       Contents
0   - 255     Red entries 0-255 in color map.
256 - 511     Green entries 0-255 in color map.
512 - 767     Blue entries 0=255 in color map.

Cell outline files   ( .CEL )

Cell outline files contain the coordinates of the cells whose
outlines have been created through the CELLS menu. The files can
be created in the CELLS menu; they get saved along with events in
the ANIM menu. A cell outline is a rectangular area of the screen
which is defined by two points, the lower left and the upper right
corners. Each cell is also assigned a name or label. The user may
determine this name when the cell is created, otherwise the value
one is used. The file contains a 16-byte record for each cell
outline that existed when the file was created. The first 2 bytes
(bytes 0-1) of each record contain a number representing the ASCII
value for the cell name, or label. The next two bytes (bytes 2-3)
currently are not used. Bytes (4-5) contain the x-coordinate of the
lower left point. Bytes (6-7) contain the y-coordinate of this
point. The next 4 bytes (bytes 8-11) contain the x and y
coordinates of the upper right point.

Bytes 12-15 are not currently used.

Bytes            Contents

 0  -  1         Cell label
 2  -  3         Unused
 4  -  5         X1
 6  -  7         Y1
 8  -  9         X2
10  - 11         Y2
12 -  15         Unused

MHI image files are 1024x964 pixels and follow the PIC format
outlined earlier, but as a much longer file.

VHI image files are 2048x1928 pixels and follow the PIC format as
well.

These file formats are created by Lumena 8+, while the PIC format
is from Lumena 8. They are all colormapped files. The colormaps
are the same and may be used with all three image formats from
Lumena 8.