home *** CD-ROM | disk | FTP | other *** search
/ IRIX 6.3 Development Libraries / SGI IRIX 6.3 Development Libraries.iso / dist / dist6.3 / ViewKit_dev.idb / usr / share / doc / Xpm / README.z / README
Encoding:
Text File  |  1996-09-20  |  7.3 KB  |  209 lines
  1. /*
  2.  * Copyright (C) 1989-95 GROUPE BULL
  3.  *
  4.  * Permission is hereby granted, free of charge, to any person obtaining a copy
  5.  * of this software and associated documentation files (the "Software"), to
  6.  * deal in the Software without restriction, including without limitation the
  7.  * rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  8.  * sell copies of the Software, and to permit persons to whom the Software is
  9.  * furnished to do so, subject to the following conditions:
  10.  *
  11.  * The above copyright notice and this permission notice shall be included in
  12.  * all copies or substantial portions of the Software.
  13.  *
  14.  * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  15.  * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  16.  * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
  17.  * GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
  18.  * AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  19.  * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
  20.  *
  21.  * Except as contained in this notice, the name of GROUPE BULL shall not be
  22.  * used in advertising or otherwise to promote the sale, use or other dealings
  23.  * in this Software without prior written authorization from GROUPE BULL.
  24.  */
  25.  
  26.  
  27.                 XPM Version 3
  28.  
  29. WHAT IS XPM?
  30. ============
  31.  
  32. XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
  33.  
  34. Here is provided a library containing a set of four functions, similar to the
  35. X bitmap functions as defined in the Xlib: XpmCreatePixmapFromData,
  36. XpmCreateDataFromPixmap, XpmReadFileToPixmap and XpmWriteFileFromPixmap for
  37. respectively including, storing, reading and writing this format, plus four
  38. other: XpmCreateImageFromData, XpmCreateDataFromImage, XpmReadFileToImage and
  39. XpmWriteFileFromImage for working with images instead of pixmaps.
  40.  
  41. This new version provides a C includable format, defaults for different types
  42. of display: monochrome/color/grayscale, hotspot coordinates and symbol names
  43. for colors for overriding default colors when creating the pixmap. It provides
  44. a mechanism for storing information while reading a file which is re-used
  45. while writing. This way comments, default colors and symbol names aren't lost.
  46. It also handles "transparent pixels" by returning a shape mask in addition to
  47. the created pixmap.
  48.  
  49. See the XPM Manual for more details.
  50.  
  51. HOW TO GET XPM?
  52. ===============
  53.  
  54. New xpm updates are announced on the comp.windows.x newsgroup, and on the
  55. "xpm-talk" list. All new "official" xpm releases can be found by ftp on:
  56.  
  57.     ftp.x.org          (18.112.44.100) contrib     (Boston, USA)
  58.     koala.inria.fr     (138.96.24.30) pub/xpm     (Sophia Antipolis, France)
  59.  
  60.  
  61. DOCUMENTATION:
  62. =============
  63.  
  64. Old users might read the CHANGES file for a history of changes interesting
  65. the user.
  66.  
  67. Read the doc. The documentation is in PostScript format (file doc/xpm.ps) and
  68. has been produced with FrameMaker. The source files are available on request.
  69.  
  70.  
  71. INSTALLATION:
  72. ============
  73.  
  74. To obtain the XPM library, first uncompress and untar the compressed tar file
  75. in an approriate directory.
  76.  
  77. Then you can either compile xpm via "imake" or in a stand-alone way.
  78.  
  79. WITH IMAKE:
  80.  
  81.     Imakefiles are provided to build both shared and unshared libraries.
  82.     However, building a shared lib is very OS specific and often a tough
  83.     task. So if it fails you can avoid trying to build one simply by
  84.     uncommenting the apropriate line the top Imakefile.
  85.  
  86.     Also you should have a look at this top Imakefile and see if you need
  87.     to do some modification, especially in regard to the DEFINES
  88.     definition, in order to fit with your system.
  89.  
  90.     Then execute the following commands:
  91.  
  92.         xmkmf -a
  93.         make
  94.  
  95.     which will build the XPM library and the sxpm application. 
  96.     Then do:
  97.  
  98.              make install
  99.         make install.man
  100.  
  101.     which will install the library and the sxpm pregram and man page.
  102.  
  103.     If it fails, you may edit the Imakefiles to add compilation flags to
  104.     suit your machine.
  105.  
  106.  
  107.     Note:
  108.  
  109.     On Solaris 2.* the compilation works only in the native svr4
  110.     environment, avoid the bsd one or it won't compile. Especially you
  111.     should be using /opt/SUNWspro/bin/cc and not /usr/ucb/cc.
  112.  
  113.  
  114. WITHOUT IMAKE:
  115.  
  116.     To compile xpm, in the xpm directory you just created, do:
  117.  
  118.             make -f Makefile.noX
  119.  
  120.     Then to install it, do:
  121.  
  122.         make -f Makefile.noX install
  123.  
  124.     However this may require a lot of work to set every Makefile depending
  125.     on your environment.
  126.  
  127.  
  128. SXPM:
  129. ====
  130.  
  131. In addition to the library the sxpm tool is provided to show XPM file and
  132. convert them from XPM1 or XPM2 to XPM version 3. If you have previously done
  133. 'make' or 'make all' you should have it yet, otherwise just do:
  134.  
  135.               cd sxpm; make
  136.  
  137. This application shows you most of the features of XPM and its source can be
  138. used to quickly see how to use the provided functions.
  139.  
  140. By executing 'sxpm -help' you will get the usage.
  141.  
  142. Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
  143. function. The pixmap is created from the static variable plaid defined in the
  144. sxpm.c file. sxpm will end when you press the key 'q' in the created window.
  145.  
  146. Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
  147. overriding color symbols giving a colorname, executing 'sxpm -plaid -sp
  148. lines_in_mix 1' will show overriding giving a pixel value, and executing 'sxpm
  149. -plaid -cp red 0' will show overriding giving a color value.
  150.  
  151. Then you should try 'sxpm -plaid -o output' to get an output file using the
  152. XpmWriteFileFromPixmap function.
  153.  
  154. You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
  155. get the pixmap printed out on the standard output with colornames instead of
  156. rgb values.
  157.  
  158. Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
  159. and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
  160.  
  161. The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
  162. flag to show the utility of this one. Indeed, compare the color section of the
  163. two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
  164. plaid.xpm -o bar'. All the default colors and also the comments have been
  165. restored.
  166.  
  167. To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
  168. extensions are handled.
  169.  
  170. Of course, other combinations are allowed and should be tried. Thus, 'sxpm
  171. plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
  172. to a XPM version 3 using sxpm.
  173.  
  174. See the manual page for more detail.
  175.  
  176. OTHER TOOLS:
  177. ===========
  178.  
  179. Several converters dealing with XPM and a pixmap editor can be found in the
  180. xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
  181. general image operations such as scaling, resizing, dithering, and to convert
  182. from and to any other image format.
  183.  
  184. DISCUSSION:
  185. ==========
  186.  
  187. There is a mailing list to discuss about XPM which is xpm-talk@sophia.inria.fr.
  188. Any request to subscribe should be sent to xpm-talk-request@sophia.inria.fr.
  189.  
  190. COPYRIGHT:
  191. ==========
  192.  
  193.   Copyright 1989-95 GROUPE BULL --
  194.   See license conditions in the COPYRIGHT file of the XPM distribution
  195.  
  196. Please mail any bug reports or modifications done, comments, suggestions,
  197. requests for updates or patches to port on another machine to:
  198.  
  199. lehors@sophia.inria.fr        (INTERNET)
  200.  
  201. 33 (FRANCE) 93.65.77.71        (VOICE PHONE)
  202.  
  203. Arnaud Le Hors            (SURFACE MAIL)
  204. Bull c/o Inria BP. 109
  205. 2004, Route des lucioles
  206. Sophia Antipolis
  207. 06561 Valbonne Cedex
  208. FRANCE
  209.