fgkslib.old

开放源码的编译器open watcom 1.6.0版的源代码

you to specify the "colour" in which an object is to be drawn.
The colours are actually just numbers or indices ranging from 0 and
upwards.
For example, a line can be drawn using colour "1" and a circle using
colour "2".
However, what colour is colour 1 or colour 2?
Some devices, like the EGA, actually permit you to define what they
are.
For example, you might decide that colour 1 should be RED and then any
time an object is drawn in colour 1, it will appear RED.
Later on, you can change your mind and decide that all objects that
were drawn in colour 1 should appear BLUE.
.np
Unfortunately some devices, such as the CGA, do not permit you to
define this "mapping" between colour indices and actual colours.
With the exception of colour index 0 (the background colour), CGA
colour 1 is CYAN, colour 2 is MAGENTA, and colour 3 is WHITE and
you cannot alter this selection.
When using the IBM Graphics Printer, the choices are limited to two -
the colour of the ink in the ribbon and the colour of the paper itself
(the "background" colour).
.np
The following figures list the default mapping between colour
indices and actual colours.
The numbers in parentheses are the colour numbers shown in the colour
table
(:FIGREF refid='gref5' page=yes.).
If your machine is an IBM PCjr or is equipped with an EGA, VGA,
or MCGA each of the available colour indices can be redefined to
any one of the 16 colours shown in :FIGREF refid='gref5'. using the
COLOURMAP routine described below.
:mbox ref='gref2'.
colour
index
  0 definable
  1 CYAN(7)
  2 MAGENTA(6)
  3 WHITE(8)
:embox text='CGA Colour Indices'.
:mbox ref='gref3'.
colour
index
  0 background
  1 WHITE(8)
:embox text='Hercules Colour Indices'.
:mbox ref='gref4'.
colour             colour
index              index
  0   BLACK (1)      8    GRAY (9)
  1   BLUE (5)       9    Light BLUE (13)
  2   GREEN (3)     10    Light GREEN (11)
  3   CYAN (7)      11    Light CYAN (15)
  4   RED (2)       12    Light RED (10)
  5   MAGENTA (6)   13    Light MAGENTA (14)
  6   YELLOW (4)    14    Light YELLOW (12)
  7   WHITE (8)     15    Light WHITE (16)
:embox text='PCjr / EGA / VGA / MCGA Default Colour Mapping'.
.np
The following is a selection of colours defined by the cover
subprograms.
The numbers are not colour indices; they represent actual colours.
For example, colour number 5 is always blue and can be mapped to any
colour index provided that
.autopoint
.apoint
the hardware supports this particular colour, and
.apoint
the hardware supports colour mapping.
.eautopoint
:mbox ref='gref5'.
1 - black       9 - gray
2 - red         10 - light red
3 - green       11 - light green
4 - yellow      12 - light yellow
5 - blue        13 - light blue
6 - magenta     14 - light magenta
7 - cyan        15 - light cyan
8 - white       16 - bright white
:embox text='Colour Table'.
.np
Each of these 16 colours is defined in terms of a red, green, and blue
colour component.
In GKS, the amount or lightness of a particular colour component is
specified in terms of a value between 0.0 (none) to 1.0 (maximum
brightness).
For example, we have defined colour number 6 or magenta to be composed
of 0.667 red, 0.0 green, and 0.667 blue.
Not surprisingly, equal amounts of red and blue should give us a
somewhat purplish hue.
.np
Many of the graphics devices available for the PC have predefined the
colour compositions of the various colours available and they cannot
be changed.
However, the IBM Video Graphics Array permits the specification of the
colour compositions of each of the 256 colour registers.
At the hardware level, each of the red, green and blue components or
primaries is specified by one of 64 discrete values (in GKS, this
means that values between 0.0 and 1.0 are mapped uniformly to integer
values in the range 0 to 63).
Since any colour has 3 components, there are 64 x 64 x 64 or 262,144
colours that can be selected.
In GKS, the VGA colour registers are modified using the
.us Set Colour Representation
subroutine.
.code
GSCR( WK_ID, COLOUR_INDEX, RED_AMOUNT, GREEN_AMOUNT, BLUE_AMOUNT )
.ecode
.pc
Although you can only display a maximum of 256 different colours
at any one time, you can vary the selection from one scene to the
next.
.np
In mode 19, the colour registers happen to correspond one to
one with GKS colour indices.
In other modes, this does not necessarily always happen to be the case.
For example, in mode 18 the mapping of colour indices to
colour registers is as follows:
:mbox ref='gref6'.
Index       Register        Index   Register
  0        0          8       56
  1        1          9       57
  2        2         10       58
  3        3         11       59
  4        4         12       60
  5        5         13       61
  6       20         14       62
  7        7         15       63
:embox text='Mode 18 Colour Register Map'.
.pc
Fortunately, GKS hides these hardware anomalies from us.
We deal only in terms of colour indices.
.np
Any time a particular graphics mode is selected, the VGA colour
registers are initialized to some default set of values.
For mode 19, IBM has initialized the 256 colour registers to 16
default colours, 16 gray levels and 216 colours selected from a
Hue-Lightness-Saturation (HLS) model.
The remaining 8 registers are zero and hence black.
The 216 colours cover 24 hues in 3 lightness values (bright, medium
and dark), and 3 saturation values (pure, impure and gray).
.np
In the IBM HLS model, hues are evenly spaced around a colour wheel at
15 degree intervals with Blue at 0.
These hues are assigned numeric values from 0 to 23.
:mbox ref='gref7'.
      8 RED     .   MAGENTA 4
           \     /
        \   /
       .     \     /     .
          \   /
           \ /
12 YELLOW - - - - - - - - - - - BLUE 0
           / \
          /   \
       .     /     \     .
        /   \
           /     \
    16 GREEN    .   CYAN 20
:embox text='HLS Colour Wheel'.
.pc
A colour made up of only 1 or 2 primaries (red, green or blue) is a
pure colour and a colour made up of 3 primaries is an impure colour.
As more of the third colour is introduced, the colour purity decreases
becoming more and more gray.
When all three primary components are equal, the colour is an
achromatic gray level.
Bright white, for example, is composed of an equal and maximum amount
of red, green and blue.
.np
We can map lightness (LGT) and saturation (SAT) onto numeric values as
follows:
:mbox ref='gref8'.
Lightness   Saturation
Bright  0   Pure    0
Medium  1   Impure  1
Dark    2   Gray    2
:embox text='Lightness and Saturation Values'.
.pc
A colour in this HLS colour space can be converted into a colour index
for use in mode 19.
The index is calculated from the HUE, LGT, and SAT numerical values
using the following equation:
.millust
Index = (LGT * 72) + (SAT * 24) + HUE + 32
.emillust
.np
.keep
.us Examples:
.code
medium, gray yellow = (1 * 72) + (2 * 24) + 12 + 32 = 164
dark, pure green    = (2 * 72) + (0 * 24) + 16 + 32 = 192
bright, impure blue = (0 * 72) + (1 * 24) +  0 + 32 =  56
.ecode
.np
For mode 19, all 256 colour registers are initialized according to the
following table.
:mbox ref='gref9'.
  0 - 15       16 default colours
 16 - 31       16 gray levels
 32 - 55       24 bright, pure hues
 56 - 79       24 bright, impure hues
 80 - 103      24 bright, grayish hues
104 - 127      24 medium, pure hues
128 - 151      24 medium, impure hues
152 - 175      24 medium, grayish hues
176 - 199      24 dark, pure hues
200 - 223      24 dark, impure hues
224 - 247      24 dark, grayish hues
248 - 255   8 uninitialized
:embox text='Mode 19 Colour Register Initialization'.
.*
:H2.Screen Coordinate System in Cover Library
.*
:I1.coordinates screen
:I1.screen coordinates
Any position on the screen can be referenced by two coordinates.
The first coordinate is called the x-coordinate, while the second is
called the y-coordinate.
Although WATCOM GKS supports any number of user-defined coordinate
systems, the cover library has chosen the following coordinare system
for simplicity.
The left side of the screen has an x-coordinate of 0, and the right
side has an x-coordinate of 1.
Similarly, the bottom of the screen has a y-coordinate of 0 and the
top has a y-coordinate of 1.
Thus any point on the screen can be referenced as (x,y) where each of
the x and y values are between 0 and 1.
The point (0,0) is the bottom left corner of the screen, and the point
(1,1) is the top right corner.
:mbox ref='gref10'.
    (0,1)               (1,1)
    +---------------------------+
    |               |
    |               |
    |      Screen       |
y-axis  |               |
    |     (0.5,0.5)     |
    |               |
    |               |
    |               |
    |               |
    +---------------------------+
    (0,0)       x-axis      (1,0)
:embox text='Screen Coordinate System'.
.np
In this coordinate system, the centre of the screen is the real number
pair (0.5,0.5).
.*
:H2.Graphics Routines
.*
:I1.GKS cover subprograms
The cover graphics library consists of routines for generating colour
graphics including lines, boxes, circles and text.
Source code for the cover routines can be found in the
"&pathnamup\SRC\FORTRAN\GKSCOVER" directory.
The file "GKSDEFN.FOR" which may be required by your application
and is required by some of the demonstration programs is found in
this directory.
The following sections describe the available routines.
.np
Many of the routines require an INTEGER argument called
.id COLOUR_INDEX.
If the graphics adapter being used can display 4 colours, then the
values for
.id COLOUR_INDEX
will be 0, 1, 2 and 3.
If only 2 colours can be displayed, the valid choices are 0 and 1.
If 16 colours can be displayed, the valid colours are any number from
0 to 15.
If 256 colours can be displayed, the valid colours are any number from
0 to 255.
.np
The routines
.id GETPIC,
.id PUTPIC
and
.id PUTPIC_ACTION
require a CHARACTER argument.
This must be a CHARACTER*80 array with
.id PIC_SIZE
elements.
.id PIC_SIZE
is defined in "GKSDEFN.FOR".
The following program fragment illustrates how to call the
subroutine
.id GETPIC.
.exam
CHARACTER*80 PIC( PIC_SIZE )
CALL GETPIC( 0.5, 0.5, 0.6, 0.4, PIC )
.eexam
.*
:H2.GKS Cover Subroutines
.*
:I1.GKS cover subroutines
.*
:H3.BLOCK Subroutine
.*
:I1.BLOCK subroutine
.cbox
    SUBROUTINE BLOCK( X1, Y1, X2, Y2, COLOUR_INDEX )
    REAL X1, Y1, X2, Y2
    INTEGER COLOUR_INDEX
.ecbox
.np
This subroutine draws a rectangular box with coordinates of opposite
corners specified by the first two pairs of arguments.
The box and area inside it are painted solid using the specified
colour index.
.*
:H3.BOX Subroutine
.*
:I1.BOX subroutine
.cbox
    SUBROUTINE BOX( X1, Y1, X2, Y2, COLOUR_INDEX )
    REAL X1, Y1, X2, Y2
    INTEGER COLOUR_INDEX
.ecbox
.np
This subroutine draws a rectangular box with coordinates of opposite
corners specified by the first two pairs of arguments.
The box is drawn using the specified colour index.
.*
:H3.CIRCLE Subroutine
.*
:I1.CIRCLE subroutine
.cbox
    SUBROUTINE CIRCLE( X, Y, RADIUS, COLOUR_INDEX )
    REAL X, Y, RADIUS
    INTEGER COLOUR_INDEX
.ecbox
.np
This subroutine draws a circle with centre at coordinates (X,Y)
using the specified colour index.
The radius specifies the distance from the edge of the circle to the
centre along the horizontal axis.
.*
:H3.CIRC_ARC Subroutine
.*
:I1.CIRC_ARC subroutine
.cbox
    SUBROUTINE CIRC_ARC( X, Y, RADIUS, COLOUR_INDEX, START, FINISH )
    REAL X, Y, RADIUS
    INTEGER COLOUR_INDEX, START, FINISH
.ecbox
.np
This subroutine draws a circular arc with centre at coordinates
(X,Y) using the specified colour index.
The radius specifies the distance from the edge of the circle to the
centre along the horizontal axis.
The start and finish angles of the arc are expressed in degrees
between 0 and 360.
A start angle of 0 represents the point (X+RADIUS,Y).
The arc is drawn in the counter-clockwise direction.
.*
:H3.CLEARSCREEN Subroutine
.*
:I1.CLEARSCREEN subroutine
.cbox
    SUBROUTINE CLEARSCREEN
.ecbox
.np
This subroutine clears the screen.
.*
:H3.COLOURMAP Subroutine
.*
:I1.COLOURMAP subroutine
.cbox
    SUBROUTINE COLOURMAP( COLOUR_INDEX, COLOUR )
    INTEGER COLOUR_INDEX, COLOUR
.ecbox
.np
This subroutine associates one of the sixteen available colours to
COLOUR_INDEX.
COLOUR_INDEX can be one of the 2, 4, 16 or 256 colour indices
supported by the graphics adapter being used.
COLOUR is one of the sixteen colours described in "Colour Table"
above.
This subroutine only works on adapters that support colour mapping
such as the IBM PCjr, the EGA, the VGA and the MCGA.
.np
Devices such as the VGA and MCGA support more colours than the 16
provided by the COLOURMAP routine.
You may wish to use the GKS