
SPCX

by Michael Thornbury

(kuwanger@iname.com)

Chapter 1 - Questions, Answers, and the whole salami
------------------------

1. What is SPCX?

A. Spcx is a simple DOS based pcx viewer able to display 256 color pcx files
   that decompress to 64K or less size. Spcx's name comes from Stretch PCX,
   as the main visual effect in spcx in the stretching of the pcx image
   in two seperate boxes.

2. What is special about SPCX?

A. Most importantly, SPCX can stretch PCX files. There is no actual economic
   benefit from this effect. Never the less, it is the most pronominent
   feature of SPCX. As an added, side bonus, SPCX offers alpha-mode (pass -a
   to SPCX on the command line).  In this mode, SPCX uses an 8-bit based
   alpha blender to mix two layers on the screen (layer 0 is the screen,
   layer 1 is the bottom image, layer 2 is the upper image). A total of 10
   alpha-blending modes are available, although not all of them are true
   alpha-blenders. Press numbers 0 to 9 on the keyboard to see the various
   "alpha-blending" effects. A predominent favorite of most people seems to
   be #9.

3. Why is SPCX so slow?

A. There are two possible reasons for SPCX appearing slow:

   1. You're using a DOS emulator of some nature (NTVDM or DOSEmu).

   2. The default 60 fps is too slow for your taste. Use "+" or "-" in the
      program to change the frame rate.

      Note: If you specify "-n" on the command line, the frame rate set is
      the rate the video buffer is processed through the output filter (if
      any) and sent to the video screen. You will likely notice a different
      frame rate drop off point where the frame rate changes suddenly. This
      is a result of a combination of the output filter (if used) and the
      video bus bandwidth.

4. The program pauses when I hit tab key and the display paused? What's up
   with that?

A. Seeing as the alpha-blending might seem "spiffy" to some people, I decided
   to include a "pause" button, and using some not often used key was the
   easiest solution to using a pause button (trust me, it was an easier
   solution for me than using the *real* pause button).

5. I can't assemble the source code. Why not?

A. Please make sure you're using NASM (a recent version, assumedly) and
   you're including macros.mac as a macro file on the command line to NASM.
   If you still can't get the program to assemble..why not?

6. What are all the command line switches? And what can I actually do IN the
   program?

A. The command line switches behave as follows:

   file.pcx = the image to use as the moving image
   -a = enables alpha-blending support; use numbers 0 to 9 in the program
        to see the various alpha-blending filters
   -h = enables the height field; the pcx file loaded is converted to a
        height field where the brightness of a pixel determines its height
   -m = a suboption used with -h to allow the user to rotate with the arrow
        keys the heightmap
   -s = causes the contents of the comspec env label to be run prior to
        the display of the images
   -n = disables the use of the timer to control the rate of the back buffer
        fill rate
   -f = displaces the actual frame rate
   -b = forces the moving image to the default image
   --file2.pcx = a pcx file you specify as the moving image

   Note: As you'll likely notice, file.pcx, --file2.pcx, and -b do the same
         thing. However, depending on what is supplied, the following occurs:

                       Supplied         |            Result
      file.pcx | -h | --file2.pcx | -b  |--------------------------------
        no       no       no        no  | default image is used as moving
                                        | image
        yes      no       no        no  | file.pcx is used as moving image
        no       yes      no        no  | default image is used as moving
                                        | image and heightmap
        yes      yes      no        no  | file.pcx is used as moving image
                                        | and heightmap
        no       no       yes       no  | file2.pcx is used as moving
                                        | image
        yes      no       yes       no  | file2.pcx is used as moving image
        no       yes      yes       no  | file2.pcx is used as moving
                                        | image, default image is used as
                                        | heightmap
        yes      yes      yes       no  | file.pcx is used as heightmap,
                                        | file2.pcx is used as moving image
        no       no       no        yes | default image is used as moving
                                        | image
        yes      no       no        yes | default image is used as moving
                                        | image
        no       yes      no        yes | default image is used as moving
                                        | image and heightmap
        yes      yes      no        yes | file.pcx is used as heightmap,
                                        | default image is used as moving
                                        | image
        no       no       yes       yes | default image is used as moving
                                        | image
        yes      no       yes       yes | default image is used as moving
                                        | image
        no       yes      yes       yes | default image is used as moving
                                        | image and heightmap
        yes      yes      yes       yes | file.pcx is used as heghtmap,
                                        | default image is used as moving
                                        | image

   Note: The following are output filters. For "o#", the output filters are
         done on the heightmap (if it exists). For "O#", the output options
         are done on the final displayed image. When using "O#", the output
         is much slower than the normal display (unless using O0 whic is
         equivalent to the normal display).

   -o0 = no effect
   -o1 = enables blur engine
   -o2 = enables motion blur effect
   -o3 = enables a modified blur engine
   -o4 = blur based upon edge definitions
   -o5 = dragged image, causing a nice trailing effect
   -o6 = a blur engine with greater pattern recognition
   -o7 = interleaved image that bounces if it doesn't fit the screen
   -o8 = dithers the final image to 4-bit gray scale
   -o9 = dithers the final image to 4-bit gray scale, without error bleeding

   Inside the program:

   Numbers 0 to 9 changes the filter for the selected filter option. The
   starting filter is in decreasing order of precedence: alpha-blending,
   output filter, heightmap filter. While in the game, use "a", "o", or
   "h" where applicable to change the filter effected by the number keys.

   Note: Pressing a key not defined for usage will exit the program.

   Virtually all other keys exit the program.

7. I really like your program and am just *DYING* to use part of it in my
   program. What license is the program covered under? Am I allowed to use
   the source code for free?

A. So long as you don't attempt to make a profit off the resulting program,
   feel free to use any or all of the source code, provided you make distinct
   references in your documentation and source code that you used some of
   SPCX's source code along with a mention that I made it. If the very
   unlikely chance you think you can make a profit by using some of my code,
   well..e-mail me and we'll talk about it.

8. Okay, you seem a bit pessimistic. Is there anything in this program worth
   mentioning?

A. Yes, there is actually. The only real thing worth mentioning is that this
   program was written completely in x86 assembly, which makes it absolutely
   useless to most people who want platform independent code. Other than that,
   the code is at least semi-intelligently comment and there's even some
   really neat parts to it, too, like the linearly interpolating stretch
   engine and the interpolating clock timer engine and...damn, way too many
   interpolating parts. Oh, and the 8-bit alpha blender uses a simple
   distance formula thing to figure out which color to use.. At some point,
   I could even write out in C the equivalent code to show how simple the
   idea is, but how ugly it gets when you don't use floating point numbers to
   do the math.

9. How do I contact you?

A. Well, apart from e-mailing me (kuwanger@iname.com), you can more than
   likely catch me on #programmers on irc.dal.net at various times of the day
   under the handle Kuwanger. If by some off chance I'm not there, feel free
   to memo me (and don't e-mail me to ask how to memo me..that's just dumb)
   on IRC or e-mail me. Spam is not appreciated in the slightest, nor is
   questions from newbies who want to know how to write programs. Go to
   #programmers on irc.dal.net if you need specific help, or try to find a
   good book. You should also check out the #programmers' website (which I
   don't have handy at the moment), which should help you on your way to
   programming.

10. Any other questions?

A. If you have any pertinent questions that you think should be added to this
   file, please e-mail me the question, and I may add it to the list.

   Note: By supplying an e-mail to me, you forfeit your copyright on that
   e-mail, thereby legally allowing me to include any questions asked into
   this file. (And that I put in for legal protection.)

   Second Note: I probably won't reply to e-mails that don't fit into category
   8 or 9, even if I do like the question. I just often don't reply (you have
   friends like that, don't you?).

