diff options
Diffstat (limited to 'sys/gio/gim/README')
| -rw-r--r-- | sys/gio/gim/README | 215 |
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. |