README.AMIGA
1The XPM library for Amiga works best with AmigaOS 3.x, but will work
2(with limited color support) with earlier OS versions too. It can be
3compiled with both SAS/C and GCC (makefiles are included).
4
5All functions except the Xpm*Pixmap* functions are supported.
6
7I have also written some Amiga-specific utility functions (not
8included). Contact me if you would like to have them too.
9
10-Lorens Younes (d93-hyo@nada.kth.se)
11
README.html
1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html lang="en">
3<HEAD>
4<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
5<TITLE>XPM README</TITLE>
6</HEAD>
7
8<body>
9<h1 align="center">XPM README</h1>
10
11<h2>Contents</h2>
12
13<ol>
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>
18<ol>
19<li><a href="#sec4.1">With imake</a>
20<li><a href="#sec4.2">Without imake</a>
21</ol>
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>
27</ol>
28
29
30<h2><a name="sec1">1. What Is XPM?</a></h2>
31<p>
32XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.
33<p>
34Here is provided a library containing a set of four functions, similar to the
35X bitmap functions as defined in the Xlib: <code>XpmCreatePixmapFromData</code>,
36<code>XpmCreateDataFromPixmap</code>, <code>XpmReadFileToPixmap</code> and <code>XpmWriteFileFromPixmap</code> for
37respectively including, storing, reading and writing this format, plus four
38other: <code>XpmCreateImageFromData</code>, <code>XpmCreateDataFromImage</code>, <code>XpmReadFileToImage</code> and
39<code>XpmWriteFileFromImage</code> for working with images instead of pixmaps.
40<p>
41This new version provides a C includable format, defaults for different types
42of display: monochrome/color/grayscale, hotspot coordinates and symbol names
43for colors for overriding default colors when creating the pixmap. It provides
44a mechanism for storing information while reading a file which is re-used
45while writing. This way comments, default colors and symbol names aren't lost.
46It also handles "transparent pixels" by returning a shape mask in addition to
47the created pixmap.
48<p>
49See the XPM Manual for details.
50
51
52<h2><a name="sec2">2. Where to get XPM?</a></h2>
53<p>
54New 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
56href="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:
58<br>Boston, USA: <a
59href="ftp://ftp.x.org/contrib">ftp://ftp.x.org/contrib</a>
60<br>Sophia Antipolis, France: <a
61href="ftp://koala.inria.fr/pub/xpm">ftp://koala.inria.fr/pub/xpm</a>
62
63
64<h2><a name="sec3">3. Documentation</a></h2>
65<p>
66Old users might read the <a href="CHANGES">CHANGES</a> file for a history
67of changes interesting the user.
68<p>
69Read the doc. The documentation is in PostScript format (<a
70href="doc/xpm.PS">doc/xpm.PS</a>) and has been produced with
71FrameMaker. The source files are available on request.
72<p>
73A <a href="FAQ.html">FAQ</a> (Frequently Asked Questions) is also provided,
74so if you experience any problem you should have a look at this file.
75
76
77<h2><a name="sec4">4. Installation</a></h2>
78<p>
79To obtain the XPM library, first uncompress and untar the compressed tar file
80in an appropriate directory.
81<p>
82Then you can either compile XPM via "imake" or in a stand-alone way.
83
84<h3><a name="sec4.1">4.1. With imake</a></h3>
85<p>
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.
93<p>
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.
98<p>
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.
110<p>
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.
116<p>
117 Then execute the following command:
118<pre>
119 xmkmf -a
120</pre>
121<p>
122 or if this option is not supported by your version of xmkmf:
123<pre>
124 xmkmf
125 make Makefiles
126 make includes
127 make depend (optional)
128</pre>
129<p>
130 Then simply execute:
131<pre>
132 make
133</pre>
134<p>
135 which will build the XPM library and the sxpm application.
136 Then do:
137<pre>
138 make install
139 make install.man
140</pre>
141<p>
142 which will install the library and the sxpm program and man page.
143<p>
144 If it fails, be sure you have set the DEFINES correctly in the top
145 Imakefile to suit your machine.
146
147<h4>NOTE ON USING IMAKE:</h4>
148<p>
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!
156
157
158<h3><a name="sec4.2">4.2. Without imake</a></h3>
159<p>
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.
165<p>
166 Once this setting is done, you should be able to compile XPM, by
167 executing the following command:
168<pre>
169 make -f Makefile.noX
170</pre>
171<p>
172 Then to install it, do:
173<pre>
174 make -f Makefile.noX install
175</pre>
176
177
178<h2><a name="sec5">5. SXPM</a></h2>
179<p>
180In addition to the library the sxpm tool is provided to show XPM file and
181convert 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:
183<pre>
184 cd sxpm; make
185</pre>
186<p>
187This application shows you most of the features of XPM and its source can be
188used to quickly see how to use the provided functions.
189<p>
190By executing 'sxpm -help' you will get the usage.
191<p>
192Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData
193function. The pixmap is created from the static variable plaid defined in the
194sxpm.c file. sxpm will end when you press the key 'q' in the created window.
195<p>
196Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of
197overriding color symbols giving a colorname, executing 'sxpm -plaid -sp
198lines_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.
200<p>
201Then you should try 'sxpm -plaid -o output' to get an output file using the
202XpmWriteFileFromPixmap function.
203<p>
204You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly
205get the pixmap printed out on the standard output with colornames instead of
206rgb values.
207<p>
208Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function,
209and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.
210<p>
211The XpmCreatePixmapFromData function is on purpose called without any XpmInfos
212flag to show the utility of this one. Indeed, compare the color section of the
213two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod
214plaid.xpm -o bar'. All the default colors and also the comments have been
215restored.
216<p>
217To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how
218extensions are handled.
219<p>
220Of course, other combinations are allowed and should be tried. Thus, 'sxpm
221plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2
222to a XPM version 3 using sxpm.
223<p>
224See the manual page for more detail.
225
226
227<h2><a name="sec6">6. CXPM</a></h2>
228<p>
229The cxpm tool is provided to help you figure out whether an XPM file is correct
230or not with regard to its format. If you have previously done 'make' or
231'make all' you should already have it, otherwise just do:
232<pre>
233 cd cxpm; make
234</pre>
235<p>
236The related man page will tell you everything about it but here is a simple
237example of what it does:
238<pre>
239$ ./cxpm bogus_pixmap
240Xpm Error: Invalid XPM file.
241Error found line 3 near character 5
242</pre>
243<p>
244It is pretty limited but at least, unlike sxpm, it gives you some hint on where
245the error occurred within the file.
246
247
248<h2><a name="sec7">7. Other Tools</a></h2>
249<p>
250Several converters dealing with XPM and a pixmap editor can be found in the
251xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of
252general image operations such as scaling, resizing, dithering, and to convert
253from and to any other image format.
254
255<h2><a name="sec8">8. Discussion</a></h2>
256<p>
257There is a mailing list to discuss about XPM which is <a
258href="mailto:xpm-talk@sophia.inria.fr">xpm-talk@sophia.inria.fr</a>.
259Any request to subscribe should be sent to <a
260href="mailto:xpm-talk-request@sophia.inria.fr">xpm-talk-request@sophia.inria.fr</a>.
261The archive of the xpm-talk list is available through the web at
262<a
263href="http://zenon.inria.fr/koala/xpm-talk-hypermail">http://zenon.inria.fr/koala/xpm-talk-hypermail</a>
264and through ftp at <a
265href="ftp://koala.inria.fr/pub/xpm/xpm-talk-archive">ftp://koala.inria.fr/pub/xpm/xpm-talk-archive</a>
266<p>
267Please mail any bug reports or modifications done, comments, suggestions,
268requests for updates or patches to port on another machine to:
269
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>
273Arnaud Le Hors<br>
274Inria BP.93<br>
2752004, Route des lucioles<br>
27606902 Sophia Antipolis Cedex<br>
277FRANCE
278
279
280<hr>
281<h2><a name="copy">Copyright (C) 1989-95 GROUPE BULL</a></h2>
282<p>
283Permission is hereby granted, free of charge, to any person obtaining a copy
284of this software and associated documentation files (the "Software"), to
285deal in the Software without restriction, including without limitation the
286rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
287sell copies of the Software, and to permit persons to whom the Software is
288furnished to do so, subject to the following conditions:
289<p>
290The above copyright notice and this permission notice shall be included in
291all copies or substantial portions of the Software.
292<p>
293THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
294IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
295FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
296GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
297AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
298CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
299<p>
300Except as contained in this notice, the name of GROUPE BULL shall not be
301used in advertising or otherwise to promote the sale, use or other dealings
302in this Software without prior written authorization from GROUPE BULL.
303</body>
304
README.MSW
1
2README.MSW hedu@cul-ipn.uni-kiel.de 5/94
3
4 The XPM library for MS-Windows
5
6Motivated by the wxWindows library, which is a (freely available) toolkit
7for developing multi-platform, graphical applications from the same body
8of C++ code, I wanted to have XPM pixmaps for MS-windows. Instead of rewriting
9a XPM-parser I managed to port the XPM-library-code to MS-windows.
10Thanks to Anaud Le Hors this became a part of the official XPM-library.
11
12Until now it's only used together with wxWindows. And even there it's more
13a kind of beta. But it should be possible to run it as a simple libxpm.a
14without wxWindows.
15
16The key is a transformation of some X types plus some basic X functions.
17There is not yet a special MSW-API, so you should know the X types used.
18
19The following is done in simx.h:
20
21typedef HDC Display;
22typedef COLORREF Pixel;
23
24typedef struct {
25 Pixel pixel;
26 BYTE red, green, blue;
27} XColor;
28
29typedef struct {
30 HBITMAP bitmap;
31 unsigned int width;
32 unsigned int height;
33 unsigned int depth;
34} XImage;
35
36With these defines and the according functions from simx.c you can call
37XPM-functions the way it's done under X windows. It can look like this:
38
39 ErrorStatus=XpmCreateImageFromData(&dc, data,
40 &ximage,(XImage **)NULL, &xpmAttr);
41 ms_bitmap = ximage->bitmap;
42 // releases the malloc,but do not destroy the bitmap
43 XImageFree(ximage);
44
45Supported functions are the Xpm*Image* but not the Xpm*Pixmap*.
46
47DRAWBACKS:
48The main drawback is the missing support for Colormaps! There was nothing for
49it in wxWindows, so I did not know how to deal with Colormaps.
50
51The size of the pixmaps is bounded by malloc() (width*height*2 < 64K).
52
53Close colors do not look that close. But that seems to be the window system.
54
55Neither a special API for MSW nor a special MSW documentation other than this.
56(I can only point you to wxxpm as an example , see below.)
57
58INSTALLATION:
59There is not yet a makefile with it. Simply take all the *.c files
60into your project except the files related to Pixmap operations: *P*.c.
61!!!You MUST set FOR_MSW on the preprocessor options!!!
62(You might uncomment NEED_STRCASECMP in xpm.h if it's in your lib)
63This should compile into libxpm.a. Good luck...
64
65FTP:
66wxWindows is currently available from the Artificial Intelligence
67Applications Institute (University of Edinburgh) by anonymous FTP.
68 skye.aiai.ed.ac.uk pub/wxwin/
69or read http://burray.aiai.ed.ac.uk/aiai/aiai.html
70
71wxxpm, XPM support for wxWindows, the latest version is available at
72 yoda.cul-ipn.uni-kiel.de pub/wxxpm/
73 and maybe in the contrib or tools of wxWindows
74
75Please contact me if you have suggestions, comments or problems!
76
77================================================================
78Some fixes and comments by Jan Wielemaker (jan@swi.psy.uva.nl),
79Oct 24, 1996:
80
81 * Please try not to disturb me on this, XPM is not my
82 piece of cake.
83
84 * Hermann Dunkel has apparently moved in virtual space.
85
86Changes:
87
88 * I've used the xpm package under NT 4.0 and MSVC++ 4.2.
89
90 * I've made a big performance improvement in
91 ParseAndPutPixels(), fixed creation of the mask in
92 SetColor() in create.c. I looked into XCreateImage()
93 in simx.c, but commented out my improvement for reasons
94 you'll find there. If you know what is going on, statement
95 (1) does not apply to you.
96
97Comments on installation:
98
99 * Donot include the to/from pixmap files into the project.
100 These are the ones containing a capital P somewhere in their
101 name. You can also first include all, and then remove all
102 the files you get errors on :-)
103
104 * The DC that is requested should be a valid memory DC, thus
105 CreateCompatibleDC(NULL) provides a good generic one, but
106 GetDC(NULL) doesn't! This costed me some time.
107
108 * The real difficulty is using the mask, mostly due to the
109 bad documentation. If 95 or NT is your target, use:
110
111 MaskBlt(context.hdc, // Destination DC
112 x, y, w, h, // Destination area
113 mhdc, // Memory DC with the image selected
114 sx, sy, // Source X,Y
115 msk, // HBITMAP of the mask
116 sx, sy, // Mask X,Y
117 MAKEROP4(SRCPAINT, SRCCOPY)); // The magic op code.
118================================================================
119
120
121--
122 ////|\\\\ \\\\\\ Hermann Dunkel
123 O O ////// IPN Uni Kiel, Germany
124 | \\\\\\ Tel: +49 431 / 880 3144
125 \___/ ////// E-mail: hedu@cul-ipn.uni-kiel.de
126 \_/ \\\\\\ X.400 : c=de;a=d400;p=uni-kiel;ou=nw-didaktik;s=dunkel
127
128