myvgaspec.exe version 0.1.3 README
by ccexplore (a.k.a. "The Guest")


Table of Contents
-----------------

 1. Change History
 2. System Requirements
 3. What is myvgaspec?
 4. How to Use
 5. Limitations
 6. How to Create Levels Using My Custom VGASPECx File
 7. Notes
 8. Found a Bug?
 9. Contact Info
10. Credits
11. Appendix A


I. Change History
-----------------

version 0.1.3 (8/12/05)
  - changes were made to try to fix a problem that prevents myvgaspec from working on Win95/98/ME
  - added the ability to "handle" bitmaps with more than 7 colors, by randomly assigning colors to pixels beyond the first 7 colors found.  Adds a user prompt to warn the user about this and let him/her choose to either go ahead or convert something else.

version 0.1.1 (8/11/05)
  - fixed a minor bug in the SPEC-compression verification routine, which caused false alarms of errors when processing raw chunks of length 128

version 0.1 (8/10/05)
  - first release of myvgaspec


II. System Requirements
-----------------------

  myvgaspec.exe requires Windows 95 or above. However, since I only have an XP machine, it has only been tested on Windows XP.  Please e-mail me (see Contact Info) if you have trouble getting it to work on earlier versions of Windows.


III. What is myvgaspec?
-----------------------

  myvgaspec is a program that allows you to create your own VGASPECx.DAT files for use with Customized Lemmings or plain DOS Lemmings.  The VGASPECx.DAT files are the files that contain the complete terrains for the four "special graphics" levels in DOS Lemmings (Fun 22, Tricky 14, etc.). A level using special graphics will load its terrain entirely from a VGASPECx.DAT file.  (Note that this means you cannot add additional terrain pieces from the normal graphics set to such a level.)

  myvgaspec works by taking a bitmap image (picture) you have created, and generates a DAT file in the VGASPECx format containing that image.  As a result, the image can then be used as a complete terrain in your own levels.  In short, myvgaspec converts picture files to VGASPECx.DAT files.

  Go on to the "How to Use" section for more details on how to use this program.  Be sure to read the "Limitations" section also, since this version of myvgaspec has quite a number of restrictions on what kinds of bitmap images it can handle.


IV. How to Use
--------------

  When you run myvgaspec, you will first be greeted by a welcome message that gives you the version number and name of the program.  Clicking OK will bring up a standard "Open File" window.  There, you select the bitmap file to convert. (Now will be a good time to read the Limitations section to learn what kinds of bitmap files myvgaspec currently handles.)

  Once you select a bitmap file that can be handled by myvgaspec, it will display a message stating that the conversion process will begin.  Click OK to go on.  After it is done (it should be pretty much instantaneous), you will then be presented with a standard "Save As" window.  There, you specified the location and name of the .DAT file to save to.  And then you're done!

  I recommend you try this out first with the included example.bmp file.  Convert and save the file as vgaspec0.dat, then go play the level in myspec.dat which uses vgaspec0.


V. Limitations
--------------

  Summary:  the image you want to convert must be a 24-bit BMP file, not exceeding the dimensions of 960x160.  It also must use no more than 7 colors, excluding the background color which must be black.

  Details:

  The game itself imposes some restrictions on what images you can use.  First of all, the VGASPECx.DAT format fixes the image's dimensions to be exactly 960 pixels wide by 160 pixels tall.  Therefore, the image you selected cannot be any larger in either dimension.  If your image is smaller, myvgaspec will automatically center it horizontally and aligned it vertically against the bottom of the 960x160 area.  Deal with this limitation by cropping and/or shrinking the image you want to use in your favorite image editor.  The 960x160 image is always drawn centered horizontally on the playing field by the game.

  Second, and this is a critical restriction the game imposes:  the VGASPECx.DAT format only supports a maximum of 7 colors to be used by the bitmap image.  7 not including the background which of course is and must be black.  As a result, this version of myvgaspec works best only when the image you selected uses no more than 7 colors plus black as the background color. Otherwise, you will be given the option to proceed, in which case myvgaspec will basically randomly assign colors when processing the rest of the bitmap.  Alternatively, you will be allowed to select another file instead.  In a future version of myvgaspec I might incorporate the capability to do automatic color reduction in a proper, desirable manner.  In the meanwhile, check if your graphics editor has a suitable color reduction feature, so that you can create a color-reduced version of the image you want to use.  Please also read the Notes section regarding how this limitation can affect you even when you create your own images from scratch.

  Finally, to simplify programming, this version of myvgaspec can only handle a very specific type of bitmap image format.  Namely, it must be in Window's BMP bitmap format, and moreover it must be a 24-bit bitmap.  Sorry, no PNGs, GIFs or JPEGs or what not, and it has to be 24-bit.  You can use Window's Paint program to convert images to this format, so hopefully this should not be a big issue.


VI. How to Create Levels Using My Custom VGASPECx File
------------------------------------------------------

The easiest way to do this is to fire up LemEdit, then open as a levelset one of the levelXXX.dat files that came with DOS Lemmings.  You can find all the special graphics levels somewhere amongst them:

level000.dat #1:  Taxing 15 (uses vgaspec0.dat)
level000.dat #2:  Tricky 14 (uses vgaspec1.dat)
level000.dat #4:  Mayhem 22 (uses vgaspec2.dat)
level001.dat #3:  Fun 22    (uses vgaspec3.dat)

Pick the one you want (it really doesn't matter which, other than affecting what to rename your VGASPECx.DAT file to), load it in LemEdit, then save it as your own level in a separate file or levelset.

LemEdit unfortunately does not understand the VGASPECx format and so will be unable to display your custom terrain.  However, you can still edit the level's statistics and interactive objects.

Write down which vgaspecX.dat the level you selected from above uses.  Then when you use myvgaspec, be sure to save the resulting DAT file using the same name.  Or save it any name you want and then copy/rename it when you want to play the level.

Alternatively, if you don't have a copy of DOS Lemmings, you can open the myspec.dat levelset included in the myvgaspec.zip.  The level in it uses vgaspec0.dat.  Save the level as your own and edit away.


VII. Notes
----------

  The 7-color limitation is sure to dampen your enthusiasm a little when creating your own special graphics levels.  It can rear its ugly head even with images you create from scratch, where you *think* you have total control over what colors were used.  For example, when creating example.bmp in Windows XP, at first myvgaspec complains that I used more than 7 colors in it.  It turns out that when Windows XP renders the text, it has a build-in feature (called ClearType) to smooth the jagged edges of the letters, by blending the edge pixels with the neighboring background pixels.  This blending process of course results in additional colors beyond the seven that I picked.  To create a usable example.bmp I had to go to Control Panel to turn off ClearType (see appendix A for instructions).  If you create your BMP from scratch and myvgaspec keeps complaining that it has too many colors, be sure to zoom in and inspect your BMP carefully.

  The 7-color limitation may also affect you when you try to shrink an image.  Depending on the image editor and/or version of Windows you use, the shrinking operation may also do some sort of blending/smoothing that results in new colors.

  Finally, note that using special graphics will affect the colors of the interactive objects in the level also.  (You probably have noticed this when playing the special graphics levels that came with DOS Lemmings.) This is because the game can only use a total of 16 colors.  The special graphics changes 8 of them, but interactive objects can use any 16.  For most level designers this is generally not a problem.


VIII. Found a Bug?
------------------

  I did my best to test the program before releasing it, but if you find a problem with the program outside of the stated limitations, be sure to tell me about it!  I will even give you credit for any bugs you found.  See the "Contact Info" section for how to e-mail me.  Be sure to e-mail me the BMP you are trying to convert--sorry, I have to have it in order to have any chance of fixing the problem, I promise I won't leak your super-secret terrain graphics to anyone. :) Also, if myvgaspec is telling you that it found a bug in itself, be sure to copy down the information it tells you to copy down, and e-mail that to me also.  At a minimum, you should be sure to tell me the version number of myvgaspec that you are using.  It also wouldn't hurt if you e-mail me as much info about your computer as possible (eg. what version of Windows, the display resolution, etc.)

  I can't promise to have time to fix everything, but at the very least, knowing about it allows me to alert others of the problem.


IX. Contact Info
----------------

  E-mail guestlevels@yahoo.com.  Be sure to specify "myvgaspec" somewhere on the subject line.  For bug reports, I recommend starting the title with "myvgaspec BUG REPORT: ".

  Keep in mind that I might not necessarily respond to e-mail in a timely fashion.  Don't waste your time or mine by sending the same e-mail multiple times.  At the very least please wait at least one week before resending anything.


X. Credits
----------

  My sincere thanks to "rt", who wrote the documentation on the .LVL ("direct save") file format.  That was the starting point that, in one way or another, enabled me to eventually figure out everything else about DOS Lemmings files, including the VGASPECx file format.

  And I suppose I should thank the author of LemEdit for creating LemEdit, despite how much I hate that program for working so poorly on modern Windows machines.  myvgaspec would be totally pointless had there been no LemEdit.

  Thanks Timballisto for alerting me that myvgaspec v0.1.1 and below does not work with Win95/98/ME.


Appendix A
----------

(How to turn off/on ClearType on Windows XP)

1) Go to Start Menu.

2) Click Control Panel.

3) Look at panel on left side of the window that pops up.  If it says something about "classic view", click it.  Otherwise ignore.

4) Find the "Display" icon (scroll down if necessary) and double-click to open.

5) Another window opens, this one with a few tabs near its top.  Click on the "Appearance" tab.

6) Find and click the "Effects..." button near the bottom right.

7) Find the checkbox next to "Use the following method to smooth edges of screen fonts:".  If the checkbox has a checkmark, click on it to clear the checkmark, thereby turning the feature (ClearType) off. Then click OK 2 or more times to close the popup windows, and your changes will be applied.

8) To turn it back on, in addition to following steps 1-7 and then clicking on the checkbox again to re-check it, you will also need to go to the nearby drop-down list and select "ClearType" instead of "Standard" as the smoothing method.