 














                             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 rectangleslines text and other graphics features with
   simple BASIC calls.

Onthe disk you will find a file named NCRGRAF.COMforinterpreted 
MS-BASICand 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 <cr>


After a few seconds the  A>  appears again.

Now load MS-BASIC by typing:

MBASIC /M:&HB90 <cr>

The graphics  routines  start at address  B90.  The extension 
/M:&HB90 allows MS-BASIC to use memory only up to locationB900 
otherwiselargeprograms or the stack could destroy the graphics 
   routines.

Using CONFIG you can define one function key as:

NCRGRAF <cr MBASIC /M:&HB90 <cr>

(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 tothe
     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 addressesOn 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.


Stringvariablesare definedbya  $ 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 startpointThe 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 highThe 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 oftext 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 factorZ for
                                              text and box
 



All parameters except A for GTEXT must be of type integer.



For detailed information and examples see the next pages.









