


IMICO(3IM)             SDSC IMAGE LIBRARY              IMICO(3IM)



NAME
     imico - Microsoft Windows ICO file translation

SYNOPSIS
     #include <stdio.h>
     #include "sdsc.h"
     #include "im.h"

     int ImFileRead( fd, "ico", flagsTable, dataTable )
          int         fd;
          TagTable   *flagsTable;
          TagTable   *dataTable;

     int ImFileFRead( fp, "ico", flagsTable, dataTable )
          FILE         *fp;
          TagTable   *flagsTable;
          TagTable   *dataTable;

     int ImFileWrite( fd, "ico", flagsTable, dataTable )
          int         fd;
          TagTable   *flagsTable;
          TagTable   *dataTable;

     int ImFileFWrite( fp, "ico", flagsTable, dataTable )
          FILE         *fp;
          TagTable   *flagsTable;
          TagTable   *dataTable;


DESCRIPTION
     ico image files are generated by  programs  running  in  the
     Microsoft   Windows  3.0,  and  later,  environments.   This
     environment commonly runs on IBM PC's and compatibles.

     ico image files store one or more icons used by Windows pro-
     grams.   Icons  can  only  have  widths and heights of fixed
     values:  16, 32, or  64.   Bitmap  images  and  cursors  are
     instead  stored  in  the  bmp  and cur Windows formats.  See
     imbmp (3IM) and imcur (3IM) for details on these formats.

FILE RECOGNITION
     Microsoft Windows ico files are recognized by the  following
     filename suffix:  .ico.

NOTES
     SDSC image library support of the Microsoft Windows ico for-
     mat  does  not require use of any Windows libraries and con-
     tains no proprietary code. Microsoft Windows ico format han-
     dling  is  available on any machine for which the SDSC image
     library is available.





SDSC              Last change: August 19, 1992                  1






IMICO(3IM)             SDSC IMAGE LIBRARY              IMICO(3IM)



  Reading Microsoft Windows ICO files
     The SDSC image library reads multiple non-compressed,  pixel
     packed 1- and 4-bit color indexed icon images as IMVFBINDEX8
     VFBs with alpha channels and CLT's.  An icon's XOR  mask  is
     read  in as the main image.  The associated AND mask is read
     in as an alpha channel for the same VFB.

     3-bit color indexed icon images are currently not  supported
     due to the lack of documentation on the pixel packing method
     used for this type of image.

  Writing Microsoft Windows ICO files
     Image library IMVFBMONO VFBs are written to  non-compressed,
     pixel  packed  1-bit  ico  files.  Image library IMVFBINDEX8
     VFBs are written to non-compressed, pixel packed  4-bit  ico
     files.   The  color  channels  of the VFB are written as the
     icon's XOR mask.  The VFB's alpha channel is written as  the
     AND mask.

     Other image library VFB types  are  converted  to  IMVFBMONO
     VFBs or IMVFBINDEX8 with alpha channels prior to being writ-
     ten out.  See the ImFileWrite(3IM) man page for details.

  AND and XOR masks
     An ico image file contains multiple  icons.   Each  icon  is
     composed of two separate images, an AND mask and a XOR mask.
     Microsoft Windows uses these masks to generate  a  displayed
     icon as follows:

          Windows first does  a  bitwise  AND  operation  on  the
          display  pixels  using the AND mask.  This preserves or
          removes existing  color  pixels.   Afterwards,  Windows
          does  a  bitwise XOR operation on the display using the
          XOR mask.  This sets  the  final  color  of  each  icon
          pixel.

     The AND mask is typically used  to  create  a  hole  on  the
     screen  into  which to paint the colors specified by the XOR
     mask.  This use of the AND mask is  similar  to  a  standard
     image alpha channel and is why the SDSC Image Tools read the
     AND mask into a VFB's alpha channel, and place the XOR  mask
     in the VFB's color index channel.

     For example, the following AND and XOR masks form a  capital
     'K'   icon   (example   taken  from  the  _M_i_c_r_o_s_o_f_t  _W_i_n_d_o_w_s
     _P_r_o_g_r_a_m_m_e_r'_s _R_e_f_e_r_e_n_c_e):

8  ______________________________     ______________________________
            AND mask                            XOR mask
8  ______________________________     ______________________________
  0   0   1   1   1   0   0   1       1   1   0   0   0   1   1   0
8  ______________________________     ______________________________
  0   0   1   1   0   0   1   1       1   1   0   0   1   1   0   0
8  ______________________________     ______________________________



2                 Last change: August 19, 1992               SDSC






IMICO(3IM)             SDSC IMAGE LIBRARY              IMICO(3IM)



  0   0   1   0   0   1   1   1       1   1   0   1   1   0   0   0
8  ______________________________     ______________________________
  0   0   0   0   1   1   1   1       1   1   1   1   0   0   0   0
8  ______________________________     ______________________________
  0   0   0   0   1   1   1   1       1   1   1   1   0   0   0   0
8  ______________________________     ______________________________
  0   0   1   0   0   1   1   1       1   1   0   1   1   0   0   0
8  ______________________________     ______________________________
  0   0   1   1   0   0   1   1       1   1   0   0   1   1   0   0
8  ______________________________     ______________________________
  0   0   1   1   1   0   0   1       1   1   0   0   0   1   1   0
8  ______________________________     ______________________________

8                    _____________________________
                           Resulting Icon
8                    _____________________________
                    K   K               K   K
8                    _____________________________
                    K   K           K   K
8                    _____________________________
                    K   K       K   K
8                    _____________________________
                    K   K   K   K
8                    _____________________________
                    K   K   K   K
8                    _____________________________
                    K   K       K   K
8                    _____________________________
                    K   K           K   K
8                    _____________________________
                    K   K               K   K
8                    _____________________________

ERRORS
     In addition to those listed for  ImFileRead(3IM),  Microsoft
     Windows ico file reading returns the following error codes:

          IMEDEPTH       Image depth not supported
          IMEMAGIC       Bad magic number in header
          IMEPLANES      Unknown image plane configuration
          IMECLTLENGTH   Bad CLT length

DOCUMENTATION
     _M_i_c_r_o_s_o_f_t _W_i_n_d_o_w_s _P_r_o_g_r_a_m_m_e_r'_s _R_e_f_e_r_e_n_c_e _V_o_l_u_m_e_s  _3  _a_n_d  _4,
     Microsoft, Inc.

SEE ALSO
     ImIntro(3IM),    ImErrNo(3IM),    imbmp(3IM),    imcat(3IM),
     imconv(1IM),    imcur(3IM),   imfile(1IM),   imformats(1IM),
     imicon(3IM), imsplit(3IM), imxbm(1IM)

AUTHOR
     Toan-Vinh Le
     San Diego Supercomputer Center

CONTACT
     SDSC consultants, (619)534-5100, consult@y1.sdsc.edu






SDSC              Last change: August 19, 1992                  3



