Using !DrawGen

!DrawGen - Getting Started.

Drawfiles are an excellent way to display graphical information, both on screen and in documents. Unfortunately, the internal details of Drawfiles are frighteningly complex and this tends to put people off creating them directly. Instead, most people use editors like !Draw, !Vector, etc. This route is fine, but it does have limitations. The purpose of this short series of articles is to introduce a flexible alternative call !DrawGen. This can be used to create Drawfiles directly from programs in 'C', BASIC, or any other language you like. For those who just what to create simple shapes and diagrams it can be used in a fairly simple way. However, it also has complex depths which can be used to create quite complicated pictures. This first article is a 'get you started' introduction so you can see how to use it and have a chance to find out for yourself how easy it can be. For clarity I'll concentrate on using Acorn 'C', but I'll deal with BASIC in more detail later.

Step one: Put a copy of the !DrawGen application on your hard-disc.

Step two: Double-click on !DrawGen. This runs it, installs the DrawGen module, and sets up some things ready for use. For BASIC use, that's it, you could now write a program which created DrawFiles. However, for 'C' there is one more thing you must do...

Step three ('C' users only): Take a copy of the 'DGLib' file and copy it into your 'h' directory.

Now we can write a test program. Try this one:

#include <stdio.h> #include "DGLib.h" int main(void) { /* Create the file */ DG_open("ram:boxes2"); /* rectangle with bottom left corner at x=200, y=300, width 50, height 80 (All 'OS' units.) */ DG_rectangle(200,300,50,80); /* Change drawing colour to green */ DG_colour("green"); /* Now draw a filled rectangle */ DG_rectanglefill(400,500,100,20); /* Tell DrawGen to make the DrawFile */ DG_make(); /* That's it! */ }

Save this, compile, and run it. Now look in your ramdisc and you should find a DrawFile which looks like figure one. It should show one open rectangle drawn with a black line, and another rectangle which is filled and coloured green.

Comparing the program with the result it should be immediately obvious what is going on. In a 'C' program the DrawGen process is driven by a series of commands which all begin with 'DG_'.

The first one should always be 'DG_make(<filename>);'. This tells the system you're about to start building a drawfile, and the filename you want. (For my examples, I'll assume the output is always being put on the ramdisc, but you can change the file's address to anything you like.)

Then come a series of commands which describe the objects you want to appear. In this case we can see:

DG_rectangle(left, bottom, width, height);

and
DG_rectanglefill(left, bottom, width, height);

By default, the position information (sizes, locations) are in 'OS' units identical to those used for the old BASIC 'PLOT' drawing commands. These are integer values which assume that 0,0 is the bottom left corner of the drawing. Objects are drawn in black using a line which is a half a point thick. You can change the default colour as required - for example, in this program the command:

DG_colour("green");

can be seen to change the drawing colour to green. This change would persist until you chose to change it again or finish the Drawfile.

At the end comes the command:

DG_make();

This tells the DrawGen module that you are finished and it should create the DrawFile. There are a number of simple example programs in the 'C' examples for you to examine and try out. The main commands not mentioned so far are:

DG_circle(x_centre, y_centre, radius);

DG_circlefill(x_centre, y_centre, radius);

DG_line(x_start, y_start, x_end, y_end);

DG_ellipse(x_centre, y_center, half_hight, half_width);

DG_ellipsefill(x_centre, y_center, half_hight, half_width);

DG_point(x, y);

DG_text("Hello World", x_position, y_position);

The current drawing colour is described by a text string for clarity. The acceptable colour names are: red, green, blue, white, grey, lightgrey, darkgrey, lightblue, darkblue, yellow, magenta, orange, and cream. For BASIC users there is more detailed information in the '!help' file inside !DrawGen. 'C' users can try reading though the DGLib file. I have deliberately left this as text so you can read it and discover the commands and what values they expect. As a taste of thing to come you could try the program below.

/* demo showing a range of things! */ #include <stdio.h> #include <math.h> #include "DGLib.h" int count; int xp,yp; double amp; int main(void) { DG_open("ram:Ooh_er!"); count=1; do { DG_colour("black"); DG_rectangle(300-16*count,200-16*count,100+32*count,150+32*count); DG_colour("orange"); DG_circle(500,500,16*count); DG_colour("blue"); DG_ellipse(800,100,25*count,10*count); count++; } while (count<10); DG_text("Twas brillig and the slythy toves",100,900); DG_font(5,20,20,"blue"); DG_text("did gyre and gimbal in the wabe",100,800); count=1; amp=200.0*sin((double)count*0.25)*exp((double)count*(-0.05)); xp=800+(int)amp; yp=800-5*count; DG_path(xp,yp,5,0x00ff0000,-1); do { count++; amp=200.0*sin((double)count*0.25)*exp((double)count*(-0.05)); xp=800+(int)amp; yp=800-10*count; DG_draw(xp,yp); } while (yp>100); DG_end(); DG_make(); /* That's it! */ }

This creates the drawfile shown as fig 2.

This includes some commands I'll explain later.

In part 2 I'll explain how to create complex shapes and how to change the other defaults, (line thickness, pattern, text font, etc). That said, you may well be able to work out some of what comes next by playing around and trying the examples! So enjoy!

What to do when things go wrong.

The !DrawGen system doesn't contain any protection against creating an 'illegal' (i.e. 'daft') DrawFile. For example, drawfile locations should never contain negative values, nor should any object have pieces which are of size zero. Problems will also occur if you try to make colossal objects which are, say, 8107540460290575063 units across! Any problems will show themselves in two ways:

1) You may find that you've created a data file instead of a DrawFile. Worse, it may resist being deleted! This will be because DrawGen got confused by an illegal command and gave up, leaving the file open. This is one reason why I always create files on the ram disc. You can then open a task window, type "ram <return> close <return>" and then you'll be able to delete the offending file.

2) The file appears OK, but you have trouble editing it with !Draw, !Vector, or whatever.

In either case, read your program carefully. Look for things which might have tried to create 'odd' objects - e.g. below the bottom-left corner of the file!

Copyright Note: I wrote !DrawGen a couple of years ago for my own use. You are free to distribute and use it as you wish without payment. Please, however, keep it in the form provided so we don't get a plethora of variant forms. Also, please note that it uses the ABCLib module which is owned by a commercial company. They permit its free distribution and use for non-commercial purposes only.

This article first appeared in the March 1997 issue of Archive magazine. It is reproduced here by kind permission of Paul Beverley. If you haven't seen Archive, I strongly recommend it! Check out the Archive Website.

Content and pages maintained by: Jim Lesurf
using HTMLEdit3 on a StrongARM powered RISCOS machine.