sources/int/graf/doc/iiuwgraf.ang

   1 you can find here certain information about graphics operation in
   2
   3 LOGLAN version DOS
   4 ________________________________________________________________________
   5
   6
   7 IIUWGRAF        - basic graphics support for MICROSOFT compilers:
   8
   9                 FORTRAN 77 vsn 3.31
  10                 PASCAL     vsn 3.31
  11         and
  12                 Lattice C  vsn 2.14
  13
  14         for IBM color graphics card & Hercules II monochrome card
  15
  16
  17
  18 Osrodek Obliczeniowy,
  19 Instytut Informatyki Uniwersytetu Warszawskiego,
  20 00-901 Warszawa, PKiN VIII p.
  21 tel. (0048)22-200211-4028
  22
  23
  24
  25
  26
  27 general info
  28 ------------
  29
  30         Drawing is done by issuing calls to subroutines which
  31         modify the contents of a bitmap video buffer. Its contents
  32         usually is directly displayed on the screen, so the
  33         changes are seen immediately.
  34         The video buffer assignment, however, can be changed to
  35         point to a user-supplied block of memory. In this case,
  36         the changes in bitmap setting are not displayed and even
  37         putting the real screen into graphics mode is not necessary.
  38         The drawing may be constructed silently, saved away
  39         and restored later on an active display or output to
  40         a binary file.
  41         The Hercules card offers additional possibilities of fast
  42         switching between two directly displayable pages.
  43
  44
  45         The interface routines are on two different levels:
  46
  47                 level 1 - screen management on pixel basis
  48                                   uses actual screen indices
  49
  50                 level 2 - positioning & drawing
  51                                   in abstract world coordinates
  52
  53         Description of calling sequences for Fortran and C
  54         are given together with explanations below. Pascal
  55         declarations may be found in the "graph.h" include
  56         file in the distribution set.
  57
  58
  59
  60 LEVEL 1 ROUTINES
  61 ________________
  62
  63 All parameters not specified explicitly as arrays or reals
  64 are integers.
  65 All integer parameters are assumed to be "integer*2" (16 bits)
  66 in Fortran, "integer" in Pascal and "int" in C.
  67
  68 screen address range:
  69
  70                         0 <= ix <= 719  for Hercules card
  71                         0 <= iy <= 347
  72
  73                         0 <= ix <= 319  for IBM color card
  74                         0 <= iy <= 199
  75
  76                         0 <= ix <= 639  for IBM color card in mono mode
  77                         0 <= iy <= 199
  78
  79         (0,0) is top left pixel
  80
  81                 (0,0)-----------> (ix,0)
  82                   |
  83                   |
  84                   |
  85                   V
  86                 (0,iy)
  87
  88
  89 Three separate libraries are supplied, each for a different
  90 kind of graphics screen:
  91
  92         HGCMSF          for Hercules
  93         MGCMSF          for IBM card in full color mode
  94         MGC64MSF        for IBM card in mono mode
  95
  96 These libraries follow Microsoft Fortran and Pascal calling
  97 conventions.
  98 Optionally, each of these libraries can be supplied in four
  99 variants, following four Lattice C models (S, D, P, L).
 100
 101 initialization/termination routines
 102 -----------------------------------
 103
 104 ---------------------------------------------->>  SCREEN
 105
 106 Fortran:        | C:
 107                 |
 108 i=screen(dummy) | int  screen();
 109                 |
 110
 111         returns code identifying which library is being used
 112
 113                 1       for Hercules
 114                 2       for IBM in full color 320*200
 115                 3       for IBM in monochrome 640*200
 116                 4       for IBM in monochrome 320*200
 117
 118
 119 ---------------------------------------------->>  GRAPH
 120
 121 call graph(i) | graph(i);
 122
 123         switches display to graphics mode
 124         clears entire screen
 125         involves a delay of approx. 3 secs  [ for Hercules only ]
 126         for IBM color display, "i" sets either regular color mode,
 127         or black&white mode, more suitable for use on monochrome
 128         displays
 129                 i should be 1 for color mode 320*200
 130
 131
 132 ---------------------------------------------->>  TEXT
 133
 134 call text | text();
 135
 136         switches display to character mode
 137         does not change current video buffer assignment
 138         fills screen with blanks
 139         delays for 3 secs  [ for Hercules only ]
 140
 141
 142 ---------------------------------------------->>  CLS
 143
 144 call cls | cls();
 145
 146         clears current video buffer in graphics mode,
 147         without turning display off
 148
 149
 150 ---------------------------------------------->>  HPAGE
 151
 152 call hpage(nr, mode, cflag) | hpage(nr,mode,cflag);
 153
 154
 155 [Hercules II only]
 156
 157         controls access to both pages of Hercules-II;
 158
 159         "nr"    - page number ( 0 or 1)
 160         "mode"  - 0 for text display,
 161                       1 for graphics display,
 162                      -1 for buffering only (display not affected)
 163         "cflag" - 0 for preserving previous contents
 164                     - 1 for clearing buffer contents
 165
 166         switching pages via "hpage" is done without delay if the mode
 167         remains unchanged;
 168         otherwise,  "call graph" is equivalent to "call hpage(0,1,1)"
 169                 "call text"  is equivalent to "call hpage(0,0,1)"
 170
 171         the typical animation loop may be done as follows:
 172
 173                 call hpage(0,1,1)
 174         c       draw initial picture
 175                 ...
 176                 page=1
 177         1       continue
 178                 call hpage(1-page,1,0)  ; set display
 179                 call hpage(page,-1,1)   ; set buffer
 180         c       draw modified picture
 181                 ...
 182                 page=1-page
 183                 if (.not.finished) go to 1
 184
 185
 186 ---------------------------------------------->>  VIDEO
 187
 188 call video(array) | video(array);
 189                   | char *array;
 190
 191         sets video buffer to "array", which should have
 192         32K bytes for Hercules, 16K bytes for IBM card.
 193         "video" preserves the previous contents of "array".
 194         Subsequent calls to drawing subroutines
 195         will not affect screen display, picture
 196         created in this buffer may be transferred
 197         to actual display via "getmap"-"putmap",
 198         or some other form of saving & restoring.
 199
 200
 201
 202 mode setting routines
 203 ---------------------
 204
 205
 206 ---------------------------------------------->>  COLOR
 207
 208 call color(i) | color(i);
 209
 210         sets current color to i
 211         for monochrome displays, 0 means black, non-0 - white
 212         for color displays, 0 means background
 213
 214
 215 ---------------------------------------------->>  STYLE
 216
 217 call style(i) | style(i);
 218
 219         sets style of lines and fill shades to a combination
 220         of current color and background color (for mono -
 221         white and black, respectively) according to 5 predefined
 222         patterns:
 223
 224                 0       ....
 225                 1       ****
 226                 2       ***.
 227                 3       **..
 228                 4       *.*.
 229                 5       *...
 230
 231         where   '*' means curent color,  '.' background color
 232
 233
 234 ---------------------------------------------->>  PATERN
 235
 236 call patern(iv,io) | pattern(iv,io);
 237
 238         sets style of lines and fill shades to an explicitly specified
 239         combination of colors : "iv" for even scan lines, "io" for odd.
 240         Color encoding is decimal, allowing 4 pixels.
 241         Lines are drawn always according to "iv".
 242
 243         Examples:
 244
 245         call patern(1100,0011)
 246                 is equivalent to
 247         call color(1), call style(3)
 248
 249
 250         call patern(1212,2121)
 251                 produces a shade that cannot be otherwise achieved
 252                 ( a dotted line consisting of pixels in colors 1 and 2 )
 253
 254
 255 ---------------------------------------------->>  BORDER
 256
 257 call border(i) | border(i);
 258
 259 [ IBM color mode only ]
 260
 261         sets actual background color to i  ( i = 0,1,...,15 )
 262
 263
 264 ---------------------------------------------->>  PALLET
 265
 266 call pallet(ip) | pallet(ip);
 267
 268 [ IBM color mode only ]
 269
 270         changes current pallette to pallette ip ( 0 or 1 )
 271         default pallette is 0
 272
 273
 274 ---------------------------------------------->>  INTENS
 275
 276 call intens(i) | intens(i);
 277
 278 [ IBM color mode only ]
 279
 280         changes current intensity, 1 means more intensity, 0 less;
 281         default intensity is 1
 282
 283
 284 positioning routines
 285 --------------------
 286
 287
 288 ---------------------------------------------->>  MOVE
 289
 290 call move(ix,iy) | move(ix,iy);
 291
 292         sets current position to (ix,iy)
 293         picture remains unchanged
 294
 295
 296 ---------------------------------------------->>  INXPOS
 297                                                   INYPOS
 298
 299 ix=inxpos(idummy) | int  inxpos();
 300
 301         returns current x screen coordinate
 302
 303
 304 iy=inypos(idummy) | int  inypos();
 305
 306         returns current y screen coordinate
 307
 308
 309 ---------------------------------------------->>  PUSHXY
 310                                                   POPXY
 311
 312 call pushxy | pushxy();
 313
 314         pushes current position, color & mode
 315         stack is kept internally, max depth is 16
 316
 317
 318 call popxy | popxy();
 319
 320         restores position, color & mode from internal stack
 321
 322
 323 ---------------------------------------------->>  TRACK
 324
 325 call track(ix,iy) | track(ix,iy);
 326
 327         displays a small (8*8) arrow-shaped cursor which can be
 328         moved around with cursor keys; a single keystroke moves
 329         it by 5 pixels, in shift mode step size is 1 pixel;
 330         "home" key returns the cursor to the initial (ix,iy);
 331         "end" removes cursor from screen, and returns - its
 332         position can be read with "in?pos" above.
 333
 334
 335
 336 pixel operations
 337 ----------------
 338
 339 ---------------------------------------------->>  POINT
 340
 341 call point(ix,iy) | point(ix,iy);
 342
 343         moves to pixel (ix,iy) and sets it to current color
 344
 345
 346 ---------------------------------------------->>  INPIX
 347
 348 ic=inpix(ix,iy) | int  inpix(ix,iy);
 349
 350         moves to pixel (ix,iy) and returns its color setting;
 351         for Hercules and IBM monochrome mode 640*200 :
 352                 it will be 1 if pixel is on, 0 if it is off.
 353
 354
 355
 356 line drawing
 357 ------------
 358
 359 ---------------------------------------------->>  DRAW
 360
 361 call draw(ix,iy) | draw(ix,iy);
 362
 363         draws a line from current screen position to (ix,iy);
 364         sets current position to (ix,iy);
 365         line is drawn in current color, with both terminal pixels
 366         always turned white ( non-background) for non-black
 367         ( non-background ) line color.
 368         Bresenham algorithm is used.
 369
 370
 371 ---------------------------------------------->>  CIRB
 372
 373 call cirb(xi,yi,ri,alfa,beta,cbord,bcint,p,q)
 374 real alfa,beta
 375
 376 [ not available in Lattice C ]
 377
 378         draws a circle (or ellipse, depending on aspect value),
 379         optionally filling its interior; does not preserve position;
 380         (xi,yi) - center coordinates
 381         ri - radius in pixels (horizontally)
 382         alfa, beta - starting & ending angles; if alfa=beta a full
 383         circle is drawn; values should be given in radians;
 384         cbord - border color
 385         bcint - if .ne.0, interior is filled in current style&color
 386         p,q - aspect ratio; if p/q=1, a perfect circle is drawn,
 387         if p/q<1, the horizontal axis is longer, if p/q>1 - the vertical
 388         axis is longer;
 389
 390
 391
 392 bitmap operations
 393 -----------------
 394
 395 ---------------------------------------------->>  GETMAP
 396
 397 call getmap(ix,iy,iarray) | getmap(ix,iy,iarray);
 398                           | char *iarray;
 399
 400         saves rectangular area between current position as
 401         top left corner and (ix,iy) as bottom right corner,
 402         including border lines;
 403         position remains unchanged.
 404         "iarray" should have  4 + ( rows * ( 3 + cols div 8))
 405         bytes.
 406
 407
 408 ---------------------------------------------->>  PUTMAP
 409
 410 call putmap(iarray) | putmap(iarray);
 411                     | char *iarray;
 412
 413         sets rectangular area of screen pixels to that saved
 414         by "getmap" in "iarray";
 415         same size is restored, with top left corner in current
 416         position;
 417         position remains unchanged.
 418
 419
 420 ---------------------------------------------->>  ORMAP
 421
 422 call ormap(iarray) | ormap(iarray);
 423                    | char *iarray;
 424
 425         same as putmap, but saved bitmap is or'ed into screen
 426         rather than just set.
 427
 428
 429 ---------------------------------------------->>  XORMAP
 430
 431 call xormap(iarray) | xormap(iarray);
 432                     | char *iarray;
 433
 434         same as putmap, but saved bitmap is xor'ed into screen
 435         rather than just set.
 436
 437
 438
 439 character i/o
 440 -------------
 441
 442 ---------------------------------------------->>  INKEY
 443
 444 ik=inkey(idummy) | int  inkey();
 445
 446         returns next character from keyboard buffer;
 447         0 is returned if buffer is empty;
 448         special keys are returned as negative numbers;
 449         ALT-NUM method may be used for entering character codes
 450         above 127 (this makes entering special keys 128-132
 451         impossible);
 452         if a character is returned, it is also removed
 453         from the buffer, so MS-DOS will not see it (CTRL-C!);
 454         typeahead is allowed, echo is suppressed.
 455
 456
 457 ---------------------------------------------->>  HASCII
 458
 459 call hascii(ic) | hascii(ic);
 460
 461         'xor's the character in a 8*8 box with top left corner
 462         in the current position;
 463         moves current position by (8,0);
 464         character code 0 sets complete box to black ( background ),
 465         with no change in position.
 466         BIOS ROM font for IBM color card is used. If the font
 467         table is not at F000:FA6E, the character will probably
 468         be unrecognizable, and most certainly wrong.
 469         For codes >127, table pointed to by interrupt vector 31
 470         is used.
 471
 472
 473 ---------------------------------------------->>  HFONT
 474
 475 call hfont(iseg,ioffs) | hfont(iseg,ioffs);
 476
 477         sets 8*8 horizontal font table address to iseg:ioffs.
 478
 479
 480 ---------------------------------------------->>  HFONT8
 481
 482 call hfont8(iseg,ioffs) | hfont8(iseg,ioffs);
 483
 484         includes a copy of IBM ROM 8*8 font and returns address
 485         suitable for passing to "hfont";
 486         use of "hfont8" makes program larger but quarantees
 487         BIOS ROM independence.
 488
 489
 490
 491 line -oriented i/o
 492 -------------------
 493
 494 ---------------------------------------------->>  OUTHLINE
 495
 496 call outhline(n,l) | outhline(n,l);
 497                    | char *l;
 498
 499         call "hascii"  "n" times with subsequent bytes
 500         from "l" array as arguments;
 501         before each character is written, "hascii(0)" is
 502         called.
 503
 504
 505 ---------------------------------------------->>  INHLINE
 506
 507 call inhline(n,l) | inhline(n,l);
 508                   | int  *n;
 509                   | char *l;
 510
 511         reads a line of at most "n" characters from
 512         the keyboard, storing them in the "l" array;
 513         characters are echoed at current position with "hascii"
 514         as they are typed in;
 515         a blinking cursor prompts for the next character;
 516         BACKSPACE works as expected, RETURN completes the line;
 517         typing "n"-th character also completes the line;
 518         "l" is blank filled up to "n" bytes;
 519         on return "n" is the total number of characters read.
 520
 521
 522
 523 window - oriented i/o
 524 ---------------------
 525
 526 ---------------------------------------------->>  MKWNDW
 527
 528 call mkwndw(ix,iy,icols,ilines,iwndw,iwndwsize,iborder)
 529
 530  | mkwndw(ix,iy,icols,ilines,iwndw,iwndwsize,iborder);
 531  | int  ix,iy, icols, ilines;
 532  | int  iwndw[];
 533  | int  iwndwsize, iborder;
 534
 535         makes a tty-like scrollable window for "ilines" lines
 536         of alphanumeric text of "icols" characters each;
 537         top left corner of the window is located at (ix,iy);
 538         if "iborder" is non-zero, the window will have a solid
 539         border and a margin of 2 black pixels drawn around it;
 540         "iwndw" should be an array large enough to "getmap"
 541         complete window into it, leaving 20 bytes free,
 542         however, if "bury" and "expose" are not to be applied to
 543         the window, 20 bytes total size is enough;
 544         "iwndwsize" is size of "wndw" array, it is ignored now.
 545
 546         Window just defines scrolling size for subsequent
 547         line-oriented i/o. Anything drawn across it will
 548         simply scroll. If you want to have overlapping
 549         windows, all you need to implement that is here.
 550
 551
 552 ---------------------------------------------->>  BURY
 553
 554 call bury(iwndw) | bury(iwndw);
 555                  | int  iwndw[];
 556
 557         makes the window disappear from the screen;
 558         the contents is saved away, so it may be "exposed" later;
 559         "iwndw" should have appeared before in call to "mkwndw".
 560         "bury" may be called only if the array supplied to "mkwndw"
 561         is large enough.
 562
 563
 564 ---------------------------------------------->>  EXPOSE
 565
 566 call expose(iwndw,ix,iy) | expose(iwndw,ix,iy);
 567                          | int  iwndw[];
 568
 569         makes the window reappear at (ix,iy) as its new top
 570         left corner;
 571         the window should have been "buried" before.
 572
 573
 574 ---------------------------------------------->>  OUTWLINE
 575
 576 call outwline(iwndw,n,l) | outwline(iwndw,n,l);
 577                          | int  iwndw[];
 578                          | char *l;
 579
 580         outputs "n" characters from "l" array at bottom line
 581         in window "iwndw", scrolling it appropriately;
 582         "n" may be larger than window line length - output
 583         will take as many window lines as needed;
 584
 585
 586 ---------------------------------------------->>  INWLINE
 587
 588 call inwline(iwndw,n,l) | inwline(iwndw,n,l);
 589                         | int  iwndw[];
 590                         | int  *n;
 591                         | char *l;
 592
 593         reads in a line of at most "n" characters from
 594         window "iwndw", putting them into "l" array;
 595         prompts at bottom of the window with ":";
 596         "n" may be larger than window size - it will be done
 597         in as many window lines as needed;
 598         BACKSPACE can be used to erase characters on bottom
 599         window line only;
 600         when specifying length, one should remember that the first
 601         column is used by the prompt;
 602         on return "n" is the total number of read characters.
 603
 604
 605 secret operations
 606 -----------------
 607
 608 ---------------------------------------------->>  HFILL
 609
 610 call hfill(ix) | hfill(ix);
 611
 612         fills current row (horizontally) from current position
 613         (ix0,iy0) up to (ix,iy0) with bit pattern depending
 614         on current color, style and/or pattern and position on
 615         the screen in such a way that adjacent "hfill"ed" rows
 616         will produce a shade simulating color;
 617         does not change current position;
 618
 619
 620 ---------------------------------------------->>  VFILL
 621
 622 call vfill(iy) | vfill(iy);
 623
 624         fills current column ( vertically ) from current
 625         position (ix0,iy0) up to (ix0,iy) in a similiar way
 626         that "hfill" does;
 627         rectangular area "vfill'ed" is not distinguishable
 628         on the screen from same shape "hfill'ed", except that
 629         it will take much longer to fill.
 630
 631
 632
 633
 634 LEVEL 2 ROUTINES
 635 _________________
 636
 637
 638         These accept coordinates a real numbers and translate
 639         them to actual pixel positions according to a previously
 640         specified "window" definition;
 641
 642
 643 abstract world window definition
 644 ________________________________
 645
 646
 647 ---------------------------------------------->>  SWINDOW
 648
 649 call swindow(r,i,scale)  | swindow(r,i,scale);
 650 real r(4)                | float  r[4];
 651 integer*2 i(4),scale     | int  i[4],scale;
 652
 653         enables positioning & drawing in abstract world
 654         coordinates ( cf. "rmove", "rdraw")
 655
 656         defines rectangular window
 657
 658                         r(1) <= x <= r(2),
 659                         r(3) <= y <= r(4)
 660
 661         in center of the rectangular area of the screen
 662         with top left corner in position (i(1),i(3))
 663         and right bottom corner in position (i(2),i(4));
 664         if "scale" equals 0, the real proportions are not
 665         preserved: the abstract window is simply mapped to fit
 666         the entire area of the screen, otherwise the window
 667         is adjusted to reflect the aspect ratio of the screen;
 668         abstract coordinates are mapped to the screen in the
 669         follwing way:
 670
 671         (r(1),r(4))
 672              ^
 673              |
 674              |
 675              |
 676         (r(1),r(3))--------------------->(r(2),r(3))
 677
 678
 679 ---------------------------------------------->>  RWINDOW
 680
 681 call rwindow(r,scale)  | rwindow(r,scale);
 682 real r(4)              | float  r[4];
 683 integer*2 scale        | integer scale;
 684
 685         equivalent to "swindow", using the entire screen;
 686         a margin of 1 pixel, however, is left on all sides
 687         to circumvent rounding problems
 688
 689
 690 positioning
 691 ___________
 692
 693
 694 ---------------------------------------------->>  RMOVE
 695
 696 call rmove(rx,ry) | rmove(rx,ry);
 697 real rx,ry        | float  rx,ry;
 698
 699         sets current abstract world position to (rx,ry)
 700         (rounded to nearest pixel) within a window
 701         that should have been defined in a previous call
 702         to "rwindow" or "swindow";
 703         picture remains unchanged
 704
 705
 706 ---------------------------------------------->>  RINXPOS
 707
 708 x=rinxpos(dummy)
 709 real dummy
 710
 711         returns abstract "x" coordinate in latest window of the
 712         current pixel position;
 713         will bomb out if there was no previous call to "rwindow"
 714         or "swindow";
 715         in case of "swindow" returned value may be negative;
 716
 717 ---------------------------------------------->>  RINYPOS
 718
 719 y=rinypos(dummy)
 720 real dummy
 721
 722         returns abstract "y" coordinate in latest window of the
 723         current pixel position;
 724         will bomb out if there was no previous call to "rwindow"
 725         or "swindow";
 726         in case of "swindow" returned value may be negative;
 727
 728
 729 drawing
 730 _______
 731
 732
 733 ---------------------------------------------->>  RDRAW
 734
 735 call rdraw(rx,ry) | rdraw(rx,ry);
 736 real rx,ry        | float  rx,ry;
 737
 738         draws a line in current color from current screen
 739         position to position (rx,ry) in abstract world
 740         coordinates ( using LEVEL 1 "draw" internally );
 741         sets current position to (rx,ry) (rounded);
 742         the window should have been defined before as for "rdraw".
 743
 744 ---------------------------------------------->>  RCIRB
 745
 746 call rcirb(xr,yr,rr,alfa,beta,cbord,bcint,p,q)
 747 real alfa,beta
 748
 749 [not available in Lattice C]
 750
 751         draws a circle (or ellipse), accepting center coordinates
 752         and radius value in abstract coordinates,
 753         optionally filling its interior; does not preserve position;
 754         (xr,yr) - center coordinates
 755         rr - radius (scaled horizontally)
 756         alfa, beta - starting & ending angles; if alfa=beta a full
 757         circle is drawn; values should be given in radians;
 758         cbord - border color
 759         bcint - if .ne.0 , interior is filled in current style&color
 760         p,q - aspect ratio; if p/q=1, a perfect circle is drawn,
 761         if p/q<1, the horizontal axis is longer, if p/q>1 - the vertical
 762         axis is longer;
 763
 764
 765
 766 OTHER USEFUL THINGS
 767 ___________________
 768
 769         Program "hgcprint.com", when called, sets up the system to
 770         make hardcopy of HERCULES graphics image on a GEMINI STAR 10
 771         dot matrix printer in the same way as MS-DOS GRAPHICS command
 772         does for the color/graphics card.
 773         To make the hardcopy, press SHIFT-PrtSc.
 774         This will work only in graphics mode.
 775
 776         Note
 777         Actually one cannot make hardcopy of IBM color graphics.
 778
 779
 780 A NOTE ON LINKING PASCAL PROGRAMS
 781 ---------------------------------
 782
 783         When linking Pascal programs which call one of the following:
 784
 785                 mkwndw  inhlin  outhlin bury    window  cirb    rcirb
 786                 track   inwlin  outwlin expose  rmove   rdraw
 787
 788         linker will complain about the missing library FORTRAN.LIB.
 789         Just ignore this complaint (simply type CR).
 790
 791
 792 A NOTE ON LINKING C PROGRAMS
 793 ----------------------------
 794
 795         When linking C programs using one of the following:
 796
 797                 rwindow swindow rmove   rdraw   rcirb   cirb
 798
 799         keep in mind that the following global names
 800         are used internally:
 801
 802                 wir*    (e.g. wirmix, wirmiy, etc.)
 803                 pqasp*  (e.g. pqaspp, pqaspq, etc.)
 804