'C' Interface Library --------------------- NOTE: Some changes have been made to the preliminary instructions concerning use of this library with the Microsoft C compiler. Jeff Armstrong (jba@member.fsf.org) September 17, 2006 ; ; ; Copyright by Digital Equipment Corporation 1983. All rights ;reserved. ; ; ; ; The information in this document is subject to change without ;notice and should not be construed as a commitment by Digital ;Equipment Corporation. Digital Equipment Corporation assumes no ;responsibility for any errors that may appear in this document. ; ; The software described in this document is furnished under a ;license and may only be used or copied in accordance with the terms of ;such license. ; ; No responsibility is assumed for the use or reliability of ;software on equipment that is not supplied by DIGITAL or its ;affiliated companies. ; ; ; The following are trademarks of Digital Equipment Corporation: ; ; ;DIGITAL MASSBUS UNIBUS ;DEC PDP VAX ;DECmate P/OS VMS ;DECsystem-10 Professional VT ;DECSYSTEM-20 Rainbow Work Processor ;DECUS RSTS DIBOL ;RSX ; What is a 'C' Interface Library : --------------------------------- The Rainbow Graphics option comes with a 'C' interface library that will allow you to write graphics application programs using a Digital supported 'C' compiler. The GSX-86 Programmer's Reference Manual describes in detail all the functions supported by Rainbow graphics devices. The 'C' interface library allows you to call any GSX-86 function without resorting to an assembly language program. Also, the input and output parameters passing scheme is designed to take full advantage of the 'C' language. Although GSX-86 requires character strings to be passed in integer arrays, the 'C' interface library will accept the char pointers and will generate integer arrays to be passed to GSX-86. How to use 'C' interface Library : ---------------------------------- The 'C' interface library package consists of the following files: 1. gsx.h - A header file to be included in your 'C' program. 2. gsx.lib - The 'C' interface library file 3. gsx86mwc.DOC - Documentation on 'C' interface library (this file) The gsx.H file contains declarations to be included in your program. Your application program must have the following statement in the beginning of your file : #include /* GSX-86 Header file */ You do not have to include this file in your program if you decide not to use any of the following outputs of the GSX-86 : - Outputs of Open workstation call - Inputs to Init workstation call - Outputs of Character Height call - Outputs of Inquire Color Representation If your C application program which uses GSX-86 'C' interface library functions is, for example, 'GRAF.C', then you can compile and load this program by using the following command: A> cl -c graf.c A> link graf.obj gsx.lib The above command line will compile your program and extract any needed GSX-86 functions from the file 'gsx.lib'. This library file contains all the functions described in the next section. NOTE: The following papragraphs do not pertain to Microsoft C: The above command line may show 'sine_' and 'cosine_' as two undefined symbols during the linking phase. You do not have to worry about these math library functions if you are not using the character rotation (SET CHARACTER UP VECTOR) function. Eliminating the use of these two functions can save you about 3.5K of memory. However, If you are using 'SET CHARACTER UP VECTOR' function of GSX-86, you must link the math library (libm.olb) file with your program. This is essential since the 'C' interface library uses 'SINE' and 'COSINE' functions of the math library to calculate the angle of rotation of the character base line. The command line in this case may look like : A> cc graf.c gsx86mwc.olb libm.olb The library file 'libm.olb' must be the last argument on the command line to resolve 'sine' and 'cosine' arguments correctly. GSX-86 Functions Callable from MWC-86 ===================================== /////////////////////////////////// // Workstation Control Functions // ////////////////////////////////// Function : Open Workstation with default settings. ---------- Calling Sequence : openws(ws_no) ------------------ int ws_no; /* workstation no. Output : Returns a pointer to the structure ws_attr defined in -------- file "gsx86mwc.h" structure ws_attr *openws(ws_no); Returns -1 if error. The actual error code can be obtained by calling the function gsx_error(). When a workstation is opened, the following default values are used. Line type = 1 : solid line Polyline Color = 1 : Marker Type = 1 : Marker Color = 1 : Text font = 1 : Text color = 1 : Fill int. style = 1 : Fill style index = 1 : Fill color index= 1 : Function : Open Workstation given the default settings. ---------- Calling Sequence : initws(ws) ------------------ struct ws_in *ws; /* workstation no. Output : Returns a pointer to the structure ws_attr defined in -------- file "gsx86mwc.h" structure ws_attr *initws(ws_no); Returns -1 if error. The actual error code can be obtained by calling the function gsx_error(). Function : Close Workstation ---------- Calling Sequence : closews() ------------------ Output : None. -------- Function : Clear Workstation ---------- Calling Sequence : clearws() ------------------ Output : None. -------- Function : Update Workstation ---------- Calling Sequence : updatews() ------------------ Output : None. -------- ///////////////////////// // ESCAPE Functions // ///////////////////////// Function : Exit graphics mode. Enter Text mode (VT102) ---------- Calling Sequence : exit_graf() ------------------ Output : None. -------- Function : Enter Graphics mode. Exit text mode(VT102) ---------- Calling Sequence : enter_graf() ------------------ Output : None. -------- Function : Move text cursor up one row ---------- Calling Sequence : cursor_up() ------------------ Output : None. -------- Function : Move text cursor down one row. ---------- Calling Sequence : cursor_down() ------------------ Output : None. -------- Function : Move text cursor right one column. ---------- Calling Sequence : cursor_right() ------------------ Output : None. -------- Function : Move text cursor left one column. ---------- Calling Sequence : cursor_left() ------------------ Output : None. -------- Function : Send cursor to home position. ---------- Calling Sequence : cursor_home() ------------------ Output : None. -------- Function : Erase to end of screen ---------- Calling Sequence : era_eos() ------------------ Output : None. -------- Function : Erase to end of line ---------- Calling Sequence : era_eol() ------------------ Output : None. -------- Function : Reverse Video On ---------- Calling Sequence : rvon() ------------------ Output : None. -------- Function : Reverse Video Off ---------- Calling Sequence : rvoff() ------------------ Output : None. -------- Function : Inquire addressable character cells ---------- Calling Sequence : inqch(rows,cols) ------------------ int *rows; /* no. of addressable rows */ int *cols; /* no. of addressable cols.*/ Output : if rows or cols = -1 , cursor addressing is not -------- possible using this device. Function : Direct cursor positioning ---------- Calling Sequence : putcursor(row,col) ------------------ int row; /* row number (1-24) */ int col; /* col number (1-80) */ Output : None. -------- Function : Output cursor addressable text ---------- Calling Sequence : ctext(string) ------------------ char *string; /* pointer to text string */ Output : None. -------- Function : Inquire current cursor address ---------- Calling Sequence : inqcursor(row,col) ------------------ int *row; /* pointer to row buffer */ int *col; /* pointer to col buffer */ Output : None. -------- Function : Inquire tablet status ---------- Calling Sequence : inqtablet() ------------------ Output : returns tablet status as the function value. -------- 0 = tablet not available. 1 = tablet available. Function : Place graphics Cursor at location ---------- Calling Sequence : dsp_gcur(x,y) ------------------ int x,y; /* x,y co-ordinate location */ Output : None. -------- Function : ---------- Remove graphics cursor Calling Sequence : rmv_gcur() ------------------ Output : None. -------- ////////////////////////// // Output Functions // ////////////////////////// Function: Output Polyline to workstation --------- Calling Sequence: polyline(no_of_points,pts_in) ---------------- int no_of_points; /* how many (X,Y) pairs. int *pts_in; /* address of (X,Y) array. Output : None. -------- Function : Output Polymarker ---------- Calling Sequence : Polymark(no_of_points,pts_in) ------------------ int no_of_points; /* how many (X,Y) pairs. int *pts_in; /* address of (X,Y) array. Output : None. -------- Function: Write text string at specified position --------- Calling Sequence : text(x, y, text_string) ------------------ int x; /* X co-ordinate value. int y; /* Y co-ordinate value. char *text_string; /* char string to output. Output : None. -------- Function : Fill a Polygon ---------- Calling Sequence : polyfill(no_of_points,ptsin) ------------------ int no_of_points; /* no of points in array. int *ptsin; /* address of X,Y array. Output : None. -------- Function : Display Cell Array ---------- Calling Sequence : cellarray(cia_length,row_length,el_per_row, ------------------ num_rows,wr_mode,xypts,cia) int cia_length; /* length of color ind. arr */ int row_length; /* length of each row in cia */ int el_per_row; /* no of elements in each row */ int num_rows; /* no of rows in cia */ int wr_mode; /* write mode (0-4) */ int *xypts; /* xy points array */ int *cia; /* color index array */ Output : -------- None. /////////////////////////////////////////////// // Generalized Drawing Primitives (GDP) // /////////////////////////////////////////////// Function : GDP - Draw a BAR ---------- Calling Sequence : bar(points_array) ------------------ int *pntsin; /* address of array having */ /* [0] = lower left x */ /* [1] = lower left y */ /* [2] = upper right x */ /* [3] = upper right y */ Output : None. -------- Function : GDP - ARC ---------- Calling Sequence : arc(startdeg,enddeg,ptsin) ------------------ int startdeg; /* start angle(tenth degree) */ int enddeg; /* end angle(tenths of deg.) */ int *ptsin; /* array of points having */ /* [0][1] = center point. */ /* [2][3] = start x,y */ /* [4][5] = end x,y. */ /* [6] = radius of the arc*/ Output : None. -------- Function : GDP - CIRCLE ---------- Calling Sequence : circle(cx,cy,radius) ------------------ int cx,cy; /* center point (cx,cy) */ int radius; /* radius */ Output : None. -------- //////////////////////////////////// // Output Attribute Functions // /////////////////////////////////// Function : Set Character Height ---------- Calling Sequence : charht(height) ------------------ int height; /* char height in dev units */ Output : returns pointer to char_attr structure. -------- struct char_attr *charht(height) char_attr is defined as struct char_attr { int sel_width; int sel_height; int cel_width; int cel_height; }; Function : Set Character Up Vector (set text direction) ---------- Calling Sequence : direction(angle) ------------------ int angle; /* angle in tenth of degree */ Output : -------- returns selected angle of rotation in tenths of degrees. Function : Set Color Representation ---------- Calling Sequence : color(index,red,green,blue) ------------------ int index; /* color no. (1-16)/(1-4) */ int red; /* red, green and blue */ int green; /* color intensities in */ int blue; /* in tenths of percent */ /* (0 - 1000) */ Output : None. -------- Function : Set Polyline Linetype ---------- Calling Sequence : linetype(style) ------------------ int style; /* line style */ Output : -------- returns selected linestyle. Function : Set Polyline Line Width ---------- Calling Sequence : linewidth(width) ------------------ int width; /* line width */ Output : -------- returns selected line width. Function : Set Polyline Color ---------- Calling Sequence : linecolor(color) ------------------ int color; /* line color */ Output : -------- returns selected line color. Function : Set Polymarker Type ---------- Calling Sequence : markertype(style) ------------------ int style; /* marker style */ Output : -------- returns selected marker style. Function : Set Polymarker Scale ---------- Calling Sequence : markerscale(height) ------------------ int height; /* polymarker height */ Output : -------- returns selected marker height. Function : Set Polymarker Color ---------- Calling Sequence : markercolor(index) ------------------ int index; /* color index value */ Output : -------- returns selected marker color. Function : Set Text Font ---------- Calling Sequence : textfont(style) ------------------ int style; /* text font number */ Output : -------- returns selected text fonts. Function : Set Text Color Index ---------- Calling Sequence : textcolor(index) ------------------ int index; /* text color index */ Output : -------- returns selected text color. Function : Set Fill Interior Style ---------- Calling Sequence : filltype(type) ------------------ int type; /* 0 = Hollow */ /* 1 = Solid */ /* 2 = Pattern */ /* 3 = Hatch */ Output : -------- returns selected fill interior style. Function : Set Fill Style Index ---------- Calling Sequence : fillstyle(index) ------------------ int index; /* style of Hatch or Pattern */ Output : -------- returns selected fill style. Function : Set Fill Color Index ---------- Calling Sequence : fillcolor(color) ------------------ int color; /* fill color index */ Output : -------- returns selected fill color. Function : Set Writing Mode ---------- Calling Sequence : setwmode(mode) ------------------ char mode; /* 1 = replace */ /* 2 = overwrite */ /* 3 = complement */ /* 4 = erase */ Output : -------- selected writing mode. Function : Set Input Mode ---------- Calling Sequence : setinmode(mode,device) ------------------ char mode; /* 1 = request mode */ /* 2 = sample mode */ char device; /* 1 = locator */ /* 2 = valuator */ /* 3 = choice */ /* 4 = string */ Output : -------- selected input mode. //////////////////////////////////////// // Miscellanious Inquire Functions. // //////////////////////////////////////// Function : Inquire Color Representation ---------- Calling Sequence : inqcolor(color,srflg) ------------------ int color; /* requested color index. */ int srflg; /* set/realized flag */ Output : returns pointer to the structure color_attr. -------- struct color_attr { int index; int red; int green; int blue; } Function : Input Locator Position Request Mode ---------- Calling Sequence : rq_locator(device,begin_x,begin_y,terminator,end_x,end_y) ------------------ int device; /* locator device no. */ int begin_x; /* beginning X co-ordinate */ int begin_y; /* beginning Y co-ordinate */ int *terminator; /* terminator character */ int *end_x; /* final X co-ordinate */ int *end_y; /* final Y co-ordinate */ Output : Returns status as the function value. -------- 0 = request unsuccessful >0 = request successful. Function : Input Locator Position Sample Mode ---------- Calling Sequence : sm_locator(device,end_x,end_y) ------------------ int device; /* locator device no. */ int *end_x; /* final X co-ordinate */ int *end_y; /* final Y co-ordinate */ Output : Returns status as the function value. -------- 0 = request unsuccessful >0 = request successful. Function : Input Valuator Request Mode ---------- Calling Sequence : rq_valuator(device,init_value,out_value) ------------------ int device; /* valuator device no. */ int init_value; /* initial value */ int *out_value; /* final value */ Output : returns status : if successful returns >0. -------- else returns 0. Function : Input Valuator Sample Mode ---------- Calling Sequence : sm_valuator(device,out_value) ------------------ int device; /* valuator device no. */ int *out_value; /* returns this value */ Output : returns status : if successful returns > 0. -------- else returns 0. Function : Return Choice Input Request Mode. ---------- Calling Sequence : rq_choice(device,init_choice,choice) ------------------ int device; /* choice device no. */ int init_choice; /* initial choice number */ int *choice; /* choice number returned */ Output : Returns status 0 if unsuccessful -------- >0 if successful Function : Return Choice Input Request Mode. ---------- Calling Sequence : sm_choice(device,choice) ------------------ int device; /* choice device no. */ int *choice; /* choice number returned */ Output : Returns status 0 if unsuccessful -------- >0 if successful Function : Input string from string device (KBD) Request Mode. ---------- Calling Sequence : rq_string(device,length,echo) ------------------ int length; /* maximum length of string */ int device; /* string device no. */ int echo; /* 0 = don't echo chars */ /* 1 = echo chars on screen */ Output : char pointer to the text string. -------- Function : Input string from string device (KBD) Sample Mode. ---------- Calling Sequence : sm_string(device,length,echo) ------------------ int length; /* maximum length of string */ int device; /* string device no. */ int echo; /* 0 = don't echo chars */ /* 1 = echo chars on screen */ Output : char pointer to the text string if successful -------- If unsuccessful, it returns 0. Function : Return last GSX-86 Error Code ---------- Calling Sequence : gsx_error() ------------------ Ouput : ------- This routine is called to retrieve the error code returned by GSX-86 in AX. Currently, only open workstation function returns an error code. //////////////////////////////// // Include file GSX86MWC.h // /////////////////////////////// /* * GSX-86 structure definitions * */ struct ws_attr { int vertices; /* no. of output vertices */ int len_intout; /* length of intout */ int max_width; /* max. addressable width */ int max_height; /* max. addressable height */ int unit_flag; /* device co-ordinate units flag*/ int pixel_width; /* width of one pixel in /u met.*/ int pixel_height; /* height of one pixel (/u met.)*/ int no_char_ht; /* no. of character heights */ int no_line_types; /* no. of line types */ int no_line_widths; /* no. of line widhts */ int no_mark_type; /* no. of marker types */ int no_mark_size; /* no. of marker sizes */ int no_fonts; /* no. of text fonts */ int no_patterns; /* no. of patterns. */ int no_hatch; /* no. of hatching styles */ int no_colors; /* no. of pre-defined colors */ int no_gdps; /* no. of GDP's */ int gdp[10]; /* linear list of GDP's */ int gdp_attr[10]; /* attribute associated with gdp*/ int color; /* color capability 0=no;1=yes; */ int rotation; /* text rotation capability */ int fill; /* area fill capability */ int pixel; /* cell array operation capability */ int colors; /* no. of available colors */ int locators; /* no. of locator devices */ int valuators; /* no. of valuator devices. */ int choices; /* no. of choice devices. */ int strings; /* no. of string devices */ int ws_type; /* workstation type */ int p1; /* = 0; */ int min_ch_ht; /* minimum character height */ int p3; /* = 0; */ int max_ch_ht; /* maximum character height */ int min_line_width; /* minimum line width */ int p6; /* = 0; */ int max_line_width; /* maximum line width */ int p8; /* = 0; */ int p9; /* = 0; */ int min_marker_ht; /* minimum marker height */ int p11; /* = 0; */ int max_marker_ht; /* maximum marker height */ }; struct ws_in { int ws; int line_type; int line_color; int mark_type; int marker_col; int text_font; int text_color; int fill_type; int fill_style; int fill_color; }; struct char_attr { int sel_width; int sel_height; int cell_width; int cell_height; }; struct color_attr { int index; int red; int green; int blue; };