forked from Ericson2314/Voxlap
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathreadme.txt
472 lines (390 loc) · 23.4 KB
/
readme.txt
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
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Porting Notes by Ericson2314
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Making Ken Silverman's "Voxlap" voxel graphics engine run on any platform
with SDL and C++.
------------------------------------------------------------------------------
Build Prerequisites:
Build Tools:
Option 1
MSVS utilities (nmake, ml, cl)
Windows SDK (libs)
Option 2
MinGW/GCC
Nasm in %MinGW%/bin
Graphics
Option 1
DirectX SDK (libs)
Option 2
SDL DEV-MinGW/GCC and RUNTIME (libs)
------------------------------------------------------------------------------
Guide to the various branches (they don't all exist yet)
I used to have an outline of things to do. But it became horrendously out of
date. This should serve the same purpose, and actually reflects what I want to
do. Keep in mind that to some extent all branches are developed
simultaneously.
Conservative: This is what master is now. In short, every block of MSVC inline
asm has a block of gcc inline asm to go with it. Nothing else semantically
should be changed. I doubt this will work, as sometimes Voxlap used persistent
registers.
no_fatbin: Currently Voxlap actually contains both SSE2 and 3DN
inline assembly, and uses some run-time stuff to chose which routines to use.
This is really weird, and makes replacing with C slightly more complicated as
some functions like "movps_3dn" are no longer used. I should remove the
"cputype" routine, and make the choice of architecture compliantly compile
time. This should be rebased off conservative. ("Fatbin" reffers to the fact
that cputype is used to compile something analogous to a fat binary.)
no_asm: This is no_asm, a rush to get something that works and also uses as
little compiler-specific code as possible. I have used ken's C alternatives
even when vector built-ins would be more efficient, or said alternatives don't
even work right (kv6draw). all the point4d vector arithmetic functions should
be moved to a separate header. This should be rebased off no_fatbin.
SIMD: This is where I want to end up. This will be completely architecture
independent. Pure C is used where appropriate, but if something is better done
with SIMD/vector built-ins I use those instead. By the time I get to this,
no_asm should be bug free. And if I haven’t bothered to redo v5.?asm in no_asm,
I should re-do it now with vector-built-ins. Probably a lot of the little
inline functions used for assembly can be manual inlined and discarded at this
point. I may drop MSVC support here, as I don't really want to have to redo all
the SIMD stuff for two compilers. Also I might do the minimal pre-processor
stuff needed to allow for building as Pure C if I have not done so already
(this involves making a few static struct members into global variables, so it
will change the API). This should be rebased off no_fatbin, not no_asm.
------------------------------------------------------------------------------
Introduction:
So, the basic idea is to get Ken Silverman's Voxlap voxel graphics engine to
run on just about any platform that supports C++ and SDL (DirectX is
still kept operational for windows). This all boils down to 2 fundamental
things: getting the code to compile in GCC, and making sure that now windows
libraries are in use.
Compiler issues:
The compiler part is pretty easy, except for one thing: the assembly code.
Voxlap uses both a single file of routines in assembly, and copious
amounts of inline assembly within it's C++ files. Now, most of this assembly
should be perfectly portable, but every compiler collection has a different
format for both external and internal assembly.
I say format, because converting from one to another is a fairly trivial task,
but not quite trivial enough where I can confidently do it with my limited
assembly knowledge in an error-free manor. I have tried various scripts to
convert assembly (inline and external), but the bottom line is that I don't
really trust them. Most significantly, v5.asm's nasm port won't work with MSVC
(though it should), so why should I trust it with GCC? Dealing with the inline
assembly is even simpler, but the conversion tools are correspondingly more
primitive, and I can't test them anyways until v5.asm works.
Therefore I HAD opted to dispense with assembly code altogether. Voxlap5 (the
main Voxlap code) is littered with commented out replacement C for various
assembly routines. Not all of it works as well as the assembly -- I think Ken
mainly used it as a guide for writing the assembly and didnt debug it as
the program evolved -- but its certainly better than nothing. As to the
external assembly, there is a macro thats supposed to let the program run
without it, but it leaves in a few missing linkages -- it was probably also
ignored as the program evolved. For better or worse, the inline assembly and
external assembly often relies on each other. On one hand, this means taking
out one can help get rid of the other. On the other hand, it means its
very difficult to replace the assembly incrementally and debug as you go.
I learned of another assembly, JWASM, on IRC which is both cross-platform and
Supports NASM syntax as close as possible. This gave me the opportunity to go
back to my original plan of porting all the assembly. This of course came with
the added benefit of leaving the original program as intact as possible, and
utilizing the inline assembly that was admittedly still faster than the C. For
ARM ports it will still have to go but this seems to be the easier solution
for now. Now my plan is to work along both methods. I don't know whether
converting or removing inline assembly will get to a finished port faster, so
I've made a git branch for each method to work on both concurrently.
I was able to quickly fix the few syntax errors that existed, and get a
working Game.exe with MSVC and JWASM. But JWASM in itself did nothing to
prevent the link errors with MSVC external assembly together is often made
easier. The cacophony of link errors, was a bit hard to decipher, and in order
to better separate assembly-caused linking errors from other issues, I decided
to get the whole thing to be compiled as C. C, unlike C++, has no name
mangling, and in addition C-derived objects files made by different compilers
have a better chance of linking correctly (especially on windows). I figured
this would open up new doors testing.
I now have everything compiling and linking on Windows and Linux, MSVC and
gcc, and SDL on both platforms. Unfortunately however, when running a gcc
build on any platform some text is displayed on the screen. When I don't use
the -ffast-math flag, it will in addition crash due to arithmetic overflows.
Because this is thus strictly a compiler-caused issue, my guess is there is
still some mistake in the inline-assembly I converted to C. It is now clear to
me that in order to get this working, I will have to remove all inline
assembly. Because in many cases the C is less efficient, I will try to add it
back in after I have fixed most bugs. But the only way to rigorously cross-
reference the MSVC and gcc builds/bugs, I must avoid as much compiler-specific
syntax as I can. I imagine once I reach the point where it is safe to again
experiment with assembly, asm and no-asm versions will be developed with some
independence, and the benchmarks will state which branch to focus on.
Library issues:
I can't really dive into this until the former step is complete, but it seems
that again a good bit of the work is already done.
Voxlap itself is a surprisingly self-contained beast, primary because its
a software render so it only uses DirectX to copy frame buffers and other
trivial stuff. The backend it currently uses Winmain, is not Voxlap-Specific,
but rather used by a couple of Kens things (maybe even the build engine).
On the flip side, the example game, and probably other games based around
Voxlap dont just use voxlaps header, but also directly use Sysmain.h,
Winmains interface. So to have a genuinely useful Voxlap port, seemingly
unused features of Sysmain.h must also be ported.
Thankfully, available on Kens site is SDLmain, a non-Voxlap-Specific
port of Winmain. Im not sure how complete it is, but Id hope it has
the most basic stuff that Voxlap itself requires available. The more progress
I've made, the more I been able to validate the SDLmain basically works as
advertised. Now that I have the Voxlap building with SDLmain and MSVC, I am
almost sure it will hardly need modification.
The other example programs besides 'game' use some GDI and other Windows-
specific APIs not abstracted in Winmain, so I will not focus on porting them
for the time being. I did recently however add Slab6 to my code base, as it
shares both Winmain code that later ended up in Voxlap. To fully incorporate
it I will need to deal with these other windows dependencies, so doing so is
definitely on the agenda.
------------------------------------------------------------------------------
What Next:
A true port should change as little of the old program as possible in order to
maintain maximal compatibility. At the same time, porting is a perfect time to
introduce deep architectural changes into a program. I believe a few obvious
improvements that would not effect existing programs ability to interface with
Voxlap to much extent.
Voxlap is a library, nothing more, nothing less. As such it should be able to
be both statically and dynamically linked with another program. Currently,
only static linking is tested to work, but with a couple trivial changes,
dynamic linking should be too.
Voxlap is C++, but in name only. In practice it contains little-to-none
Object-Oriented components, and only a few C++ idiosyncrasies prevent it from
being compiled as C. In fact, it even contains a couple of preprocessor
conditionals to test for C or C++ completion. Ideally it should fully support
being compiled as C or C++ in order to work in many situations.
------------------------------------------------------------------------------
License:
Based on my concept of a true port I should keep the license the same
as the original: basically attribution + non-commercial only without Ken
Silvermans explicit permission. I previously stated here my work could be
licensed with the LGPL provided Ken's restrictions are also followed, but I
now see that is not possible due to the GPL's requirement that commercial
distribution *must* be permitted.
As before, Ken's licensing restrictions must be obeyed. If obtains
permission to use Ken's code under different terms, he or she must also
contact me and obtain permission if they want to use my modifications.
------------------------------------------------------------------------------
Acknowledgements:
Freenode IRC network: It about as indispensable a resource as exists for
programming these days. #C and especially #asm in particular for this project.
Many people on the network offered excellent advice, and copious amounts of
patience and time, but I'd especially like to thank:
- vulture: (on #asm) for helping me get v5 to change memory permissions on
Linux for the sake of self-modifying code.
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
[Original] Voxlap engine notes by Ken Silverman (http://advsys.net/ken)
=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
Introduction:
The Voxlap engine includes all the tools you need to create your own game
using a high-speed software voxel engine. I have included 4 applications:
* GAME: An unfinished sample game
* SIMPLE: Minimalist application code to help get you started.
* VOXED: My voxel world editor
* KWALK: My voxel model animation editor
I compiled the code with Microsoft Visual C/C++ 6.0. It should work with later
versions of Visual C. If you don't have a copy of MSVC, you can download the
VC 2003 Toolkit from Microsoft. (See note in requirements).
After unzipping, the first thing you should do is look at this file :) First,
I'll describe my way of compiling. I like to compile at the command line. To
set up your VC environment, run VCVARS32.BAT (as described at the top of
MAKESTUF.BAT) Then in MAKESTUF.BAT, check to make sure your directories are
set up correctly. Make sure your environment variables (lib and include)
point to the right path. You'll need them to point to the Visual C directories
as well as the directories from the DirectX SDK. Once this is done, you are
ready to run MAKESTUF.BAT. I put an in-line makefile at the top of each source
file. This is why there is no "makefile" in the directory. Cool trick, eh?
You can compile the examples from the VC GUI environment as well, but you'll
need to create your own project if you do so. Here are some hints on setting it
up to compile Voxlap:
* Be sure to specify these non-default compiler settings:
/J default char type is unsigned
/TP compile all files as .cpp (I incorrectly use .c to save typing :)
* Add these libraries to your linker settings:
ddraw.lib
dinput.lib
dxguid.lib
* To compile V5.ASM, you'll need an assembler. I use MASM. I'm not quite
sure how to set this up in the VC environment. To make things easier,
I included V5.OBJ. You can add this to your project if you have
trouble assembling V5.ASM.
To compile with VC Toolkit 2003:
* Change the linker option: /MD to /ML
(see top of GAME.C, SIMPLE.C, VOXED.C, KWALK.C)
* To fix the "MSVCRT.LIB not found" error, in WINMAIN.CPP, change:
#define USETHREADS 20
To:
#define USETHREADS 0
-Ken S.
------------------------------------------------------------------------------
Requirements:
CPU: Pentium III, Athlon, or above
System memory: 128MB RAM or above
Graphics card: Any old piece of junk should be fine :)
OS: Microsoft Windows 98/ME/2K/XP
DirectX 8.0 or above
Compiler: Microsoft Visual C/C++ 6.0 or above.
NOTE: WINMAIN.CPP uses SSE or 3DNow! instructions, so if you are compiling
with VC6, you will need to install the Processor Pack (VCPP.ZIP). VCPP
will only install over VC6 SP5 Professional edition, although I have had
some success in fooling the installation program :) Fortunately, this is
not an issue with VC7. You can also download a "free" version of the VC
compiler: google for "c++ toolkit 2003". Unfortunately, it's missing a few
files, such as WINDOWS.H and NMAKE.EXE, but they can be found elsewhere -
either from the Platform SDK, or by googling for them.
------------------------------------------------------------------------------
File description:
MAKESTUF.BAT: Quick&dirty batch file showing how to compile things at the
command prompt.
SIMPLE.C: Minimalist sample code showing how to interface Voxlap. Study this
code before looking at GAME.C. It should also be easier to start a new
project from this code.
GAME.*: A big ugly testing ground for many Voxlap features. Think of this
as the example code for most functions in VOXLIB.TXT.
VOXLAP5.H: Include file for VOXLAP5.C, V5.ASM, KPLIB.C
VOXLAP5.C: Voxlap engine C routines
V5.*: Voxlap engine assembler routines
KPLIB.C: Ken's Picture LIBrary. Decoding for: PNG,JPG,GIF,TGA,BMP,PCX and ZIP.
This library can be used independently from the engine. Voxlap depends on
this library for various functions.
WINMAIN.CPP: Windows layer (setup screen, sound, input). This code is
independent of Voxlap and can be replaced if you want to use your own
windows layer, such as SDL. I've been maintaining WINMAIN.CPP for years, so
it is rather stable now.
SYSMAIN.H: Include file for my windows layer (WINMAIN)
VOXDATA.ZIP: Game data. You do not need to extract this data to run GAME.EXE,
SIMPLE.EXE, or VOXED.EXE. You will need to extract it to select models for
loading in KWALK though.
VOXED.*: My VXL voxel editor. I made UNTITLED.VXL using VOXED. There are a lot
of keys to learn - so have patience. As a convenience, you can view the
help file (VOXEDHLP.TXT) inside the editor by pressing F1.
KWALK.*: An animation editor for .KV6 voxel sprites using .KFA animations.
You'll need to extract files from VOXDATA.ZIP to see my example models.
VXLFORM.TXT: Description of the VXL format
KWALKHLP.TXT: Help file for KWALK
VOXEDHLP.TXT: Help file for VOXED
VOXLIB.TXT: Help file for VOXLAP5, KPLIB, and WINMAIN.
README.TXT: This help file
------------------------------------------------------------------------------
GAME.EXE information:
Command line options:
/win Run in a window
/3dn Force 3DNow! code. Crashes if not Athlon series.
/sse Force Pentium III code. Crashes if not P3+/AthXP+!
/sse2 Force Pentium 4 code (ignored currently)
/#x#x# Specify resolution. Max resolution is 1024x768
In-game controls:
ESC Quit
Arrows Move forward/backward/left/right
Rt.Ctrl Move up
KP0 Move down
Lt.Shift Move 16 times slower
Rt.Shift Move 16 times faster
1,2,3,4 Select weapon
Lt.Ctrl/Lt.Mouse button Shoot weapon
Space/Rt.Mouse button Activate object (open/close door for example)
` Change animation of female character. Try it! :)
PrintScreen Capture screen to uncompressed PNG file.
Ctrl+PrintScreen Capture panorama to uncompressed PNG file. Slow!
(compatible with KUBE/KUBEGL)
KP-/+ Decrease/increase sound volume
F1 Play a 3D looping sound (tries to load
"wav/airshoot.wav" but fails since not included
in VOXDATA.ZIP)
F2 Stop least recently started looping sound
KP Enter Toggle DirectInput exclusive mouse
F8 Change video mode to random settings :)
In-game commands (press 'T' to enter typing mode):
/fps Toggle fps meter
/fallcheck Toggle fall checking
/sideshademode Toggle cube face shading
/faceshade=#,#,#,#,#,# Specify shade offsets for each of the 6 faces.
Example: /faceshade=0,5,10,15,20,25
/monst Toggle monsters active/inactive.
/curvy Toggle KV6 sprite in front of view (cycles through
all 3 bending/twisting modes) Try it!
/curvy=[KV6_file] Toggle and select KV6 sprite in front of view.
Example: /curvy=caco
/curvystp=# Set stepsize for /curvy mode
/light Add a light source (lightmode 2 only)
/lightclear Clear all light sources
/lightmode=# Specify lightmode (0=no lighting,1=normal
lighting, 2=point source lighting)
/scandist=# Set maximum radius to scan for VXL raycasting
/fogcol=# Set RGB fogcol. Example: /fogcol=0xff0000 sets fog
color to bright red. /fogcol=-1 to disable
/kv6col=# Set RGB color to blend with all KV6 sprites with
(default:0x808080)
/anginc=# Select raycast width (affects framerate/detail
significantly) Default:1, Typical range:1-8
/vxlmip=# Select raycast distance where VXL (world map)
MIP-mapping begins. (Default:192)
/kv6mip=# Select distance where KV6 (sprite) MIP-mapping
begins. (Default:128)
/health=# Set player health (Default:100)
/numdynamite=# Set number of dynamite (choose a high number :)
/numjoystick=# Set number of joysticks (choose a high number :)
/showtarget=# Toggle target in center of screen
/showhealth=# Toggle health display
Here are some effects that you should not overlook: Did you try them all? :)
* Press '1','2','3','4' in game to select different weapons.
* Press '`' in game to change the female character animation.
* Press 't', then type '/curvy=caco' to see some cool effects!
* Press 't', then type '/numdynamite=10000', and enjoy :)
------------------------------------------------------------------------------
Credits:
Ken Silverman: (http://advsys.net/ken)
*.C, *.H, *.BAT, *.OBJ, *.EXE, *.TXT (Voxlap engine, tools, documentation)
*.VXL, *.SXL, *.WAV, *.PNG (Most of the game content in VOXDATA.ZIP)
*.KV6 (except ANASPLIT.KV6, which was drawn by local artist, Ana Lorenzo)
*.KFA (I separated the limbs & animated the female character)
Tom Dobrowolski: (http://moonedit.com/tom)
WINMAIN.CPP: This is 95% my code. Tom added a few small things to improve
it over the years.
TOONSKY.JPG: Tom originally made this sky for his own Voxlap game.
KASCI9x12.PNG: Tom added Polish characters to the bottom of my font :)
Tom has been a great help to me over the past few years. I thank him for
his many ideas, help, and keeping me motivated to work on Voxlap for as
long as I did. He has written many things for Voxlap in addition to the
Voxlap Cave Demo and his untitled game from 2002 which was never released.
Jonathon Fowler: (http://www.jonof.id.au)
KPLIB.C (1%): JonoF upgraded this library to be compatible with Linux for
his Build port.
------------------------------------------------------------------------------
Voxlap Engine non-commercial license:
[1] Any derivative works based on Voxlap may be distributed as long as it is
free of charge and through noncommercial means.
[2] You must give me proper credit. This line of text is sufficient:
VOXLAP engine by Ken Silverman (http://advsys.net/ken)
Make sure it is clearly visible somewhere in your archive.
[3] If you wish to release modified source code to your game, please add the
following line to each source file changed:
// This file has been modified from Ken Silverman's original release
[4] I am open to commercial applications based on Voxlap, however you must
consult with me first to acquire a commercial license. Using Voxlap as a
test platform or as an advertisement to another commercial game is
commercial exploitation and prohibited without a commercial license.
------------------------------------------------------------------------------
Release history:
09/14/2005: Full voxlap source code released. Changes since 11/09/2004:
* In-line makefile at top of GAME.C now includes VOXLAP5.C and V5.ASM.
* KPLIB.C updated with Linux support (thanks to JonoF). NOTE: the other
files are not Linux-compatible!
* WINMAIN.CPP updated. For sound, link OLE32.LIB instead of DSOUND.LIB
* VOXLAP5.H: kzaddstack and kzseek now return a value
* Added GAME.EXE, VOXED.C, KWALK.C, VOXLAP5.C, and V5.ASM to distribution
* SIMPLE.C: Added sample code showing how to render a simple voxel sprite
* MAKESTUF.BAT: Updated to include VOXED and KWALK
11/09/2004: Voxlap library released.
------------------------------------------------------------------------------
Contact info:
If you do anything cool with Voxlap, I would love to hear about it! I prefer
that you contact me in either of these ways:
1. Write about it on my personal forum ("advsys.net/ken" topic) at:
http://www.jonof.id.au
2. You can write me a private E-mail (address can be found at the bottom of
my main page). Please use this for license requests.
If you have any questions or feature requests about other things in Voxlap, it
doesn't hurt to ask, although keep in mind that I haven't really worked on the
engine since 2003.
Ken's official website: http://advsys.net/ken
------------------------------------------------------------------------------