Initial commit

1 files changed, 215 insertions, 0 deletions

diff --git a/sys/gio/gim/README b/sys/gio/gim/README
new file mode 100644
index 00000000..3c98b736
--- /dev/null
+++ b/sys/gio/gim/README
@@ -0,0 +1,215 @@
+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.