Pl2 VDI.DOC
--------------------
CHAPTER N°7:
THE VDI
--------------------
*** INTRODUCTION ***
--------------------
- The VDI is a set of functions (like Gemdos, bios, and xbios) for graphics:
By calling the relevant functions, you can, for example, display a circle, a polygon, fill surfaces, etc...
I will also have to talk about AES functions, these will not be studied in this book (given the complexity of their implementation). The AES functions mainly deal with the management of the screen and the mouse (Windows, object management...)
- A certain number of parameters will have to be supplied to the VDI functions to obtain the desired effect:
The transmission of parameters is done via an ARRAY: (An ARRAY is nothing other than a memory space which we have reserved from an address (with DS.x place)). This array is common to the functions of the VDI and the AES. The array is located in the BSS segment and it is at certain of its addresses that we will place the parameters. In the DATA segment, we will also have to place a label pointing to the various addresses of the array. (A label pointing to addresses in the DATA zone is generally called VECTOR...) In the array which groups all the reservations for the functions of the VDI and the AES, we can distinguish several groups of arrays:
.The array pointed to by the 'CONTROL' address (for the VDI and AES): it is in this array that we will deposit the function code and the dimensions of the arrays 'intin', 'ptsin', 'intout', 'ptsout'.
.The one pointed to by the address 'GLOBAL' (for the AES): details further on...
.4 arrays pointed to by addresses 'INTIN', 'INTOUT', 'PTSIN', 'PTSOUT' In the 'IN' type arrays, the user can supply parameters and in the 'OUT' type ones, certain VDI or AES functions return values. In INTIN we will place the parameters specific to the VDI or AES function used. In INTOUT, the VDI or AES will deposit return data. In PTSIN we store coordinates: this array is used by the VDI. In PTSOUT the VDI in return provides coordinates (with certain functions).
.There will also be 2 arrays: ‘ADDRIN’ and ‘ADDROUT’ which are specific to the AES and contain addresses (pointing to data...).
.The 'VDIPB' vector of the DATA segment successively points to the addresses of the arrays: CONTROL, INTIN, PTSIN, INTOUT, PTSOUT which are used by the VDI.
.There is also a vector (AESPB) that points to the addresses of the arrays OPCODE, APVERS, INTIN, INTOUT, ADDRIN, ADDROUT, and which is used by the AES functions.
This array is therefore composed as follows:
BSS ;BSS segment
CONTROL: ;CONTROL array (':' because it points to an
;address and not to an instruction...)
opcode ds.w 1 ;1st address of the 'control' array: opcode sptsin ds.w 1 ;2nd address: sptsin sptsout ds.w 1 ;3rd address: sptsout sintin ds.w 1 ;4th address: sintin sintout ds.w 1 ;5th address: sintout idsfct ds.w 1 ;6th address: idsfct handle ds.w 1 ;7th address: handle
ds.w 10
- the CONTROL array has a size of 54 bytes.
GLOBAL: ;start of the GLOBAL array
apvers ds.w 1 ;1st address of the 'global' array: apvers
apcount ds.w 1 ;2nd address: apcount
apid ds.w 1 ;3rd address: apid
apprivate ds.l 1 ;4th address: apprivate
apptree ds.l 1 ;5th address: apptree
ap1resv ds.l 1 ;6th address: ap1resv
ap2resv ds.l 1 ;7th address: ap2resv
ap3resv ds.l 1 ;8th address: ap3resv
ap4resv ds.l 1 ;9th address: ap4resv
- the GLOBAL array has a size of 30 bytes
intin ds.w 128 ;'intin' array: 128 words
intout ds.w 128 ;'intout' array: 128 words
ptsin ds.w 128 ;'ptsint' array: 128 words
ptsout ds.w 128 ;'ptsout' array: 128 words
addrin ds.w 128 ;'addrin' array (AES): 128 words
addrout ds.w 128 ;'addrout' array (AES): 128 words
grhandle ds.w 1 ;here we reserve 1 word for the handle
ds.b 300 ;RESERVATIONS FOR SETBLOCK in 'STACK'
PILE ds.b 1
DATA ;DATA segment
- the vector of the AES
ALIGN.W ;even address because here are L-words
aespb dc.l control,global,intin,intout,addrin,addrout
- the vector of the VDI
ALIGN.W ;even address because here are L-words
vdipb dc.l control,intin,ptsin,intout,ptsout
END
- This array must be included in your listings if you use VDI or AES functions. It is found in the file: TABLEAU.L, you will just need to include it at the end of your listing.
- Here now is the meaning of each FIELD (sub-parts) of the CONTROL and GLOBAL arrays:
CONTROL Array:
opcode :(at CONTROL+0) = the function code to call sptsin :(at CONTROL+2) = the number of pairs of points in PTSIN sptsout :(at CONTROL+4) = idem for PTSOUT sintin :(at CONTROL+6) = number of words in INTIN sintout :(at CONTROL+8) = idem for INTOUT idsfct :(at CONTROL+10)= identification number of the function handle :(at CONTROL+12)= handle number
GLOBAL Array
apvers :(at GLOBAL+0) = version number of the AES in service apcount :(at GLOBAL+2) = maximum authorized number of programs simultaneously in memory apid :(at GLOBAL+4) = current application number apprivate:(at GLOBAL+6) = depending on the function apptree :(at GLOBAL+10)= pointer to an object tree structure ap1resv :(at GLOBAL+14)= reserved for future applications... ap2resv :(at GLOBAL+18)= idem ap3resv :(at GLOBAL+22)= idem ap4resv :(at GLOBAL+26)= idem
- But before you can use the various functions of the VDI or the AES, you will need to make some initializations. (As for GEMDOS with SETBLOCK).
You will have to call the functions: APPL_INIT and then GRAF_HANDLE to initialize the AES.
You will have to call the functions: OPEN_SCREEN_ WORKSTATION then to initialize the VDI.
- To call these functions, we will pass the necessary parameters in the array (at the correct addresses) of the reservations and we will call the VDI with:
MOVE.L #vdipb,d1 ;address of the VDIPB VECTOR in d1 MOVE #$73,d0 ;word=$73 in d0 TRAP #2 ;call to the VDI
or the AES with:
MOVE.L #aespb,d1 ;address of the AESPB VECTOR in d1 MOVE #$C8,d0 ;word=$C8 in d0 TRAP #2
and this after each VDI or AES function that we will call.
The OPEN_SCREEN_WORKSTATION function allows to open a workstation by loading the VDI graphic management system into memory.
The parameters to provide are:
In opcode, 1 WORD=100 (the function CODE) In sptsin, 1 WORD=0 In sintin, 1 WORD=11 In handle, the WORD pointed by grhandle In intin up to intin+20, 1 WORD=1
In reality, the parameters placed in INTIN must provide the following information:
intin = identification of the device to the motherboard
intin+2 = line type
intin+4 = line color
intin+6 = marking type
intin+8 = marking color
intin+10= character set
intin+12= writing color
intin+14= fill type
intin+16= fill pattern
intin+18= fill color
intin+20= coordinates for flags
But we will not use them, we then put all these values at 1...
The APPL_INIT function of the AES allows to initialize the AES.
The parameters to provide are:
In the 4 apresv, 1 L-M=0 In opcode, 1 WORD=10 (the function CODE) In sptsin, 1 WORD=0 In sptsout, 1 WORD=1 In sintin, 1 WORD=0 In sintout, 1 WORD=0
The GRAF_HANDLE function of the AES enables to give an identification number to our program. This number returns in INTOUT and we will place it in 'grhandle'.
The parameters to pass are:
In opcode, 1 WORD=77 (the function CODE) In sptsin, 1 WORD=0 In sptsout, 1 WORD=5 In sintin and sintout, 1 WORD=0
As the OPEN_SCREEN_WORSTATION function of the VDI needs this identification number (parameter), it is with the call of the AES that it will be necessary to start.
After calling the GRAF_HANDLE function of the AES, we will deposit the identification number deposited in INTOUT in 'grhandle' with:
MOVE INTOUT,GRHANDLE
We will also create 2 MACRO instructions that will be responsible for calling the VDI and the AES.
VDI MACRO ;VDI call macro
MOVE.L #VDIPB,d1 ;address of the VDIPB Vector in d1
MOVE #$73,d0 ;word=$73 in d0
TRAP #2 ;call to the GEM
ENDM ;end of the macro
AES MACRO ;AES call macro
MOVE.L #AESPB,d1 ;address of the AESPB Vector in d1
MOVE #$C8,D0 ;word=$C8 in d0
TRAP #2 ;call to the GEM
ENDM ;end of the macro
- The complete listing of the initialization program for the AES and the VDI will therefore be:
- initialization of the VDI and the AES
TEXT
VDI MACRO
move.l #vdipb,d1
move #$73,d0
trap #2
ENDM
AES MACRO
move.l #aespb,d1
move #$C8,D0
trap #2
ENDM
- APPL_INIT
move.l #0,ap1resv
move.l #0,ap2resv
move.l #0,ap3resv
move.l #0,ap4resv
move.w #10,opcode
move.w #0,sptsin
move.w #1,sptsout
move.w #0,sintin
move.w #0,sintout
AES ;-->AES
- GRAF_HANDLE
move.w #77,opcode
move.w #0,sptsin
move.w #5,sptsout
move.w #0,sintin
move.w #0,sintout
AES ;-->AES
move.w intout,grhandle ;We save the HANDLE
- OPEN VIRTUAL SCREEN WORKSTATION
move.w #100,opcode
move.w #0,sptsin
move.w #11,sptsout
move.w grhandle,handle
move.w #1,intin
move.w #1,intin+2
move.w #1,intin+4
move.w #1,intin+6
move.w #1,intin+8
move.w #1,intin+10
move.w #1,intin+12
move.w #1,intin+14
move.w #1,intin+16
move.w #1,intin+18
move.w #1,intin+20
VDI ;-->VDI
END
The listing for this initialization is found in the file INIT_GEM.L
- All your programs that use the VDI or AES will therefore have this structure:
TEXT
INCLUDE "INIT_TOS.L" ;file of the SETBLOCK macro
INCLUDE "INIT_GEM.L" ;file of the VDI/AES initializations
SETBLOCK ;memory reserve
. ;the instructions that form
. ;your program...
.
DATA
. ;the initialized data
.
BSS
INCLUDE "TABLEAU.L" ;the TABLEAU of the VDI and AES:
;Also contains the 'STACK' reservations
;for SETBLOCK...
END
*** THE FUNCTIONS OF THE VDI ***
---------------------------
You are now ready to use the graphic functions of the VDI:
I will quote the most interesting functions and give you for each the parameters to pass in the array: TABLEAU.L
I will also give you the return parameters if the function provides them and if they can be useful...
TEXT: Allows editing a text at coordinates (x, y). ---- Parameters:
Opcode=8 sptsin=1 sintin=n handle=grhandle intin=the character string composed of 'n' letters ptsin=x ptsin+2=y
NB: The character string must end with a NULL value.
GRAPHIC TEXT COLOR: Allows selecting the color of a graphic text. ------------------ Parameter:
opcode=22 sptsin=0 sintin=1 handle=grhandle intin=chosen color
GRAPHIC TEXT SPECIAL EFFECTS: Allows manipulating the type of graphic text. ---------------------------- The type of graphic text is deposited in 'intin' in the form of a word, only the bits 0 to 5 of the word are used and allow to choose:
BIT number: Effect on TEXT
0 bold characters 1 thin characters 2 italic characters 3 underlined characters 4 'light' characters 5 'outline' characters
parameters:
opcode=106 sptsin=0 sintin=1 handle=grhandle intin=bit vector
CONTOUR FILL: Allows filling a surface from a starting point of coordinates (x, y). ------------ Parameters:
opcode=103 sptsin=1 sintin=1 handle=grhandle intin=fill color ptsin=x ptsin+2=y
SET FILL COLOR INDEX: Determines the color used for filling functions. --------------------- Parameters:
opcode=25 sptsin=0 sintin=1 handle=grhandle intin=fill color
Return parameters:
intout=fill color
SET FILE INTERIOR: Allows selecting the type of fill for filling functions ------------------ There are 5 types of fills:
0=no fill 1=solid fill with the selected color 2=filling with predefined patterns 3=fills with HATCHES 4=fills with a pattern redefined by the programmer
Parameters:
opcode=23 sptsin=0 sintin=1 handle=grhandle intin=type of fill (0-5)
SET FILL STYLE: Allows selecting the matrix for filling functions: 36 patterns are available
The matrix is the pattern used for filling the surface: It can be type 3 (24 patterns) or type 2 (12 patterns) (see the SET FILL INTERIOR function for the 5 types available)
Parameters:
opcode=24 sptsin=0 sintin=1 handle=grhandle intin=pattern number (1-24) or (1-12)
SET WRITING MODE: Allows selecting the writing mode of all graphic editions.
In mode 1: AND mode, what is underneath is always erased. In mode 2: OR mode, we only write where there are no points yet and the voids are always represented. In mode 3: XOR mode, we only place points where there are not any yet and the points already occupied are erased In mode 4: inverse transparent mode, we only place points where there were already and only if they do not have color (allows to obtain a NEGATIVE of the destination pattern).
Parameters:
opcode=32 sptsin=0 sintin=1 handle=grhandle intin=graphic mode (1-4)
FILL RECTANGLE: Fills a rectangle defined as follows: coordinates of the upper left corner (x1, y1), coordinates of the lower right corner (x2, y2)
Parameters:
opcode=114 sptsin=2 sintin=0 handle=grhandle ptsin =x1 ptsin+2=y1 ptsin+4=x2 ptsin+6=y2
CIRCLE: Allows drawing a circle of coordinates (x, y) with a radius R on the screen.
Parameters:
opcode=11 sptsin=3 sintin=0 idsfct=5 handle=grhandle
ptsin =x ptsin+2=y ptsin+4=0 pts