1
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
4
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5
<TITLE>XPM README</TITLE>
9
<h1 align="center">XPM README</h1>
14
<li><a href="#sec1">What Is XPM?</a>
15
<li><a href="#sec2">Where to get XPM?</a>
16
<li><a href="#sec3">Documentation</a>
17
<li><a href="#sec4">Installation</a>
19
<li><a href="#sec4.1">With imake</a>
20
<li><a href="#sec4.2">Without imake</a>
22
<li><a href="#sec5">SXPM</a>
23
<li><a href="#sec6">CXPM</a>
24
<li><a href="#sec7">Other Tools</a>
25
<li><a href="#sec8">Discussion</a>
26
<li><a href="#copy">Copyright</a>
30
<h2><a name="sec1">1. What Is XPM?</a></h2>
32
XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
34
Here is provided a library containing a set of four functions, similar to the
35
X bitmap functions as defined in the Xlib: <code>XpmCreatePixmapFromData</code>,
36
<code>XpmCreateDataFromPixmap</code>, <code>XpmReadFileToPixmap</code> and <code>XpmWriteFileFromPixmap</code> for
37
respectively including, storing, reading and writing this format, plus four
38
other: <code>XpmCreateImageFromData</code>, <code>XpmCreateDataFromImage</code>, <code>XpmReadFileToImage</code> and
39
<code>XpmWriteFileFromImage</code> for working with images instead of pixmaps.
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
49
See the XPM Manual for details.
52
<h2><a name="sec2">2. Where to get XPM?</a></h2>
54
New XPM updates are announced on the comp.windows.x newsgroup, and on the
55
"xpm-talk" list and you can always consult the XPM Home page at <a
56
href="http://www.inria.fr/koala/lehors/xpm.html">http://www.inria.fr/koala/lehors/xpm.html</a>
57
<p>The latest "official" XPM release can always be found at:
59
href="ftp://ftp.x.org/contrib">ftp://ftp.x.org/contrib</a>
60
<br>Sophia Antipolis, France: <a
61
href="ftp://koala.inria.fr/pub/xpm">ftp://koala.inria.fr/pub/xpm</a>
64
<h2><a name="sec3">3. Documentation</a></h2>
66
Old users might read the <a href="CHANGES">CHANGES</a> file for a history
67
of changes interesting the user.
69
Read the doc. The documentation is in PostScript format (<a
70
href="doc/xpm.PS">doc/xpm.PS</a>) and has been produced with
71
FrameMaker. The source files are available on request.
73
A <a href="FAQ.html">FAQ</a> (Frequently Asked Questions) is also provided,
74
so if you experience any problem you should have a look at this file.
77
<h2><a name="sec4">4. Installation</a></h2>
79
To obtain the XPM library, first uncompress and untar the compressed tar file
80
in an appropriate directory.
82
Then you can either compile XPM via "imake" or in a stand-alone way.
84
<h3><a name="sec4.1">4.1. With imake</a></h3>
86
Imakefiles are provided to build both shared and unshared libraries.
87
However, building a shared lib is very OS dependent and often requires
88
specific files which are not available. Also config files are often not
89
set correctly for this task. So if it fails you can avoid trying to
90
build one and simply build the static library instead. In order to do
91
so you should edit the top Imakefile to add -DSharedLibXpm=NO to the
92
definition of IMAKE_DEFINES as described.
94
The compilation and installation of the library and the sxpm program
95
should only require you to edit the top Imakefile. But you should do so
96
in order to specify the locations where the various files should be
97
installed and to set the DEFINES variable accordingly to your system.
99
On Solaris 2.* the compilation works only in the native svr4
100
environment, avoid the bsd one or it won't compile. Especially you
101
should be using /opt/SUNWspro/bin/cc and not /usr/ucb/cc.
102
Also since the compiler is no longer part of the OS distribution a lot
103
of people use gcc instead. This is fine, but be aware that the imake
104
tool you get as part of the X Window System on a solaris box is
105
configured for cc. Therefore the compilation using the generated
106
Makefiles will not succeed unless you have changed the default
107
configuration. An easy work around is to directly edit the generated
108
lib/Makefile to change '-K pic' to '-fpic'. Fixing your imake
109
configuration would be better though.
111
On Linux, if you do not use ELF yet you'd better get the binary
112
distribution available from sunsite. Because it's really a pain to
113
build a shared lib and the current XPM distribution doesn't contain
114
the jump files you would need to do so. On the other hand people have
115
had no problems building it using ELF.
117
Then execute the following command:
122
or if this option is not supported by your version of xmkmf:
127
make depend (optional)
135
which will build the XPM library and the sxpm application.
142
which will install the library and the sxpm program and man page.
144
If it fails, be sure you have set the DEFINES correctly in the top
145
Imakefile to suit your machine.
147
<h4>NOTE ON USING IMAKE:</h4>
149
Building the XPM distribution with imake requires to have imake
150
<strong>correctly installed and configured</strong> on your
151
system. I do my best at tweaking the Imakefiles so they work with
152
as many imake flavors people might have as possible but there is
153
nothing I can do against wrong imake configurations. So if your
154
build fails using imake, don't send me email for advice. Get your
155
imake configuration fixed or forget about it!
158
<h3><a name="sec4.2">4.2. Without imake</a></h3>
160
A set of makefiles is provided for those who do not have imake
161
available on their system. However, this is only provided as a
162
convenience and you should be considered as a starting point and not as
163
something ready to use. These makefiles, called Makefile.noX, will most
164
likely require some editing in order be set accordingly to your system.
166
Once this setting is done, you should be able to compile XPM, by
167
executing the following command:
172
Then to install it, do:
174
make -f Makefile.noX install
178
<h2><a name="sec5">5. SXPM</a></h2>
180
In addition to the library the sxpm tool is provided to show XPM file and
181
convert them from XPM1 or XPM2 to XPM version 3. If you have previously done
182
'make' or 'make all' you should already have it, otherwise just do:
187
This application shows you most of the features of XPM and its source can be
188
used to quickly see how to use the provided functions.
190
By executing 'sxpm -help' you will get the usage.
192
Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
193
function. The pixmap is created from the static variable plaid defined in the
194
sxpm.c file. sxpm will end when you press the key 'q' in the created window.
196
Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
197
overriding color symbols giving a colorname, executing 'sxpm -plaid -sp
198
lines_in_mix 1' will show overriding giving a pixel value, and executing 'sxpm
199
-plaid -cp red 0' will show overriding giving a color value.
201
Then you should try 'sxpm -plaid -o output' to get an output file using the
202
XpmWriteFileFromPixmap function.
204
You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
205
get the pixmap printed out on the standard output with colornames instead of
208
Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
209
and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
211
The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
212
flag to show the utility of this one. Indeed, compare the color section of the
213
two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
214
plaid.xpm -o bar'. All the default colors and also the comments have been
217
To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
218
extensions are handled.
220
Of course, other combinations are allowed and should be tried. Thus, 'sxpm
221
plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
222
to a XPM version 3 using sxpm.
224
See the manual page for more detail.
227
<h2><a name="sec6">6. CXPM</a></h2>
229
The cxpm tool is provided to help you figure out whether an XPM file is correct
230
or not with regard to its format. If you have previously done 'make' or
231
'make all' you should already have it, otherwise just do:
236
The related man page will tell you everything about it but here is a simple
237
example of what it does:
239
$ ./cxpm bogus_pixmap
240
Xpm Error: Invalid XPM file.
241
Error found line 3 near character 5
244
It is pretty limited but at least, unlike sxpm, it gives you some hint on where
245
the error occured within the file.
248
<h2><a name="sec7">7. Other Tools</a></h2>
250
Several converters dealing with XPM and a pixmap editor can be found in the
251
xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
252
general image operations such as scaling, resizing, dithering, and to convert
253
from and to any other image format.
255
<h2><a name="sec8">8. Discussion</a></h2>
257
There is a mailing list to discuss about XPM which is <a
258
href="mailto:xpm-talk@sophia.inria.fr">xpm-talk@sophia.inria.fr</a>.
259
Any request to subscribe should be sent to <a
260
href="mailto:xpm-talk-request@sophia.inria.fr">xpm-talk-request@sophia.inria.fr</a>.
261
The archive of the xpm-talk list is available through the web at
263
href="http://zenon.inria.fr/koala/xpm-talk-hypermail">http://zenon.inria.fr/koala/xpm-talk-hypermail</a>
264
and through ftp at <a
265
href="ftp://koala.inria.fr/pub/xpm/xpm-talk-archive">ftp://koala.inria.fr/pub/xpm/xpm-talk-archive</a>
267
Please mail any bug reports or modifications done, comments, suggestions,
268
requests for updates or patches to port on another machine to:
270
<p>Email: <a href="lehors@sophia.inria.fr">lehors@sophia.inria.fr</a>
271
<br>Phone: +33 (0)4 93 65 78 89
272
<br>Surface Mail:<br>
275
2004, Route des lucioles<br>
276
06902 Sophia Antipolis Cedex<br>
281
<h2><a name="copy">Copyright (C) 1989-95 GROUPE BULL</a></h2>
283
Permission is hereby granted, free of charge, to any person obtaining a copy
284
of this software and associated documentation files (the "Software"), to
285
deal in the Software without restriction, including without limitation the
286
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
287
sell copies of the Software, and to permit persons to whom the Software is
288
furnished to do so, subject to the following conditions:
290
The above copyright notice and this permission notice shall be included in
291
all copies or substantial portions of the Software.
293
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
294
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
295
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
296
GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
297
AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
298
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
300
Except as contained in this notice, the name of GROUPE BULL shall not be
301
used in advertising or otherwise to promote the sale, use or other dealings
302
in this Software without prior written authorization from GROUPE BULL.