PalettestealerSuspender (updated 2011-04-24)
============================================

Contact
-------
* By: Seppe "Macuyiko" vanden Broucke
* E-mail: macuyiko@gmail.com
* Website: http://blog.macuyiko.com

Description
-----------
Allows you to play Directdraw games in fullscreen on Windows Vista and Windows 7 without color problems.

Works with:

* Worms Armageddon
* Age Of Empires (and Rise Of Rome)
* Age Of Empires 2: Age Of Kings (and The Conquerors)
* Starcraft (and Broodwar)
* Diablo 1 (and expansions)
* Diable 2 (and expansions, note that Blizzard fixed the color issue in a recent patch)
* Star Wars: Galactic Battlegrounds (fun fact: this game uses the same engine as the Age Of Empires series)
* Others... (?)

Quickstart
----------
Run the program, press "Browse" and pick your game executable. Press "Start Game" and have fun.

Usage (GUI)
-----------
1) Open program.
2) Browse for game executable.
3) The program will set the "Start in" path for you, in most cases, this should be fine, so don't change it.

You now have two options:
4a) Press "Start Game". The program will suspend processes in the list which are changing the colors and start the game.
4b) Press "Watch Game". The program will wait until the game is started and then automatically suspend the processes in the list. Use this if you're using a launcher or lobby program like Garena which start the game for you.

If the game is still having color problems:
5) Close the game.
   Did the program add new entries to the list? If so, they should be checked, redo step 4.
   No new entries and still having problems? Then goto 6.
6) Try selecting another method:
    - Recommended (kernel32): should work for most people.
    - Legacy (ntdll): uses an undocumented API call and might work when the first one does noe.
    - Alternative (dbgproc): not recommended, try this if the previous two don't work.
    - Kill process: will kill the listed tasks (!), and restarts explorer.exe for you when the game finishes. Annoying, so use this as a last option.
   Goto 4 and try this new method, if you've tried them all, then feel free to contact me at macuyiko@gmail.com


By checking and unchecking items in the list you can choose which processes you want to suspend. Note that for some processes, it is impossible to change their option. "Idle" and "csrss" may never be checked, and "explorer" should always be checked. Depending on the game, some other rules may apply as well. The best thing is not to tamper with it if you don't have to.

Usage (Console)
---------------
As of April 2011, the program also contains a console mode, so it can for example be used in batch scripts. This mode is currently still experimental and programs may occur. Following command line parameters are currently available:

    PaletteStealerSuspender.exe /nogui /game <GAME_PATH> [/wait] [/restore]

* /nogui: must be set to use the program in console mode, otherwise the GUI window will open and other parameters will be ignored.
* /game: must be set, <GAME_PATH> contains the full path the the game's executable. Double quotes (") may be used to delimit complex paths (see example below).
* /wait: optional. Don't start the game automatically but wait until the game is started.
* /restore: optional. Use this in case of a lockout/frozen system to try to restore it to a non-suspended state. Other parameters will be ignored.

Example:

    PaletteStealerSuspender.exe /nogui /game "C:\Games\Age Of Empires 2\age2_x1\age2_x1.exe"

Note that you should not ALT+TAB out of the game or close the console window while the game is still running, since you will probably not be able to return to the game, resulting in an unusable, suspended system. If you do encounter a problem, try one of the following:

* You ALT+TABbed and cannot return to the game:
    -> Use CTRL+SHIFT+ESC and force close the game process.
* You've closed the program as well, but a console window is still open:
    -> Use PaletteStealerSuspender.exe with the /restore and /nogui parameters to try to resume the processes.
* You've closed the console window:
    -> Use CTRL+SHIFT+ESC and press "File" -> "New Task". Browse to the location of PaletteStealerSuspender.exe and edit the path with the /restore and /nogui parameters, e.g.: "C:\Users\Seppe\Desktop\PalettestealerSuspender.exe" /restore /nogui

As of now, only the "explorer" process will be suspended, and the console mode will make no effort to try and capture other palette stealing processes (because a console application cannot intercept painting events). If you need to suspend other processes as well, use the GUI mode. 
Planned parameters:

* /startdir <DIRECTORY>: to manually set the working directory.
* /suspendlist <PROCESS_LIST>: to manually set the list of process to suspend. This way, you can use the GUI mode the first time to spot palette stealing processes, and then use these in the console mode.

Bugs
----
If the program should crash, an error report will be copied to the clipboard. Please contact me and include that pasted report, thanks!

Known bugs
----------
* For some people none of the first three methods are working. Please contact me if this happens.
* Some people experience black screens when starting the game with the program, or experience random resolution changes after using the program. This might, however, be more related to graphics drivers.
* The console mode uses a kernel call to attach itself to the parent host process (the command window), which means that pressing ENTER while the program is running will return you to a cmd prompt, although the program is still running. The alternative would have been to make the Visual Studio project a console application, but then a command window would spawn even when starting the program in its GUI mode. Since most people use the GUI mode, I choose the first approach.

Disclaimer
----------
THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

License
-------
This work is licensed under a Creative Commons Attribution-Share Alike 2.0 Belgium License as stated at http://creativecommons.org/licenses/by-sa/2.0/be/.
