home *** CD-ROM | disk | FTP | other *** search
/ Encyclopedia of Graphics File Formats Companion / GFF_CD.ISO / formats / lumena / spec / lumena.txt
Text File  |  1994-06-01  |  19KB  |  506 lines
  1.  
  2.                       LUMENA FILE STRUCTURE
  3.  
  4. LUMENA file structures are described for those who want to inspect
  5. or edit image file values. For example, if you intend to load a
  6. non-standard image file, you might need to read its header to
  7. extract information required by loadalien.
  8.  
  9. The LUMENA image file format, as of LUMENA/Vista v.3.4, is based
  10. on the Truevision TGA file format, v.2.0. The format is type 2 for
  11. unmapped data and type 10 for run-length encoded RGB data. The
  12. structures for headers and other file areas in these formats differ
  13. from those in earlier-version TGA and LUMENA image files.
  14.  
  15. Note, however, that LUMENA high-resolution files (.BPX files) still
  16. use the earlier LUMENA format.
  17.  
  18. Three file formats are described below: TGA v.2.0, TGA prior to
  19. v.2.0, and LUMENA .PIX or .BPX.
  20.  
  21. TGA File Format, v.2.0
  22.  
  23. Decimal
  24. Byte        Number
  25. Offset      of
  26. Into File   Bytes       Contents
  27.  
  28.                               HEADER
  29.  
  30. 0:          1    Number of bytes in image ID field
  31. 1:          1    Color map type: 0 = no map, 1 = map
  32. 2:          1    Image type: 2 = standard, 0A = run-length encoded
  33. 3:          5    Color map specification
  34. 8:          2    X-origin of image
  35. 10:         2    Y-origin of image
  36. 12:         2    Image width
  37. 14:         2    Image height
  38. 16:         1    Pixel depth
  39. 17:         1    Image descriptor
  40.  
  41.                IMAGE/COLOR MAP DATA (Image Field)
  42. 18:     varies   255 bytes, max
  43.  
  44.                            IMAGE DATA
  45.  
  46. varies  varies   Start of image data
  47.  
  48.                          DEVELOPER AREA
  49.  
  50. varies
  51.  
  52.                          EXTENSION AREA
  53.  
  54.         2        Extension size
  55.        41        Author name
  56.       324        Author comments
  57.        12        Date and time stamp
  58.        41        Job name or ID
  59.         6        Job time
  60.        41        Software ID
  61.         3        Software version
  62.         4        Key color
  63.         4        Pixel aspect ratio
  64.         4        Gamma value
  65.         4        Color correction offset
  66.         4        Stamp offset
  67.         4        Scan line offset
  68.         1        Attributes type
  69.       varies     Scan line table
  70.       varies     Start of postage stamp data
  71.       2048       Color correction table
  72.  
  73.                          TGA FILE FOOTER
  74.  
  75.         4        Extension area offset
  76.         4        Developer directory offset
  77.        16        Signature
  78.         1        Reserved character
  79.         1         Binary terminator
  80.  
  81. Typical Header of a LUMENA/Vista TGA File, v.2.0
  82.  
  83. Byte
  84. Offset
  85. (In Hex)
  86.  
  87. 0000:0000 00 00 02 00 00 00 00 00 00 00 00 00 00 02 E2 01
  88. 0000:00101 20 08 ------- (image ID field begins here) ---
  89.  
  90. LUMENA .PIX and .BPX File Format
  91.  
  92. Decimal
  93. Byte        Number
  94. Offset      of
  95. Into File   Bytes       Contents
  96.  
  97. LUMENA      LUMENA
  98. 16   32     16    32    HEADER
  99.  
  100.  0:   0:     1     1    number of bytes in descriptor
  101.  1:   1:     1     1    pix with stamp = 1, pix w/o stamp = 0,
  102.                         bigpix = 0
  103.  2:   2:     1     1    standard file 2, run-length encoded file
  104.                         = 0A, compressed file = 8E
  105.  3:   3:     2     2    stamp width in pixels
  106.  5:   5:     2     2    stamp size in pixels
  107.  7:   7:     1     1    number of bits per pixel in stamp
  108.                         (including alpha (mask) bits)
  109.  8:   8:     2     2    origin of lower left X coordinate
  110. 10:  10:     2     2    origin of lower left Y coordinate
  111. 12:  12:     2     2    image width in pixels
  112. 14:  14:     2     2    image height in pixels
  113. 16:  16:     1     1    number of bits per pixel (including alpha
  114.                         (mask) bits)
  115. 17:  17:     1     1    number of alpha (mask) bits per pixel
  116.  
  117. LUMENA      LUMENA
  118. 16   32     16    32    DESCRIPTOR
  119.  
  120. 18:  18:     2     2    magic word for LUMENA internal routine (use
  121.                         8E)
  122. 20:  20:     2     4    mask for red bits
  123. 22:  24:     2     4    mask for green bits
  124. 24:  28:     2     4    mask for blue bits
  125. 26:  32:     2     2    image aspect ratio, X component
  126. 28:  34:     2     2    image aspect ratio, Y component
  127. 30:  36:     2     4    background color (black = 0)
  128. 32:  40:    40    40    40 bytes reserved for comment
  129. 72:  80:     varies     start of stamp data (followed immediately
  130.                         by image data)
  131.  
  132. NOTE: All values are to be entered in HEX.
  133.  
  134. Typical Header of a LUMENA/16 .PIX File
  135.  
  136. Byte
  137. Offset
  138. (In Hex)
  139.  
  140. 0000;0000  36 01 02 40  00 00 0F 10  00 00 00 00  00 02 E2 01
  141. 0000:0010  10 01 8E 00  00 7C E0 03  1F 00 1A 03  00 04 00 00
  142. 0000:0020  54 69 6D 65  00 41 72 74  73 20 49 6E  63 20 45 2E
  143. 0000:0030  56 2E 41 2E  20 66 69 6C  65 00 00 00  00 00 00 00
  144. 0000:0040     00 00 00 00  00 00 00 00  (Stamp begins here)
  145.  
  146. Typical Header of a LUMENA/32 .PIX File
  147.  
  148. Byte
  149. Offset
  150. (In Hex)
  151.  
  152. 0000:0000  3e 01 02 40  00 00 0F 20  00 00 00 00  00 02 E2 01
  153. 0000:0010  20 08 8E 00  00 00 FF 00  00 FF 00 00  FF 00 00 00
  154. 0000:0020  11 00 14 00  FF FF FF 00  54 69 6D 65  00 41 72 74
  155. 0000:0030  73 20 49 6E  63 20 45 2E  56 2E 41 2E  20 66 69 6C
  156. 0000:0040  65 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00
  157. 0000:0050  (Stamp begins here)
  158.  
  159. Typical Header of a LUMENA/16 .BPX File
  160.  
  161. Byte
  162. Offset
  163. (In Hex)
  164.  
  165. 0000:0000  36 00 02 00  00 00 00 00  00 00 00 00  00 04 C4 03
  166. 0000:0010  10 01 8E 00  00 7C E0 03  1F 00 11 00  14 00 00 00
  167. 0000:0020  54 69 6D 65  20 41 72 74  73 20 4C 75  6D 65 6E 61
  168. 0000:0030  20 66 69 6C  65 2E 00 6C  65 00 00 00  00 00 00 00
  169. 0000:0040  00 00 00 00  00 00 00 00  (Image begins here)
  170.  
  171. Typical Header of a LUMENA/32 .BPX File
  172.  
  173. Byte
  174. Offset
  175. (In Hex)
  176.  
  177. 0000:0000  3e 00 02 00  00 00 00 00  00 00 00 00  00 04 8B 03
  178. 0000:0010  20 08 8E 00  00 00 FF 00  00 FF 00 00  FF 00 00 00
  179. 0000:0020  11 00 14 00  FF FF FF 00  54 69 6D 65  00 41 72 74
  180. 0000:0030  73 20 49 6E  63 20 45 2E  56 2E 41 2E  20 66 69 6C
  181. 0000:0040  65 00 00 00  00 00 00 00  00 00 00 00  00 00 00 00
  182. 0000:0050  (Image begins here)
  183.  
  184. Earlier TGA Header Structure (prior to v.2.0)
  185.  
  186. The Truevision TGA file header format described below is the basis
  187. for the Time Arts .PIX and .BPX header. A TGA header can be edited
  188. to emulate the Time Arts header.
  189.  
  190. Earlier TGA Header Structure
  191.  
  192. Decimal
  193. Byte        Number
  194. Offset      of
  195. Into File   Bytes       Contents
  196.  
  197. 0:          1     number of characters in identification field
  198. 1:          1     color map type
  199. 2:          1     image type (2 = standard file; 0A = run-length
  200.                   encoded; 8E = compressed)
  201. 3:          5     color map specification
  202. 8:          2     origin of lower left X coordinate
  203. 10:         2     origin of lower left Y coordinate
  204. 12:         2     image width in pixels
  205. 14:         2     image height in pixels
  206. 16:         1     number of bits per pixel (including alpha (mask)
  207.                   bits)
  208. 17:         1     number of alpha (mask) bits per pixel
  209. 13:     variable  identification field
  210.  
  211. Typical Header of a .TGA File
  212.  
  213. Byte
  214. Offset
  215. (In Hex)
  216.  
  217. 0000:0000 00 01 02 00 00 00 01 10 00 00 00 00 00 02 E2 01
  218. 0000:0010 10 00 (Identification field or image begins here)
  219.  
  220. Header Sizes
  221.  
  222. LUMENA/16 or /32 .TGA Image = 18 bytes
  223. LUMENA/16 .BPX Image = 18 [header] + 54 [descriptor] = 72 bytes
  224. LUMENA/32 .BPX Image = 18 [header] + 62 [descriptor] = 80 bytes
  225.  
  226. * The stamp width and height = 1/8 of image file proportions.
  227. Bigpic files do not have stamps.
  228.  
  229. File Format For Lumena .CEL File
  230.  
  231. Decimal
  232. Byte        Number
  233. Offset      of
  234. Into File   Bytes       Contents
  235.  
  236. 0:          2    Width of cell
  237. 3:          2    Height of cell
  238. 4:      variable Cell data ... (followed by next width, height,
  239.                  cell data, etc.)
  240.  
  241. The formula to determine where next cell file will begin is:
  242.  
  243.      width x height x depth (2 for 16 bits, or 4 for 32 bits)
  244.      of previous cell
  245.  
  246.  
  247.             VECTOR FILE FORMAT (as written by LUMENA)
  248.  
  249. The vector file is written by a set of calls to POLYSTORE (poly,
  250. handle). Each call writes the data for one character. The following
  251. gets written:
  252.  
  253. Offset        Description
  254.  
  255. 0         |   P polygon flag     (char)
  256. 1         |   image pixel height (integer)
  257. 3         |   font dam height     (integer)            H
  258. 5         |   x-offset            (integer)            E
  259. 7         |   y-offset            (integer)            A
  260. 9         |   frameb->xsize       (integer)            D
  261. 11        |   frameb->ysize       (integer)            E
  262. 13        |   red                 (unsigned char)      R
  263. 14        |   green               (unsigned char)
  264. 15        |   blue                (unsigned char)
  265.  
  266. M    O    |   o   start of outline (char)
  267. U    U    |       . point          (char)               D
  268. L    T    |       x                (integer)            A
  269. T    L    |       y                (integer)            T
  270. I    I    |       .                                     A
  271. P    N    |       x
  272. L    E    |       y
  273. E    S    |       (and so on)
  274.  
  275.           |   e  end of polygon   (char)
  276.  
  277.  
  278. Comments:
  279.  
  280. frameb->xsize & frameb->ysize are not really helpful. These are
  281. designed for distinguishing a bigpic from a regular size image. A
  282. bigpic would use a different scaling factor than a non bigpic.
  283. However, this is already handled at creation time when the user
  284. set the font size. He will set it differently depending on whether
  285. he is using a bigpic or a regular image. Also, these are global
  286. values so they should not be duplicated within each polygon.
  287.  
  288. I'm planning to use this space for storing:
  289.  
  290.      Polygon angle       (100ths of a degree)
  291.      Italic angle        (100ths of a degree)
  292.      Shadow offset x     (pixels)
  293.      Shadow offset y     (pixels)
  294.  
  295. struct tiffhead   /* structure for our TIFF Version 5.0 header */
  296.  
  297. Int order;                 /* byte order in file = II for Intel */
  298. Int version;               /* TIFF magic number is always 42 */
  299. long offset1;              /* offset of 1st sub directory */
  300. int tags;                  /* number of entries in directory */
  301. struct tag NewSubfileType; /* tag254 = 0 */
  302. struct tag ImageWidth;     /* tag256 = pixels/line */
  303. struct tag ImageLength;    /* tag257 = lines/image */
  304. struct tag BitsPerSample;  /* tag258 = 8 or offset to rbits */
  305. struct tag Compression;    /* tag259 = 1 for none, 5 for LZW */
  306. struct tag Photometric;    /* tag262 = 1 for grey, 2 for rgb */
  307. struct tag StripOffsets;   /* tag273 = offset of strip offsets */
  308. struct tag SamplesPerPixel;  /* tag277 = 1 for grey, 3 for rgb */
  309. struct tag RowsPerStrip;   /* tag278 = 1 */
  310. struct tag StripByteCounts;/* tag279 = offset of byte count table*/
  311. struct tag XResolution;    /* tag282 = offset of xresi */
  312. struct tag YResolution;    /* tag283 = offset of yresi */
  313. struct tag PlanarConfiguration; /* tag284 = 1 for rgbrgbrgb ... */
  314. struct tag ResolutionUnit; /* tag296 = 1 for undefined */
  315. struct tag Predictor;      /* tag3l7 = 1 for none, 2 for LZW */
  316. long offsetn;              /* offset of next subdirectory = 0 */
  317. long xres1,xres2, yres1,yres2;  /* x & y aspect */
  318. short rbits,gbits,bbits; /* bits per pixel of red, green, blue */
  319.  
  320. Note: rbits, gbits, and bbits are not present if SamplesPerPixel
  321.       = 1.
  322.       All file offset fields are filled in at run time.
  323.       Here are the default values we start with:
  324.  
  325. struct tiffhead ctiff =   /* an actual tiff file header */
  326. {                         /* with our defaults in place */
  327. 0X4949,42;BL,159
  328. 254,3,1L,0L,           256,3,1L,512L,
  329. 257,3,1L,482L,         258,3,1L,0L,
  330. 259,3,1L;1L,           262,3,1L,1L,
  331. 273,4,482L,0L,         277,3,1L,3L,
  332. 278,3,1L,1L,           279,3,482L,0L,
  333. 282,5,1L,0L,           283,5,1L,0L,
  334. 284,3,1L,1L,           296,3,1L,1L,
  335. 317,3,1L,1L,
  336. 0L,                    /* mark end of header */
  337. 1L,1L,1L,1L            /* the aspect rationals */
  338. 8,8,8                  /* BitsPerSample for color */
  339. };
  340.  
  341. /* Format of a Lumena/16/32 version 2.40 greyscale TIFF file
  342.  
  343. offset      contents     comment
  344.  
  345. 0   */    0x4949,     /* byte order in file is usually Intel
  346. 2   */    42,         /* this has "deep philosophical significance"
  347. 4   */    8L,         /* offset of first sub directory
  348. 8   */    8,          /* 8 tags in first subdirectory
  349. 10  */ 255,3;1L,1L;   /* SubfileType = full resolution data
  350. 22  */ 256,3,1L,512L, /* ImageWidth can change
  351. 34  */ 257,3,1L,482L, /* ImageLength can change
  352. 46  */ 258,3,1L,8L,   /* BitsPerSample is 9 for greyscale data
  353. 58  */ 262,3,1L,1L,   /* PhotometricInterpretation = black to white
  354. 70  */ 273,3,1L,126L, /* StripOffsets = offset where image starts
  355. 82  */ 282,5,1L,110L, /* XResolution offset of xresi and xres2
  356. 94  */ 283,5,1L,11BL, /* Yresolution offset of yresi and yres2
  357. 106 */ 0L,            /* offset of next subdirectery(there is none)
  358. 110 */ 150L,1L,       /* xresi = system aspect times 150, xres2=1
  359. 118 */ 150L,1L        /* yresi=150, yres2=1. These never change.
  360.  
  361. 126 Image data starts here, consisting of one byte per pixel
  362.     stored in horizonal lines scanned left to right, top to
  363.     bottom.  */
  364.  
  365.                     TIME ARTS FILE STRUCTURE
  366.              for Lumena/16/32 and ColorScheme 1 & 2
  367.  
  368. Time Arts is using the AT&T Targa file formats, types 2 and 10,
  369. for unmapped and run-length encoded RGB data, respectively. The
  370. detailed header struct is shown below, and the stamp description,
  371. which is placed after the descriptor, is noted at the bottom. The
  372. "stamp" is a small version of the entire image that is used in
  373. previewing. It is stored immediately following the descriptor data,
  374. in the same place a map would have been put in a mapped image. We
  375. are using this same format for high-resolution (bigpic) image files
  376. but without a stamp.
  377.  
  378. Decimal
  379. Byte        Number
  380. Offset      of
  381. Into File   Bytes       Contents
  382.  
  383. LUMENA      LUMENA
  384. 16    32    16    32
  385.                        * * * HEADER * * *
  386.  
  387.  0:    0:   1     1     number of bytes in descriptor
  388.  1:    1:   1     1     pix with stamp=1 pix w/o stamp=0 bigpix=0
  389.  2:    2:   1     1     standard file=2 run-length encoded file=0A
  390.                           compressed file=8E
  391.  3:    3:   2     2     stamp width in pixels
  392.  5:    5:   2     2     stamp size in pixels
  393.  7:    7:   1     1     number of bits per pixel in stamp
  394.                           [including alpha (mask) bits]
  395.  8:    8:   2     2     origin of lower left X coordinate
  396. 10:   10:   2     2     origin of lower left Y coordinate
  397. 12:   12:   2     2     image width in pixels
  398. 14:   14:   2     2     image height in pixels
  399. 16:   16:   1     1     number of bits per pixel [including alpha
  400.                           (mask) bits]
  401. 17:   17:   1     1     number of alpha (mask) bits per pixel
  402.  
  403.  
  404.                      * * * DESCRIPTOR * * *
  405.  
  406. 18:   18:   2     2     magic word for Lumena internal routine (use
  407.                           8E)
  408. 20:   20:   2     4     mask for red bits
  409. 22:   24:   2     4     mask for green bits
  410. 24:   28:   2     4     mask for blue bits
  411. 26:   32:   2     2     image aspect ratio-X coordinate | Note:
  412.                                                         | These two
  413. 28:   34:   2     2     image aspect ratio-Y coordinate | values
  414.                                                         | together
  415.                                                         | indicate
  416.                                                         | a ratio.
  417. 30:   36:   2     4     background color (black=0)
  418. 32:   40:  40    40     40 bytes (reserved for comment)
  419. 72:   80:               start of stamp data (followed immediately
  420.                           by image data)
  421.  
  422. NOTE: All values are to be entered in HEX.
  423.       Assuming an image size of 512 x 482:
  424.       Lumena/16 header size, bytes = 18 [header] + 54 [descriptor]
  425.                                         + (64x60x2) [stamp] = 7752
  426.       Lumena/32 header size, bytes = 18 [header] + 62 [descriptor]
  427.                                         + (64x60x4) [stamp] = 15440
  428.       Stamp width and height = 1/8 of image file proportions.
  429.  
  430. Lumena /8
  431. File Formats
  432.  
  433.  
  434. Image files ( .PIC )
  435.  
  436. Image files contain the entire contents of the frame buffer i.e.
  437. all pixel values at the time the SAVE command was issued. The frame
  438. buffer contents are not encoded in any way, and there is no header
  439. record. The first 512 bytes of the file contain the top line of
  440. pixels , left to right, with the next 512 bytes containing the next
  441. line of pixels, and so on. 512 lines are saved. PIC files do not
  442. contain any color map information.
  443.  
  444. Bytes            Contents
  445. 0      - 511     Line 511 (top of screen) pixel 0-511 values.
  446. 512    - 1023    Line 510 pixel values.
  447. 261633 - 262144  Line 0 (bottom of frame buffer--not visible).
  448.  
  449.  
  450. Map files  ( .MAP )
  451.  
  452. Map files contain the contents of the current color map at the time
  453. they were created. They are automatically created when an image is
  454. saved, or can be saved by themselves through the MAPS menu. The
  455. file consists of 768 bytes. The first 256 bytes contain the red
  456. color component of the 256 entries in the color map, starting with
  457. the first entry. The next 256 bytes contain the green color
  458. component, and the next 256 bytes contain the blue component.
  459.  
  460. Bytes           Contents
  461. 0   - 255     Red entries 0-255 in color map.
  462. 256 - 511     Green entries 0-255 in color map.
  463. 512 - 767     Blue entries 0=255 in color map.
  464.  
  465. Cell outline files   ( .CEL )
  466.  
  467. Cell outline files contain the coordinates of the cells whose
  468. outlines have been created through the CELLS menu. The files can
  469. be created in the CELLS menu; they get saved along with events in
  470. the ANIM menu. A cell outline is a rectangular area of the screen
  471. which is defined by two points, the lower left and the upper right
  472. corners. Each cell is also assigned a name or label. The user may
  473. determine this name when the cell is created, otherwise the value
  474. one is used. The file contains a 16-byte record for each cell
  475. outline that existed when the file was created. The first 2 bytes
  476. (bytes 0-1) of each record contain a number representing the ASCII
  477. value for the cell name, or label. The next two bytes (bytes 2-3)
  478. currently are not used. Bytes (4-5) contain the x-coordinate of the
  479. lower left point. Bytes (6-7) contain the y-coordinate of this
  480. point. The next 4 bytes (bytes 8-11) contain the x and y
  481. coordinates of the upper right point.
  482.  
  483. Bytes 12-15 are not currently used.
  484.  
  485. Bytes            Contents
  486.  
  487.  0  -  1         Cell label
  488.  2  -  3         Unused
  489.  4  -  5         X1
  490.  6  -  7         Y1
  491.  8  -  9         X2
  492. 10  - 11         Y2
  493. 12 -  15         Unused
  494.  
  495. MHI image files are 1024x964 pixels and follow the PIC format
  496. outlined earlier, but as a much longer file.
  497.  
  498. VHI image files are 2048x1928 pixels and follow the PIC format as
  499. well.
  500.  
  501. These file formats are created by Lumena 8+, while the PIC format
  502. is from Lumena 8. They are all colormapped files. The colormaps
  503. are the same and may be used with all three image formats from
  504. Lumena 8.
  505.  
  506.