Index of /netbsd/NetBSD-release-10/xsrc/external/mit/libXpm/dist/doc

Icon  Name                                                     Last modified      Size  Description
[PARENTDIR] Parent Directory                                                              -   
[   ] xpm.PS.gz                                                2010-11-21 16:48   48K  
[TXT] FAQ.html                                                 2013-05-31 11:09   13K  
[TXT] Makefile.in                                              2023-10-07 14:34   13K  
[   ] Makefile.am                                              2010-11-21 16:48   83
XPM README

XPM README

Contents

  1. What Is XPM?
  2. Where to get XPM?
  3. Documentation
  4. Installation
    1. With imake
    2. Without imake
  5. SXPM
  6. CXPM
  7. Other Tools
  8. Discussion
  9. Copyright

1. What Is XPM?

XPM (X PixMap) is a format for storing/retrieving X pixmaps to/from files.

Here is provided a library containing a set of four functions, similar to the X bitmap functions as defined in the Xlib: XpmCreatePixmapFromData, XpmCreateDataFromPixmap, XpmReadFileToPixmap and XpmWriteFileFromPixmap for respectively including, storing, reading and writing this format, plus four other: XpmCreateImageFromData, XpmCreateDataFromImage, XpmReadFileToImage and XpmWriteFileFromImage for working with images instead of pixmaps.

This new version provides a C includable format, defaults for different types of display: monochrome/color/grayscale, hotspot coordinates and symbol names for colors for overriding default colors when creating the pixmap. It provides a mechanism for storing information while reading a file which is re-used while writing. This way comments, default colors and symbol names aren't lost. It also handles "transparent pixels" by returning a shape mask in addition to the created pixmap.

See the XPM Manual for details.

2. Where to get XPM?

New XPM updates are announced on the comp.windows.x newsgroup, and on the "xpm-talk" list and you can always consult the XPM Home page at http://www.inria.fr/koala/lehors/xpm.html

The latest "official" XPM release can always be found at:
Boston, USA: ftp://ftp.x.org/contrib
Sophia Antipolis, France: ftp://koala.inria.fr/pub/xpm

3. Documentation

Old users might read the CHANGES file for a history of changes interesting the user.

Read the doc. The documentation is in PostScript format (doc/xpm.PS) and has been produced with FrameMaker. The source files are available on request.

A FAQ (Frequently Asked Questions) is also provided, so if you experience any problem you should have a look at this file.

4. Installation

To obtain the XPM library, first uncompress and untar the compressed tar file in an appropriate directory.

Then you can either compile XPM via "imake" or in a stand-alone way.

4.1. With imake

Imakefiles are provided to build both shared and unshared libraries. However, building a shared lib is very OS dependent and often requires specific files which are not available. Also config files are often not set correctly for this task. So if it fails you can avoid trying to build one and simply build the static library instead. In order to do so you should edit the top Imakefile to add -DSharedLibXpm=NO to the definition of IMAKE_DEFINES as described.

The compilation and installation of the library and the sxpm program should only require you to edit the top Imakefile. But you should do so in order to specify the locations where the various files should be installed and to set the DEFINES variable accordingly to your system.

On Solaris 2.* the compilation works only in the native svr4 environment, avoid the bsd one or it won't compile. Especially you should be using /opt/SUNWspro/bin/cc and not /usr/ucb/cc. Also since the compiler is no longer part of the OS distribution a lot of people use gcc instead. This is fine, but be aware that the imake tool you get as part of the X Window System on a solaris box is configured for cc. Therefore the compilation using the generated Makefiles will not succeed unless you have changed the default configuration. An easy work around is to directly edit the generated lib/Makefile to change '-K pic' to '-fpic'. Fixing your imake configuration would be better though.

On Linux, if you do not use ELF yet you'd better get the binary distribution available from sunsite. Because it's really a pain to build a shared lib and the current XPM distribution doesn't contain the jump files you would need to do so. On the other hand people have had no problems building it using ELF.

Then execute the following command: 

		xmkmf -a

or if this option is not supported by your version of xmkmf: 

		xmkmf
		make Makefiles
		make includes
		make depend		(optional)

Then simply execute: 

		make

which will build the XPM library and the sxpm application. Then do: 

	     	make install
		make install.man

which will install the library and the sxpm program and man page.

If it fails, be sure you have set the DEFINES correctly in the top Imakefile to suit your machine.

NOTE ON USING IMAKE:

Building the XPM distribution with imake requires to have imake correctly installed and configured on your system. I do my best at tweaking the Imakefiles so they work with as many imake flavors people might have as possible but there is nothing I can do against wrong imake configurations. So if your build fails using imake, don't send me email for advice. Get your imake configuration fixed or forget about it!

4.2. Without imake

A set of makefiles is provided for those who do not have imake available on their system. However, this is only provided as a convenience and you should be considered as a starting point and not as something ready to use. These makefiles, called Makefile.noX, will most likely require some editing in order be set accordingly to your system.

Once this setting is done, you should be able to compile XPM, by executing the following command: 

	        make -f Makefile.noX

Then to install it, do: 

		make -f Makefile.noX install

5. SXPM

In addition to the library the sxpm tool is provided to show XPM file and convert them from XPM1 or XPM2 to XPM version 3. If you have previously done 'make' or 'make all' you should already have it, otherwise just do: 

		      cd sxpm; make

This application shows you most of the features of XPM and its source can be used to quickly see how to use the provided functions.

By executing 'sxpm -help' you will get the usage.

Executing 'sxpm -plaid' will show a demo of the XpmCreatePixmapFromData function. The pixmap is created from the static variable plaid defined in the sxpm.c file. sxpm will end when you press the key 'q' in the created window.

Executing 'sxpm -plaid -sc lines_in_mix blue' will show the feature of overriding color symbols giving a colorname, executing 'sxpm -plaid -sp lines_in_mix 1' will show overriding giving a pixel value, and executing 'sxpm -plaid -cp red 0' will show overriding giving a color value.

Then you should try 'sxpm -plaid -o output' to get an output file using the XpmWriteFileFromPixmap function.

You can now try 'sxpm -plaid -o - -nod -rgb /usr/lib/X11/rgb.txt' to directly get the pixmap printed out on the standard output with colornames instead of rgb values.

Then you should try 'sxpm plaid.xpm' to use the XpmReadFileToPixmap function, and 'cat plaid_mask.xpm|sxpm' to see how "transparent pixels" are handled.

The XpmCreatePixmapFromData function is on purpose called without any XpmInfos flag to show the utility of this one. Indeed, compare the color section of the two files foo and bar obtained from 'sxpm -nod -plaid -o foo' and 'sxpm -nod plaid.xpm -o bar'. All the default colors and also the comments have been restored.

To end look at plaid_ext.xpm and try "sxpm -nod plaid_ext.xpm -v" to see how extensions are handled.

Of course, other combinations are allowed and should be tried. Thus, 'sxpm plaid.xpm -o output -nod' will show you how to convert a file from XPM1 or XPM2 to a XPM version 3 using sxpm.

See the manual page for more detail.

6. CXPM

The cxpm tool is provided to help you figure out whether an XPM file is correct or not with regard to its format. If you have previously done 'make' or 'make all' you should already have it, otherwise just do: 

		      cd cxpm; make

The related man page will tell you everything about it but here is a simple example of what it does: 

$ ./cxpm bogus_pixmap
Xpm Error: Invalid XPM file.
Error found line 3 near character 5

It is pretty limited but at least, unlike sxpm, it gives you some hint on where the error occurred within the file.

7. Other Tools

Several converters dealing with XPM and a pixmap editor can be found in the xpm-contrib distribution. Also I recommend the use of netpbm to do any kind of general image operations such as scaling, resizing, dithering, and to convert from and to any other image format.

8. Discussion

There is a mailing list to discuss about XPM which is xpm-talk@sophia.inria.fr. Any request to subscribe should be sent to xpm-talk-request@sophia.inria.fr. The archive of the xpm-talk list is available through the web at http://zenon.inria.fr/koala/xpm-talk-hypermail and through ftp at ftp://koala.inria.fr/pub/xpm/xpm-talk-archive

Please mail any bug reports or modifications done, comments, suggestions, requests for updates or patches to port on another machine to:

Email: lehors@sophia.inria.fr
Phone: +33 (0)4 93 65 78 89
Surface Mail:
Arnaud Le Hors
Inria BP.93
2004, Route des lucioles
06902 Sophia Antipolis Cedex
FRANCE

Copyright (C) 1989-95 GROUPE BULL

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL GROUPE BULL BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Except as contained in this notice, the name of GROUPE BULL shall not be used in advertising or otherwise to promote the sale, use or other dealings in this Software without prior written authorization from GROUPE BULL.