16e7d3316Smrg<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> 26e7d3316Smrg<html lang="en"> 36e7d3316Smrg<HEAD> 46e7d3316Smrg<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> 56e7d3316Smrg<TITLE>XPM README</TITLE> 66e7d3316Smrg</HEAD> 76e7d3316Smrg 86e7d3316Smrg<body> 96e7d3316Smrg<h1 align="center">XPM README</h1> 106e7d3316Smrg 116e7d3316Smrg<h2>Contents</h2> 126e7d3316Smrg 136e7d3316Smrg<ol> 146e7d3316Smrg<li><a href="#sec1">What Is XPM?</a> 156e7d3316Smrg<li><a href="#sec2">Where to get XPM?</a> 166e7d3316Smrg<li><a href="#sec3">Documentation</a> 176e7d3316Smrg<li><a href="#sec4">Installation</a> 186e7d3316Smrg<ol> 196e7d3316Smrg<li><a href="#sec4.1">With imake</a> 206e7d3316Smrg<li><a href="#sec4.2">Without imake</a> 216e7d3316Smrg</ol> 226e7d3316Smrg<li><a href="#sec5">SXPM</a> 236e7d3316Smrg<li><a href="#sec6">CXPM</a> 246e7d3316Smrg<li><a href="#sec7">Other Tools</a> 256e7d3316Smrg<li><a href="#sec8">Discussion</a> 266e7d3316Smrg<li><a href="#copy">Copyright</a> 276e7d3316Smrg</ol> 286e7d3316Smrg 296e7d3316Smrg 306e7d3316Smrg<h2><a name="sec1">1. What Is XPM?</a></h2> 316e7d3316Smrg<p> 326e7d3316SmrgXPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files. 336e7d3316Smrg<p> 346e7d3316SmrgHere is provided a library containing a set of four functions, similar to the 356e7d3316SmrgX bitmap functions as defined in the Xlib: <code>XpmCreatePixmapFromData</code>, 366e7d3316Smrg<code>XpmCreateDataFromPixmap</code>, <code>XpmReadFileToPixmap</code> and <code>XpmWriteFileFromPixmap</code> for 376e7d3316Smrgrespectively including, storing, reading and writing this format, plus four 386e7d3316Smrgother: <code>XpmCreateImageFromData</code>, <code>XpmCreateDataFromImage</code>, <code>XpmReadFileToImage</code> and 396e7d3316Smrg<code>XpmWriteFileFromImage</code> for working with images instead of pixmaps. 406e7d3316Smrg<p> 416e7d3316SmrgThis new version provides a C includable format, defaults for different types 426e7d3316Smrgof display: monochrome/color/grayscale, hotspot coordinates and symbol names 436e7d3316Smrgfor colors for overriding default colors when creating the pixmap. It provides 446e7d3316Smrga mechanism for storing information while reading a file which is re-used 456e7d3316Smrgwhile writing. This way comments, default colors and symbol names aren't lost. 466e7d3316SmrgIt also handles "transparent pixels" by returning a shape mask in addition to 476e7d3316Smrgthe created pixmap. 486e7d3316Smrg<p> 496e7d3316SmrgSee the XPM Manual for details. 506e7d3316Smrg 516e7d3316Smrg 526e7d3316Smrg<h2><a name="sec2">2. Where to get XPM?</a></h2> 536e7d3316Smrg<p> 546e7d3316SmrgNew XPM updates are announced on the comp.windows.x newsgroup, and on the 556e7d3316Smrg"xpm-talk" list and you can always consult the XPM Home page at <a 566e7d3316Smrghref="http://www.inria.fr/koala/lehors/xpm.html">http://www.inria.fr/koala/lehors/xpm.html</a> 576e7d3316Smrg<p>The latest "official" XPM release can always be found at: 586e7d3316Smrg<br>Boston, USA: <a 596e7d3316Smrghref="ftp://ftp.x.org/contrib">ftp://ftp.x.org/contrib</a> 606e7d3316Smrg<br>Sophia Antipolis, France: <a 616e7d3316Smrghref="ftp://koala.inria.fr/pub/xpm">ftp://koala.inria.fr/pub/xpm</a> 626e7d3316Smrg 636e7d3316Smrg 646e7d3316Smrg<h2><a name="sec3">3. Documentation</a></h2> 656e7d3316Smrg<p> 666e7d3316SmrgOld users might read the <a href="CHANGES">CHANGES</a> file for a history 676e7d3316Smrgof changes interesting the user. 686e7d3316Smrg<p> 696e7d3316SmrgRead the doc. The documentation is in PostScript format (<a 706e7d3316Smrghref="doc/xpm.PS">doc/xpm.PS</a>) and has been produced with 716e7d3316SmrgFrameMaker. The source files are available on request. 726e7d3316Smrg<p> 736e7d3316SmrgA <a href="FAQ.html">FAQ</a> (Frequently Asked Questions) is also provided, 746e7d3316Smrgso if you experience any problem you should have a look at this file. 756e7d3316Smrg 766e7d3316Smrg 776e7d3316Smrg<h2><a name="sec4">4. Installation</a></h2> 786e7d3316Smrg<p> 796e7d3316SmrgTo obtain the XPM library, first uncompress and untar the compressed tar file 806e7d3316Smrgin an appropriate directory. 816e7d3316Smrg<p> 826e7d3316SmrgThen you can either compile XPM via "imake" or in a stand-alone way. 836e7d3316Smrg 846e7d3316Smrg<h3><a name="sec4.1">4.1. With imake</a></h3> 856e7d3316Smrg<p> 866e7d3316Smrg Imakefiles are provided to build both shared and unshared libraries. 876e7d3316Smrg However, building a shared lib is very OS dependent and often requires 886e7d3316Smrg specific files which are not available. Also config files are often not 896e7d3316Smrg set correctly for this task. So if it fails you can avoid trying to 906e7d3316Smrg build one and simply build the static library instead. In order to do 916e7d3316Smrg so you should edit the top Imakefile to add -DSharedLibXpm=NO to the 926e7d3316Smrg definition of IMAKE_DEFINES as described. 936e7d3316Smrg<p> 946e7d3316Smrg The compilation and installation of the library and the sxpm program 956e7d3316Smrg should only require you to edit the top Imakefile. But you should do so 966e7d3316Smrg in order to specify the locations where the various files should be 976e7d3316Smrg installed and to set the DEFINES variable accordingly to your system. 986e7d3316Smrg<p> 996e7d3316Smrg On Solaris 2.* the compilation works only in the native svr4 1006e7d3316Smrg environment, avoid the bsd one or it won't compile. Especially you 1016e7d3316Smrg should be using /opt/SUNWspro/bin/cc and not /usr/ucb/cc. 1026e7d3316Smrg Also since the compiler is no longer part of the OS distribution a lot 1036e7d3316Smrg of people use gcc instead. This is fine, but be aware that the imake 1046e7d3316Smrg tool you get as part of the X Window System on a solaris box is 1056e7d3316Smrg configured for cc. Therefore the compilation using the generated 1066e7d3316Smrg Makefiles will not succeed unless you have changed the default 1076e7d3316Smrg configuration. An easy work around is to directly edit the generated 1086e7d3316Smrg lib/Makefile to change '-K pic' to '-fpic'. Fixing your imake 1096e7d3316Smrg configuration would be better though. 1106e7d3316Smrg<p> 1116e7d3316Smrg On Linux, if you do not use ELF yet you'd better get the binary 1126e7d3316Smrg distribution available from sunsite. Because it's really a pain to 1136e7d3316Smrg build a shared lib and the current XPM distribution doesn't contain 1146e7d3316Smrg the jump files you would need to do so. On the other hand people have 1156e7d3316Smrg had no problems building it using ELF. 1166e7d3316Smrg<p> 1176e7d3316Smrg Then execute the following command: 1186e7d3316Smrg<pre> 1196e7d3316Smrg xmkmf -a 1206e7d3316Smrg</pre> 1216e7d3316Smrg<p> 1226e7d3316Smrg or if this option is not supported by your version of xmkmf: 1236e7d3316Smrg<pre> 1246e7d3316Smrg xmkmf 1256e7d3316Smrg make Makefiles 1266e7d3316Smrg make includes 1276e7d3316Smrg make depend (optional) 1286e7d3316Smrg</pre> 1296e7d3316Smrg<p> 13097cf2ee2Smrg Then simply execute: 1316e7d3316Smrg<pre> 1326e7d3316Smrg make 1336e7d3316Smrg</pre> 1346e7d3316Smrg<p> 13597cf2ee2Smrg which will build the XPM library and the sxpm application. 1366e7d3316Smrg Then do: 1376e7d3316Smrg<pre> 1386e7d3316Smrg make install 1396e7d3316Smrg make install.man 1406e7d3316Smrg</pre> 1416e7d3316Smrg<p> 1426e7d3316Smrg which will install the library and the sxpm program and man page. 1436e7d3316Smrg<p> 1446e7d3316Smrg If it fails, be sure you have set the DEFINES correctly in the top 1456e7d3316Smrg Imakefile to suit your machine. 1466e7d3316Smrg 1476e7d3316Smrg<h4>NOTE ON USING IMAKE:</h4> 1486e7d3316Smrg<p> 1496e7d3316Smrg Building the XPM distribution with imake requires to have imake 1506e7d3316Smrg <strong>correctly installed and configured</strong> on your 1516e7d3316Smrg system. I do my best at tweaking the Imakefiles so they work with 1526e7d3316Smrg as many imake flavors people might have as possible but there is 1536e7d3316Smrg nothing I can do against wrong imake configurations. So if your 1546e7d3316Smrg build fails using imake, don't send me email for advice. Get your 1556e7d3316Smrg imake configuration fixed or forget about it! 1566e7d3316Smrg 1576e7d3316Smrg 1586e7d3316Smrg<h3><a name="sec4.2">4.2. Without imake</a></h3> 1596e7d3316Smrg<p> 1606e7d3316Smrg A set of makefiles is provided for those who do not have imake 1616e7d3316Smrg available on their system. However, this is only provided as a 1626e7d3316Smrg convenience and you should be considered as a starting point and not as 1636e7d3316Smrg something ready to use. These makefiles, called Makefile.noX, will most 1646e7d3316Smrg likely require some editing in order be set accordingly to your system. 1656e7d3316Smrg<p> 1666e7d3316Smrg Once this setting is done, you should be able to compile XPM, by 1676e7d3316Smrg executing the following command: 1686e7d3316Smrg<pre> 1696e7d3316Smrg make -f Makefile.noX 1706e7d3316Smrg</pre> 1716e7d3316Smrg<p> 1726e7d3316Smrg Then to install it, do: 1736e7d3316Smrg<pre> 1746e7d3316Smrg make -f Makefile.noX install 1756e7d3316Smrg</pre> 1766e7d3316Smrg 1776e7d3316Smrg 1786e7d3316Smrg<h2><a name="sec5">5. SXPM</a></h2> 1796e7d3316Smrg<p> 1806e7d3316SmrgIn addition to the library the sxpm tool is provided to show XPM file and 1816e7d3316Smrgconvert them from XPM1 or XPM2 to XPM version 3. If you have previously done 1826e7d3316Smrg'make' or 'make all' you should already have it, otherwise just do: 1836e7d3316Smrg<pre> 1846e7d3316Smrg cd sxpm; make 1856e7d3316Smrg</pre> 1866e7d3316Smrg<p> 1876e7d3316SmrgThis application shows you most of the features of XPM and its source can be 1886e7d3316Smrgused to quickly see how to use the provided functions. 1896e7d3316Smrg<p> 1906e7d3316SmrgBy executing 'sxpm -help' you will get the usage. 1916e7d3316Smrg<p> 1926e7d3316SmrgExecuting 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData 1936e7d3316Smrgfunction. The pixmap is created from the static variable plaid defined in the 1946e7d3316Smrgsxpm.c file. sxpm will end when you press the key 'q' in the created window. 1956e7d3316Smrg<p> 1966e7d3316SmrgExecuting 'sxpm -plaid -sc lines_in_mix blue' will show the feature of 1976e7d3316Smrgoverriding color symbols giving a colorname, executing 'sxpm -plaid -sp 1986e7d3316Smrglines_in_mix 1' will show overriding giving a pixel value, and executing 'sxpm 1996e7d3316Smrg-plaid -cp red 0' will show overriding giving a color value. 2006e7d3316Smrg<p> 2016e7d3316SmrgThen you should try 'sxpm -plaid -o output' to get an output file using the 2026e7d3316SmrgXpmWriteFileFromPixmap function. 2036e7d3316Smrg<p> 2046e7d3316SmrgYou can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly 2056e7d3316Smrgget the pixmap printed out on the standard output with colornames instead of 2066e7d3316Smrgrgb values. 2076e7d3316Smrg<p> 2086e7d3316SmrgThen you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function, 2096e7d3316Smrgand 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled. 2106e7d3316Smrg<p> 2116e7d3316SmrgThe XpmCreatePixmapFromData function is on purpose called without any XpmInfos 2126e7d3316Smrgflag to show the utility of this one. Indeed, compare the color section of the 2136e7d3316Smrgtwo files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod 2146e7d3316Smrgplaid.xpm -o bar'. All the default colors and also the comments have been 2156e7d3316Smrgrestored. 2166e7d3316Smrg<p> 2176e7d3316SmrgTo end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how 2186e7d3316Smrgextensions are handled. 2196e7d3316Smrg<p> 2206e7d3316SmrgOf course, other combinations are allowed and should be tried. Thus, 'sxpm 2216e7d3316Smrgplaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2 2226e7d3316Smrgto a XPM version 3 using sxpm. 2236e7d3316Smrg<p> 2246e7d3316SmrgSee the manual page for more detail. 2256e7d3316Smrg 2266e7d3316Smrg 2276e7d3316Smrg<h2><a name="sec6">6. CXPM</a></h2> 2286e7d3316Smrg<p> 2296e7d3316SmrgThe cxpm tool is provided to help you figure out whether an XPM file is correct 2306e7d3316Smrgor not with regard to its format. If you have previously done 'make' or 2316e7d3316Smrg'make all' you should already have it, otherwise just do: 2326e7d3316Smrg<pre> 2336e7d3316Smrg cd cxpm; make 2346e7d3316Smrg</pre> 2356e7d3316Smrg<p> 2366e7d3316SmrgThe related man page will tell you everything about it but here is a simple 2376e7d3316Smrgexample of what it does: 2386e7d3316Smrg<pre> 2396e7d3316Smrg$ ./cxpm bogus_pixmap 2406e7d3316SmrgXpm Error: Invalid XPM file. 2416e7d3316SmrgError found line 3 near character 5 2426e7d3316Smrg</pre> 2436e7d3316Smrg<p> 2446e7d3316SmrgIt is pretty limited but at least, unlike sxpm, it gives you some hint on where 24519569120Smrgthe error occurred within the file. 2466e7d3316Smrg 2476e7d3316Smrg 2486e7d3316Smrg<h2><a name="sec7">7. Other Tools</a></h2> 2496e7d3316Smrg<p> 2506e7d3316SmrgSeveral converters dealing with XPM and a pixmap editor can be found in the 2516e7d3316Smrgxpm-contrib distribution. Also I recommend the use of netpbm to do any kind of 2526e7d3316Smrggeneral image operations such as scaling, resizing, dithering, and to convert 2536e7d3316Smrgfrom and to any other image format. 2546e7d3316Smrg 2556e7d3316Smrg<h2><a name="sec8">8. Discussion</a></h2> 2566e7d3316Smrg<p> 2576e7d3316SmrgThere is a mailing list to discuss about XPM which is <a 2586e7d3316Smrghref="mailto:xpm-talk@sophia.inria.fr">xpm-talk@sophia.inria.fr</a>. 2596e7d3316SmrgAny request to subscribe should be sent to <a 2606e7d3316Smrghref="mailto:xpm-talk-request@sophia.inria.fr">xpm-talk-request@sophia.inria.fr</a>. 2616e7d3316SmrgThe archive of the xpm-talk list is available through the web at 2626e7d3316Smrg<a 2636e7d3316Smrghref="http://zenon.inria.fr/koala/xpm-talk-hypermail">http://zenon.inria.fr/koala/xpm-talk-hypermail</a> 2646e7d3316Smrgand through ftp at <a 2656e7d3316Smrghref="ftp://koala.inria.fr/pub/xpm/xpm-talk-archive">ftp://koala.inria.fr/pub/xpm/xpm-talk-archive</a> 2666e7d3316Smrg<p> 2676e7d3316SmrgPlease mail any bug reports or modifications done, comments, suggestions, 2686e7d3316Smrgrequests for updates or patches to port on another machine to: 2696e7d3316Smrg 2706e7d3316Smrg<p>Email: <a href="lehors@sophia.inria.fr">lehors@sophia.inria.fr</a> 2716e7d3316Smrg<br>Phone: +33 (0)4 93 65 78 89 2726e7d3316Smrg<br>Surface Mail:<br> 2736e7d3316SmrgArnaud Le Hors<br> 2746e7d3316SmrgInria BP.93<br> 2756e7d3316Smrg2004, Route des lucioles<br> 2766e7d3316Smrg06902 Sophia Antipolis Cedex<br> 2776e7d3316SmrgFRANCE 2786e7d3316Smrg 2796e7d3316Smrg 2806e7d3316Smrg<hr> 2816e7d3316Smrg<h2><a name="copy">Copyright (C) 1989-95 GROUPE BULL</a></h2> 2826e7d3316Smrg<p> 2836e7d3316SmrgPermission is hereby granted, free of charge, to any person obtaining a copy 2846e7d3316Smrgof this software and associated documentation files (the "Software"), to 2856e7d3316Smrgdeal in the Software without restriction, including without limitation the 2866e7d3316Smrgrights to use, copy, modify, merge, publish, distribute, sublicense, and/or 2876e7d3316Smrgsell copies of the Software, and to permit persons to whom the Software is 2886e7d3316Smrgfurnished to do so, subject to the following conditions: 2896e7d3316Smrg<p> 2906e7d3316SmrgThe above copyright notice and this permission notice shall be included in 2916e7d3316Smrgall copies or substantial portions of the Software. 2926e7d3316Smrg<p> 2936e7d3316SmrgTHE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 2946e7d3316SmrgIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 2956e7d3316SmrgFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL 2966e7d3316SmrgGROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN 2976e7d3316SmrgAN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN 2986e7d3316SmrgCONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. 2996e7d3316Smrg<p> 3006e7d3316SmrgExcept as contained in this notice, the name of GROUPE BULL shall not be 3016e7d3316Smrgused in advertising or otherwise to promote the sale, use or other dealings 3026e7d3316Smrgin this Software without prior written authorization from GROUPE BULL. 3036e7d3316Smrg</body> 304