PHILOSOPHY OF THIS "GENERAL SCALING" PACKAGE

 

  It would be nice to have a graphics' package that could work across all platforms (and by platform I here mean DOS32, EuWinGUI and Win32Lib, not the differences between MS-DOS, MS-WINDOWS and the various shades of Linux).

 

  In this package I have tried to get such a scheme started, at least for the drawing of simple 2D graphics.

 

The package had to meet some of the following criteria:

 

1.      The core package would comprise a set of "include" files.

 

2.      Commands to drawing functions and routines should as far as possible have the same syntax and parameter lists_ across all platforms (platforms as defined above). Commands should be as simple as possible and, where relevant, reflect the pattern of the syntax of Euphoria's native (graphics.e) graphic commands, draw_line() and polygon(), but in a style not easily confused with them.

 

3.      If a programmer wants to draw directly on a screen or on a drawing control, (s)he can already do so quite adequately using the commands native to the platform in which (s)he is programming. This package should cater rather for automatic mapping of drawing done in "real-world" coordinates to a viewport, using a system of scaling.

 

4.      Clipping is a process by which portions of a drawing which lie outside the limits of a screen or viewport are "trimmed off" at display time.

 

The package should provide clipping of images at the programmer's option. Automatic clipping of drawings is provided by Window's environments and by DOS32. But both of them often work inadequately at a drawing's margins, leaving disfiguring traces of earlier images at the screen or drawing-control edges. If you are drawing to a viewport that is smaller than the size of the screen or drawing-control in use, clipping may well become obligatory to keep your drawing inside the viewport. So clipping must be available at the programmer's option, and not done when not needed.

 

5.      The business of scaling data is actually platform independent, as are the calculations relating to clipping. Routines for such tasks can be written once and for all and shared across platforms. This contributes to maintainability and consistency.

 

6.      Routines relating to output to screen or graphic control, or input from same are platform specific, and would have to be accommodated in include files, one for each particular platform.

 

7.      In practice, the include files were written in the following order:

 

 

SScale.e

Containing scaling and clipping routines

 

SPlotEWG.ew

EuWinGUI routines for scaled I/O to Windows graphics controls via memory bitmaps. This was worked on until bug-free operation was achieved. It also contains routines to display a graph, a histogram, or a pie chart.

 

SPlotDOS.e

DOS32 routines for I/O to viewports on a DOS graphic-screen. SPlotEWG.ew was used as the template for this file. This made it easier to write and ensured that routines would all have the same names as for the EuWinGUI version (name clashes here not a problem, since SPlotEWG.ew and SPlotDOS.e should never both be included in the same program). This is now (I think) bug-free. It is deficient in not yet providing mouse and font support.

 

Bustout.e

This also is included in the package. The ability to quickly generate sequences representing assorted common polygons and figures is so useful that this file, whose routines do only that, was included in the package; these routines are platform independent.

 

 

  You will notice an obvious omission; nothing about WIN32LIB. Unfortunately I have so far not "got into" WIN32 programming and so can not write the file SPlotW32.ew, although I think doing so would probably be quite easy; using SplotEWG.ew as the starting template, modifying it to SPlotW32.ew would I think prove a minor chore for anyone practised in writing for WIN32LIB. Hands up anyone?

 

  No attempt has been made to optimise the routines for speed, never mind rendering critical routines into C or machine code. They work quite fast enough for reproducing simple static graphics and even simple animations.

DrawBustV2 Vector Drawing Program

 

An earlier submission, a vector graphic drawing program called DrawBust, is in the Euphoria Archive. I have included in this package its successor, DrawBustV2, which remedies some of the rough edges of DrawBust and gives greater flexibility in image editing options and export options. DrawBust and DrawBustV2 are file compatible, so you can use DrawBustV2 to edit any drawings created with the old DrawBust. DrawBustV2 has an export option which exports drawings in a Euphoria form, not quite ready to use but which can easily be edited to a form that can be embedded into your Euphoria program text, or loaded from a file into a sequence by your Euphoria program. It is planned to have it export in some other (non-Euphoria) formats for use with other programming languages.

 

The "General Scaling" package contains the following folders:

 

DrawBustV2

Vector graphics drawing program executable and sample files. Disregard references to "Trial Version" and "Activation" in the Help file - the program as supplied here needs no activation.

 

Demos

Program source code demonstrating use of the scaling routines in DOS32 and EuWinGUI, at various levels of complexity. They also illustrate use of image "objects" exported from DrawBustV2.

 

Docs

Documentation about the package.

 

IncludeFiles

Contains copies of the include files you will need for the C:\Euphoria\Include folder if you want to make SPlotEWG.ew and/or SPlotDOS.e a permanent feature of your graphics programs.

 

 

  Additional notes etc. will be found in each of these folders and their sub-folders as well as in program file listings.

 

  NOTE: I have previously also submitted to the Euphoria Archive a separate package for scaling drawings for EuWinGUI under the title "Graphic Scaling". This present ("General Scaling") package owes quite a bit to that package but is not compatible with it; "General Scaling" is a "root and branch" redo, getting rid of a lot of redundancies, organising things better, and having different routine names. Having said that, it is not too difficult to modify a EuWinGUI program that used the old include file ScaleW.ew to work with SPlotEWG.ew instead, since for every call in the old ScaleW.ew there is an analogous call in SPlotEWG.ew.

 

SUMMARY OF MAIN GLOBAL ROUTINES

(parameter lists omitted)

Command

Platform

Comment

A = S_CreateBitmap()

WIN

Creates and scales a bitmap for EuWinGI, returns bitmap handle.

 

S_CreateViewport()

DOS

Creates and scales a viewport for a DOS graphic                  screen.

 

SetScale()

ALL

Allows rescaling of an existing bitmap (EuWinGUI) or of an existing viewport scaling (DOS).

 

S = ScalePoly()

ALL

Returns a submitted polyline (in world coordinates) as its equivalent polyline (in viewport coordinates).

 

S = AskMachineCoord()

ALL

Returns a point (in world coordinates) as its equivalent point (in viewport coordinates).

 

s = S_WorldMousePosition()

ALL

Returns position of mouse as world coordinates.

 

S_DrawPolygon()

ALL

Draws a polygon (world coordinates) to scale.

 

S_DrawPolygonClip()

ALL

Clipping version of S_DrawPolygon().

 

S_DrawPolyline()

ALL

Draws a polyline (world coordinates) to scale.

 

S_DrawPolylineClip()

ALL

Clipping version of S_DrawPolyline().

 

S_DrawSequenceXor()

ALL

Draws a polyline (viewport coordinates) with XORing.

 

S_DrawPolyPic()

ALL

Draws a structured sequence containing a multi-elemented drawing object.

 

S_Grapher()

ALL

Draws a program generated graph in viewport.

 

S_Histo()

ALL

Draws program generated data as a histogram in viewport.

 

S_PieChart()

ALL

Draws program generated data as a pie-chart in viewport.

 

 

GLOBAL CONSTANTS:           MIN = 1, MAX = 2, X = 1, Y = 2.

GLOBAL VARIABLES:             C_View, C_Win                                -- don't alter these.

 

SEE SPlotCommandEWG.doc and SPlotCommandDOS.doc for more detail about command usage.

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

 

If you encounter problems in using this package or have suggestions to improve it I would be most happy to hear from you at: Mangan_Fred@yahoo.com.au

 

Fred Mangan - October 2010

 

 

 

 

 

 

 

 

Overview.doc