


IMCUR(3IM)             SDSC IMAGE LIBRARY              IMCUR(3IM)



NAME
     imcur - Microsoft Windows CUR file translation

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

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

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

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

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


DESCRIPTION
     cur 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.

     cur image files store one or more cursors  used  by  Windows
     programs.  Bitmap images and icons are instead stored in the
     bmp and ico Windows formats.   See  imbmp  (3IM)  and  imico
     (3IM) for details on these formats.

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

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

  Reading Microsoft Windows CUR files
     The SDSC image library reads multiple non-compressed,  pixel



SDSC              Last change: August 19, 1992                  1






IMCUR(3IM)             SDSC IMAGE LIBRARY              IMCUR(3IM)



     packed  1-bit  color  indexed  cursor  images as IMVFBINDEX8
     VFB's with alpha channels and CLT's.  A cursor'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.

  Writing Microsoft Windows CUR files
     Image library IMVFBMONO VFBs are written to  non-compressed,
     pixel  packed  1-bit cur files.  The mono-channel of the VFB
     is written as the cursor's XOR mask.  The VFB's alpha  chan-
     nel is written as the AND mask.

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

  AND and XOR masks
     A cur image file contains multiple cursors.  Each cursor  is
     composed  of  two  separate  images,  an AND mask and an XOR
     mask.  Microsoft Windows uses  these  masks  to  generate  a
     displayed cursor 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  cursor
          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  an  up-
     and-left-pointing arrow cursor.

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



2                 Last change: August 19, 1992               SDSC






IMCUR(3IM)             SDSC IMAGE LIBRARY              IMCUR(3IM)



8                    _____________________________
                          Resulting Cursor
8                    _____________________________
                    W   W   W   W
8                    _____________________________
                    W   W   W
8                    _____________________________
                    W   W   W   W
8                    _____________________________
                    W           W   W
8                    _____________________________
                                    W   W
8                    _____________________________
                                        W   W
8                    _____________________________
                                            W   W
8                    _____________________________
                                                W
8                    _____________________________


     The following table shows bit mask results:


                AND mask   XOR mask   Resulting Pixel
8                _____________________________________
                0          0          Black
                0          1          White
                1          0          Transparent
                1          1          Inverted



ERRORS
     In addition to those listed for  ImFileRead(3IM),  Microsoft
     Windows cur 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),    imfile(1IM),   imformats(1IM),   imico(3IM),
     imsplit(3IM)

AUTHOR
     Toan-Vinh Le
     San Diego Supercomputer Center

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


SDSC              Last change: August 19, 1992                  3



