If you are interested in Hollow Horse Softwares's Mode 19 engine and have not yet installed that. then unzip the file M19b202.zip, read the instructions that come with it and install it. When that is done, copy the files M19CLIP.E and TESTCLIP.EX to the folder containing the engine. You can now run the demo in TESTCLIP.EX.
If you have no interest in Hollow Horse Softwares's Mode 19 engine, but just want mapping, clipping and viewing capabilities for general use with your graphics programs, copy the file MAPCLIP.E to a place where it will be on your euphoria search path(s). The installation can be tested with the demo file TESTCMAP.EX.
Read on below for more information about these two installation options.
Recently, looking for some routines which would handle virtual screens for me in a speedy way and I came across Hollow Horse Softwares's Mode 19 engine, so took a copy of it to play around with, even though it was not exactly what I was looking for (I prefer the resolution given by 640x480 pixels or higher to the chunky rendering of 320x200 pixels). The package has facilities for virtual screen pages, as many as you like subject to memory availability, services for bitmaps and sprites, but no services or primitives for graphic drawing other than a vpixel() function and a vline() function, the last to draw a simple straight line via a Bresenham-like algorithm, which did not work properly in the copy I have.
I already had a number of graphic service routines, gleaned from various sources in my system which I use regularly for my own graphics programs. They work well, I like and understand them and know that they are reliable, but I have never got around to integrating them satisfactorily, so I made this the opportunity to do something about that.
It took about two weeks to do the integration work, to test it and to make sure that I would be able to interface it to existing programs without too much need to drastically rewrite those programs. Along the way I found that I could dump a lot of accumulated routines either because they had now became redundant or because they posed complications. The result was far more versatile and more compact and flexible than what I had had before.
Only at this point did I start to think about virtual screens. A copy of the new header file was brought over to the mode19 folder for further modification. Some additional routines had to be written to allow polylines and polygons to be written to virtual screens -- you can't use Euphoria's draw_line() and polygon() for this -- and to allow filling of polygons with colour (an adaptation of an old routine for drawing hatching lines in polygons worked nicely for here). Neither of these tasks took too long and I was soon up and running with the model19Clip.e working well with the Mode19 engine.
There are three vital things needed for drawing graphics on a computer screen in a controlled way:
A viewport is a rectangular area on your computer screen inside which you want your drawing to appear. A viewport can be as small as a few pixels each way, or as big as (but not be bigger than) the entire screen. No part of a viewport should be off the screen.
Even when your drawing has been properly scaled to a viewport, parts of the drawing may still lie outside the limits of the viewport. In the case of drawing on the real computer screen the worst this can do is mess the display up; when drawing to virtual screens if part of your drawing is drawn outside the limits of the currently active virtual screen it will probably crash the program or even the computer. Clipping discards those parts of your drawing that are outside a viewport's boundaries.
When people such as architects, engineers and computer buffs make drawings in the "real world", they do it in terms of some sort of coordinate system, very often the Cartesian (x, y) coordinate system we all learned about in school and college. A system like this comes naturally -- well fairly naturally -- to humans, unlike the numerically restricted and "upside down" coordinate system employed by computer screens.
To make drawings defined by (x, y) points in a Cartesian coordinate system appear correctly in a computer screen viewport, we need some mechanism to transfer (to "map" is the technical term) those points to the appropriate points inside the screen viewport.
That mechanism is known as a window, which consists of an imaginary rectangle along with various behind-the-scenes scaling calculations. You can think of the window as a frame enclosing only that part of your drawing (that part can of course be all of your drawing!) that you want to appear in the viewport. The window rectangle actually used by the computer is defined by four (x, y) coordinates, one for each corner of the rectangle. These coordinates are given in terms of the Cartesian system used when designing the "real world" drawing. Programmed alterations of the window (immediately followed by remapping of the new window to the current viewport) are often used to produce animated "zoom" and "panning" effects on a displayed drawing.
Mode19Clip.e is for use with Hollow Horse Software's Mode19, which is included with this package (and can be obtained direct from the graphics section of the RDS website, RapidEuphoria.com you need to have some idea of how to use Mode19, and should read the instructions that come with it.
Here are the additional commands provided by Mode19Clip.e. Before using any of them your program should already have
This is used to establish a viewport and scaling parameters, and must be executed at least once before using any of the other Mode19Clip commands below. It draws requested viewport conditions on the screen. The parameters used are:
v_set_view() does not execute a CLS(colour, u) command. v_set_view() regards a bk_colour = 0 (BLACK) as
meaning no colour. If you have not executed a CLS() for screen n, and then execute
v_set_view(BLACK, frame_flag, view, win_diag, n)
the function will create the viewport without erasing whatever underlies it. This is useful if you want to
draw over something that's already on the screen, and still be able to see whatever parts of the origional
ground you did not draw over.
The same as Mode19's vline(), but without the error in that command; also, the line should be passed to
v_line() as
{{x1, y1}, {x2, y2}},
where the points are "real world" coordinates.
Used to draw a polyline on the screen in circumstances where clipping is needed. The parameters are:
Exactly the same as v_polyline_clip() except that no clipping will be done.
Draws a polygon, with clipping, to the current viewport. Parameters are:
Exactly the same as v_polylgon_clip() except that no clipping will be done.
The following two functions have been included because they are very handy:
Creates a 4-element sequence in sequence s representing the four vertices of the rectangle defined by diagonal diag.
Creates in sequence s a sequence representing the circumference of a circle centered on centre and of radius radius. The circumference will have num_points points in it.
Most of the above are procedures, not functions ... i.e., they do not return a value. I considered making v_set_view() a function returning the diagonal of the view it actually sets but decided against this as an unnecessary complication. If it would suit your applications, it is not difficult to modify v_set_view() to do this.
A little program called testclip.ex is included to demonstrate use of m19clip.e functions.
As mentioned at the start of this document, M19clip.e was written to accompany Hollow Horse Softwares's Mode 19 engine. If you have no intention of using this engine and just want to use the M19clip.e routines in Euphoria's standard graphics modes, I have included another file, MAPCLIP.E. This performs the same operations as M19clip.e, but has had all the virtual-screen-specific code stripped out of it. All the commands in it are the same as for M19clip.e, with the following differences:
You can try the MAPCLIP.E routines out with the trial program testcmap.ex.
Any comments, suggestions or moans to my email address below.
See also: Colin Taylor's excellent Vega package, available from RDS at RapidEuphoria.com This package is very comprehensive, with functions suited to stylish presentation of graphics and text on DOS pixel-graphics screens.
---ooOoo---