This is file GraphDoc describing FORTRAN graphics utilities.

There is a subroutine library (GRATS) of low-level routines which
perform the functions of the BBC BASIC graphics commands.
Include grats,f77 when linking.

       Initialization must CALL GRATS(IUNIT) to open the graphics
stream on unit "IUNIT" which is just a suitable FORTRAN stream number
and must be <= 60. We usually use 10.

       Termination is not needed because all Fortran units are
automatically closed on exit. You can CLOSE(IUNIT) if you want.

       COLOUR(K)     sets text colour to K
       DRAW(IX,IY)   draws a line from current point to (IX,IY), but
                     see LINE below.
       GCOL(M,K)     like GCOL M,K in BASIC.
       GWIND(IX1,IY1,IX2,IY2) makes graphics window with bottom left
                     at (IX1,IY1) and top right at (IX2,IY2)
       LINE(IX1,IY1,IX2,IY2) draws line from (IX1,IY1) to (IX2,IY2).
       MODE(M)       sets graphics screen mode to M.
       MOVE(IX,IY)   moves graphics cursor to the point (IX,IY).
       PLOT(IPL,IX,IY) does BASIC "PLOT IPL,IX,IY".
       PLOT85(IX,IY) completes a filled triangle.
       POLY(N,KX,KY) filled convex N-gon from arrays KX,KY
       PRDUMP(NL)    screen dump for all graphics modes. 0< NL <32 is
                     the number of (pseudo-text) lines to dump. This
                     routine needs ifp in the link step.
       RECTAN(IX1,IY1,IX2,IY2) draws filled rectangle with opposite
                     corners (IX1,IY1) and (IX2,IY2).
       SPOT(IX,IY)   plots a single point at (IX,IY).
       TAB(IX,IY)    moves text cursor to the column:row IX:IY.
       VDU(I)        like BASIC VDU I.
       VDU19(I1,I2)  like VDU19,I1,I2,0,0,0
       VDU23(ICHAR,I1,I2,I3,I4,I5,I6,I7,I8) redefines character.
       WINDOW(IX1,IY1,IX2,IY2) makes text window (remember IY2<IY1)

       ---------------------------------------------------------------

       There is also a library (FCOL) of routines for manipulating
screen images.

       The FORTRAN callable subroutine RDSCRN reads a BBC screen
formatted picture, or a packed version of such a screen and transforms
it into a matrix of integers giving the colour at each pixel:

       CALL RDSCRN(FILENAME,MODE,IBUF,IERR)

Input:
       FILENAME      character variable: name of the file to be read.

       MODE          integer: mode of the picture, must be 1 or 2.

Output:
       IBUF          byte array: buffer for the matrix of integers.
                     These are of byte length, but there must be an
                     extra 640 bytes on the end for working space in
                     the decoding process. Hence for mode 1, IBUF must
                     be at least of length (320x256+640)/4 = 20640
                     words long, while for mode 2 it needs
                     (160x256+640)/4 = 10400 words.

                     The extra 160 words can be used afterwards for
                     other purposes.

       IERR          integer: if >0 explains why it has not worked:
                     =1 file can not be read (or may not exist)
                     =2 the file has the wrong load address or length
                     =3 the packed format is wrong
                     =4 illegal mode.

       The arrays from RDSCRN can be compressed by the CERN library
routine UCOCOP.  This can easily make the 320x256 array from a mode 1
screen into a contiguous 256x256 array, or the 160x256 mode 2 screen
into a 128x128 array.

       ---------------------------------------------------

       Three FCOL packages provide a fast way of making a graphics
screen from an array of grey-level data. (Actually the "grey-levels"
are plotted as different colours because the BBC micro doesn't know
about grey levels). There are three packages which expect their data
in bytes, Integer*2 or Integer*4 format.
       They work by loading a section of native machine code into the
BBC and then sending it data in complete rows. Hence there are three
separate functions:
       1) Set up the host-code in the BBC, and tell it about the mode
and dimensions of the plot; this is performed by Subroutine STARTCODEn
       2) Send "grey-levels" for a complete row: Subroutine FCOLn
       3) Stop the host-code: Subroutine STOPCODEn
          This last step is ESSENTIAL otherwise other programs using
BBC host codes will not work afterwards (e.g. the panos editor).
       The n after each routine name is either 1, 2, or 4, depending
on the data type.
       The host-code is "$.graphics.utils.hostfcol" which name is
coded into the routines. You will have to change this and re-assemble
the FCOL routines if the host-code is moved. Hostfcol is made by
running the Basic program FcolAssem in the same directory.

       STARTCODE1(nx,mode,nc,kols,nds,mx,my)
       STARTCODE2(nx,mscale,mode,nc,kols,nds)
       STARTCODE4(nx,mscale,mode,nc,kols,nds)

Input parameters (all are in integer*4 format):
       nx            number of bytes to plot on a line
                     (<=320 in MODE 1, <=160 in MODE 2)

       mode          MODE of plot (must be 1 or 2)

       nc            number of "grey-level" boundaries (see nds)

       kols          array of colours for each boundary (should be in
                     the range 0 to 3 for MODE1, 0 to 15 for MODE2)

       nds           array of "grey-level" boundaries. These must
                     start with 0, and ascend monotonically, but
                     be < 256, 65536 & 2**32 for n = 1, 2 & 4. The
                     data passed to FCOLn are compared with these
                     boundaries to find which colour to plot.

       mx,my         number of pixels to plot for each point.
                     Examples explain this best:
                     In MODE 1 if we want to plot 256x256 points in a
                     square, nx should be 256, and mx=my=1, however if
                     we only want 128x128 points, and want to fill the
                     same sized square, then nx=128 and mx=my=2.
                     In MODE 2 the natural pixels are twice as long as
                     they are high; thus to make a 128x128 square
                     picture in mode 2 use nx=128, mx=1 & my=2

Alternatively, for the n = 2 & 4 routines

       mscale        In MODE 1 this is the same as mx and my.
                     In MODE 2 mx=mscale but my=2*mscale; thus only
                     square pixels can be made.

       FCOLn(jbuf)   plots one row of pixels from the array jbuf
                     according to the formulae defined in STARTCODEn.
                     jbuf is integer*1, *2, or *4 depending on the
                     value of n. The numbers are assumed to be
                     unsigned, but the maximum number is NOT allowed.
                     Hence FCOL1 accepts numbers from 0 to 254,
                           FCOL2 accepts numbers from 0, to 65534,
                     and   FCOL4 accepts numbers from 0, to 2**32-2

       STOPCODEn     stops the BBC code at the end of the picture.
                     This must be done at the end of every plot.

       **********    IMPORTANT NOTES:
                     1) do not give FCOL more rows than are needed to
                        fill the screen.
                     2) call STOPCODE at the end of the picture.

       The FCOL2 package also contains a histogram facility showing
how many plotted pixels have been plotted in each "grey-level" band:

       FUNCTION IHIST(i) returns the contents of bin i, where i is in
                     the range 1 to nc

also the "grey-level" boundaries can be moved (without replotting,
provided that the jbuf array has been stored contiguously) to see how
the histogram changes:

       SUBROUTINE MOVBND(jb,n,i,nval)
       jb            the full integer*2 array of values (as
                     passed to FCOL2 line by line)
       n             total number of pixels
       i             the index of the boundary to move
       nval          the new value for the boundary

       SUBROUTINE INSBND(jb,n,in)
       jb & n        as above
       inserts new boundary at a value one above the boundary at in.

       SUBROUTINE DELBND(id)
       deletes the boundary id.

       ---------------------------------------------------------------

Additional Utilities included in the FCOL library

       SUBROUTINE MOVE14(IBYTE,IWORD,N) makes the N bytes in array
IBYTE into words in IWORD. IBYTE and IWORD may coincide in memory. The
bytes are assumed to be positive in the range 0 - 255.
       Similar routines MOVE41, MOVE12, MOVE21, MOVE24, MOVE42
work similarly to transform byte, integer*2 and integer*4 arrays. All
words are assumed positive, and the arrays may coincide in memory.

       The following FORTRAN program illustrates the uses.

      PROGRAM TestScrn
      DIMENSION KOLS(8),NDS(8)
      COMMON IBUF(20480),IEX(160)
      CHARACTER*40 NAME
      DATA KOLS/0,1,2,3,4,5,6,7/,NDS/0,1,2,3,4,5,6,7/
    2 PRINT 102
  102 FORMAT(' Enter file name ')
      READ 103,NAME
  103 FORMAT(A)
    5 PRINT 104
  104 FORMAT(' which mode (1 or 2)')
      READ *,M
      CALL RDSCRN(NAME,M,IBUF,IERR)
      IF(IERR.NE.0) THEN
        PRINT 101,IERR
  101   FORMAT(' IERR ',I1)
        STOP
      ENDIF
C            NC is number of colour bounds
      NC=4*M
C            NX is number of pixels in row
      NX=320/M
C            NY is number of rows
      NY=256
      CALL GRATS(10)
      CALL MODE(M)
      CALL STARTCODE1(NX,M,NC,KOLS,NDS,1,1)
C        LINE is address of start of line; (begin at bottom!)
      LINE=(NY-1)*(NX/4)+1
      DO 10 I=1,NY
        CALL FCOL1(IBUF(LINE))
   10 LINE=LINE-NX/4
      CALL STOPCODE1
C            now remove the bytes for square pictures
      NX=256/M
      NY=NX
C      CALL UCOCOP(IBUF,IBUF,NY,NX/4,80,NX/4)
      NXBY4=NX/4
      IBIN=1
      IBOUT=1
      DO 15 I=1,NY
        DO 14 J=1,NXBY4
   14   IBUF(IBOUT+J-1)=IBUF(IBIN+J-1)
        IBOUT=IBOUT+NXBY4
        IBIN=IBIN+80
   15 CONTINUE
C            now plot again
      CALL VDU(12)
      CALL STARTCODE1(NX,M,NC,KOLS,NDS,1,M)
      J=(NY-1)*(NX/4)+1
      DO 20 I=1,NY
        CALL FCOL1(IBUF(J))
   20 J=J-NX/4
      CALL STOPCODE1
      END

---------------------------------------------------------------------