Graphics

The following functions represent an interface for exporting graphics to a ``foreign'' X window. In particular, the interface can be used to draw into a window owned by a Tk script. This interface is not available on Microsoft Windows.

(handle) GRopen(display, window)
This function returns a handle to a graphical interface that can be used to export graphics to a foreign X window, possibly on another machine. The first argument is the X display string, corresponding to the server which owns the target window. The second argument is the X window id of the target window to which graphics rendering is to be exported. If all goes well, and the user has permission to access the window, a positive integer handle is returned. If the open fails, 0 is returned. The handle should be closed with the Close function when done.

(int) GRcheckError()
This function returns 1 if the previous operation by any of the GR interface functions caused an X error, 0 otherwise.

(drawable) GRcreatePixmap(handle, width, height)
This function returns the X id of a new pixmap. The first argument is a handle returned from GRopen. The remaining arguments set the size of the pixmap. If the operation fails, 0 is returned.

(int) GRdestroyPixmap(handle, pixmap)
This function destroys a pixmap created with GRcreatePixmap. The first argument is a handle returned from GRopen. The second argument is the pixmap id returned from GRcreatePixmap. The function returns 1 on success, 0 if there was an error.

(int) GRcopyDrawable(handle, dst, src, xs, ys, ws, hs, x, y)
This function is used to copy area between drawables, which can be windows or pixmaps. The first argument is a handle returned from GRopen. The next two arguments are the ids of destination and source drawables. The area copied in the source drawable is given by the next four arguments. The coordinates are pixel values, with the origin in the upper left corner. If these four values are all zero, the entire source drawable is understood. The final two values give the upper left corner of the copied-to area in the destination drawable.

(int) GRdraw(handle, l, b, r, t)
This function renders an Xic cell. The first argument is a handle returned from GRopen. The remaining arguments are the coordinates of the cell to render, in microns. The action is the same as the Display function. The function returns 1 on success, 0 if there was an error.

(int) GRgetDrawableSize(handle, drawable, array)
This function returns the size, in pixels, of a drawable. The first argument is a handle returned from GRopen. The second argument is the id of a window or pixmap. The third argument is an array of size two or larger that will contain the pixel width and height of the drawable. Upon success, 1 is returned, and the array values are set, otherwise 0 is returned. The width is in the 0'th array element.

(drawable) GRresetDrawable(handle, drawable)
This function allows the target window of the graphical context to be changed. Then, the rendering functions will draw into the new window or pixmap, rather than the one passed to GRopen. The return value is the previous drawable id, or 0 if there is an error.

(int) GRclear(handle)
This function clears the window. The argument is a handle returned from GRopen. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRpixel(handle, x, y)
This function draws a single pixel at the pixel coordinates given in the second and third arguments, using the current color. The first argument is a handle returned from GRopen. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRpixels(handle, array, num)
This function will draw multiple pixels using the current color. The first argument is a handle returned from GRopen. The second argument is an array of pixel coordinates, taken as x-y pairs. The third argument is the number of pixels to draw (half the length of the array). Upon success, 1 is returned, otherwise 0 is returned.

(int) GRline(handle, x1, y1, x2, y2)
This function renders a line using the current color and line style. The first argument is a handle returned from GRopen. The next four arguments are the endpoints of the line in pixel coordinates. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRpolyLine(handle, array, num)
This function renders a polyline in the current color and line style. The first argument is a handle returned from GRopen. The second argument is an array containing vertex coordinates in pixels as x-y pairs. The line will be continued to each successive vertex. The third argument is the number of vertices (half the length of the array). Upon success, 1 is returned, otherwise 0 is returned.

(int) GRlines(handle, array, num)
This function renders multiple distinct lines, each using the current color and line style. The first argument is a handle returned by GRopen. The second argument is an array of coordinates, in pixels, which if taken four at a time give the x-y endpoints of each line. The third argument is the number of lines in the array (one fourth the array length). Upon success, 1 is returned, otherwise 0 is returned.

(int) GRbox(handle, l, b, r, t)
This function renders a rectangular area in the current color with the current fill pattern. The first argument is a handle returned from GRopen. The remaining arguments provide the diagonal vertices of the rectangle, in pixels. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRboxes(handle, array, num)
This function renders multiple rectangles, each using the current color and fill pattern. The first argument is a handle returned from GRopen. the second argument is an array of pixel coordinates which specify the boxes. Taken four at a time, the values are the upper-left corner (x-y), width, and height. The third argument is the number of boxes represented in the array (one fourth the array length). Upon success, 1 is returned, otherwise 0 is returned.

(int) GRarc(handle, x0, y0, radius, theta1, theta2)
This function renders an arc, using the current color and line style. The first argument is a handle returned from GRopen. The next two arguments are the pixel coordinates of the center of the circle containing the arc. The remaining arguments are the radius, and the starting and ending angles. The angles are in radians, relative to the three-o'clock position, counter-clockwise. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRpolygon(handle, array, num)
This function renders a polygon, using the current color and fill pattern. The first argument is a handle returned from GRopen. The second argument is an array containing the vertices, as x-y pairs of pixel coordinates. The third argument is the number of vertices (half the length of the array). The polygon will be closed automatically if the first and last vertices do not coincide. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRtext(handle, text, x, y, transform)
This function renders text in the current color. The first argument is a handle returned form GRopen. The second argument is the text string to render. The next two arguments give the anchor point in pixel coordinates. If there is no transformation, this will be the lower-left of the bounding box of the rendered text. The next argument is a transformation code, which allows the text to be rotated and/or reflected about the anchor point. The bits in this code have the following effects:

Bits	Effect
0-1	00-no rotation, 01-90, 10-180, 11-270
2	mirror y after rotation
3	mirror x after rotation and mirror y
4	shift rotation to 45, 135, 225, 315
5-6	horiz justification 00,11 left, 01 center, 10 right
7-8	vert justification 00,11 bottom, 01 center, 10 top

Upon success, 1 is returned, otherwise 0 is returned.

(int) GRtextExtent(handle, text, array)
This function returns the width and height in pixels needed to render a text string. The first argument is a handle returned from GRopen. The second argument is the string to measure. If the string is null or empty, a ``typical'' single character width and height is returned, which can be simply multiplied for the fixed-pitch font in use. The third argument is an array of size two or larger which will receive the width (0'th index) and height. The function returns 1 on success, 0 otherwise.

(int) GRdefineColor(handle, red, green, blue)
This function will return a color code corresponding to the given color. The first argument is a handle returned from GRopen. The next three arguments are color component values, each in a range 0-255, giving the red, green, and blue intensity. The return value is a color code representing the nearest displayable color to that given. If an error occurs, 0 (black) is returned. The returned color code can be passed to GRsetColor to actually change the drawing color.

(int) GRsetBackground(handle, pixel)
This function sets the default background color assumed by the graphics context. The first argument is a handle returned from GRopen. The second argument is a color code returned from GRdefineColor. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRsetWindowBackground(handle, pixel)
This function sets the color used to render the window background when the window is cleared. The first argument is a handle returned from GRopen. The second argument is a color code returned from GRdefineColor. The function returns 1 on success, 0 otherwise.

(int) GRsetColor(handle, pixel)
This function sets the current color, used for all rendering functions. The first argument is a handle returned from GRopen. The second argument is a color code returned from GRdefineColor. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRdefineLinestyle(handle, index, mask)
This function defines a line style. The first argument is a handle returned from GRopen. The second argument is an index value 1-15 which corresponds to an internal line style register. The third argument is an integer value whose bits set the line on/off pattern. the pattern starts with the most significant '1' bit in the mask. The '1' bits will be drawn. The pattern continues to the least significant bit, and is repeated as the line is rendered. The indices 1-10 contain pre-defined line styles, which can be overwritten with this function. The SetLinestyle function is used to set the pattern actually used for rendering. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRsetLinestyle(handle, index)
This function sets the line style used to render lines. The first argument is a handle returned from GRopen. The second argument is an integer 0-15 which corresponds to an internal style register. Index 0 is always solid, whereas the other values can be set with GRdefineLinestyle. The function returns 1 on success, 0 otherwise.

(int) GRdefineFillpattern(handle, index, nx, ny array_string)
This function is used to define a fill pattern for rendering boxes and polygons. The first argument is a handle returned from GRopen. The second argument is an integer 1-15 which corresponds to internal fill pattern registers. The next two arguments set the x and y size of the pixel map used for the fill pattern. These can take values of 8 or 16 only. The final argument is a character string which contains the pixel map. The most significant bit of the first byte is the upper left corner of the map. The SetFillpattern function is used to set the fill pattern actually used for rendering. The function returns 1 on success, 0 otherwise.

(int) GRsetFillpattern(handle, index)
This function sets the fill pattern used for rendering boxes and polygons. The first argument is a handle returned from GRopen. The second argument is an integer index 0-15 which corresponds to internal fill pattern registers. The value 0 is always solid fill. The other values can be set with GRdefineFillpattern. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRupdate(handle)
This function flushes the X queue and causes any pending operations to be performed. This should be called after completing a sequence of drawing functions, to force a screen update. Upon success, 1 is returned, otherwise 0 is returned.

(int) GRsetMode(handle, mode)
This function sets the drawing mode used for rendering. The first argument is a handle returned from GRopen. The second argument is one of the following:

0	normal drawing
1	XOR
2	OR
3	AND-inverted

Modes 2,3 are probably not useful on other than 8-plane displays. The function returns 1 on success, 0 otherwise.