1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
|
<html>
<head>
<meta name="GENERATOR" content="vim">
<title>viDOOM - Free Software DOOM editor</title>
</head>
<body>
<h1 align="center">Porting viDOOM</h1>
<p>This document is provided in case anyone wishes to port viDOOM
to a new platform. Below is an indication of what OS dependent
routines must be provided and what configuration needs to be
done. It is requested that any ports are also released as Free
Software.</p>
<ul>
<li><a href="#MAKEFILE">Makefile configuration</a></li>
<li><a href="#INI">INI File</a></li>
<li><a href="#FILES">Files</a></li>
<li><a href="#MAIN">Main entry point</a></li>
<li><a href="#GFX_H">Graphics and input</a></li>
<li><a href="#PLATGUI_H">Platform GUI</a></li>
<li><a href="#FILE_H">File interface</a></li>
<li><a href="#MEM_H">Memory allocation</a></li>
<li><a href="#RUNCMD_H">External command execution</a></li>
<li><a href="#VSTRING_H">String functions</a></li>
<li><a href="#INSTALLATION">Installation script</a></li>
<li><a href="#DOCUMENTATION">Documentation</a></li>
</ul>
<hr>
<h2><a name="MAKEFILE"></a>Makefile configuration</h2>
<p><strong><u>makefile</u></strong></p>
<p><a name="MAKEPLAT"></a>Set the variable <strong>MAKEPLAT</strong>
to the name of your platform, eg.</p>
<p><tt>MAKEPLAT=</tt><em><tt>OS</tt></em></p>
<p>You will then need to create a matching file the <strong>make</strong>
sub directory called <em>OS</em>.cfg. Also all the OS dependent C
source should go into a sub directory defined in the following
make config file by the <strong>PLATFORM</strong> variable. See
the <a href="#FILES">Files</a> section for an overview of these
files.</p>
<p><a name="MAKE_CONFIG"></a><strong><u>make config file</u></strong></p>
<p>The following values need to be set in the file <strong>make</strong><em><strong>/OS</strong></em><strong>.cfg</strong>:</p>
<table border="1" cellpadding="3">
<tr>
<td valign="top" nowrap><strong><tt>CC</tt></strong></td>
<td valign="top">Set to the name of the C compiler.</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>LD</tt></strong></td>
<td valign="top">The name of the linker.</td>
</tr>
<tr>
<td valign="top" nowrap><a name="PLATFORMVAR"></a><strong><tt>PLATFORM</tt></strong></td>
<td valign="top">The name of the D containing the OS
dependent C sources. The idea of defineing tdefining
here, rather than using the MAKEPLAT variable defined in
the top level makefile, is so that different
configurations can share sources. i.e. An X11 port may
use the same code for all the unix platforms, but each
machine may require slightly different configuration
(library search paths for example).</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>EXE_EXT</tt></strong></td>
<td valign="top">An extension to add to the executable
name, e.g.<br>
<tt>EXE_EXT=.EXE</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>OBJ_EXT</tt></strong></td>
<td valign="top">The extension used in this OS to denote
object files produced by the C compiler. Generally:<br>
<tt>OBJ_EXT=.o</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>LIBS</tt></strong></td>
<td valign="top">Any extra libraries to link in with
viDOOM for the OS dependent routines.</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>EXRACF</tt></strong></td>
<td valign="top">Any extra C flags required when
compiling the sources. Use it to enable optimisation and
to include any extra include paths required by this OS.</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>EXTRALF</tt></strong></td>
<td valign="top">Any extra flags required when linking
viDOOM. Use it to enable include any extra library paths
required by this OS.</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>DIRSEP</tt></strong></td>
<td valign="top">The directory separator character for
this OS. The character must be included in quotes, e.g.<font
face="Courier New"><tt><br>
</tt></font><tt>DIRSEP="/"</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>MATHLIB</tt></strong></td>
<td valign="top">The options required to include the
maths library when linking.</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>TRACEFORM</tt></strong></td>
<td valign="top">This variable is a printf format string
and the arguments to the format. This string is used to
provide a tracing function used to track bugs in the
editor. A simple, portable example is:<br>
<tt>TRACEFORM="%s:%d",__FILE__,__LINE__</tt><p>It
can just be defined to an empty string if you are not
compiling the debug version.</p>
</td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>EXEFLAG</tt></strong></td>
<td valign="top">The flag to provide to the linker to
generate an executable. The flag is used in a rule
something like this:<br>
<tt>$(LD) $(EXTRALF) $(EXEFLAG) vidoom$(EXE_EXT)
$(ALL+VIDOOM_OBJECTS)</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>OBJFLAG</tt></strong></td>
<td valign="top">The flag to provide to the C compiler to
generate an object file from the supplied C source. The
flag is used in a rule something like this:<br>
<tt>$(CC) $(EXTRACF) $(OBJFLAG) file.c</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>DEFINEFLAG</tt></strong></td>
<td valign="top">The flag to provide to the C compiler
with pre-processor definition from the command line. The
flag is used in a rule something like this (note no space
after the DEFINEFLAG - if there is a space between the
switch and the argument put it in this variable
definition):<br>
<tt>$(CC) $(EXTRACF) $(OBJFLAG) $(DEFINEFLAG)MACRO=value
file.c</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>INCFLAG</tt></strong></td>
<td valign="top">The flag to provide to the C compiler
with extra directories in which the pre-processor
searches for include files. The flag is used in a rule
something like this (note no space after the INCFLAG - if
there is a space between the switch and the argument put
it in this variable definition):<br>
<tt>$(CC) $(EXTRACF) $(OBJFLAG) $(INCFLAG)include_dir
file.c</tt></td>
</tr>
<tr>
<td valign="top" nowrap><strong><tt>MAKEINSTALL</tt></strong></td>
<td valign="top">The command used to execute the <strong>install</strong>
makefile as described in the <a href="#INSTALLATION">installation
script </a>section. The command must define the
INSTALLDIR variable for the makefile and invoke the first
rule in the install makefile.<p>For instance, using a
normal unix/GCC type make command, this would be:<br>
<tt>make INSTALL_DIR='$(INSTALL_DIR)' -f install</tt></p>
</td>
</tr>
</table>
<hr>
<h2><a name="INI"></a>INI File</h2>
<p>If your port requires or wants configuration to be set at
tun-time from the INI file, it is best to place it a
system-dependent section called the same as the <em>OS</em> value
you set <a href="#MAKEPLAT">MAKEPLAT</a> to for this platform,
e.g.</p>
<p><tt>[</tt><em><tt>OS</tt></em><tt>]<br>
degreelessness mode=off</tt></p>
<hr>
<h2><a name="FILES"></a>Files</h2>
<p>The following files are the minimum that must be provided by
the platform:</p>
<table border="1" cellpadding="3">
<tr>
<td valign="top" nowrap><strong>make/</strong><em><strong>OS</strong></em><strong>.cfg</strong></td>
<td valign="top">The make config file. Described in the <a
href="#MAKE_CONFIG">previous section</a>.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>main.c</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides the <a href="#MAIN">startup
code</a> for the operating system.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>gfx.c</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides the <a href="#GFX_H">low level
graphics and input</a>.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>platgui.c</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides the <a href="#PLATGUI_H">system
dependent GUI</a>.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>file.c</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides the portable part of the <a
href="#FILE_H">file system interface</a>.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>mem.c</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides the <a href="#MEM_H">memory
handling</a>.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>runcmd.c</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides the method for <a
href="#RUNCMD_H">running external commands</a>.</td>
</tr>
<tr>
<td><strong>vstring.c</strong></td>
<td>This goes in the <a href="#PLATFORMVAR">platform
directory</a> and provides functions for <a
href="#VSTRING_H">string comparisons</a>.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>install</strong></td>
<td valign="top">This goes in the <a href="#PLATFORMVAR">platform
directory</a> and is the makefile invoked to <a
href="#INSTALLATION">install viDOOM</a>.</td>
</tr>
</table>
<hr>
<h2><a name="MAIN"></a>Main entry point</h2>
<p><strong><u>main.c</u></strong></p>
<p>The OS dependent code must provide it's own main (this is to
allow for various non-standard environments where main() is not
the standard entry point). The entry point must do any OS
dependent initialisations then invoke the following entry point
to start up viDOOM:</p>
<p><tt>int viDOOM(int argv, char *argv[])</tt></p>
<p>If the OS uses main() as an entry point the following example
could be enough:</p>
<pre>int main(int argc,char *argv[])
{
return (viDOOM(argc,argv));
}</pre>
<hr>
<h2><a name="GFX_H"></a>Graphics and input</h2>
<p><strong><u>gfx.c</u></strong></p>
<p>This provides the low-level graphics access and interfaces to
keyboard and mouse. The GFX object is expected to work on a weak,
semi-event driven basis for keyboard/mouse access. The following
are the basic assumptions about the GFX interface:</p>
<ul>
<li>A true, or hicolor, display.</li>
<li>A Fixed font.</li>
<li>Default origin is in the top left of the display, with X
positive along and Y positive down.</li>
<li>A buffered display. The screen contents should not change
until GFX_redraw() is called. If not honoured viDOOM
should still work up to a point, but it's use of the XOR
mode may not be apparent to the user.</li>
<li>Colours are represented using an int, with 8 bits each
for the red, green and blue component. The int used to
define the colour, when viewed in hex, would look like <tt>0xRRGGBB</tt>.
e.g.<ul type="disc">
<li><tt>0xFF0000</tt> - Red</li>
<li><tt>0x00FF00</tt> - Green</li>
<li type="disc"><tt>0x0000FF</tt> - Blue</li>
<li><tt>0xFFFFFF</tt> - White</li>
<li><tt>0x808080</tt> - 50% grey</li>
<li><tt>0x000000</tt> - Black</li>
</ul>
</li>
</ul>
<p>The following types are defined and used by the GFX object :</p>
<table border="1" cellpadding="3">
<tr>
<td valign="top" nowrap><pre>typedef void *GFX_IMAGE; </pre>
</td>
<td valign="top">This is an opaque type provided to allow
the GFX object to provide whatever is required to
reference a bitmap on the machine.</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct
{
int w;
int h;
int pal[256];
unsigned char *data;
} GFX_BITMAP; </pre>
</td>
<td valign="top">This type represents the bitmap objects
that viDOOM defines. These bitmaps are converted into
GFX_IMAGE prior to use. The fields are: <table border="0"
cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>w</td>
<td valign="top" nowrap>-</td>
<td valign="top">width of bitmap</td>
</tr>
<tr>
<td valign="top" nowrap>h</td>
<td valign="top" nowrap>-</td>
<td valign="top">height of bitmap</td>
</tr>
<tr>
<td valign="top" nowrap>pal[256]</td>
<td valign="top" nowrap>-</td>
<td valign="top">The palette used to define the
bitmap. Each bitmap pixel is an index into this
array of RGB values. Each entry is an integer,
that when represented in hex would define the RGB
triplet as 0xRRGGBB.</td>
</tr>
<tr>
<td valign="top" nowrap>*data</td>
<td valign="top" nowrap>-</td>
<td valign="top">A pointer to the data of the
bitmap. This should be accessed using pointer
arithmetic as *(data+(x)+(y*w))</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct
{
int type;
int shift;
int ctrl;
int alt;
char ascii;
int code;
} GFXKey;</pre>
</td>
<td valign="top">This defines an object for reporting key
presses. The fields are:<table border="0" cellpadding="3"
cellspacing="6">
<tr>
<td valign="top" nowrap>type</td>
<td valign="top" nowrap>-</td>
<td valign="top">The type of event. This field is
just used to line up with the event union defined
later on. Should just hold GFX_KEY_EVENT.</td>
</tr>
<tr>
<td valign="top" nowrap>shift</td>
<td valign="top" nowrap>-</td>
<td valign="top">TRUE if the Shift key is being
pressed.</td>
</tr>
<tr>
<td valign="top" nowrap>ctrl</td>
<td valign="top" nowrap>-</td>
<td valign="top">TRUE if the Control key is being
pressed.</td>
</tr>
<tr>
<td valign="top" nowrap>alt</td>
<td valign="top" nowrap>-</td>
<td valign="top">TRUE if the Alt key is being
pressed.</td>
</tr>
<tr>
<td valign="top" nowrap>ascii</td>
<td valign="top" nowrap>-</td>
<td valign="top">The ASCII code of the character
read. If the key is not an ASCII key (e.g. a
function key) this field should be zero.</td>
</tr>
<tr>
<td valign="top" nowrap>code</td>
<td valign="top" nowrap>-</td>
<td valign="top">Holds the code for non-ASCII
keys, e.g. GFX_F1. This field should be set to
GFX_ASCII for key presses reported through the
ascii field.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct GFXMouse
{
int type;
int shift;
int ctrl;
int alt;
int x;
int y;
int b;
} GFXMouse;</pre>
</td>
<td valign="top">This defines the type for reporting
mouse movements and button presses. The fields are:<table
border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>type</td>
<td valign="top" nowrap>-</td>
<td valign="top">The type of event. This field is
just used to line up with the event union defined
later on. Should just hold GFX_MOUSE_EVENT.</td>
</tr>
<tr>
<td valign="top" nowrap>shift</td>
<td valign="top" nowrap>-</td>
<td valign="top">TRUE if the Shift key is being
pressed.</td>
</tr>
<tr>
<td valign="top" nowrap>ctrl</td>
<td valign="top" nowrap>-</td>
<td valign="top">TRUE if the Control key is being
pressed.</td>
</tr>
<tr>
<td valign="top" nowrap>alt</td>
<td valign="top" nowrap>-</td>
<td valign="top">TRUE if the Alt key is being
pressed.</td>
</tr>
<tr>
<td valign="top" nowrap>x</td>
<td valign="top" nowrap>-</td>
<td valign="top">The X co-ordinate of the mouse,
relative to the top left of the display.</td>
</tr>
<tr>
<td valign="top" nowrap>y</td>
<td valign="top" nowrap>-</td>
<td valign="top">The Y co-ordinate of the mouse,
relative to the top left of the display.</td>
</tr>
<tr>
<td valign="top" nowrap>b</td>
<td valign="top" nowrap>-</td>
<td valign="top">The currently pressed buttons.
This should be made up of a bit mask composed
from GFX_BUTLEFT, GFX_BUTMIDDLE and GFX_BUTRIGHT.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef union GFXEvent
{
int type;
GFXKey key;
GFXMouse mouse;
} GFXEvent;</pre>
</td>
<td valign="top">This defines the type for reporting
events (a combination of both mouse movements or key
presses). The fields are:<table border="0"
cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>type</td>
<td valign="top" nowrap>-</td>
<td valign="top">The type of event. This field is
just used to decide which of the other two fields
should be accessed to get the event information.
This field must be GFX_MOUSE_EVENT or
GFX_KEY_EVENT.</td>
</tr>
<tr>
<td valign="top" nowrap>key</td>
<td valign="top" nowrap>-</td>
<td valign="top">The GFXKey structure defining
the event if this is a GFX_KEY_EVENT.</td>
</tr>
<tr>
<td valign="top" nowrap>mouse</td>
<td valign="top" nowrap>-</td>
<td valign="top">The GFXMouse structure defining
the event if this is a GFX_MOUSE_EVENT.</td>
</tr>
</table>
</td>
</tr>
</table>
<p>The following interfaces must be supplied by the GFX object:</p>
<p><strong><tt>void GFX_init(void)</tt></strong></p>
<blockquote>
<p>Initialises the GFX object. No other GFX interfaces are
called prior to this, with the possible (though current not
used) exception of <strong><tt>GFX_exit()</tt></strong>.</p>
</blockquote>
<p><strong><tt>void GFX_close(void)</tt></strong></p>
<blockquote>
<p>Called when viDOOM is terminating. Note that other (none
system dependent) processing may go on between calling this
and then invoking <strong><tt>exit()</tt></strong> or <strong><tt>return()</tt></strong>.</p>
</blockquote>
<p><strong><tt>GFX_IMAGE GFX_create_image(GFX_BITMAP *bm)</tt></strong></p>
<blockquote>
<p>Should create a GFX_IMAGE from the passed bitmap <em>bm</em>.</p>
</blockquote>
<p><strong><tt>void GFX_destroy_image(GFX_IMAGE img)</tt></strong></p>
<blockquote>
<p>Release the bitmap object pointed to by <em>img</em>.</p>
</blockquote>
<p><strong><tt>void GFX_draw_image(GFX_IMAGE img, int x, int y)</tt></strong></p>
<blockquote>
<p>Draws <em>img</em> with it's top-left co-ordinate
represented by <em>x,y</em>. This function should implement
any necessary clipping when drawing the bitmap.</p>
</blockquote>
<p><strong><tt>void GFX_fill_screen(GFX_IMAGE img)</tt></strong></p>
<blockquote>
<p>Should fill the screen with the image, scaled if
necessary. Note that this call is just used for the main menu
backdrop, so if it cannot be honoured no harm will be done.</p>
</blockquote>
<p><a name="GFX_OPEN"></a><strong><tt>void GFX_open(int width,
int height)</tt></strong></p>
<blockquote>
<p>Opens the display (or window or whatever) with the
specified <em>width</em> and <em>height</em>. Note that
failures in here should terminate the program.</p>
</blockquote>
<p><strong><tt>void GFX_clear(int col)</tt></strong></p>
<blockquote>
<p>This clears the display to the passed colour <em>col</em>.</p>
</blockquote>
<p><strong><tt>void GFX_redraw(void)</tt></strong></p>
<blockquote>
<p>This redraws the contents of the screen. All drawing
operations should not update the actual screen till this is
called (i.e. the display should be buffered).</p>
</blockquote>
<p><strong><tt>void GFX_line(int x1, int y1, int x2, int y2, int
col)</tt></strong></p>
<blockquote>
<p>Draw a line from <em>x1,y1</em> to <em>x2,y2</em> in
colour <em>col</em>.</p>
</blockquote>
<p><strong><tt>void GFX_plot(int x, int y, int col)</tt></strong></p>
<blockquote>
<p>Plot the point <em>x,y</em> in colour <em>col</em>.</p>
</blockquote>
<p><strong><tt>void GFX_circle(int x, int y, int r, int col)<br>
void GFX_fcircle(int x, int y, int r, int col)</tt></strong></p>
<blockquote>
<p>Draw a circle centred on <em>x,y</em> with a radius <em>r</em>
and in colour <em>col</em>. The <strong>fcircle</strong>
version should draw a filled circle.</p>
</blockquote>
<p><strong><tt>void GFX_rect(int x, int y, int w, int h, int col)<br>
void GFX_frect(int x, int y, int w, int h, int col)</tt></strong></p>
<blockquote>
<p>Draw a rectangle with one corner at <em>x,y</em> and the
other corner at <em>(x+w),(y+h)</em> in colour <em>col</em>.
Note that zero length and negative width and heights must be
allowed. The <strong>frect </strong>version should draw a
filled rectangle.</p>
</blockquote>
<p><strong><tt>void GFX_set_XOR_mode(void)<br>
void GFX_clear_XOR_mode(void)</tt></strong></p>
<blockquote>
<p>This should set and clear XOR mode. Normally all GFX
operations should set the pixels to the colour specified, but
when XOR mode is enabled the pixel values should be XORed
into place.</p>
</blockquote>
<p><strong><tt>void GFX_print(int x, int y, int col, char *fmt,
...)</tt></strong></p>
<blockquote>
<p>Print the printf style arguments (<em>fmt</em> and <em>...</em>)
with their top left corner at <em>x,y</em> in colour <em>col</em>.
Note that text should rendered transparently.</p>
</blockquote>
<p><strong><tt>int GFX_fh(void)<br>
int GFX_fw(void)</tt></strong></p>
<blockquote>
<p>Return the height (GFX_fh) and width (GFX_fw) of the fixed
width font used for display purposes.</p>
</blockquote>
<p><strong><tt>int GFX_mouse_buttons(void)</tt></strong></p>
<blockquote>
<p>Returns the number of mouse buttons. This is just used as
check on initialisation as viDOOM expects at least 2 mouse
buttons.</p>
</blockquote>
<p><strong><tt>int GFX_mouse(int *x, int *y)</tt></strong></p>
<blockquote>
<p>Return the current point position in <em>x</em> and <em>y</em>.
If any of the passed pointers are NULL that variable should
be ignored.</p>
</blockquote>
<p><strong><tt>void GFX_waitkey(GFXKEy *key)</tt></strong></p>
<blockquote>
<p>Waits for a <em>key</em> to be pressed and returns the key
press in <em>key</em>. If <em>key</em> is NULL simply wait
for a key press.</p>
</blockquote>
<p><strong><tt>int GFX_key(GFXKey *key)</tt></strong></p>
<blockquote>
<p>Returns TRUE if a key has been pressed and returns the
keypress in <em>key</em>. Returns FALSE if there is no
outstanding keypresses, in which case the contents of <em>key</em>
are undefined.</p>
</blockquote>
<p><strong><tt>void GFX_bounce(void)</tt></strong></p>
<blockquote>
<p>Waits for all keys and mouse buttons to be released. On a
real event-driven system could be ignored, or flush any
outstanding events.</p>
</blockquote>
<p><strong><tt>void GFX_await_input(GFXEvent *ev)</tt></strong></p>
<blockquote>
<p>Waits for either a keypress or a mouse button to be
pressed and fills in <em>ev</em> accordingly.</p>
</blockquote>
<p><strong><tt>void GFX_await_input_full(GFXEvent *ev)</tt></strong></p>
<blockquote>
<p>Waits for either a keypress, a mouse button to be pressed
or the mouse to be moved and fills in <em>ev</em>
accordingly.</p>
</blockquote>
<p><strong><tt>void GFX_exit(int code, char *fmt, ...)</tt></strong></p>
<blockquote>
<p>This call should do any necessary tidying of the display
(switching from graphics mode, closing windows, whatever)
then display the printf style arguments (<em>fmt</em> and <em>...</em>)
and the exit with the passed return <em>code</em>.</p>
</blockquote>
<p><strong><tt>void GFX_save_screen(char *path)</tt></strong></p>
<blockquote>
<p>This call need not be supported. It just allows screen
grabs to be captured when viDOOM is compiled with debug
information. If supported it should just save a bitmap in the
file pointed to by <em>path</em>.</p>
</blockquote>
<hr>
<h2><a name="PLATGUI_H"></a>Platform GUI</h2>
<p><strong><u>platgui.c</u></strong></p>
<p>This provides access to the platform's GUI routines.</p>
<p>The following types are defined and used by the PLATGUI object
:</p>
<table border="1" cellpadding="3">
<tr>
<td valign="top" nowrap><pre>typedef struct
{
char *text;
GFX_IMAGE img;
int client_index;
} PLAT_IMG_PICKLIST;</pre>
</td>
<td valign="top">This structure is used to define a
picklist that has graphical images and client defined
values attached to them. This is used for selection of
textures, flats and sprites (things) in viDOOM.<p>The
fields in the structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">This defines the text for a
picklist entry. NULL marks the end of the list of
picklist entries.</td>
</tr>
<tr>
<td valign="top" nowrap>img</td>
<td valign="top" nowrap>-</td>
<td valign="top">The GFX_IMAGE to associate with
this entry. Can be NULL to indicate show no
image.</td>
</tr>
<tr>
<td valign="top" nowrap>client_index</td>
<td valign="top" nowrap>-</td>
<td valign="top">The value returned if this item
is selected.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct
{
char *text;
int client_index;
} PLAT_PICKLIST;</pre>
</td>
<td valign="top">This structure is used to define a
picklist that has client defined values attached to the
entries.<p>The fields in the structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">This defines the text for a
picklist entry. NULL marks the end of the list of
picklist entries.</td>
</tr>
<tr>
<td valign="top" nowrap>client_index</td>
<td valign="top" nowrap>-</td>
<td valign="top">The value returned if this item
is selected.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct PLATMENU
{
char *text;
int client_index;
struct PLATMENU *child;
} PLAT_MENU;</pre>
</td>
<td valign="top">This structure is used to define menu
entries that have client defined values attached to them.<p>The
fields in the structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">This defines the text for the
menu entry. NULL marks the end of the list of
menu entries.</td>
</tr>
<tr>
<td valign="top" nowrap>client_index</td>
<td valign="top" nowrap>-</td>
<td valign="top">The value returned if this item
is selected. If the child field is not NULL, this
field is ignored.</td>
</tr>
<tr>
<td valign="top" nowrap>child</td>
<td valign="top" nowrap>-</td>
<td valign="top">If not NULL points to a further
array of PLAT_MENU objects defining a child menu.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct
{
char *text;
int group;
int val;
} PLAT_MULTI;
</pre>
</td>
<td valign="top">This structure is used to entries for
the multi box call. A multi box is a dialog that holds a
mixture of radio buttons and check boxes.<p>The fields in
the structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">This defines the text for the
multio box entry. NULL marks the end of the list
of entries.</td>
</tr>
<tr>
<td valign="top" nowrap>group</td>
<td valign="top" nowrap>-</td>
<td valign="top">The group this entry belongs to.
Group zero means that it is a check box and can
be checked/unchecked independently of other
entries. Entries in the same group should act as
radio buttons in that group.</td>
</tr>
<tr>
<td valign="top" nowrap>val</td>
<td valign="top" nowrap>-</td>
<td valign="top">The state of the check box/radio
button. TRUE means that it's set, FALSE means
it's clear. These fields are updated on exit once
the multo box is completed.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct
{
char *text;
int client_index;
} PLAT_RADIO;</pre>
</td>
<td valign="top">This structure is used to define entries
for a radio style picklist (i.e. where only one option
can be chosen) that have client defined values attached
to them.<p>The fields in the structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">This defines the text for the
radio button. NULL marks the end of the list of
radio button entries.</td>
</tr>
<tr>
<td valign="top" nowrap>client_index</td>
<td valign="top" nowrap>-</td>
<td valign="top">The value returned if this item
is selected.</td>
</tr>
</table>
</td>
</tr>
<tr>
<td valign="top" nowrap><pre>typedef struct
{
int no;
int current;
char **text;
} PLAT_DIAL_PL;</pre>
<pre>typedef struct
{
char *text;
int type;
union /* Data */
{
int i;
char s[PLAT_DIAL_MAXSTRLEN+1];
double d;
PLAT_DIAL_PL pl;
} data;
} PLAT_DIALOG;
</pre>
</td>
<td valign="top">These structures are used to define
entries for a simple dialog.<p>The fields in the
PLAT_DIAL_PL structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>no</td>
<td valign="top" nowrap>-</td>
<td valign="top">The number of elements pointed
to by text.</td>
</tr>
<tr>
<td valign="top" nowrap>current</td>
<td valign="top" nowrap>-</td>
<td valign="top">The currently selected item in
the picklist. This is updated on exit if the
dialog is accepted.</td>
</tr>
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">The text for the picklist
entries. This is treated as an array of character
pointers.</td>
</tr>
</table>
<p>The fields in the PLAT_DIALOG structure are:</p>
<table border="0" cellpadding="3" cellspacing="6">
<tr>
<td valign="top" nowrap>text</td>
<td valign="top" nowrap>-</td>
<td valign="top">This defines the text for this
field in the dialog. NULL marks the end of the
list of dialog entries.</td>
</tr>
<tr>
<td valign="top" nowrap>type</td>
<td valign="top" nowrap>-</td>
<td valign="top">The type of field this is.
Possible values are PLAT_DIAL_STRING,
PLAT_DIAL_INTEGER, PLAT_DIAL_DOUBLE and
PLAT_DIAL_PICKLIST.</td>
</tr>
<tr>
<td valign="top" nowrap>data.i</td>
<td valign="top" nowrap>-</td>
<td valign="top">This is the field that is
displayed and updated on exit if the type is
PLAT_DIAL_INTEGER.</td>
</tr>
<tr>
<td valign="top" nowrap>data.s</td>
<td valign="top" nowrap>-</td>
<td valign="top">This is the field that is
displayed and updated on exit if the type is
PLAT_DIAL_STRING.</td>
</tr>
<tr>
<td valign="top" nowrap>data.d</td>
<td valign="top" nowrap>-</td>
<td valign="top">This is the field that is
displayed and updated on exit if the type is
PLAT_DIAL_DOUBLE.</td>
</tr>
<tr>
<td valign="top" nowrap>data.pl</td>
<td valign="top" nowrap>-</td>
<td valign="top">This is the structure that
defines how a PLAT_DIAL_PICKLIST is displayed.
The current field in this is updated if the
selected picklist value changes.</td>
</tr>
</table>
</td>
</tr>
</table>
<p>Note that along with the types, the following predefined
values are set (these are read from the INI file). Note that they
should be considered to be unset until immediately prior to
viDOOM's call to <strong><tt>GUI_setscreen()</tt></strong>:</p>
<table border="1" cellpadding="3">
<tr>
<td valign="top" nowrap><strong>GUI_HI</strong></td>
<td valign="top">The brightest colour used to draw the 3D
looking interface.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>GUI_MID</strong></td>
<td valign="top">The medium colour used to draw the 3D
looking interface.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>GUI_LO</strong></td>
<td valign="top">The darkest colour used to draw the 3D
looking interface.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>GUI_TEXT</strong></td>
<td valign="top">The colour of text.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>GUI_TEXTSHADOW</strong></td>
<td valign="top">The colour of the shadow behind text.
This is only really used by viDOOM's own portable GUI
routines.</td>
</tr>
<tr>
<td valign="top" nowrap><strong>GUI_BOLD</strong></td>
<td valign="top">The colour of bold text (used for
titles).</td>
</tr>
</table>
<h3>Functions</h3>
<p>The following interfaces are defined by the PLATGUI object.
Note that all these calls are assumed to not destroy screen
contents (ie. the screen should be restored after displaying the
GUI object):</p>
<p><strong><tt>void GUI_setscreen(int width, int height)</tt></strong></p>
<blockquote>
<p>Once the display has been opened with <a href="#GFX_OPEN"><strong>GFX_open()</strong></a>
then this is called to inform the platform's GUI routines of
the display size.</p>
</blockquote>
<p><strong><tt>int GUI_yesno(char *question)</tt></strong></p>
<blockquote>
<p>Display an alert with <em>question</em> in it and <em>Yes</em>
and <em>No</em> buttons. Returns TRUE if <em>Yes</em> is
pressed and FALSE if <em>No</em> is pressed.</p>
</blockquote>
<p><strong><tt>int GUI_yesno_all(char *question)</tt></strong></p>
<blockquote>
<p>Works like <strong>GUI_yesno()</strong>, but displays to
extra options - "Yes to All" and "No to
All". If either of these options are selected then
further calls to this function should return TRUE/FALSE
accordingly, until <strong>GUI_start_yesno__all()</strong> is
called.</p>
</blockquote>
<p><strong><tt>int GUI_start_yesno_all(void);</tt></strong></p>
<blockquote>
<p>Resets <strong>GUI_yesno_all()</strong>.</p>
</blockquote>
<p><strong><tt>int GUI_alert(char *title, char *text, char
*button_text)</tt></strong></p>
<blockquote>
<p>Display an alert with a title of <em>title</em>,
containing <em>text</em> as the message and with a single
button labelled <em>button_text</em>. Note that text is split
into multiple lines by the pipe (|) character.</p>
</blockquote>
<p><strong><tt>int GUI_menu(char *title, int x, int y, PLAT_MENU
menu[], int defval)</tt></strong></p>
<blockquote>
<p>Displays a menu with title <em>title</em> at position <em>x,y</em>.
The displayed items are taken from <em>menu</em>. The return
is the client_index field from the selected menu item, or
from the selected option in a child menu, or <em>defval</em>
if the menu is cancelled.</p>
</blockquote>
<p><strong><tt>char *GUI_fsel(char *title, char *default_path,
char filter)</tt></strong></p>
<blockquote>
<p>Allows a file to be selected. The file selector should
have <em>title</em> for it's title and start selecting from
the <em>default_path</em>. If <em>filter </em>is NULL then
all files should be displayed, otherwise only files ending in
<em>filter</em>.</p>
<p>The return is NULL if the selector is cancelled. Otherwise
a pointer is returned containing the fully qualified path of
the selected file. This pointer must be dynamically allocated
and will be freed using <a href="#FRELEASE"><strong>FRelease()</strong></a>.</p>
</blockquote>
<p><strong><tt>int GUI_picklist(char *title, char *opts[])</tt></strong></p>
<blockquote>
<p>Displays a picklist with title <em>title</em>. The options
are taken from the array of character pointers <em>opts</em>.
The return value is the index of the selected item in <em>opts</em>
if selected, or -1 if the picklist is cancelled.</p>
</blockquote>
<p><strong><tt>int GUI_client_picklist(char *title, PLAT_PICKLIST
opts[], int defval)</tt></strong></p>
<blockquote>
<p>Displays a picklist with title <em>title</em>. The text
items to display are taken from <em>opts</em>. The return is
the client_index field from the selected picklist item, or <em>defval</em>
if the picklist is cancelled.</p>
</blockquote>
<p><strong><tt>int GUI_image_picklist(char *title,
PLAT_IMG_PICKLIST opts[], int defval)</tt></strong></p>
<blockquote>
<p>Displays a picklist with title <em>title</em>. The text
items and associated image to display are taken from <em>opts</em>.
The return is the client_index field from the selected
picklist item, or <em>defval</em> if the picklist is
cancelled.</p>
</blockquote>
<p><strong><tt>int GUI_radio_box(char *title, PLAT_RADIO opts[],
int current, int defval)</tt></strong></p>
<blockquote>
<p>Displays a dialog containing radio buttons with title <em>title</em>.
The text to display is taken from <em>opts</em>. The selected
object when the the radio box is first displayed is the
option who's client_index field matches <em>current</em> (or
the first item if there is no match). The return is the
client_index field from the selected radio button, or <em>defval</em>
if the radio box is cancelled.</p>
</blockquote>
<p><strong><tt>int GUI_multi_box(char *title, PLAT_MULTI opts[])</tt></strong></p>
<blockquote>
<p>Display a mutli-selection radio box. The items are
described <em>opts</em>. The return is TRUE if the dialog is
accepted, otherwise FALSE.</p>
</blockquote>
<p><strong><tt>int GUI_dialog(char *title, int no, PLAT_DIALOG
dial[])</tt></strong></p>
<blockquote>
<p>Displays a dialog with the title <em>title</em>. The
fields for the dialog are extracted from <em>dial</em>, for
which there is expected to be <em>no</em> elements. The
return is TRUE if the dialog is accepted, or FALSE if it is
cancelled. On being cancelled the contents of the data union
within the <em>dial</em> elements is undefined.</p>
</blockquote>
<p><strong><tt>void GUI_file_view(char *title, char *file)</tt></strong></p>
<blockquote>
<p>Displays the contents of a text file, allowing the user to
move around and view the file. What form this takes is no
concern at all to viDOOM.</p>
<p>If is assumed this can view both DOS format (lines
terminated with CR and LF) and UNIX format text files (lines
terminated with LF).</p>
</blockquote>
<p><strong><tt>char *GUI_text_edit(char *title, char *text)</tt></strong></p>
<blockquote>
<p>Allows simple text editting. The form this display takes
is of noconcern to viDOOM (if applicable it would be more
than OK to start an external text editor). <em>text </em>is a
pointer to the original text, which is one long string with
line breaks denoted by the '\n' character.</p>
<p>The return is a newly allocated copy of the edited text is
the text is OKed, or NULL if the text is cancelled. In either
case, the original string pointed to by text should be as it
was.</p>
</blockquote>
<hr>
<h2><a name="FILE_H"></a>File interface</h2>
<p><strong><u>file.c</u></strong></p>
<p>This provides access to various file system functions and also
provides some filename manipulation routines. The following
interfaces should be provided:</p>
<p><strong><tt>char *Pwd(void)</tt></strong></p>
<blockquote>
<p>This call should return the current working directory. The
return should be static.</p>
</blockquote>
<p><strong><tt>void Cd(char *path)</tt></strong></p>
<blockquote>
<p>This call should change the current working directory to <em>path</em>.</p>
</blockquote>
<p><strong><tt>char *Dirname(char *path)</tt></strong></p>
<blockquote>
<p>This call should return the directory part of <em>path</em>
if any. The return should be static.</p>
</blockquote>
<p><strong><tt>char *Basename(char *path)</tt></strong></p>
<blockquote>
<p>This call should return the filename part of <em>path</em>.
The return should be static, or a pointer into the <em>path</em>
parameter.</p>
</blockquote>
<p><strong><tt>int FileExists(char *path)</tt></strong></p>
<blockquote>
<p>This call should return TRUE if the file pointed to by <em>path</em>
exists.</p>
</blockquote>
<p><strong><tt>int FilenamesEqual(char *path1, char *path2)</tt></strong></p>
<blockquote>
<p>This call should return TRUE if the file pointed to by <em>path1</em>
and <em>path2</em> are the same file. At it's most basic
(e.g. like in the DOS port) it can simply makes sure that
directory separators are in the same form and then does <strong>strcasecmp()</strong>
on the paths.</p>
</blockquote>
<hr>
<h2><a name="MEM_H"></a>Memory allocation</h2>
<p><strong><u>mem.c</u></strong></p>
<p>This provides memory allocation. While memory allocation can
generally be done portably using <tt>malloc()</tt> providing this
library just covers for any possible OS dependent twist. Also
these routines are expected to handle errors internally. In all
the interfaces <em>file</em> and <em>line</em> parameters are
included so that errors can be reported more accurately.</p>
<p>The following interfaces should be provided:</p>
<p><strong><tt>void *FGrab (char *file, int line, int len)</tt></strong></p>
<blockquote>
<p>This call should allocate <em>len</em> bytes and return a
pointer to it. A <em>len</em> of zero is valid. Memory should
be initialised to zero. Failure to allocate the memory should
terminate the program.</p>
</blockquote>
<p><strong><tt>void *FReGrab (char *file, int line, void *ptr,
int len)</tt></strong></p>
<blockquote>
<p>This call should re-allocate the memory pointed to by <em>ptr</em>
and return a new memory area of <em>len</em> bytes. The
original data pointed to by <em>ptr</em> should be copied to
the new memory area. Failure to allocate the memory should
terminate the program.</p>
</blockquote>
<p><strong><tt>char *FStrdup (char *file, int line, char *str)</tt></strong></p>
<blockquote>
<p>This call should allocate enough bytes to copy the nul
terminated <em>str</em> to it. The returned pointer should
point to the new copy of <em>str</em>.<em> </em>Failure to
allocate the memory should terminate the program.</p>
</blockquote>
<p><strong><tt>void *FCopy (char *file, int line, void *ptr, int
len)</tt></strong></p>
<blockquote>
<p>This call should allocate <em>len</em> bytes and copy <em>len</em>
bytes from <em>ptr</em> into the new area. The newly
allocated memory should be returned. Failure to allocate the
memory should terminate the program.</p>
</blockquote>
<p><a name="FRELEASE"></a><strong><tt>void FRelease (char *file,
int line, void *ptr)</tt></strong></p>
<blockquote>
<p>This call should release the memory pointed to by <em>ptr</em>,
which will have been allocated by FGrab, FReGrab, FStrdup or
FCopy.</p>
</blockquote>
<hr>
<h2><a name="RUNCMD_H"></a>External command execution</h2>
<p><strong><u>runcmd.c</u></strong></p>
<p>Provides a mechanism to run an external command. The following
interfaces should be provided:</p>
<p><strong><tt>int RunCommand(char *argv[], char *path)</tt></strong></p>
<blockquote>
<p>Run a command. The output from the command (if there is
any) should NOT disturb the screen contents. The call should
return TRUE if the call succeeds, FALSE otherwise.</p>
<p>The <em>argv</em> list is an array of pointers to various
sections of the command and it's arguments, terminated with a
NULL pointer. Note that arguments may contain more than one
argument in each line - the actual command is described
simply by concatenating all the pointers together, eg.</p>
<p><tt>argv[0]="bsp"<br>
argv[1]="file.wad"<br>
argv[2]="-o file.wad"<br>
argv[3]=NULL</tt></p>
<p>The <em>path</em> argument is a place to copy the path to
a file where the output from the command has been stored. If
this is not supported then the empty string should be
assigned to it. viDOOM will <tt>remove()</tt> the file after
it has read it.</p>
</blockquote>
<hr>
<h2><a name="VSTRING_H"></a>Portable String routines</h2>
<p><strong><u>vstring.c</u></strong></p>
<p>Provides common string functions that are not actually part of
the ANSI standard. While these can easily be portably written,
they are provided as functions in case local implementations
supply them (which will probably more effecient):</p>
<p><strong><tt>int StrCaseCmp(char *a, char *b)</tt></strong></p>
<blockquote>
<p>Performs in exactly the same way as the ANSI <tt>strcmp()</tt>
function, save for the fact that the case of the strings
being compared is ignored.</p>
</blockquote>
<p><strong><tt>int StrNCaseCmp(char *a, char *b)</tt></strong></p>
<blockquote>
<p>Performs in exactly the same way as the ANSI <tt>strncmp()</tt>
function, save for the fact that the case of the strings
being compared is ignored.</p>
</blockquote>
<hr>
<h2><a name="INSTALLATION"></a>Installation script</h2>
<p>Each platform should provide a makefile called <strong>install</strong>.
This is invoked from the top level makefile like this:</p>
<blockquote>
<p><tt>cd $(PLATFORM) ; $(MAKEINSTALL)</tt></p>
</blockquote>
<p>Note that the install makefile will be invoked with the <a
href="#PLATFORMVAR">PLATFORM</a> directory as the current working
directory.</p>
<p>The following files must be copied (where $SRC represents the
source build directory and $INSTALLDIR the install directory):</p>
<table border="1" cellpadding="3">
<tr>
<td valign="top" nowrap><tt>$SRC/vidoom</tt></td>
<td valign="top"><tt>$INSTALLDIR/vidoom</tt><p>Note that
this file may have a system specific extension (e.g. .EXE
in DOS)</p>
</td>
</tr>
<tr>
<td valign="top" nowrap><tt>$SRC/LICENSE</tt></td>
<td valign="top"><tt>$INSTALLDIR/LICENSE</tt><p>The GNU
GPL should be copied into the installation directory so
that binary distributions can be easily generated with
the license included and so that the LICENSE can be
viewed from viDOOM's main menu.</p>
</td>
</tr>
<tr>
<td valign="top" nowrap><tt>$SRC/base.ini</tt></td>
<td valign="top"><tt>$INSTALLDIR/vidoom.ini</tt></td>
</tr>
<tr>
<td valign="top" nowrap><tt>$SRC/*.cfg</tt></td>
<td valign="top"><tt>$INSTALLDIR/*.cfg</tt></td>
</tr>
<tr>
<td valign="top" nowrap><tt>$SRC/doc/*.htm</tt></td>
<td valign="top"><tt>$INSTALLDIR/doc/*.htm</tt></td>
</tr>
<tr>
<td valign="top" nowrap><tt>$SRC/doc/*.gif</tt></td>
<td valign="top"><tt>$INSTALLDIR/doc/*.gif</tt></td>
</tr>
</table>
<p>Note that, obviously, any OS specific files should also be
copied.</p>
<hr>
<h2><a name="DOCUMENTATION"></a>Documentation</h2>
<p>If you release a port of viDOOM to any platform please update <a
href="bugs.htm#CONTACTS">doc/bugs.htm</a> with a contact address
for problems on that platform. Also include a link to a system
specific HTML document detailing how the GUI works and any know
bugs, from <a href="sys.htm">doc/sys.htm</a>.</p>
<p>For an example look at the <a href="djgpp.htm">DJGPP</a>
documentation. As you can see, it doesn't have to be too big.</p>
<hr>
<p><a href="index.htm">Back to index</a></p>
<p><tt>$Id$</tt></p>
</body>
</html>
|
