N C R G R A F A GRAPHICS EXTENSION FOR MS-BASIC Prepared by B® Kowol¬ Adv.Dev® Augsburg Š    Introduction    To  provide the possibility of programming graphics for the N C R    DECISION  MATE V„ with MS-BASIC„ NCR has developed some callable    assembler routines. These routines allow the user to produce  circles¬ rectangles¬ lines¬ text and other graphics features with simple BASIC calls.    On the disk you will find a file named NCRGRAF.COM„ for interpreted    MS-BASIC and a file named NCRGRAF.REL„ for linking it with compiled    BASIC programs or assembler routines. * MS-BASIC is a registered trademark of Microsoft Corp.    Load graphics and start MS-BASIC    To load the graphics routines into memory, start your DECISION MATE V and type    NCRGRAF           After a few seconds the A>„ appears again.          Now load MS-BASIC by typing:    MBASIC /M:&HB90°             The  graphics routines start at address B90±.   The  extension    /M:&HB90° allows MS-BASIC to use memory only up to location B900¬    otherwise large programs or the stack could destroy the  graphics routines.    Using CONFIG„ you can define one function key as:    NCRGRAF     (For a description of config see the NCR CP/M manual)® (For all MS-BASIC statements see the MS-BASIC manual). Š   Programming Graphics with MS-BASIC and NCRGRAF    Calls and Parameters    Every  graphics  routine must have a specific  name®  This  name¬    which  is a BASIC variable¬  must contain the exact start address„    of the corresponding routine.    Exampleº GCIRCL=&HB90B     GCIRCL is the name of the routine and       &H specifies the value B90B as an       address    After the name and the start address are defined¬ the routine may    be called in the program.    Exampleº GCIRCL=&HB90B     .     .     .     R=100       .       CALL GCIRCL(R)       Z=Z+1       .       .       The BASIC statement CALL„ causes a jump to the address     which is specified in the name.     After executing the graphics routine and returning to the      BASIC program, execution continues with the next statement       after the call (in our example Z is incremented by 1).    It  is  very important that all start addresses are  correct  and    that  the  names  used in the definition and  in  the  calls  are    exactly„ the same.    Exampleº GCIRCL=&HB90B     .       .     CALL CIRCLE(R)             This program will not jump to B90B, because the name         CIRCLE used in the CALL statement has not been         defined yet and therefore contains the default value 0.         So in the example above, the program will jump to memory location 0000 and you are in CP/M or anywhere else.    The appendix gives a summary of the implemented graphics features and their start addresses® On flexible disk there is a BASIC file    called GRAFINIT. To start programming load "GRAFINIT". Now you have a program line with number zero containing all names and their start addresses. (GRAFINIT is stored in ASCII format, so it can be merged to the current program at any time). Š    Most  of  the graphics routines demand parameters„  which  are    transferred to NCRGRAF.    The number  and  type  of  parameters  must  satisfy  the  syntax    requirements of each graphics routine¬ otherwise wrong values are    transferred to the graphics.    All parameters must be variables !    If   you're  calling  a  routine  with  constants  or  arithmetic    expressions as parameters a syntax error will occur.    Almost all routines ask for the parameter type integer,    only the routine GTEXT„ has one parameter of type string.    MS-BASIC„ offers two ways to define an integer variable :    1® Typing a %„ after the name    Exampleº X%=100           YMAX%=400     PRINT RADIUS%    2® Using the DEFINT„ statement    Exampleº DEFINT X,Y       With the above statement all variables       beginning with the letter X or Y       are integers.    The  second way is very comfortable¬  because you don't  have  to    type the ¥ every time.    String variables are defined by a $„  or the  DEFSTR„ statement. Note : If you want to program graphics with assembler, then the address of the first parameter must be in register H,L, " " " " second " " " " " D,E, " " " " third " " " " " B,C. Declare all graphics routines as EXTERNALS in your assembler program, assemble it with the M80 assembler and link it with NCRGRAF.REL. If you want to link compiled BASIC programs with the graphics routines, you don't need the variable declarations with the start addresses. Š    GINIT    Initialize the graphics memory,    erase the screen,    set default values for    GPATT º P=0    GZOOM º Z=0    GMODE º M=1          set the error byte to ° (for error handling see page 13 ).    In a program GINIT„ must be the first graphics statement.    GEXIT    Erase the screen,    leave the graphics mode,    return to alpha mode.          GEXIT„ should be used to leave the graphics mode in a proper    way (for the problem graphics mode - alpha mode see page 14 ).    After a GEXIT statement¬ the next graphics routine to be called    must be GINIT . Š   GPOINT(X,Y)„ X ½ ° - 63¹ Y ½ ° - 399    Set the cursor for a following routine at the point (X,Y).    GPOINT defines the centre of a circle     the start point for rectangles and boxes     the start point for a line     the start point for a text.    The point (0,0) defines the lower left corner of the screen.    Calling GPOINT sets the cursor¬ but the cursor remains    invisible® To make this point visible use the GLINE    command with the same parameters after GPOINT.    After GPOINT and execution of one of the above routines¬ the    cursor may be at a different location¬ so always use GPOINT    to locate your drawings correctly.    GCIRCL(R)„ R ½ ± - 25µ    Draw a circle with radius R with the centre defined by GPOINT®    Noteº The name is GCIRCL„ and not GCIRCLE¬ because          only ¶ letters for names are allowed for compiled programs.    Exampleº The following program asks for the coordinates X and Y      and the radius R and then draws a circle with these values. 0 GINIT=&HB902 : GPOINT=&HB905 : GCIRCL=&HB90B 10 DEFINT X,Y,R 20 INPUT"X";X 30 INPUT"Y";Y 40 INPUT"R";R 50 CALL GINIT 60 CALL GPOINT(X,Y) 70 CALL GCIRCL(R) 80 INPUT$(1) 'wait for keyboard input 90 CALL GEXIT 100 END Š   GRECT(M,N,D)„ M ½ ² - 64° N ½ ² - 64° D ½ ° - 7    Draw a rectangle with the sidelengths M and N in direction D.    GPOINT defines the lower left corner of the rectangle and    with the direction d the rectangle is rotated in steps of    4µ degrees counterclockwise around the cursor.    GBOX(M,N,D)„ minimal values for M and N ½ ± ¬ see GRECT    Draw a filled rectangle with sides M and N in direction D.    The fill pattern can be selected with the GPATT„ statement.          The size of the box is affected by the GZOOM„ command.    The fill pattern is also zoomed®    If the zoom factor is Z ¬ then the actual sidelengths are M*(Z+1) and N*(Z+1) . These sidelengths should not exceed 640. Š    GLINE(X,Y)„ X ½ ° - 63¹ Y ½ ° - 399    Draw a line from the cursor to the point (X,Y).    To define a start point for the first GLINE command use GPOINT.    Continuous GLINE commands without subsequent GPOINT can be used    to draw polygons (the end point is the new start point).    Noteº Drawing a line¬ the cursor doesn't stand exactly at the          end point¬ but one point ahead of the line     e. g. drawing 10 times a horizontal line of 10 points     the resulting line will have 109 points.     For exact drawing use GPOINT after each GLINE with the same parameters.    For a simple example see appendix.    GTEXT(A$,D)„ D ½ ° - 7    Draw the string A¤ in direction D.          GPOINT  defines the lower left corner of the first  character  as    the start point® The direction D rotates the text  around  the    cursor in the same way as described above (see GRECT).    The size of the text is affected by the GZOOM„ statement.    If the zoom factor is ° then the character field is ¸ pixels wide and 16 pixels high® The character itself has a size of 6 by 9 pixels. If the zoom factor is Z then the size of the character field is 8*(Z+1© by 16*(Z+1© pixels. A  text  of  ³ characters with zoom factor  ´  is  3*8*(4+1)=12°  pixels long.    There  is no size check done for GTEXT¬  so be careful  with  the    text length and the zoom factor. Š   GPRINT(P,L)„ P ½ ° - ´ L ½ ° - 99    Print a hardcopy from the screen with printer P and linefeed L.    P ½ ° EPSON MX8² F/T in single density    P ½ ± ¢ ¢ in double density    Because the EPSON MX8² F/T can print only 57¶ points    horizontally only the first 57¶ pixels are sent to the printer.    P ½ ² EPSON MX100 in single density    P ½ ³ ¢ ¢ in double density    P ½ ´ ITOH M8510A    The EPSON MX100 and the ITOH M8510A can print all 64° pixels.    The EPSON MX8° can only print 48° pixels.    L ½ ¸ recommended linefeed for the EPSONs    L ½ 1¶ recommended linefeed for the ITOH.    The recommended values for L provide connected lines.    Smaller  values  will produce overlapped lines and bigger  values    will produce lines with a visible distance.    Because GPRINT is only a hardcopy (each pixel on will cause a    printer  needle  to  print)¬  a circle may  be  distorted  to  an    ellipse.    The EPSON MX8² F/T does not distort¬ a circle on the screen is a    circle on the paper.    The EPSON MX100 distorts horizontally.         The ITOH M8510A distorts vertically.    Note º Before you call GPRINT„ use the BASIC statement     WIDTH LPRINT 255 to avoid the sending of a carriage return and a linefeed after every 128 pixels.    The EPSONs print graphics only in one direction.    The ITOH can print bidirectionally¬ but to achieve better    printing quality you should switch on unidirectional printing    with the statement    LPRINT CHR$(27);CHR$(62);    After GPRINT , bidirectional print can be selected with    LPRINT CHR$(27);CHR$(60);    GPRINT  prints  the  whole  screen¬  and  printing  can  only  be    interrupted by switching off the NCR DM V .    After printing is finished an additional linefeed is printed. Š    The items selected with the next three features remain until they    are changed using these statements again or a GINIT.    GMODE(M)„ M ½ ° - 3    Selects the drawing mode. M = 0 replace draw white, the black background of a character and the black parts of a dashed line and a box pattern are drawn black    M  ½  1 complement the crossing point of two white  lines  is        black    M  ½  2  draw black on a black  background¬  drawing  is  not          visible         on a white background¬ drawing is visible    M ½ 3 draw white opposite of M=2    GINIT sets the default value M ½ 1.    The following picture shows the effect of drawing a text in different modes on a white box.  The  expressions  "white¢  and    "black¢  are  related to those of the CRT and not of the  printer    (the printer converts a white line on CRT to a black line on  paper). Š    GPATT(P)„ P ½ ° - 15    Selects one of 1¶ patterns for the filling of boxes.    The different patterns are listed in the appendix.    With  the pattern¬ which is an ¸ by ¸ pixel character, a    specific  linestyle is defined by the last two ¸ pixel  rows  of    the  pattern®  All drawing (lines¬  rectangles¬  circles© is done    with that style.    The default value of P after a GINIT is ° .    With different zoom factors¬ the fill pattern is also zoomed. The picture below shows the effect of zooming a pattern.    GZOOM(Z)„ Z ½ ° - 15    Selects the zoom factor for text and for boxes (for the effect on    boxes see GBOX).    GINIT sets the default value Z=0 Š   Error Handling    At  memory location B901„ is a status byte  which must have the    value ° ¬ otherwise the drawing will stop when an error occurs.    GINIT„  sets  the  status  byte to ° and it  remains  °  if  the    checked parameters are correct.    If  a  parameter  is recognized to be wrong the  status  byte  is    changed to a specific value (for a list see below).    The  BASIC  statement PEEK (&HB901)„ returns the  value  of  the    status  byte®  If an error occurs¬  read the status byte and then    check your program for the error source.      Error Meaning Routine„      ± X coordinate ¼ ° GPOINT      ² X coordinate ¾ 63¹ GPOINT      ³ Y coordinate ¼ ° GPOINT      ´ Y coordinate ¾ 39¹ GPOINT      µ X ¼ ° GLINE      ¶ X ¾ 639 GLINE      · Y ¼ ° GLINE      ¸ Y ¾ 39¹ GLINE      1° zoom factor out of range GZOOM      2° radius out of range GCIRCL      3° direction out of range GBOX ¯ GRECT      4° pattern out of range GPATT      5° mode out of range GMODE      6° direction out of range GTEXT      7° printer selector out of range GPRINT      8° side M ¼ ² ¯ ± GRECT ¯ GBOX      8± side M ¾ 64° GRECT       side M for zoomed box ¾ 64° GBOX      8² side N ¼ ² ¯ ± GRECT ¯ GBOX      8³ side N ¾ 64° GRECT       side N for zoomed box ¾ 64° GBOX Note: There is no clipping done, that means if a figure is drawn over the edges of the screen, the rest of the picture is visible on other parts of the screen. Š   Graphics Mode and Alpha Mode    With GINIT„ you are entering the graphics mode and with GEXIT„ you    are leaving the graphics mode and entering the alpha mode again.    A program running in graphics mode can be switched immediately to alpha mode, if one of the following things occur :    typing CTRL C¬  a STOP„ statement¬  a syntax error„ or a printing of text with  the  BASIC statement PRINT„.    The  resulting CRT display will be a curious blinking picture filled with many unusual signs. Don't worry about that.     The reason for this effect is simple :    ¸  pixels in a row in graphics mode are changed to the  character    with the ASCII value defined by these ¸ points.    The uppermost 2´ pixel lines define the alpha CRT display.    To  avoid  a  disturbance of graphics  when  you  want  to  work    interactively, use  GTEXT  to print your strings on CRT  and  the    BASIC  statements INKEY$„ and INPUT$®  These statements  will  not    echo your keyboard input on the CRT. It is possible that the error message of an occurring syntax error is not readable because of the graphics-to-alpha-switching. In this case the use of the BASIC statements ON ERROR GOTO and RESUME is very helpful. Š Appendix Program Examples Fill Patterns Survey of Implemented Graphics Features Š   Summary of the Implemented Graphics Features    Name Syntax Start Value Range Meaning     Address    GINIT GINIT B902 initialize graphics    GEXIT GEXIT B920 erase screen¬ leave     graphics¬ enter alpha     mode    GPOINT GPOINT(X,Y© B905 X ½ ° - 63¹ set the cursor     Y ½ ° - 39¹ at point (X,Y©    GCIRCL  GCIRCL(R© B90B R ½ ± - 25µ circle with radius R    GRECT GRECT(M,N,D© B914 M ½ ² - 64° rectangle with     N ½ ² - 64° sidelengths M and N     D ½ ° - · in direction D    GBOX GBOX(M,N,D© B911 same as GRECT filled rectangle except min. for M and N is 1    GLINE GLINE(X,Y© B90E X ½ ° - 63¹ draw line to     Y ½ ° - 39¹ point (X,Y)    GTEXT GTEXT(A$,D© B91D D ½ ° - · draw string A$     ASCII 20H - 7EH in direction D    GPRINT GPRINT(P,L© B923 P ½ ° - ´ hardcopy on printer     L ½ ° - 9¹ P with linefeed L    GMODE GMODE(M© B91A M ½ ° - 3 draw in mode M    GPATT  GPATT(P© B917 P ½ ° - 1µ fill pattern for box     or line style P    GZOOM  GZOOM(Z©  B908 Z ½ ° - 1µ zoom factor Z for     text and box    All parameters¬ except A¤ for GTEXT must be of type integer.    For detailed information and examples see the next pages. Š