home *** CD-ROM | disk | FTP | other *** search
/ The Best of Windows 95.com 1996 September / WIN95_09962.iso / vrml / dm2v-10.zip / README.TXT < prev   
Text File  |  1996-06-24  |  10KB  |  224 lines
  1. doomToVrml2 (a.k.a. Doom2VRML),                        Kenneth B. Russell
  2. Doom to VRML 2.0 Converter.                            kbrussel@engr.sgi.com
  3. Version 1.0                                            (kbrussel@media.mit.edu
  4. June 24, 1996                                          after Aug 31, 1996)
  5.  
  6.                        ***************************
  7.                Copyright (C) 1996 Silicon Graphics, Inc.
  8.  
  9.           Permission is hereby granted, free of charge, to any person
  10.           obtaining a copy of this software (the "Software") to use
  11.           and modify the Software for personal use.  The Software may
  12.           not be resold or licensed for a fee without Silicon
  13.           Graphics, Inc.'s ("SGI") prior written consent.  The above
  14.           copyright notice and permission must be included in all
  15.           copies or substantial portions of the Software.
  16.  
  17.           THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
  18.           KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
  19.           WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR
  20.           PURPOSE AND NONINFRINGEMENT.  IN NO EVENT IS SGI LIABLE FOR
  21.           ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
  22.           OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
  23.           CONNECTION WITH THE SOFTWARE OR THE USE OF THE SOFTWARE.
  24.  
  25.           Except as contained in this notice and permission, SGI's
  26.           name may not be used in advertising or otherwise to promote
  27.           the use or other dealings of the Software without SGI's
  28.           prior written consent.
  29.                        ***************************
  30.  
  31. Contents
  32. --------
  33.  
  34.       i.   Version History
  35.       I.   What is Doom2VRML?
  36.       II.  Improvements Over WadToIv
  37.       III. Using Doom2VRML
  38.       IV.  Compiling and Porting Doom2VRML
  39.       V.   Credits
  40.       VI.  Known Problems
  41.       VII. For More Information
  42.  
  43.  
  44. Section i. Version History
  45. --------------------------
  46.  
  47. Version 1.0 - June 24, 1996
  48.        - First Public Release
  49.  
  50.  
  51. Section I. What is Doom2VRML?
  52. -----------------------------
  53.  
  54. Doom2VRML, as the name implies, is a utility which converts the
  55. polygon and texture information in a Doom level into a VRML 2.0 world
  56. file. The resulting file can be posted on the World Wide Web. In
  57. short, it's "Doom on the Web".
  58.  
  59. Doom2VRML was based on WadToIv (see Section VII), by the same
  60. author. All of the code has been rewritten, and several new functions
  61. and improvements over WadToIv have been made. Most significantly,
  62. Doom2VRML is cross-platform compatible; it runs on the PC and SGI, and
  63. porting to other platforms should be straightforward (see Section IV,
  64. below).
  65.  
  66. What is Doom2VRML good for? First, it allows users to author VRML 2.0
  67. content using standard Doom editors. These programs, created by
  68. dedicated authors, are arguably the best (and least expensive!) way to
  69. create large, compelling environments to explore. Second, it provides
  70. an immediate content infusion to the VRML community, by giving access
  71. to the thousands of freely available Doom levels on the Internet.
  72.  
  73.  
  74. Section II. Improvements Over WadToIv
  75. -------------------------------------
  76.  
  77. Doom2VRML sports the following new features over WadToIv:
  78.  
  79.        - New tesselation algorithm for floors and ceilings, using
  80.          Doom's BSP tree information. Sunken floors/raised ceilings
  81.          now appear properly in the output file. 
  82.        - MOVING DOORS! Click to open; they close automatically.
  83.        - VIEWPOINTS! All player starts (including Deathmatch ones) are
  84.          converted into VRML 2.0 Viewpoints.
  85.        - Spatial organization of the scene graph; polygons are grouped
  86.          into rooms. Render culling should now work; improves
  87.          performance greatly on platforms which support this
  88.          functionality.
  89.        - Checks on polygons eliminate "coincident vertex" errors and
  90.          resulting slowdowns.
  91.        - Optional materials provide solid coloring for walls in
  92.          situations where texture mapping is too expensive.
  93.        - Both JPEG and IRIS RGB texture output formats supported.
  94.        - Dependency on Open Inventor eliminated for better
  95.          cross-platform compatibility.
  96.  
  97.  
  98. Section III. Using Doom2VRML
  99. ----------------------------
  100.  
  101. Doom2VRML is run from the command line on both UNIX platforms and
  102. PCs. Therefore, the PC version must be run from within DOS. The currently
  103. available versions run under Irix 5.3 or above on SGI platforms and under
  104. the DOS shell in Windows 95 on the PC.
  105.  
  106. Typing "doomToVrml2" (or "dm2vrml" in the PC version) prints a screen
  107. describing the command line options. Again, they are:
  108.  
  109.    doomToVrml2 [-2] [-f <WAD filename>] [-e <episode>]
  110.                [-m <mission>] [-a] [-t <texture mode>]
  111.                [-p <palette number>]
  112.       -2 turns on Doom 2 mode: mission can go from 1 to 32,
  113.          episode is ignored, and doomToVrml2 looks for doom2.wad
  114.       -f <WAD filename> specifies an optional patch wad
  115.       -a causes Material nodes to be Added to the outputted
  116.          VRML file. This adds background colors to the
  117.          polygons, but may slow down rendering.
  118.       -t <texture mode> changes the file format in which
  119.          textures will be outputted. Valid values are
  120.          JPEG and SGI; default is JPEG.
  121.       -p <palette number> changes which Doom palette is used
  122.          for wall and floor/ceiling textures; allows
  123.          outputting of "hurt" or "power-up" tinted
  124.          textures. NOTE that this option is NOT bounds
  125.          checked. Use at your own risk.
  126.       Episode and mission default to E1M1 (or MAP01 for Doom 2).
  127.  
  128. Doom2VRML does all its work in the current directory. This means it
  129. looks in the current directory for the main WAD file (either doom.wad
  130. or doom2.wad) and outputs all its files (lots of .jpg's, plus one .wrl
  131. file) in the same place. To avoid making a mess of your hard drive,
  132. you may want to make subdirectories for each Doom level you create. In
  133. UNIX you can make symlinks to put references to the executable and
  134. main WAD file in each of these subdirectories; under DOS you will have
  135. to move files around.
  136.  
  137. The converted level, which appears as a world file (for example,
  138. "e2m1.wrl" or "map03.wrl") can be viewed in any VRML 2.0-compliant
  139. browser, such as SGI's Cosmo Player (see Section VII). The following
  140. two aspects of the file are probably the most interesting:
  141.  
  142.        - DOORS MOVE! Click on a door to open it, and it closes
  143.          automatically after a delay. Doors requiring keys should work.
  144.        - Player starts in the level appear as Viewpoints in the world
  145.          file. These viewpoints can be animated, or sufficiently many
  146.          can be added, to create a guided tour of the level.
  147.  
  148.  
  149. Section IV. Compiling and Porting Doom2VRML
  150. -------------------------------------------
  151.  
  152. The first thing you will need to do is obtain the Independent JPEG
  153. Group's JPEG software, available from
  154. ftp://ftp.uu.net/graphics/jpeg/. The version Doom2VRML uses is version
  155. 6a, but it should work with any later version as long as the API
  156. hasn't changed too much. Create a subdirectory inside the Doom2VRML
  157. directory called "jpeg-6a", uncompress the archive in this
  158. subdirectory, and configure and compile the JPEG library.
  159.  
  160. Once this is done, you will need to configure the file "byteswap.h" for
  161. your architecture. If you are running on a little-endian machine, add
  162. a conditionalized #define LITTLE_ENDIAN to the top of byteswap.h; see
  163. the current entry for Windows already present for an example.
  164.  
  165. If your sys/types.h does not predefine types such as uint16_t (you'll know
  166. because the compile will fail inside sgiimage.cpp with a related error),
  167. see the top of sgiimage.cpp and conditionally typedef those types to the
  168. appropriate ones. uint16_t is an unsigned integer of 16 bits; uint32_t is
  169. an unsigned integer of 32 bits.
  170.  
  171. If your compiler does not automatically find the code for templates
  172. (as SGI's does), you may need to add a conditionalized #include at the
  173. bottom of "growarray.h", as was necessary for Windows. This will
  174. almost certainly be necessary for users of g++.
  175.  
  176. Finally, you will need to rewrite the Makefile so it does not depend
  177. on SGI-specific makerules. Sorry.
  178.  
  179.  
  180. Section V. Credits
  181. ------------------
  182.  
  183. Thanks go to:
  184.   - id Software for the game Doom
  185.   - Raphael Quinet and Brendan Wyber for DEU (the Doom Editing
  186.     Utilities), especially for distributing the source code (from
  187.     which I borrowed several WAD reading functions)
  188.   - David Frerichs for the initial door motion code
  189.   - The Independent JPEG Group for a wonderful library
  190.   - Matthew S. Fell for the Unofficial Doom Specs
  191.   - Scott Amspoker for TEXTURES.TXT, a terrific explanation of Doom
  192.     texture alignment
  193. Doom is a trademark of id Software, inc.
  194.  
  195.  
  196. Section VI. Known Problems
  197. --------------------------
  198.  
  199.   - The Cosmo Player implementation on the PC currently suffers from
  200.     limitations in RenderWare on the number of times a texture can be
  201.     repeated. Textures (especially floor and ceiling textures) may
  202.     appear "striped" as they are clamped to their last values beyond
  203.     this point.
  204.   - The PC version of Cosmo Player occasionally appears to stretch
  205.     certain textures vertically by about a factor of two. The same
  206.     textures appear fine on the SGI version.
  207.   - The code which detects the presence of doors is not very robust (yet?),
  208.     and fails for certain types of Doom doors (i.e. those which only open
  209.     on one side). This can cause missing polygons where those doors should
  210.     be, as well as doors which do not open.
  211.  
  212.  
  213. Section VII. For More Information
  214. ---------------------------------
  215.  
  216. On Doom:
  217.   http://www.cdrom.com/pub/idgames/docs/rgcd-pips/FTP_WWW_sites.html
  218.  
  219. On VRML/Cosmo Player:
  220.   http://vrml.sgi.com/
  221.  
  222. On WadToIv:
  223.   http://www-white.media.mit.edu/~kbrussel/wadtoiv.html
  224.