GIM -- GIO graphics imaging library.  This is a developmental library based
on GIO escapes, providing IRAF applications with access to the Gterm widget
imaging functions.  This library is tied directly to the Gterm widget and is
expected to be replaced by a more general imaging library in the future.

This library is intended only for clients that need to directly access the
imaging functions in the Gterm widget for full control over the imaging
capabilities of the Gterm widget.  Applications which merely need to display
an image as part of a more complex graphic would probably be better off
using the more device independent gpcell (put cell-array) and gpcmap (put
colormap) calls.


The following functions are direct RPC calls to the corresponding Gt-prefixed
imaging functions in the Gterm widget.

            gim_rasterinit (gp)
          gim_createraster (gp, raster, type, width, height, depth)
         gim_destroyraster (gp, raster)
  exists = gim_queryraster (gp, raster, type, width, height, depth)
	     gim_setraster (gp, raster)		# see gseti(gp,G_RASTER,n)

           gim_writepixels (gp, raster, data, nbits, x1, y1, nx, ny)
            gim_readpixels (gp, raster, data, nbits, x1, y1, nx, ny)
	    gim_refreshpix (gp, raster, ct, x1, y1, nx, ny)
	     gim_setpixels (gp, raster, ct, x1, y1, nx, ny, color, rop)

         gim_writecolormap (gp, colormap, first, nelem, r, g, b)
  nelem = gim_readcolormap (gp, colormap, first, maxelem, r, g, b)
          gim_loadcolormap (gp, colormap, offset, slope)
          gim_freecolormap (gp, colormap)
	    gim_iomapwrite (gp, iomap, first, nelem)
	     gim_iomapread (gp, iomap, first, nelem)

          gim_initmappings (gp)
	   gim_freemapping (gp, mapping)
            gim_copyraster (gp, rop, src,st,sx,sy,sw,sh, dst,dt,dx,dy,dw,dh)
            gim_setmapping (gp, mapping, rop, 
				src,st,sx,sy,sw,sh, dst,dt,dx,dy,dw,dh)
   status = gim_getmapping (gp, mapping, rop,
			        src,st,sx,sy,sw,sh, dst,dt,dx,dy,dw,dh)
         gim_enablemapping (gp, mapping, refresh)
        gim_disablemapping (gp, mapping, erase)
        gim_refreshmapping (gp, mapping)

The following Gterm widget imaging functions have no analogue in the GIM
imaging interface, but can be called from within GUI code.  These functions
are not implemented at the GIM level either because they are not essential
and would be too inefficient to be worth using via RPC, or because they
access resources available only to GUI code.

            GtAssignRaster (gt, raster, drawable)
  pixmap = GtExtractPixmap (gt, src, ct, x, y, width, height)
            GtInsertPixmap (gt, pixmap, dst, ct, x, y, width, height)
   raster = GtSelectRaster (gt, dras, dt, dx, dy, rt, rx, ry, mapping)
     raster = GtNextRaster (gt)
      raster = GtGetRaster (gt)
            n = GtNRasters (gt)
  pixel = GtGetClientPixel (gt, gterm_pixel)
   mapping = GtNextMapping (gt)
  active = GtActiveMapping (gt, mapping)


The following messaging routines are also defined by the GIO interface.
These are used to set the values of UI parameters (i.e., send messages to
the user interface).

		      gmsg (gp, object, message)
	    gmsg[bcsilrdx] (gp, object, value)
		  gmprintf (gp, object, format)


The imaging model of the Gterm widget defines the following key object or
data types: rasters, mappings, and colors.

    raster	A raster is a MxN array of pixels.  At present pixels are 8
		bits deep but hooks are built in to the interface to expand
		this in the future.  Pixel values are indices into the Gterm
		virtual colormap, with values starting at zero.  A raster
		may be any size.  A raster is merely a two-dimensional array
		in the graphics server; it is not displayed unless mapped.
		An exception is raster zero, which is the graphics window.
		Rasters are referred to by number, starting with zero.
		Initially only raster zero exists; new rasters are created
		with gim_createraster.  Space for rasters may be allocated
		either in the graphics server, or in the X server.  This has
		implications on performance but is otherwise transparent to
		the client.  By default rasters are allocated in the
		graphics server, i.e., in the X client.

    mapping	A mapping defines a projection of a rectangle of the source
		raster onto a rectangle of the destination raster.  Mappings
		may be either enabled (active) or disabled.  When a mapping
		is enabled, any change to a pixel in the source rect will
		cause the corresponding pixels in the destination rect to be
		updated.  Mappings are referred to by number starting with
		one.  Initially no mappings are defined.  If the size of the
		input and output rect is not the same the input rect will be
		scaled by pixel replication or subsampling to fill the
		output rect.  If the argument DW or DH of the destination
		rect is negative, the image will be flipped around the
		corresponding axis when copied to the destination; the
		region of the destination drawn into is the same in either
		case.  Multiple mappings may reference the same source or
		destination raster.  Mappings are refreshed in order by the
		mapping number.  Modifying a mapping causes the changed
		regions of the destination rect to be refreshed.

    color	The gterm widget provides a fixed number of preassigned colors
		corresponding to pixel values 0 through 9.  0 is the background
		color, 1 is the foreground color, and 2-9 (8 colors) are
		arbitrary colors defined by Gterm widget resources.  These
		static colors are normally used to draw the background, frame,
		axes, titles, etc. of a plot, or to draw color graphics within
		the drawing area.  The advantage of static colors is that they
		are shared with other X clients, and the values of these
		colors may be assigned by the user to personalize the way
		plots look.

		The gterm widget also allows any number (up to about 200 or
		so) additional colors to be defined at runtime by the client
		application.  These color values start at pixel value 10 and
		go up to the maximum pixel value assigned by the client.  The
		client application allocates colors with gim_writecolormap.
		Attempts to overwrite the values of the static colors are
		ignored.  The values of already allocated colors may be
		changed dynamically at runtime using gim_writecolormap to
		write the desired range of color values.

		Applications should not assume that there are 10 static
		colors and 200 or so allocatable colors.  The graphcap entry
		for the logical device in use defines these parameters for
		the device.  Alternatively, the readcolormap call may be
		used to dynamically determine how many colors the server has
		preallocated when the application starts up.

		An image may use either static and dyamic pixel values or
		both types of values, but in most cases imaging applications
		involve smoothly shaded surfaces hence will require
		dyamically assigned private colors.

		If for some reason the client application cannot use the
		gterm widget color model, the IOMAP feature can be used to
		make the widget appear to have some externally defined
		(i.e., client defined) color model.


The maximum number of rasters and maximum number of mappings is defined by
Gterm widget resources (e.g. in the GUI file) when the graphics application
starts up.  The maximum values should be much larger than most applications
require.  Applications should allocate raster or mapping numbers
sequentially starting at 1 (more or less) to avoid running out of raster or
mapping descriptors.

The {read|write}pixels routines in the GIM interface operate directly on
raster pixels.  The mapping routines support two alternative coordinate
systems, raster pixels and NDC (normalized device coordinates), as indicated
by the ST or DT argument (source or destination coordinate type).  Note
that the origin of the pixel coordinate system is the upper left corner of
the display window (consistent with most graphics systems), whereas the origin
of the NDC coordinate system is the lower left corner (consistent with IRAF).

Pixel coordinates allow precise control of imaging but require the
application to know the window size, and may result in complications e.g. if
the window is resized.  NDC coordinates pretty much guarantee that a mapping
will involve sampling, hence are not the most efficient, but the graphics
will be drawn correctly no matter how the window is resized and for most
applications the performance difference is negligible.  Most applications
should use NDC coordinates for raster 0 (the display window), and pixel
coordinates for rasters 1-N.

Although the size of rasters 1 and higher are defined by the client
application, the size of raster zero, the actual gterm display window, is
subject to the constraints of the window system.  The client can attempt to
reset the size of the gterm window using gim_createraster with raster=0,
however the Gterm widget, UI containing the gterm widget, and the window
manager are all free to deny such a request.  gim_queryraster should be
called to determine the actual size of the window one will be drawing into.


EXAMPLE

    A simple example of an imaging application might download an image and
display it in the gterm window, filling the window.  This could be done as
follows (following a GOPEN and other GIO calls to prepare the drawing surface).

	gim_createraster	Create raster 1 the size of the pixel array
				to be displayed.  This need not be the same
				as the size of the gterm display window.

	gim_setmapping		Define a mapping between raster 1 and raster 0,
				the display window, using NDC coordinates to
				define the region of the display window to be
				filled.  The mapping number is arbitrary but
				mappings should normally be allocated starting
				with 1.  The mapping is automatically enabled
				when first defined.

	gim_writecolormap	(Optional).  Define the pixel value to RGB
				color assignments for the image pixels.

	gim_writepixels		This routine is called one or more times to
				write pixels into raster 1.  At most 32K
				pixels (minus a bit for the GKI headers) can
				be written in each call.  As each write is
				made the affected region of the display
				window will be updated.

Alternatively, one could write the pixels and then define the mapping, to
cause the entire image to be displayed at once.

Note that the GIM calls can be combined with normal GIO graphics to draw text
and graphics around or on top of an image region.  The order in which drawing
operations occur is important, e.g., to draw graphics or text on top of an
image the image should be drawn first.
