This is the README file for the raster widget, release 0.1.
The only differences between version 0.0 and this one consists of bug
fixes. 

I've also included a file called tkv.tcl which is a simple image
displaying utility. It views portable pixmaps, gif pictures (with the
aid of giftoppm -- part of Jef Poskanzer's Pbmplus package) and
jpeg pictures (with the aid of the djpeg program -- see file jpegsrc.v4.tar.Z
at ftp.uu.net). 

The original README file follows:

------------------------------------------------------------------------------

Well, folks, you asked for it. This is the "raster" tk widget. 

Q: What is it for?

A: It's for people who want to produce drawings from within a tcl script
   but do not want to use the "canvas" widget.

Q: In what way is a "raster" different from a "canvas"?
 
A: A Canvas implements structured drawing whereas a "raster" implements
   bitmapped graphics. In short, after you draw something on a "canvas"
   you can still change your mind and modify its appearance, location,
   dimension etc. If you draw it on a "raster", the only net effect is
   that some pixels will change colors -- and that's it.

Q: So you mean that I will have to take care of "Expose" events and all that?

A: No. Associated with a "raster" there's a backing "pixmap" that is copied
   to the window in case of an "Expose".

Q: What kind of drawing primitives are implemented?

A: Not many. You can draw points, rectangles, lines and polygons. You can
   new primitives, though -- read the documentation.

Q: What documentation?

A: There's a postscript file called raster.ps that describes the raster widget.
   The LaTeX source file, raster.tex, is also included.

Q: How do you compile this stuff?

A: Change the definition of INCDIRS and LIBDIRS in the Makefile so they
   point to the directories where the X, Tcl and Tk files are installed.
   (Don't forget to precede each the name of each "include" directory
   in INCDIRS with -I and each library directory in LIBDIRS with -L). After
   this, type "make raster_wish" and stand back. If everything goes right,
   you should have raster_wish, a tcl/tk windowing shell extended with
   the raster widget.

Q: Have you tested it?

A: Sort of. I compiled this stuff in a Sun SparcStation with "gcc" and SunOS. 
   I have no idea if there's any portability problem if you try to use a 
   Dec Alpha, Linux, HP or whatever, since I don't have access to any of
   these here. I also do not know how to "install" the software, since
   I don't have superuser privileges and all that. You people out there
   should be able to figure these things out for yourselves (Sorry).

Q: And what's image_wish?

A: It's a BONUS! If you succeeded in making raster_wish, try "make image_wish".
   In short, image_wish is raster_wish where the raster widget command was
   extended with the "image" option - it allows you to manipulate areas
   of the raster's pixmap and even load/save (ppm) images. You should look at
   the code (ugly as it is) in order to get some hints on how to extend
   a raster widget.

Q: Documentation for image_wish?

A: Nope, there's none yet. I can give you a summary of the image options, 
   though:
   <raster> image create <imgname> <nx> <ny> : creates an internal memory
       buffer called <imgname> which is big enough to hold an image of
       <nx> by <ny> pixels.
   <raster> image delete <imgname> : deallocates image <imgname>
   <raster> image get <imgname> <x> <y> : copies pixels starting from position
       <x> <y> of the raster widget to image <imgname>. The width and 
       height of the area to be copied correspond to the size of the image.
   <raster> image put <imgname> <x> <y> : copies pixels from image <imgname> to
       position <x> <y> of the raster widget.
   <raster> image load <imgname> <ppmfilename> : creates an internal image 
       corresponding (roughly) to the portable pixmap file <ppmfilename>.
       (Note: the code for this option works for my 8 bit plane display -- may
       not work for a monochrome or 24 bit plane display -- I have no way
       to know. Also, the color quantization code I use is naive and may
       not produce visually acceptable results)
   <raster> image save <imgname> <ppmfilename> : dumps the contents of image
       <imgname> in raw ppm format as file <ppmfilename>

Q: What do I do with Bugs and Suggestions?

A: Send them to me (esperanc@umiacs.umd.edu). I'll be glad to know. Bug
   fixes though are subject to my availability of time (not much these days).

Q: Thanks!

A: You are welcome.

--Claudio Esperanca
  




