1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
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.
|
