intro(3G) intro(3G)
NAME
introduction - description of routines in the Graphics
Library
DESCRIPTION
The Graphics Library Reference contains descriptions of the
routines in the Graphics Library.
Each description defines the number, order, and types of the
arguments for each routine. C and FORTRAN are provided
under the heading SPECIFICATION. A description of the
routine, including function, effects, and potential errors
is given in the section called DESCRIPTION; related routines
and related material are listed under SEE ALSO.
Some of the routines have several versions, depending on the
number and type of the arguments. Coordinate data can be 2D
or 3D, and can be specified as floating-point numbers,
integers, or short (16-bit) integers. The default is 3-D
floating-point data. Integer data and 2-D points are
specified with suffixes: i for integer, s for short, and 2
for 2D.
If the routine can be compiled into a display list, it is so
stated in the NOTE.
TEXT STRINGS
C text strings are terminated with a null character (ASCII
0); FORTRAN has a character data type that includes the
length of the string.
POINTERS
Many of the Graphics Library routines return several values
to the caller. The arguments to these routines are
pointers, or addresses of memory locations. In C, they are
declared as pointer variables by prefixing the variable name
with an asterisk in the declaration. FORTRAN passes all
parameters by reference, so no special declaration is
necessary.
BOOLEANS
Many of the routines have boolean arguments or return
boolean values. These are declared as type Boolean in C,
and as logical or integer in FORTRAN. We assume that FALSE
is zero, and that TRUE is anything except FALSE.
TYPE DECLARATIONS
We have constructed type declarations for C wherever they
add to the readability of the code. Here are the type
definitions:
C #define PATTERN_16 16
Page 1 (printed 8/20/87)
intro(3G) intro(3G)
#define PATTERN_32 32
#define PATTERN_64 64
#define PATTERN_16_SIZE 16
#define PATTERN_32_SIZE 64
#define PATTERN_64_SIZE 256
typedef unsigned char Byte;
typedef long Boolean;
typedef short Angle;
typedef short Scoord;
typedef short Screencoord;
typedef long Icoord;
typedef float Coord;
typedef char *String;
typedef float Matrix[4][4];
typedef unsigned short Device;
typedef unsigned short Colorindex;
typedef unsigned char RGBvalue;
typedef unsigned short Linestyle;
typedef unsigned short Cursor[16];
typedef struct {
unsigned short offset; /* 2 bytes */
Byte w,h; /* 2 bytes */
char xoff,yoff; /* 2 bytes */
short width; /* 2 bytes */
} Fontchar;
typedef long Object;
typedef long Tag;
typedef unsigned short Pattern16[PATTERN_16_SIZE];
typedef unsigned short Pattern32[PATTERN_32_SIZE];
typedef unsigned short Pattern64[PATTERN_64_SIZE];
Page 2 (printed 8/20/87)
intro(3G) intro(3G)
LIST OF GRAPHICS LIBRARY ROUTINES
addtopup - adds items to an existing pop-up menu
arc - draws a circular arc
arcf - draws a filled circular arc
attachcursor - attaches the cursor to two valuators
backbuffer - enables updating in the back buffer
backface - turns backfacing polygon removal on and off
bbox2 - specifies bounding box and minimum pixel radius for
drawing commands
blankscreen - turns screen refresh on and off
blanktime - sets the screen blanking timeout
blink - changes the color map entry at a selectable rate
blkqread - reads multiple entries from the queue
callfunc - calls a function from within an object
callobj - draws an instance of an object
charstr - draws a string of raster characters on the screen
chunksize - specifies minimum object size in memory
circ - outlines a circle
circf - draws a filled circle
clear - clears the viewport
clearhitcode - sets the system hitcode to zero
clkoff - turns off the keyboard click
clkon - turns on the keyboard click
closeobj - closes an object
cmode - sets color mode as the current mode
cmov - updates the current character position
color - sets the color index in the current mode
Page 3 (printed 8/20/87)
intro(3G) intro(3G)
compactify - compacts the memory storage of an object
concave - allows the system to draw concave polygons
crv - draws a curve
crvn - draws a series of curve segments
curorigin - sets the origin of a cursor
cursoff - turns off the cursor
curson - turns on the cursor
curstype - defines the type and/or size of cursor
curvebasis - sets the basis matrix used in drawing curves
curveit - draws a curve segment
curveprecision - sets the number of line segments that make
up a curve segment
cyclemap - cycles through color maps at a specified rate
dbtext - sets the dial and button box text
defbasis - defines a basis matrix
defcursor - defines a cursor glyph
deflinestyle - defines a line style
defpattern - defines patterns
defpup - defines a menu
defrasterfont - defines a raster font
delobj - deletes an object
deltag - deletes tags from objects
depthcue - turns depth-cue mode on and off
dopup - calls up the specified pop-up menu
doublebuffer - sets the display mode to double buffer mode
draw - draws a line
drawmode - sets the current mode for the color and writemask
Page 4 (printed 8/20/87)
intro(3G) intro(3G)
routines
editobj - opens an object for editing
endfeedback - turns off feedback mode
endfullscrn - ends full screen mode
endpick - turns off picking mode
endpupmode - ends pop-up mode
endselect - turns off selecting mode
feedback - turns on feedback mode
finish - blocks the host process until the Geometry Pipeline
is empty
font - selects a raster font for drawing text strings
foreground - prevents a graphical process from being put
into the background
freepup - returns a menu and its structures to the system
frontbuffer - enables updating in the front buffer
fudge - specifies fudge values that are added to a graphics
window when it is resized
fullscrn - gives a program the entire screen as a window
gammaramp - defines a color map ramp for gamma correction
gbegin - initializes the system without altering the color
map
gconfig - reconfigures the system
genobj - returns a unique integer for use as an object
identifier
gentag - returns a unique integer for use as a tag
getbackface - returns whether backfacing polygons will
appear
getbuffer - indicates which buffers are enabled for writing
getbutton - returns the state (up or down) of a button
Page 5 (printed 8/20/87)
intro(3G) intro(3G)
getcmmode - returns the current color map mode
getcolor - returns the current color
getcpos - returns the current character position
getcursor - returns the cursor characteristics
getdcm - indicates whether depth-cue mode is on or off
getdepth - returns the parameters of setdepth
getdescender - returns the character characteristics
getdev - reads a list of valuators at one time
getdisplaymode - returns the current display mode
getdrawmode - returns the current drawing mode
getfont - returns the current raster font number
getgpos - returns the current graphics position
getheight - returns the maximum height of the characters in
the current raster font
gethitcode - returns the current system hitcode
getlsbackup - returns the current value of the linestyle
backup flag
getlsrepeat - returns the linestyle repeat count
getlstyle - returns the current linestyle
getlwidth - returns the current linewidth
getmap - returns the number of the current color map
getmatrix - returns the current transformation matrix
getmcolor - returns a color map entry
getmmode - returns the current matrix mode
getmonitor - returns the display monitor
getopenobj - returns the current object
getorigin - returns the position of a graphics window in the
window manager
Page 6 (printed 8/20/87)
intro(3G) intro(3G)
getothermonitor - returns the nondisplayed monitor type
getpattern - returns the index of the current pattern
getplanes - returns the number of available bitplanes
getport - creates a graphics window
getresetls - returns the current value of resetls
getscrmask - returns the current screenmask
getsize - returns the size of a graphics window
getsm - returns the shading model the system uses to draw
polygons
gettp - returns the location of the current textport
getvaluator - returns the current state of a valuator
getvideo - returns the value of video hardware register
getviewport - returns the current viewport
getwritemask - returns the current writemask
getzbuffer - indicates whether z-buffering is on or off
gexit - terminates a program
gflush - forces all unsent commands down the Geometry
Pipeline
ginit - initializes the system
greset - resets all global attributes to their initial
values
gRGBcolor - returns the current RGB value
gRGBmask - returns the current RGB writemask
gselect - puts the system in selection mode
gsync - waits for a vertical retrace period
imakebackground - registers the screen background process
initnames - initializes the name stack
ismex - returns TRUE if the window manager is running
Page 7 (printed 8/20/87)
intro(3G) intro(3G)
isobj - indicates whether a given object number identifies
an object
isqueued - indicates if a specific device is queued
istag - indicates whether a given tag is in use within the
current open object
keepaspect - specifies the aspect ratio of a graphics window
lampoff - turns off the keyboard display lights
lampon - turns on the keyboard display lights
linewidth - specifies the linewidth
lmbind - binds a new material, light, or lighting model
definition
lmdef - defines a new material, light, or lighting model
loadmatrix - loads a transformation matrix
loadname - loads the name on the top of the name stack
lookat - defines a viewing transformation
lsbackup - controls whether the last two pixels of a line
are closed
lsrepeat - sets repeat factor for linestyle
makeobj - creates an object
maketag - numbers a routine in the display list
mapcolor - changes a color map entry
mapw - maps a point on the screen into a line in 3-D world
coordinates
mapw2 - maps a point on the screen into 2-D world
coordinates
maxsize - specifies a maximum size of a graphics window
minsize - specifies a minimum size of a graphics window
mmode - sets the current matrix mode
move - moves the current graphics position to a specified
point (for line drawing)
Page 8 (printed 8/20/87)
intro(3G) intro(3G)
multimap - organizes the color map as 16 small maps
multmatrix - premultiplies the current transformation matrix
newpup - allocates and initializes a structure for a new
menu
newtag - creates a new tag in an object
noise - filters valuator motion
noport - specifies that a program does not require a
graphics window
normal - updates the current normal vector
objdelete - deletes routines from an object
objinsert - inserts routines in an object at a specified
location
objreplace - overwrites existing display list routines with
new ones
onemap - organizes the color map as one large map
ortho - defines an orthographic projection transformation
overlay - sets the number of user-defined bitplanes used for
overlay colors
pagecolor - sets the color of the textport background
passthrough - passes a single token through the Geometry
Pipeline
patch - draws a surface patch
patchbasis - sets current patch basis matrices
patchcurves - sets number of curves used to represent a
patch
patchprecision - sets the precision at which curves are
drawn
pclos - polygon close
pdr - polygon draw
perspective - defines a perspective projection
transformation
Page 9 (printed 8/20/87)
intro(3G) intro(3G)
pick - puts the system in picking mode
picksize - sets the dimensions of the picking region
pmv - polygon move
pnt - draws a point
polarview - defines the viewer's position in polar
coordinates
polf - draws a filled polygon
poly - outlines a polygon
popattributes - pops the attribute stack
popmatrix - pops the transformation matrix stack
popname - pops a name off the name stack
popviewport - restores the viewport, screenmask, and
setdepth parameters
prefposition - specifies the preferred location and size of
a graphics window
prefsize - specifies the preferred size of a graphics window
in the window manager
pupmode - provides access to the pop-up menu bitplanes
pushattributes - saves the global state attributes
pushmatrix - pushes down the transformation matrix stack
pushname - pushes a new name on the name stack
pushviewport - duplicates the current viewport
qdevice - queues a device (keyboard, button, or valuator)
qenter - creates an event queue entry
qread - reads the first entry in the event queue
qreset - empties the event queue
qtest - checks the contents of the event queue
rcrv - draws a curve
Page 10 (printed 8/20/87)
intro(3G) intro(3G)
rcrvn - draws a series of curve segments
rdr - relative draw
readpixels - returns values of specific pixels
readRGB - returns values of specific pixels
rect - outlines a rectangular region
rectcopy - copies a rectangle of pixels on the screen
rectf - fills a rectangular area
resetls - controls the continuity of linestyles
reshapeviewport - sets the viewport to the dimensions of the
current graphics window
RGBcolor - sets the current color in RGB mode
RGBmode - sets a display mode that bypasses the color map
RGBrange - sets the range of color indices used in depth-
cueing in RGB mode
RGBwritemask - grants write access to a subset of the
available bitplanes
ringbell - rings the keyboard bell
rmv - relative move
rot - rotates graphical primitives
rotate - rotates graphical primitives
rpatch - draws a surface patch as rational cubic splines
rpdr - relative polygon draw as rational cubic splines
rpmv - relative polygon move
scale - scales and mirrors objects
screenspace - makes a program interpret graphics positions
as absolute screen coordinates
scrmask - defines a clipping mask for fine character
clipping
setbell - sets the duration of the keyboard bell
Page 11 (printed 8/20/87)
intro(3G) intro(3G)
setcursor - sets the cursor characteristics
setdblights - sets the lights on the dial and button box
setdepth - sets up a 3-D viewport
setlinestyle - selects a linestyle pattern
setmap - chooses one of the 16 small color maps in multimap
mode
setmonitor - sets the monitor type
setpattern - selects a pattern for filling polygons,
rectangles, and curves
setshade - sets the current polygon shade
setvaluator - assigns an initial value to a valuator
setvideo - sets video hardware registers
shademodel - selects the shading model used to draw polygons
shaderange - sets range of color indices used in depth-
cueing
singlebuffer - writes and displays all the bitplanes
spclos - draws current open shaded polygon
splf - draws a shaded filled polygon
stepunit - specifies that a graphics window change size in
discrete steps
strwidth - returns the width of the specified text string
swapbuffers - swaps the front and back buffers in double
buffer mode
swapinterval - defines a minimum time between buffer swaps
textcolor - sets the color of text drawn in the textport
textinit - initializes the console textport
textport - allocates an area of the screen for the textport
tie - ties two valuators to a button
tpoff - turns off the textport
Page 12 (printed 8/20/87)
intro(3G) intro(3G)
tpon - turns on the textport
translate - translates graphical primitives
underlay - sets the number of user-defined bitplanes used
for underlay color
unqdevice - disables the specified device from makeing
entries in the event queue
viewport - allocates an area of the window for an image
winattach - attaches the input focus to the current window
and call process
winclose - closes the identified graphics window
winconstraints - changes the constraints of the current
graphics window
window - defines a perspective projection transformation
winget - returns the identifier of the current graphics
window
winmove - moves the lower left corner of the current
graphics window
winopen - creates a graphics window
winpop - moves the current window in front of all other
windows
winposition - changes the size and position of the current
graphics window
winpush - moves the current window behind all other graphics
windows
winset - sets the current graphics window
wintitle - adds a title bar to the current graphics window
writemask - grants write permission to available bitplanes
writepixels - paints a row of pixels on the screen
writeRGB - paints a row of pixels on the screen
xfpt - transforms points
zbuffer - starts or ends z-buffer mode
Page 13 (printed 8/20/87)
intro(3G) intro(3G)
zclear - initializes the z-buffer
Page 14 (printed 8/20/87)