GKS Update

The OzAPI software is being developed to support the porting of the OzGIS mapping system from the WINDOWS 3.1 (using MS FORTRAN 5.1, MS ‘C’ and the WIN3.1 SDK). The decision was made to spend more time to see if the software could be made of general use.

OzAPI is developed using Visual C++ V4.0 and MS Fortran Powerstation V4.0 under MS NT workstation 4.0

OzAPI can hence be used to develop or port FORTRAN code for 32bit WINDOWS applications using MS Fortran Powerstation a nd presumeably DEC Visual Fortran. It should be able to be used with any FORTRAN that can call and be called by MS ‘C’ functions e.g. MS FORTRAN 5.1) with some hacking, but you will probably need Visual C++ so you have the resource compiler, a current linker and some include files.

The major component is a demonstration program that shows all the facilities.This is also the development environment.

OzAPI allows the latest software development techniques to be applied (i.e. you get the demo program running and hack it around to get what you want).

You are free to use OzAPI to develop programs. If there is sufficient interest the source code will be made available for purchase at a nominal (I.e. exorbitant) price. There is nothing fancy about the software, but it takes a lot of time to find relevant documentation.

OzAPI comes with an industry standard guarantee i.e. there isnt one! You use the software at your own risk!

OzAPI will be enhanced to provide more facilities for OzGIS and other features may be added upon request or if anyone donates source code.

OzAPI and OzGIS are available on the Net and are developed by:

Lloyd Simons,

The Clever Company P/L

Box 6108 East Queanbeyan

Australia 2620.

FAX +61 2 6299 3211

lse.simons@bigpond.com

Execute OzAPI.exe and work through the menu options to see what you can do.To develop an application you will first build this demonstartion program from the supplied files and then modify it (and incorporate your own code) to generate your WINDOWS application.

OzAPI.obj The WINDOWS main program

*.for FORTRAN files that you modify

OzAPI.lib Library of functions

OzAPI.rc Resource file. Some modifications may be made.

Res subdirectory of icons, bitmaps etc. Some modifications may be made.

OzAPI.hlp The help file. Optional. You may find it useful to initially incorporate this for quick reference to the API functions.

Integers: Are all INTEGER*4

Logical: Are all LOGICAL*4

Reals: Are all REAL*4

Text: Input parameters are ‘C’ strings, which differ from Fortran character values in that they are terminated by a NULL byte i.e. CHAR(0) in FORTRAN-speak.

Examples are: 1. ‘Hello’C in MS Powerstation

2. ‘Hello’ // char(0)

3. character*40 string

character*1 null

null = char(0)

write (string, 100) num, null

100 format (‘Number is’,i4, a1)

etc

Be carefull of the blank filling of character types

Be especially careful to remember the null terminator

Character*n: These are used for input arrays, although the members are still C strings.

Where they are output arrays too the lengths must be specified and the values will return as ordinary blank filled Fortran types.

If you are using MS Development Studio with Fortran Powerstation, DEC visual Fortran or any other Fortran the procedure to set up a new application is as follows:

File->New and select project Workspace

Select Application

Give the program a name and a directory

From the command line copy the above API files into the directory (including res\*.*)

Insert->Files into project and give ozapi.obj, *.for and ozapi.rc

Build->Settings and select Link, Input. Put OzAPI.lib at front of library list. You will also need msvcrtd.lib in the ignore libraries list.

Then build, and if you are lucky you should have a program that will run.

An example set of files APIdemo.* are provided. You can set up a directory called APIdemo and copy the files, and those above, to it.

You will probably need Visual C++ for the resource compiler and header files. This does give you a WINDOWS debugger.

Set up a directory.

From the command line copy the above API files into the directory (including res\*.*)

You will need to compile the *.FOR files and the resource file ozapi.rc

Link OzAPI.obj as the main program and reference the OzAPI.lib library.

Look at the APIdemo.mak file (if you can see past the garbage). If you use NMAKE you can probably use it.

The OzAPI.inc file defines the ‘C’ function calls to Fortran Powerstation, and will need to be modified for other compilers. For example the format is different for MS Fortran 5.1

The file OzFTN.h defines the Fortran subroutines to Visual C++.

There has been a quick attempt to use OzAPI on a WIN95 system, and some *51* files are included.

You have to put ftn51.inc at the front of each fortran source file and include ftn51def.inc in reach routine.

See menu51.for which is a replacement for ozmenu.for (as the compiler kept running out of memory).

Problems came when trying to run the resource co0mpiler. A compiler from Visual C++ was used. Some *.rc and *.h files from visual C++ were required. Some DLLs were also required, so at this stage it was decided that you probably need a new version of Visual C++.

Linking was tested, but a new linker was also required.

You will need to modify all the *.FOR files for your application. They are fairly well documented.

OZCURSOR.FOR - This is the call-back function when a cursor mode has been set. Either add your code to handle the user’s selections or make it a dummy routine if cursors are not used.

OZINISTP.FOR - Contains routines that are called at the start of the program (on the first paint message) and at the end after the window has been destroyed. You will normally generate your menus and carry out any one-time initialisation in the start routine, and any termination code in the end routine (but nothing that needs the window).

OZMENU.FOR - This is the call-back function that is activated whenever the user chooses a menu item. In particular the handle given to identify the menu item when it was created is passed so you know what was selected.

OZNEWDOC.FOR - This is a call-back function that is called at the start of the program and whenever File->New is chosen.

OZSERIAL.FOR - Call-back fuction that is activated when data are stored or retrieved into the program by File->Save or File->Open. Most of the processing is handled by the application framework,. Basically it is just a matter of providing the addresses of data that are to be serialised (in Windoze-speak) and the framework will either read or write it. You simply place your global data in common blocks and reference the start of each block and give its length (from a linker map file).

You will make most modifications within MS Development Studio. If you are not using it you can edit OzAPI.rc with a bit of care.

Edit OzAPI.rc to change the saved file definition used in the File->Save etc menu items:

IDR_MAINFRAME "OzAPI\n\nOzAPI\nOzAPI Files (*.oza)\n.OZA\nOzAPI.Document\nOzAPI Document"

Modify the About dialog for your application.

Modify the program icon.

The Files menu is usually present to provide file saving, printing and program exit. If you dont want any of these the resource has to be modified.

Note that plotting is handled by the print mechanism via an appropriate driver.

Description: Sequentially add pulldown menus to the menu bar.

Definition: INTEGER FUNCTION OZADDPULLDOWN (STRING)

Parameters: Name In/Out Type Description

Returns: The handle of the pulldown (1,2,3).

C++: extern "C" long ozaddpulldown (char* string);

Notes: It is usual to add menu items immediately after defining the pulldown, which saves storing the handle.

Menus are usually defined in the OZINIT subroutine.

Description: Sequentially adds items to a pulldown menu.

Definition: INTEGER FUNCTION OZADDMENUITEM (PULLDOWN, STRING, IDENT)

Parameters: Name In/Out Type Description

PULLDOWN I Int The handle of the pulldown menu

STRING I Cstring The item text

IDENT I Int A unique identifier for the menu item.

Returns: Handle of the menu item within the pulldown (1,2,3…)

C++: extern "C" long ozaddmenuitem (long* pullDown, char* string, long* Id);

Notes: When a user selects the menu item the call-back subroutine is called. You place your code to handle the selection there. See the file OZMENU.FOR

Description: Removes all items from a pulldown menu.

Definition: SUBROUTINE OZCLEARPULLDOWN (PULLDOWN)

Parameters: Name In/Out Type Description

PULLDOWN int The pulldown menu’s handle.

C++: extern "C" void ozclearpulldown (long* pullDown);

Notes: The entry is still there in the menu bar.

Description: Remove all menus and clear the menu bar.

Definition: SUBROUTINE OZCLEARALLMENUS

C++: extern "C" void ozclearallmenus ();

Notes: initialises ready for a different set of menus.

Description: Sequentially adds items to a popup menu.

Definition: INTEGER FUNCTION OZADDPOPUPITEM (STRING, IDENT)

Parameters: Name In/Out Type Description

STRING I Cstring The text that appears in the menu

IDENT I integer The identifier psassed to the menu callback routine

Returns: The item handle (1,2,3….)

C++: extern "C" long ozaddpopupitem (char* string, long* Id);

Notes: See OZADDMENUITEM.

Description: Initialises for a new popup menu by removing all items.

Definition: SUBROUTINE OZCLEARPOPUPMENU

C++: extern "C" void ozclearpopupmenu ();

Notes: saffdgfdsgfdsgsfgf

Description: Displays the current popup menu.

Definition: SUBROUTINE OZDISPLAYPOPUP

C++: extern "C" void ozdisplaypopup ();

Notes: The menu only allows one selection.

Description: Display of standard Windows message boxes.

Definition: INTEGER FUNCTION OZMESSAGEBOX (STRING, ITYPE, ICON, IDEFAULT)

Parameters: Name In/Out Type Description

1 = The message box has abort, retry, ignore buttons

2 = The message box has just the OK button.

3 = The message box has OK and Cancel

4 = The message box has Retry and cancel

5 = The message box has Yes and No

6 = The message box has Yes, No and Cancel

1 = Exclamation point

2 = Information

3 = Question mark

4 = Stop sign

5 = xxx

6 = xxx

Returns: The selected button:

0 = ran out of memory

1 = Abort

2 = Cancel

3 = Ignore

4 = No

5 = OK

6 = Retry

7 = Yes

C++: extern "C" long ozmessagebox (char* text, long* type, long* icon, long* button);

Notes: The user can disable the warning beep by using the Control Panel Sound application.

Description: Asks for an integer value.

Definition: INTEGER FUNCTION OZINTDLG (PROMPT, MIN, MAX, DEFAULT)

Parameters: Name In/Out Type Description

Returns: The entered integer

C++: extern "C" long ozintdlg (char* prompt, long* min, long* max, long* default)

Description: Asks for a real value.

Definition: REAL FUNCTION OZREALDLG (PROMPT, MIN, MAX, DEFAULT)

Parameters: Name In/Out Type Description

Returns: The entered real

C++: extern "C" float ozrealdlg (char* prompt, float* min, float* max, float* default)

Description: Accepts a string from the user.

Definition: SUBROUTINE OZSTRINGDLG (PROMPT, STRING, LENGTH)

Parameters: Name In/Out Type Description

C++: extern "C" void ozstringdlg (char* prompt, char* text, long* length)

Notes: Make sure you get the length right as it is blank filled e.g.

CHARACTER*40 TEXT needs a value of 40

Description: Displays a list from which a selection can be made..

Definition: INTEGER FUNCTION OZLISTBOXDLG (PROMPT, ITEMS,

Parameters: Name In/Out Type Description

Returns: Index of selected item

C++: extern "C" long ozlistboxdlg (char* prompt, char* items, long* itemSize, long* numItems);

Notes: You will often sort the array first.

Description: Displays a listbox populated from a file.

Definition: SUBROUTINE OZFILELISTBOXDLG (PROMPT, FILENAME, ITEM,

- ITEMTEXT, LENTEXT)

Parameters: Name In/Out Type Description

C++: extern "C" void ozfilelistboxdlg (char* prompt, char* fileName, long* item,

char* text, long* lenStr)

Notes: Keep the file records to < 100 chars.

Description: Display the contents of an ascii file in a dialog.

Definition: SUBROUTINE OZTEXTDLG (FILENAME)

Parameters: Name In/Out Type Description

C++: extern "C" void oztextdlg (char* fileName)

Notes: Keep the file records to < 100 chars.

Description: SUBROUTINE OZHELPCONTENTS (FNAME).

Definition: Display contents from windows help file.

Parameters: Name In/Out Type

C++: extern "C" void ozhelpcontents (char* fileName);

Notes: Try one of the shareware Help File systems off the Net to prepare your help.

Description: SUBROUTINE OZHELPINDEX (FNAME).

Definition: Display index from windows help file.

Parameters: Name In/Out Type Description

C++: extern "C" void ozhelpindex (char* fileName);

Description: Displays the help dialog.

Definition: SUBROUTINE OZABOUT ()

C++: extern "C" void ozabout ();

Notes: Edit the About dialog that comes with OzAPI.

Description: Standard dialog to allow a colour to be chosen & a standard set of 16 colours

Definition: LOGICAL FUNCTION OZCOLOURDLG (RED, GREEN, BLUE, ICUST)

Parameters: Name In/Out Type Description

Returns: TRUE if a colour was chosen

C++: extern "C" BOOL ozcolourdlg (float* red, float* green, float* blue,

Notes: There are 16 custom colours in the dialog, which are stored in the array on exit from the dialog. I.e. 16 X double words. Each pair of integers is 4 bytes, with the colours stored XBGR. You would normally make the array global (in common) and initialise it to zero. If you want to keep the custom colours you’ll have to store them in a file.

Description: Displays the standard File Open / Save dialogs.

Definition: LOGICAL FUNCTION OZFILENAME (SAVEFILE, FNAME,

Parameters: Name In/Out Type Description

Returns: TRUE if a filename was chosen / specified.

C++: extern "C" BOOL ozfilename (BOOL* save, char* fileName,

char* filterPattern, long* patternSize )

Notes: You must get all the parameters right. If the dialog displays but theres something wrong ITS YOUR FAULT!. (and its not obvious what the parameters are!)

Serialization is the term for saving and restoring the programs environment to files. E.g. a wordprocessor saves documents.

The process is handled by the application framework and initiated by the File->Save and File->Open menu items. When the user selects the menu item the OZSERIAL.FOR module is called. All you have to do is reference all the data that you need to save and restore. Usually you just reference the first variable in each common block and give the length of that block.

Description: Serialise a character variable.

Definition: CHARACTER*?? STRING

SUBROUTINE OZSERIALSTRING(STRING, LENGTH)

Parameters: Name In/Out Type Description

C++: extern "C" void ozserialstring (char* string, long* numByte);

Notes: Can be start of common block.

Description: Serialise a real variable.

Definition: SUBROUTINE OZSERIALREAL(VAR)

Parameters: Name In/Out Type Description

C++: extern "C" void ozserialreal (float* real);

Description: Serialise a real variable.

Definition: SUBROUTINE OZSERIALINT(VAR)

Parameters: Name In/Out Type Description

C++: extern "C" void ozserialint (long* integer);

Description: Serialise a real array.

Definition: REAL VAR(??)

SUBROUTINE OZSERIALREALARRAY(VAR, LENGTH)

Parameters: Name In/Out Type Description

C++: extern "C" void ozserialrealarray (float* realArray, long* numReal);

Notes: Can be start of common block.

Description: Serialise a real array.

Definition: REAL VAR(??)

SUBROUTINE OZSERIALINTARRAY(VAR, LENGTH)

Parameters: Name In/Out Type Description

C++: extern "C" void ozserialintarray (long* intArray, long* numInt);

Notes: Can be start of common block.

Description: Displays text in the main window title bar..

Definition: SUBROUTINE OZTITLE (STRING)

Parameters: Name In/Out Type Description

C++: extern "C" void oztitle (char* text);

Notes: Usually called from the OZINIT subroutine to set the program title. Can also be used for trace messages.

Description: These functions turn the cursor to the busy hourglass shape..

Definition: SUBROUTINE OZBUSY

SUBROUTINE OZNOTBUSY

C++: extern "C" void ozbusy ();

Notes: Usually turned on during long calculations etc.

A set of graphics functions are provided that were originally based on the FORTRAN bindings of the GKS standard. They have now been distorted to fit the WONDOZE environment, and enable traditional interactive graphics on a single window.

Segments are the core of the display mechanism.

Segments hold graphics data in memory:

Window definitions

Viewport definitions

Polygons

Lines

markers

Text

When windows needs to redraw the screen the contents of all the segments are displayed. This occurs

When the window is resized

Upon user request

When printing.

When the program outputs graphics they are actually stored in the current segment and displayed only when a request to update the screen or print is issued.

Segments are displayed in order (1,2,3….) and the data within each segment in the order that it was added. Care needs to be taken with segment order e.g. as solid polygons will overwrite anything on the screen they would normally be added to a segment with a lower number than that used to hold text.

Description: Inititialise GKS functions.

Definition: CALL GOPKS

C++: extern "C" void gopks ()

Notes: Must be called at start of program.

Description: Terminates use of GKS functions.

Definition: CALL GCLKS

C++: extern "C" void gclks ()

Notes: Should be called at end of program.

Description: Open a workstation.

Definition: SUBROUTINE GOPWK (IDWK, IDCON, ITYPE)

Parameters: Name In/Out Type Description

C++: extern "C" void gopwk (long* wkid, long* conid, long* wtype)

Notes: Called before any drawing takes place.

There is only one workstation in this implementation so the parameters are redundant. However you should probably have a variable for the workstation ID that you use in all calls - just in case multiple workkstations (windows) are implemented later.

Printing is done with the WINDOZE facilities, so there is no special workstation required.

Description: Close workstation.

Definition: CALL GCLWK (IDWK)

Parameters: Name In/Out Type Description

C++: extern "C" void gclwk (long* wkid)

Notes: Called when drawing is complete.

Description: SUBROUTINE GACWK (IDWK).

Definition: Activate workstation

Parameters: Name In/Out Type Description

C++: extern "C" void gacwk (long* wkid)

Notes: Called before drawing.

Description: SUBROUTINE GDAWK (IDWK).

Definition: Dectivate workstation

Parameters: Name In/Out Type Description

C++: extern "C" void gdawk (long* wkid)

Notes: Called after drawing.

Description: Clear workstation.

Definition: SUBROUTINE GCLRWK (IDWK, ICTRL).

Parameters: Name In/Out Type Description

C++: extern "C" void gclrwk (long* wkid, long* cofl)

Notes: Clears the screen i.e. clears all segments.

Description: Update workstation..

Definition: SUBROUTINE GUWK (IDWK, ICTRL)

Parameters: Name In/Out Type Description

C++: extern "C" void guwk (long* wkid,long* regfl)

Notes: Tells WINDOWS to repaint the screen. The contents of the segments are displayed.

Description: Draw polyline..

Definition: DIMENSION PX(), PY()

Parameters: Name In/Out Type Description

Returns: Integer handle (identifier)

C++: extern "C" long gpl (long* n, float* px, float* py)

Notes: Adds a line to the current segment i.e. vertices and current attributes.

Description: Draw polymarker ..

Definition: DIMENSION PX(), PY()

Parameters: Name In/Out Type Description

Returns: Integer handle (identifier)

C++: extern "C" long gpm (long* n, float* px, float* py)

Notes: Adds a set of markers to the current segment i.e. vertices and current attributes.

Description: Draw filled area.

Definition: DIMENSION PX(), PY()

LOGICAL BND

Parameters: Name In/Out Type Description

Returns: Integer handle (identifier)

C++: extern "C" long gfa (long* num, float* px, float* py, long* bnd)

Notes: Adds a polygon to the current segment i.e. vertices and current attributes.

The current line colour is used for the boundary.

Description: Draw text ..

Definition: SUBROUTINE GTX (PX, PY, STRING)

Parameters: Name In/Out Type Description

Returns: Integer handle (identifier)

C++: extern "C" long gtx (float* px, float* py, char* pString)

Notes: Adds a text string to the current segment i.e. point, string and current attributes.

Description: Draw a filled rectangle.

Definition: SUBROUTINE GFRECT (X1,X2,Y1,Y2)

Parameters: Name In/Out Type Description

Returns: Integer handle (identifier)

C++: extern "C" long gfrect (float* x1, float* x2, float* y1, float* y2)

Notes: Easy way of displaying a rectangle by giving the corners. Handled internally as a polygon.

Description: Update attributes of a polyline.

Definition: SUBROUTINE GUPDPL (IHAND, ITYPE, IWIDTH, ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gupdpl (long* handle, long* type, long* width, long* colIndex)

Notes: Changes the attributes of a polyline within the current segment. The handle is the identifier returned when created. Hence enables the appearance to be modified..

Description: Update attributes of a polymarker.

Definition: SUBROUTINE GUPDPM (IHAND, SIZE, ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gupdpm (long* handle, float* size, long* colIndex)

Notes: Changes the attributes of a polymarker within the current segment. The handle is the identifier returned when created. Hence enables the appearance to be modified..

Description: Update attributes of a filled area.

Definition: SUBROUTINE GUPDFA (IHAND, ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gupdfa (long* handle, long* colIndex)

Notes: Changes the attributes of a polygon within the current segment. The handle is the identifier returned when created. Hence enables the appearance to be modified..

Description: set current segment.

Definition: SUBROUTINE GSSEG (ISEG)

Parameters: Name In/Out Type Description

C++: extern "C" void gsseg (long* seg)

Notes: Defines the current segment i.e. where drawing primitives are to be stored..

Description: Sets the line type.

Definition: SUBROUTINE GSLN (ITYPE)

Parameters: Name In/Out Type Description

C++: extern "C" void gsln (long* ltype)

Notes: Line types are:

1 = solid

2 = dashed

3 = dotted

4 = dash dot

5 = dash dot dot

The line width must be 1 for patterns to be applied.

Description: Define polyline width.

Definition: SUBROUTINE GSLW (IWIDTH)

Parameters: Name In/Out Type Description

C++: extern "C" void gslw (long* width)

Notes: Defines the line width in pixels. Usually 1..

Description: Set polyline colour index.

Definition: SUBROUTINE GSPLCI (ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gsplci (long* coli)

Notes: The index is to the colour look-up table (or palette).

Description: Set the marker type.

Definition: SUBROUTINE (MTYPE)

Parameters: Name In/Out Type Description

C++: extern "C" void gsmk (long* mtype)

Notes: The type is the character number within the marker font.

Description: Set the marker size.

Definition: SUBROUTINE GSMKSIZE (SIZE)

Parameters: Name In/Out Type Description

C++: extern "C" void gsmksize (float* msize)

Notes: Sets character size. The size is given in normalised device coordinates i.e. range 0 to 1.0, being the proportion of the window.

Description: Set polymarker colour index.

Definition: SUBROUTINE GSPMCI (ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gspmci (long* coli)

Notes: The index is to the colour look-up table (or palette).

Description: Defines the fonts that can be used.

Definition: SUBROUTINE WINFNT (NAME, IDENT)

Parameters: Name In/Out Type Description

C++: extern "C" void winfnt (char* font_name, long* id)

Notes: Fonts can be chosen from those listed in the Fonts section of the control panel.

Description: Defines the font to be used for drawing markers.

Definition: SUBROUTINE MRKFNT (NAME,)

Parameters: Name In/Out Type Description

C++: extern "C" void mrkfnt (char* font_name)

Notes: The font can be chosen from those listed in the Fonts section of the control panel.

Description: Set font and precision.

Definition: SUBROUTINE GSTXFP (IFONT, IPREC)

Parameters: Name In/Out Type Description

C++: extern "C" void gstxfp (long* font, long* prec)

Notes: Default precision is currently used.

Description: Set text character height.

Definition: SUBROUTINE GSCHH (HT)

Parameters: Name In/Out Type Description

C++: extern "C" void gschh (float* chh)

Description: Set character expansion factor.

Definition: SUBROUTINE GSCHXP (RATIO)

Parameters: Name In/Out Type Description

C++: extern "C" void gschxp (float* chxp)

Notes: Default x/y ratio is 0.75.

Description: Set text colour index.

Definition: SUBROUTINE GSTXCI (ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gstxci (long* coli)

Notes: The index is to the colour look-up table (or palette).

Description: set text path.

Definition: SUBROUTINE GSTXP (IPATH)

Parameters: Name In/Out Type Description

C++: extern "C" void gstxp (long* txp)

Notes: Sets direction that text is to be drawn.

Description: set text alignment.

Definition: SUBROUTINE GSTXAL (IHORIZ, IVERT)

Parameters: Name In/Out Type Description

C++: extern "C" void gstxal (long* txalh, long* txalv)

Notes: Defines alignment of text relative to drawing point..

Description: set fill area interior style.

Definition: SUBROUTINE GSFAIS (ISTYLE)

Parameters: Name In/Out Type Description

C++: extern "C" void gsfais (long* ints)

Notes: Solid fill is most likely to be used. Style codes are:

7=vertical hatch

Description: Set polyline colour index.

Definition: SUBROUTINE GSFACI (ICOLOUR)

Parameters: Name In/Out Type Description

C++: extern "C" void gsfaci (long* coli)

Notes: The index is to the colour look-up table (or palette).

Description: set colour representation.

Definition: SUBROUTINE GSCR (IDWK, INDEX, RED, GREEN, BLUE)

Parameters: Name In/Out Type Description

C++: extern "C" void gscr (long* wkid, long* ci, float* cr, float* cg, float* cb)

Notes: Sets the colour look-up table. Basically defines the colour for each pixel value. E.g. the video memory is usually initialised to zero, so the background colour is index zero.

Colour palettes are complicated:

The designers of the WINDOZE API know that you are an idiot and cannot be trusted to directly handle colours.

Designers of display systems know that 256 simultaneous colours is already more than you deserve and are not going to give you any more..

Windows reserves 16 colours for a standard VGA and an extra 4 colours for super VGAs. This could be what they are:

1.0 1.0 1.0 WHITE (BACKGROUND)

0.0 0.0 1.0 RED

0.0 0.0 0.5 DARK RED

0.5 0.0 0.5 DARK MAGENTA

0.5 0.0 0.0 DARK BLUE

0.5 0.5 0.0 DARK CYAN

0.0 0.5 0.0 DARK GREEN

0.0 0.5 0.5 DARK YELLOW

1.0 0.0 1.0 MAGENTA

1.0 1.0 0.0 CYAN

0.0 1.0 0.0 GREEN

0.0 0.0 0.0 BLACK

0.0 1.0 1.0 YELLOW

0.753 0.753 0.753 DARK GREY

1.0 0.0 0.0 BLUE

0.5 0.5 0.5 GREY

Hence on the usual 256 colour system you can define an additional (256-20) colours.

The colours you load into the table are matched to those in the actual hardware lookup table. If you load too many colours (e.g. if are operating in 16 colour mode) the system will match colouirs the best it can.

So if you load any of the standard colours (red, green etc) they will always be matched exactly. Often this will be all you need. The order doesnt matter.

If you need many colours simply load up to 256 of them and you will get something that will look OK.

Complications are likely to arise when colours are allocated for other purposes such as displaying lots of bit maps that each have different colour paletrtes.

Description: set whole 256 value colour look-up table.

Definition: DIMENSION RED(256), GREEN(256),BLUE(256)

SUBROUTINE GSLUT(IDWK, RED, GREEN, BLUE)

Parameters: Name In/Out Type Description

C++: extern "C" void gslut (long* wkid, float* cr, float* cg, float* cb)

Notes: Convenient way of seeting all colours. See GSCR..

Description: Define window.

Definition: SUBROUTINE GSWN (ITRANS, XMIN, XMAX, YMIN, YMAX)

Parameters: Name In/Out Type Description

C++: extern "C" void gswn (long* tnr, float* xmin, float* xmax, float* ymin, float* ymax)

Notes: Defines world coordinate system (user coordinates, drawing coordinates).

Description: Set viewport.

Definition: SUBROUTINE GSVP (ITRANS, XMIN, XMAX, YMIN, YMAX)

Parameters: Name In/Out Type Description

C++: extern "C" void gsvp (long* tnr, float* xmin, float* xmax, float* ymin, float* ymax)

Notes: The viewport is the part of the screen that the current window is defined on. i.e. points are transformed from the world coordinates defined by the window onto the viewport.

The viewport is defined in normalised device coordinate (N.D.C.) i.e. range 0 - 1.

Hence a WINDOZE window is actually a viewport (but the designers of the WINDOZE API seem to have no knowledge of basic computer graphics).

The viewport and window are stored in the current segment. As segments may not be drawn in the order that graphics are defined in the program it is good practice to ensure that the window and viewport are defined at the start of each segment (they can be changed as required).

The window and viewport do not have to have the same aspect ratio, but they often will.

As the user can resize the wiindow (the WINDOZE window that is) the viewport will actually be transformed to the screen so that a viewport with aspect ratio 4:3 will always be visible). Hence use a maximum viewport (0, 1.0, 0, 0.75). Note that the GKS workstation window and workstation viewport are superceded by this process.

Description: Set clipping.

Definition: LOGICAL CLIP

SUBROUTINE GSCLIP (CLIP)

Parameters: Name In/Out Type Description

C++: extern "C" void gsclip (long* clsw)

Notes: Turning on clipping stops any graphics outside the viewport (and window) from appearing..

Description: Get screen parameters.

Definition: SUBROUTINE GDEFN (NOPIX, NOLINE, NOLUT)

Parameters: Name In/Out Type Description

C++: extern "C" void gdefn (long* nnox, long* nnoy, long* nnlut)

Notes: Returns drawing area currently used in aspect ratio 4:3.

Description: Initialise locator. Set cursor mode.

Definition: DIMENSION START(20)

Parameters: Name In/Out Type Description

C++: extern "C" void ginlc (long* wkid, long* type, float* initial, long* handle)

Notes: Sets the cursor into a mode. The user clicks the left button to initiate a selection. When the button is released the cursor parameters are passed to the ozcursor callback routine. See OZCURSOR.FOR

The cursor mode must be explicitly disabled. There are also a set of single selection functions.

The window / viewport of the current segment is applied, so the segment MUST be chosen before the call.

The cursor type is:

. 0 = none, disable

1 = cross hair (point)

2 = box cursor (select both corners)

3 = circle type, select centre & outside point

4 = straight line (select both ends)

5 = fixed size box

6 = digitise line

Initial data is required for:

fixed size box - size of box in world coords X then Y size

Description: request locator (Cross hair point cursor).

Definition: SUBROUTINE GRQLC (IDWK, PX, PY)

Parameters: Name In/Out Type Description

C++: extern "C" void grqlc (long* wkid, float* px, float* py)

Notes: Returns a location selected by the user..

Description: request locator - box type, select both corners.

Definition: SUBROUTINE GRQBOX (IDWK, XMIN, XMAX, YMIN, YMAX)

Parameters: Name In/Out Type Description

C++: extern "C" void grqbox (long* wkid, float* px1, float* py1, float* px2, float* py2)

Notes: Enables selection of two corners of a rectangular area.

Description: request locator - fixed size box.

Definition: SUBROUTINE GRQFB (IDWK, XMIN, XMAX, YMIN, YMAX)

Parameters: Name In/Out Type Description

C++: extern "C" void grqfb (long* wkid, float* px1, float* py1, float* px2, float* py2)

Notes: Enables selection of a rectangular area of fixed size. The initial values define the size.

Description: request locator - circle type

Definition: SUBROUTINE GRCIRC (IDWK, PX, PY, RADIUS)

Parameters: Name In/Out Type Description

C++: extern "C" void grqcirc (long* wkid, float* px, float* py, float* radius)

Notes: select centre, then outside point.

Description: request locator - line type.

Definition: SUBROUTINE GRQLIN (IDWK, X1, Y1, X2, Y2)

Parameters: Name In/Out Type Description

C++: extern "C" void grqlin (long* wkid, float* px1, float* py1, float* px2, float* py2)

Notes: Select both ends.

Description: request locator - digitise a line

Definition: REAL PX(NSIZE),PY(NSIZE)

Parameters: Name In/Out Type Description

C++: extern "C" void grqdig (long* wkid, float* px, float* py, int* sizearray, int* numdig)

Notes: Returns the points traced by the cursor.