
                           InterDesk Shadow Files

                                Introduction

  InterDesk uses 'shadow' files  to  record  certain  information  about  an
  executable  file or directory.  Assuming the name of a file is 'filename',
  its shadow file is automatically named  '.filename.idsh':  with  a  period
  prefixing it, and an extension of '.idsh'.

  Shadow  files  must  be  located in the same directory as their associated
  executable or directory, and they should  not  be  flagged  as  executable
  files.

  When  InterDesk  performs  a  file  operation  on  an executable file or a
  directory, it automatically  performs  the  operation  on  any  associated
  shadow file.

  Shadow files are not, by default, shown in an InterDesk directory  window.
  Because  they have a period before their name, they should also not appear
  in directory listings from 'ls', and other utilities.

  Because the shell does  NOT  expand  '*'  with  the  names  of  all  files
  beginning in '.', you should be careful, when copying and archiving files,
  to  also  copy/archive  the shadow files as well.  Pax, for instance, when
  doing a recursive archive write for '*', will miss all  filenames  in  the
  specified  directory  that  begin  in  '.',  but  WILL  itself  gather all
  filenames beginning in '.' in any subdirs.

  InterDesk  ships  with  shadow  files  for  several  standard   QNX/QNXWin 
  programs.   Application  developers  may  ship  shadow  files  with  their 
  products  so  that  InterDesk  can  recognize  and  use them.  Third-party 
  programs may also read and utilize the data in shadow files for their  own 
  purposes.

  If a version of InterDesk for Photon/X is developed, it will use the  same 
  format for shadow files as InterDesk for QNXWin.

  A simple shadow file editor is shipped with InterDesk.  This lets you edit
  all data within a given shadow file, including the icons.


                                Legal Issues

  This library, source code, and documentation are all Copyright (C) 1996 by 
  Scott C. Moonen.  All Rights Reserved.

  You may use this library, code, and  documentation  free  of  charge.   No
  royalty  fee  whatsoever  is  charged  for  use of this library, code, and
  documentation, whether by individuals, governments, or corporate entities.

  You may  freely  distribute  this  code,  but  only  under  the  following
  conditions:  If  you  redistribute this code, library, or documentation to
  others, you must distribute it in  full,  including  ALL  files  in  their
  original form, completely unmodified.


                                 Disclaimer

  Anyone who uses this library, code, and documentation does so at their own 
  risk,  and  bears ALL responsibility as to the outcome.  Scott Moonen will 
  not be held liable for any errors in this library, code, or documentation; 
  or for any results arising from their use.

  The information in this  code  and  documentation  is  subject  to  change 
  without  notice.  Scott Moonen reserves the right to update or change such 
  information at his discretion and without the consent of or any obligation 
  to any users.


                     Format of an InterDesk Shadow File

  Bytes             Description  

  0-1 (WORD)        Magic number -- 0x0FE6 (E6 0F).

  2-3 (WORD)        Extensions info.  Set this to 0.  Future formats for the
                    file, as long as they remain compatible with this format
                    and use only the reserved bytes for  their  information,
                    will  keep  the  magic number at 0x0FE6 so programs that
                    recognize only the old format will work.   Such  formats
                    will  change this flag to indicate that more information
                    exists in the file.  If you are reading and using shadow
                    files in your programs, check the magic number  word  to
                    be  sure  it  is  a shadow file of the right format, but
                    ignore this value.  If your program modifies an EXISTING
                    shadow file, KEEP THIS FLAG AND ALL RESERVED DATA SET TO
                    THEIR ORIGINAL VALUES -- DON'T CLEAR THEM TO ZERO!   If,
                    however,  you  are  CREATING a shadow file, you MUST set
                    this and all reserved values to zero!

  4-5 (WORD)        Type of  program.  This  is  a  bitmask.   Since  it  is
                    conceivable  that  a  program could support multiple i/o
                    types, multiple bits  can  be  set.   Currently  defined
                    values:

                        0xFFFF - All  bits  set.   A  file  which   is   not
                                 executable (e.g., a directory).
                        0x0000 - No bits set.   Program  type  is  currently
                                 unknown.

                        0x0001 - Program for a QNX 4 terminal/console.
                        0x0002 - Program for QNXWin 4.
                        0x0004 - Program for Photon.
                        0x0008 - Program for X-Windows.

                    When launching a  program,  InterDesk  will  check  this
                    value  first.   If  it's a QNXWin app, it'll be launched
                    directly.  If it's a QNX terminal app, it'll be run in a
                    WTerm window.  If it's a  Photon  or  X  app,  it'll  be
                    launched  using  WTerm,  letting  the program handle any
                    errors resulting from the fact that either  may  not  be
                    loaded.  If  the  type is unknown, InterDesk will assume
                    that the app is a terminal  app  and  execute  it  using
                    WTerm.

                    For  programs  which do not have shadow files, InterDesk 
                    assumes that they are terminal applications.

  6-63 (BYTES)      Reserved -- set to 0 when creating a new shadow file.

  64-3088 (BYTES)   55x55 pixel QNXWin icon  (See below for description).

  3089-3152 (BYTES) AND bitmask for 64x64 pixel Photon icon (See below).

  3153-15440 (BYTES)  OR bitmask for 64x64 pixel Photon icon (See below).


                   Format of InterDesk Shadow File Icons

  InterDesk shadow files contain two icons: a QNXWin icon and a Photon icon.  
  QNXWin  icons  are stored as arrays of QNXWin color numbers.  Photon icons 
  are stored as two bitmasks which are  combined  together  to  display  the 
  icon.

  InterDesk's  shadow  file editor can convert QNXWin icons to Photon icons,
  and vice-versa,  although  the  latter  may  not  turn  out  quite  right.
  However,  the  InterDesk  Graphical  Shell  and File Manager are unable to
  convert from either format to the other.


            Format of InterDesk Shadow File Icons: QNXWin Icons

  QNXWin  icons  are  stored  as a sequence of bytes specifying QNXWin color
  numbers.  Each byte (8 bits) specifies a single pixel in the  icon.   Each
  byte  may  have  a  value  from 0-16.  The value 0 specifies a transparent
  pixel.  The values from 1-16  specify  the  basic  QNXWin  color  numbers.
  Values  in the range of 17-255 are illegal, and are treated as color value
  0 (transparent).

  QNXWin icons MUST be 55x55 pixels.  The bytes are stored in the file from 
  left to right for each row, and the rows from top to bottom.

  Picture a 10x10 pel icon (an illegal size, but it suffices as an example).
  The sequence of bytes (base 16) for this hypothetical  icon  could  be  as
  follows:

    00 00 00 00 00 00 00 00 00 00
    00 05 05 05 05 05 05 05 04 00
    00 05 02 02 02 02 02 04 04 00
    00 05 02 02 0E 02 02 04 04 00
    00 05 02 0E 0E 0E 02 04 04 00
    00 05 02 02 0E 02 02 04 04 00
    00 05 02 02 02 02 02 04 04 00
    00 04 04 04 04 04 04 04 04 00
    00 00 00 00 00 00 00 00 00 00


            Format of InterDesk Shadow File Icons: Photon Icons

  Photon  icons  utilize  a  different  format  from QNXWin icons, primarily
  because Photon uses a different means of  specifying  colors  (24-bit  RGB
  color values, as opposed to indexes into a system color table).

  Photon icons MUST be 64x64 pixels.

  This format also has the unique property of being able  to  produce  icons
  whose pixels can be 'partially transparent', or translucent.

  This  format uses two bitmasks: an AND mask, which is applied first, and a
  OR mask, which is applied afterwards.  The AND bitmask is  AND'ed  to  the
  screen, while the OR bitmask is OR'ed to the screen.

  The AND bitmask is located immediately before the OR bitmask in the file.

  The AND bitmask is an array of bits specifying the outline  of  an  icon's
  contents.   Pixels  whose  bits  are  set  to  1 will be transparent after
  applying the OR mask.  Pixels whose bits are set to  0  become  solid,  or
  opaque, after applying the OR mask.

  The bits in an AND bitmask are stored  from  LSB  to  MSB  in  the  bytes.
  Therefore, bit 0 would be 0x01, bit 1 0x02, bit 2, 0x04, and so forth.

  In keeping with our above example of a 10x10 icon (again, an illegal size,
  but sufficing as an example), the AND bitmask for the  Photon  version  of
  that icon would be as follows, with each value being a single bit.

  Note that the ends of each row of pixels are padded out with 1's.  This is
  unnecessary  in the normal Photon format, for the width of a row of pixels
  (64) is exactly divisible by the byte size (8).

  Also,  note  that  the  bits  are shown in the reverse order in which they 
  would normally appear.  The LSB is on the left, and  the  MSB  is  on  the 
  right, though normally those positions are reversed in binary numbers.

   LSB           MSB  LSB               MSB

    1 1 1 1 1 1 1 1    1 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1
    1 0 0 0 0 0 0 0    0 1  |  1 1 1 1 1 1 
    1 1 1 1 1 1 1 1    1 1  |  1 1 1 1 1 1

  The  OR  bitmask consists of an array of 24-bit (3-byte) RGB color values,
  applied after the AND mask.  If the associated AND mask bit is 0,  the  OR
  value specifies the RGB value of the color to be displayed.

  If,  on  the  other  hand,  the  associated  AND mask bit is 1, the result
  depends on the value of the OR value.

    0x000000              The associated pixel will appear transparent.
    0xFFFFFF              The associated pixel will appear White.
    0x000001 - 0xFFFFFE   The associated pixel will be 'translucent'.  Where
                          bits in this OR value are 0,  those  bits  may  be 
                          changed  to  1, depending on the underlying color. 
                          However, the behavior of this is  not  necessarily 
                          always  what  one would consider to be logical for 
                          translucency.   Two  dark  colors  would   usually 
                          result  in  a  brighter  color.   Combinations  of 
                          strikingly  different  colors could end up looking 
                          very  wierd.   Using  translucent  pixels  is  not 
                          recommended, and indeed not even supported by  the 
                          InterDesk  shadow file editor.  Naturally, though, 
                          since icons are  usually  only  displayed  on  the 
                          plain  gray background of InterDesk File Manager's 
                          window or the Application Dock, translucency would 
                          have little effect  other  than  to  brighten  the 
                          translucent portions of the icon.

  Our  OR  mask  for  the sample icon is as follows.  Each sequence of three
  bytes defines a single pixel.  Please note that the bytes  are  stored  in
  R,G,B order within the file.

    00 00 00  00 00 00  00 00 00  00 00 00  00 00 00
    00 00 00  00 00 00  00 00 00  00 00 00  00 00 00

    00 00 00  FF FF FF  FF FF FF  FF FF FF  FF FF FF
    FF FF FF  FF FF FF  FF FF FF  50 50 50  00 00 00

    00 00 00  FF FF FF  C8 C8 C8  C8 C8 C8  C8 C8 C8
    C8 C8 C8  C8 C8 C8  50 50 50  50 50 50  00 00 00

    00 00 00  FF FF FF  C8 C8 C8  C8 C8 C8  FF 00 00
    C8 C8 C8  C8 C8 C8  50 50 50  50 50 50  00 00 00

    00 00 00  FF FF FF  C8 C8 C8  FF 00 00  FF 00 00
    FF 00 00  C8 C8 C8  50 50 50  50 50 50  00 00 00

    00 00 00  FF FF FF  C8 C8 C8  C8 C8 C8  FF 00 00
    C8 C8 C8  C8 C8 C8  50 50 50  50 50 50  00 00 00

    00 00 00  FF FF FF  C8 C8 C8  C8 C8 C8  C8 C8 C8
    C8 C8 C8  C8 C8 C8  50 50 50  50 50 50  00 00 00

    00 00 00  FF FF FF  50 50 50  50 50 50  50 50 50
    50 50 50  50 50 50  50 50 50  50 50 50  00 00 00

    00 00 00  50 50 50  50 50 50  50 50 50  50 50 50
    50 50 50  50 50 50  50 50 50  50 50 50  00 00 00

    00 00 00  00 00 00  00 00 00  00 00 00  00 00 00
    00 00 00  00 00 00  00 00 00  00 00 00  00 00 00


  Thankfully,  InterDesk's  shadow  file editor utility lets you edit shadow
  files and their icons.  Thus, there is no need for you to laboriously edit
  a shadow file's icons by hand.

  The  InterDesk  shadow  file  editor even permits you to convert the icons 
  from one type to another, but  please  note  that  such  a  conversion  is 
  naturally  very  incomplete  and  inaccurate, particularly when converting 
  from a Photon/X icon to a QNXWin icon.  For this reason, it is recommended 
  that you directly edit each icon individually, without using conversion.


                                 Structures

  The following structure may be used in a program to  access  an  InterDesk
  shadow file.


  #pragma pack(1);

  typedef struct _ShadowFile  ShadowFile;

  struct _ShadowFile
  {
    short     MagicNum;                 /* Magic number -- set to 0x0FE6.   */
    short     ExtFlag;                  /* Extensions flag.                 */
    short     ProgType;                 /* Program type bitmask.            */
    char      _Rsvd[58];                /* Reserved -- set to 0.            */

    char      QWinIcon[55][55];         /* QNXWin icon.                     */

    char      PhotonAND[64][8];         /* Photon AND bitmask.              */
    char      PhotonOR[64][64][3];      /* Photon OR bitmask.               */
  };

  #pragma pack();
