Dragon 32 Universe
%LOGIN_INFO%
PROFS RELEASES:
 

Introduction

The Pixel Editor can be used to create and edit graphics shapes. These could be anything from a letter in an alphabet, to a picture of a multi-coloured umbrella. We have used it to help produce the graphics in this program, and the screen that is shown while the program is loading is an example of what can be done. The graphics shapes that you create with the program can be saved in a cassette file and later used in either BASIC or machine code programs.

Pixels are the dots on the display screen, and the Editor allows you to create multi-coloured characters at this level without the need to know how the display works or even how the colours are stored within the machine. In addition, there is a BASIC routine on the tape that can be inserted into your own programs, so that using the shapes you create is as easy as possible.

For the more experienced programmer, a second version of the routine is provided in relocatable machine code to enable faster and more compact programs to be produced.

You will also find a set of characters on the tape that can be loaded into the program and added to, or edited, as desired. One of these sets is a lowercase alphabet - a, b, c, etc - which can be used on the graphics screen.

General Information

You will find four items on the tape:

  1. The Pixel Editor itself, called PIXED
  2. The GETPUT routine
  3. The Multi-Colour Print routine
  4. Collection of character sets

We shall be looking at how to load and use each of these in the following sections. Before we do that, let's define some of the terminology we will be using.

The Dragon Reference Manual will give you the details of the different graphics modes and the memory layout. We will be dealing with the blocks of store known as graphics pages, specifically pages 5 to 8 in the Dragon memory map. We use these pages of store to hold the shapes we are editing.

A pixel is the term for each of the dots on a display screen; they are combined together in varying brightness and colour to make the picture. On the Dragon, they can be addressed at different levels, depending on the resolution required and the number of colours being used.

We will be using Modes 3 and 4, and in these, it takes four pages to make up a screen. While you are editing shapes you will see that the page being edited takes up a quarter of the screen.

It is important to note, before using the pixel editor, that whereas in normal computing one would expect to count from 1 upwards, in computing one counts from zero. This state has arisen because at the start of any counting in computing there is nothing, i.e. zero, so that is the first number. If, therefore, you want to have a block of memory accessed that is 12 columns wide, it would be addressed from 0 - 11, rather than 1 - 12 as you might expect.

The pixel editor enables up to three sets of shapes to be edited at any one time, and holds each set in a separate page.

The number of addressable elements in a page will depend on the mode in use. Mode 3 has 48 rows x 128 columns, giving 6144 addressable elements. Mode 4 has 48 rows x 256 columns. It therefore has twice the resolution, but has only two colours available.

These addressable elements are grouped together into "grids" which are used whilst editing each character or shape. The *grid size* is the number of rows and columns used by each shape. For example, the grid size of the character sets supplied on tape is 8 rows x 6 columns. On a page, one can therefore fit 21 characters across (128 columns per page divided by 6 columns per character) with 6 down (48 rows per page divided by 8 rows per character line. This is shown in Fig 1, below).

0 1 2 18 19 20
21 22 23   39 40 41
             
105 106 etc.   123 124 125

Fig 1

The numbers on the grid are the numbers used to reference each shape.

If you define a grid size that does not fit the page exactly, there will be some room left at the edge. If, for example, you set a grid size of 24 rows of 12 columns, they will be held on the page as shown in Fig 2.

0 1 2 3 4 5 6 7 8 9  
10 11 12 13 14 15 16 17 18 19

Fig 2

The Pixel Editor - How To Use It

If you have not already done so, load the Pixel Editor.

The Pixel Editor control works on a standard method of repeated choice. On running the program, the user is presented with an immediate choice of whether to load, edit or save a character set and this is the Base Menu. Throughout this system of menus it is only necessary for the user to follow the instruction. The second selection, edit, will lead on to another menu - the Main Menu - and this has the eight basic selections available within the editor. In each of these eight options there will be further options and so the whole program structure can be thought of as a series of "levels" through which the user descends to arrive at a specific action. To return back up through the layers it is simply necessary to press the # key for each level ascended.

Base Menu - Load, Edit, Save

The Base Menu has three options available and these are as follows:

  1. Load an old character set
    If there are three consecutive character or graphics sets on the cassette then the Auto Load function can be employed. This takes the first character set and places it into page 6, the second into page 7, and the third into 8. If only one character set is required, or if the sets are not consecutive, the manual option can be used to take named sets from the tape into a specified page of memory.
     
    If you have a tape with three sets on it, insert it into the cassette unit and, after selecting the Auto-load option, press PLAY. The sets will be loaded in one by one and the program reverts to the Main Menu when finished.
  2. Edit
    The use of this option takes the user straight through to the Main Menu - see below.
  3. Save
    This is used when a character set has been modified or created and it is now desired to save it on cassette for later use.
     
    Any of the three graphics pages can be saved under any name on the tape, but it is important to name sets sensibly and to save them in an appropriate place on the tape.
     
    Insert the tape to which you wish to save your character set into the cassette unit. After specifying the name of the set, start the tape by pressing the RECORD and PLAY keys and start the program saving the data by pressing Space. If you save more than one set, make sure you leave an adequate space between each.

An Example

Having seen the explanations, you will want to try it out. If you have not already done so, load the program.

Unless you have a character set you wish to modify, type 2 to get to the Main Menu. As we are creating a new character set the first thing to do is to set the background colour (option 5). Now set the background colour of page 6 to yellow (value 2). There is now an odd display on the screen. What we see is pages 5, 6, 7 and 8. Page 5 is used as a palette by the program. Page 6 is the second quarter of the screen and is yellow which is what we wanted. Pages 7 and 8 are still unassigned and should be multi-coloured. Any key will now return us to the Main Menu.

Page 6 is now ready to draw on as it is a blank yellow page. This can be validated by choosing option 3 to view a page. As usual typing # will return you back up towards the Main Menu - type # until you are there. Now try editing a character (option 8). The editor has split the page into grids, each of 8 rows x 6 columns. They are numbered from 0 to 125 and character 21 beneath it and so on. Type 0 to edit the first character. There should now be a copy of page 6 at the bottom of the screen and an expanded version of the character above it. Now try drawing a box around the outside of the square in blue by selecting 3 as the colour and using the ENTER and arrow keys as described in Edit Characters. You should now see this blue box in the top left hand corner of the copy on the bottom of the screen. When you've finished drawing one character, type # and the editor will invite you to edit another character.

Try drawing an X in a different colour in character number 22 and then 0 in character 0. To do this just paint in the centre four squares and you have an 0. Obviously you could go on drawing characters like this as long as you wanted; with this grid size there is room for 126 characters in a page.

We have drawn two characters:- Character 0 and character 22. Now let us see how to use these characters in another program. We shall first save them on a cassette.

Use the # key to return to the Base Menu. Now selection Option 3 to save the character set.

First make sure that the tape in the cassette unit is not the one with the Pixel editor on it. It is best to use a blank cassette which can be later used as a library of character sets.

The Pixel Editor is now telling you that you have been working with page 6. You may have been working on several pages so you have the choice of which page to save. We want to save page 6, so type 6 followed by the ENTER key. It is now necessary to type a filename, and it is a good idea to try and use a meaningful filename. In this case it would therefore be sensible to try CHR-OX so type this and press the ENTER key. Now press the Record and Play buttons and make sure that the leader tape is past the tape heads. Now press ENTER and you should hear the page being saved (provided that the volumn on your TV is turned up!).

The Getput Routine

The way the character set can be used in BASIC relies on two of the Dragon's Graphics commands GET and PUT. It will help you to understand the GETPUT listing (see Appendix A) if you have read Chapter 10 of the Dragon User Guide which deals with the GET and PUT statements.

Firstly, load the GETPUT program in much the same way as the Pixel Editor, but in this case it is a BASIC program so you will type CLOAD "GETPUT" rather than CLOADM. Follow with the ENTER key, and press PLAY on your cassette unit. When the program has loaded, you will recieve the OK message. Insert the tape with your characters into the cassette unit. Now type RUN (ENTER). Start the cassette unit playing and press Space. You should now see your character set being loaded into page 5 at the top of the screen. When it has been loaded you should press Space to continue. You will be asked to type in your grid size - if you want the same size shapes as shown then type Y; if you want to change the size type in the new values, following each with ENTER.

The GET and PUT areas now have to be selected and these are done as follows:

The GET position is the position within page 5 to get the shape from. This is calculated in addressable elements and you have to remember that in Mode 3, page 5 will be made up of 48 rows or 128 columns. The top left hand element is referred to as (0,0) and will match up with shape 0. If your grid size is 8 rows of 6 columns, position (0,8) would give you the left hand character in the second row.

The PUT position is worked out in the same way, but is the position in the graphics screen that the shape will be displayed. After you have typed in your GET and PUT coordinates, the character selected should appear on the screen. If you press Space, you can then move further areas into the graphics screen. Try building a house with the 0 and X characters you created earlier. By looking through the listing of the GETPUT routine, you will see how to use the shapes you have created, in your own programs.

The Multi-Coloured Print Routine

The Multi-Coloured Print Routine - MCPR - uses Mode 3 character sets created with the Pixel Editor. It is provided in relocatable machine code which normally gets loaded into memroy at $2400. It provides a quicker method of displaying custom-built characters on the screen, and gives a straightforward interface to the user. Having understood how to use the subroutine, the user can access the internal parameters and extend its facilities still further. For a full description of MCPR and its parameters, their defaults, etc, see Technical Appendix B.

Firstly, type PCLEAR8 to prevent the basic program overlapping MCPR and the character set. Then follow the standard loading procedure to load the routine into memory using a CLOADM"MCPR" command. The system will reply "OK" when it has loaded.

Having loaded the multi-coloured print routine, load one of the character sets provided on the tape into graphics page 5 with the following command: CLOADM "name of character set", &H600. Now try typing in the following:

For example:

10 REM MCPR TEST
20 PCLEAR8
30 A1=&H2400:PP$="":VPT=VARPTR(PP$)
40 POKE A1+4,INT(VPT/256):POKE A1+5,VPT AND 255
50 POKE A1+13,ASC("<")
60 PMODE 3,1:SCREEN 1,1:PCLS:COLOR 2,1
70 POKE A1+2,0:POKE A1+3,0
80 PP$="Would you like to <play<<@3A@2:Game 1<":EXEC A1
90 PP$="@3B@2:Game 2<":EXEC A1
100 GOTO 100

For better understanding of this program refer to the Dragon User Guide, and the Technical Appendix B.

If you run this you will see the power and speed of the MCPR. The text is displayed very quickly; the colour of the text changes and lower case characters are displayed. Once you understand how the routine is used within BASIC programs you can experiment with the various parameters shown in the appendix. Try changing, e.g.:

A1+13 - the line feed/carriage return key
A1+2,A1+3 - the X and Y start co-ordinates
the strings and colours printed etc.

The MCPR routine, although slightly harder to use, is much faster than anything that could be produced using BASIC alone and is ideal when lower case etc, is required for fast text displays on the Dragon. Larger characters than these can be used by changing other parameters.

Appendix A. The GETPUT Program

GETPUT is a general program designed to take an area of the graphics pages and output it on to the screen. The program centres around two Basic commands in the Dragon's Graphics facility - GET and PUT. GET command gets an area of the current graphics page defined by two pairs of co-ordinates (X1,Y1) and (X2,Y2). (X1,Y1) pinpoints the top left-hand corner of the area to be transferred and (X2,Y2) pinpoints the bottom right-hand corner. In the program, then, X1 and Y1 are input by the user and the size of the area input earlier is used to calculate (X2,Y2). The PUT statement works the same way - see chapter 10 of the Dragon User Guide for further information on the technical aspect of these two statements.

Between the GET and PUT statements there is a statement changing the current graphics screen from page 5 to page 1. This causes the GET statement to get the information from page 5 and the PUT statement to put the information out on to page 1, and using the SCREEN command to output page 1 on to the screen. In this way, whole pictures can be built up from graphics and character sets defined earlier, and, by changing the character grid size the size of the area being moved can be changed.

The GETPUT Routine

10 CLS:PMODE3,1:PCLS2:PCLEAR8
20 INPUT"TYPE THE NAME OF THE CHARACTER SET YOU WISH TO LOAD (N FOR NONE)";Q$
30 IF Q$="N" THEN 100
40 PRINT@128,"LOADING CHAR SET INTO PAGE 5",,,"START CASSETTE PLAYING",,,
50 PRINT"PRESS SPACE BAR WHEN READY"
60 IF INKEY$="" THEN 60
70 PMODE3,5:SCREEN1,0
80 CLOADM Q$,1536
90 IF INKEY$="" THEN 90
100 DIMGP(59,39)
110 GX=12:GY=8
120 CLS:PRINT"SAME GRID SIZE(";GX"*";GY;")":INPUT "",Q$
130 IF Q$="Y" THEN 160
140 INPUT"HORIZONTAL (MAX 60)";GX
150 INPUT"VERTICAL (MAX 40)";GY
160 REM GET COORDS...
170 CLS:PRINT"CHOOSE GET COORDS":INPUT"X1";X1:INPUT"Y1";Y1
180 PMODE3,5
190 GET(X1,Y1)-(X1+GX-1,Y1+GY-1),GP,G
200 REM CHOOSE PUT COORDS
210 PRINT"CHOOSE PUT COORDS":INPUT"X1";X1:INPUT"Y1";Y1
220 PMODE3,1:SCREEN1,0
230 PUT(X1,Y1)-(X1+GX-1,Y1+GY-1),GP,PSET
240 IF INKEY$="" THEN 240
250 GOTO 120
260 PMODE3,5:SCREEN1,0:GOTO260

Appendix B - Multi-Colour Print Routine

Dragon 32 High Resolution Graphics Text Print Routine

Version 1.1 Multi-colour
In string colour switch
Graphics mode 3 only

1. Technical Summary

This machine code routine displays text in high resolution graphics mode by reading a BASIC string and transferring characters (from a character set held somewhere in RAM) to the graphics screen area.

1.1. Facilities

The text string can be displayed starting from any point on the screen. Parameteres DX and DY give the coordinates of the top left corner where the string starts.

The BASIC "COLOR" command can be used to specify the foreground and background colours of the text.

The colour of the lettering (foreground colour) can be changed at any point in the string with a user-definable escape character (normally @) followed by the desired BASIC colour number (1-8). This greatly simplifies the printing of multiple coloured menu screens.

A user-specified character (normally '<'), at any point in the string will cause a return-newline on the screen; the remainder of the string is displayed one character-line down, starting from the left border of the screen.

The 'configuration parameters' (which determine character size, spacing, and character set type) have default values loaded with the routine. They are set for use with the standard character set supplied, and can be changed for use with other character sets.

1.2. Restrictions

In its present form the routine will only work in graphics mode 3.

No range checking is performed on any of the routine parameters, except the 'hidden parameters' which are checked by BASIC.

The colour change escape character (normally '@') may not appear in the string except when followed by a colour number.

1.3. Code

The routine is supplied in fully re-locateable object code from $2400 (graphics page 6). It can be moved to any position in store.

Where A is the base address of the (relocated) routine, A is also the entry point and A+2 through to A+15 is the parameter area.

2. Parameters

2.1. Hidden Parameters

The hidden parameters are taken from the BASIC system storage in page 0 and hence do not require special attention by the programmer.

(a) Target Screen
 
Parameter name
 
address
 
system use
DBP $B7,$B8 top of current graphics screen

Characters are printed to the screen area specified by the most recent PMODE command - as with other graphics functions such as PUT, LINE etc.

(a) Target Colours
 
Parameter name
 
address
 
system use
DFCL $B2 current foreground colour
DBCL $B3 current background colour

The character colouring is determined by the BASIC foreground and background colours (unless the colour change character is encountered in the string). Where a normal single colour character set is being used, COLOUR F,B will cause the string to be displayed with characters colour F on a background strip colour B. Remember the 'C' command used in a DRAW string also changes the current foreground colour. Any other colours in a non-standard character set are unaffected by the colour switching software.

2.2. Functional Parameters

The functional parameters are passed in the first part of the parameter area. Values must be poked in before the routine is called.

Name Address Use
DX A+2 Target X coordinate (top left corner). DX is altered by the routine such that on exit it points to the next character position following the string; consecutive calls to the routine will cause strings to be displayed one following the other. Beyond the right border the screen DX wraps around in a non-useful way. An end-of-line character in the string causes DX to be reset to zero.
DY A+3 Target Y coordinates. DY is not altered unless an end-of-file character is encountered in the string, in which case DY is incremented by RSP (see 2.3). There is no range checking on DY which may exceed 191 - as if the screen extended downwards.
VPT A+4
A+5
String variable pointer. VPT must contain the 2 byte address of the basic 5 byte string descriptor. The name PP$ is recommended for all calls to the routine so that the following installation code can be executed once at the start of the program.
 
PP$="":VPT=VARPTR(PP$):POKEA+4,INT(VPT/256):POKEA+5,VPT AND 255

2.3. Configuration Parameters

The configuration Parameters all have default values loaded with the object code. these are set up for use with the standard character set supplied, held in graphics page 5, coloured blue on yellow, with CR as the end-of-line character and '@' as the colour switching character.

Name Address Default Use
SBP A+6 $1E00
(page 5)
Character set base address. The character set may be located anywhere in RAM.
 
GL A+8 8 Character height.
GN A+9 6 Character width in mode 3 addressable elements.

3. Recommendations for Use: See Section 6 for an example of its use

3.1 Other Character sets

When using other character sets, the following considerations should be borne in mind:

  1. The characters are indexed by the ASCII code, minus 32; thus space is normally the first character in a set. Where non-ASCII characters are to be printed one at a time this routine should not be used. Use the GETPUT Program instead.
  2. Where more than two colours are used in the set, only the Character Set Foreground Colour and Character Set Background Colour will be detected and switched to the foreground or background colours; other colours are unaffected. Where multi-coloured characters must be faithfully reproduced, select the same target forground and background colours as are set in the Character Set Foreground Colour and Character Set Background Colour.

In general, for non-standard character sets with fundamentally differ from ASCII (graphics sets etc), the GETPUT program method should be used.

3.2 In-String Colour Switching

The Character editor (foreground) can be changed mid-stream with the colour switch escape character, normally '@', immediately followed by a single digit giving the BASIC colour number required. This change is only for the duration of one call, the BASIC system foreground colour is not altered. See the example program in Section 6 for a typical application. To disable the facility change the Colour Switch Escape Character to some character which is never used.

Loading

CLOADM (ENTER)

The program will run automatically after loading.