Color Clutch Files

~~~~~~~~~~~~~~~~~~~
 Color Clutch v0.3
~~~~~~~~~~~~~~~~~~~

Please read this readme in its entirety before attempting to use Color Clutch, or at least before sending me bug reports or other problems.

Also, "game", "app", "application", "exe", "executable", "process", and "target" all mean basically the same thing for the purposes of this readme, and are used interchangeably.  In addition, "DirectX", "DX", "Direct3D" "D3D" are used interchangeably.


+----------+
| Contents |
+----------+

- Contents
- What?
- Why?
- When?
- How?
- Example
- FAQ
- Debugging
- Caveats
- Credits
- Contact
- Disclaimer
- License
- Legal


+-------+
| What? |
+-------+

Color Clutch is a set of tools (an injector and a set of DLLs) that are used to hold color calibration in various full screen Windows DirectX games and other full screen DirectX applications.

The latest version of Color Clutch (as well as old versions) can be found at the SourceForge Project Page, located @ http://sf.net/projects/colorclutch/

You can also find general information on the project, as well as a link to the latest version and the SF Project Page on the home page @ http://colorclutch.sf.net/


+------+
| Why? |
+------+

If you use the standard sRGB color space, with no calibration profile, you probably do NOT need to use these tools at all.  However, if you have a monitor calibration device (typically a USB device that sits on your monitor and generates a profile) or have calibrated your screen via another method, and lose this calibration in full screen games or applications, then this will likely solve your problem.

Also, occasionally, there is a workaround in some games that lose color in full screen that will not require the use of Color Clutch at all.  These games have a "Full Screen (windowed)" or "Windowed Full Screen" option, and include most of Valve's games (e.g. Left 4 Dead, Left 4 Dead 2), StarCraft II, and probably many more games that I have not played.


+-------+
| When? |
+-------+

Color Clutch's injector (the tool used to make use of Color Clutch in games, etc.) MUST be run before the target application is launched.  In fact, it is not necessary to run the app--the injector will launch it for you.  You cannot inject the DLLs after the application has started, as there is no way to guarantee that color calibration can be maintained unless they are started by the injector.

In most cases, where applications use their own launchers, you can still use Color Clutch.  This is because the typical usage of Color Clutch will cause the DLLs to self-inject into "child" or "orphaned" processes.  That is to say, that all processes created by the process that was initially injected will also be injected, as will all further processes spawned by them, ad infinitum.  This behavior can be changed depending on the parameters passed to the injector, see the "How" section below for details.

In rare cases, e.g. StarCraft II, the launchers ("StarCraft II.exe" and "SC2Switcher.exe") will detect Color Clutch's presence and refuse to continue launching the final process ("SC2.exe").  As there is no way to start StarCraft II without using one of its launchers, and both launchers detect Color Clutch, there is currently no way to use Color Clutch in conjunction with StarCraft II.  However, you can always use its "Windowed (Fullscreen)" mode to maintain color calibration while playing.


+------+
| How? |
+------+

The easiest way to regularly use Color Clutch is to create a batch (.bat) file to launch Color Clutch's injector with the correct arguments.  If you run the injector without any parameters, you'll see the following usage line printed:

Usage: inject.exe <c:\full\path\to\injected.dll> <function> <c:\full\path\to\target.exe> [parameters]

The first parameter, the DLL picked, depends on what version of DirectX the target application uses.  Color Clutch's DLLs are all named "cclutch_", followed by the DirectX version it supports as a Roman numeral, and finally the ".dll" extension.  Remember, this MUST include the full path to the DLL (e.g. "C:\Program Files (x86)\cclutch\cclutch_ix.dll"), and NOT JUST the file name ("cclutch_ix.dll").  Be sure to place the path in quotes if it contains spaces (quotes will not hurt even if it doesn't, so in general, always use them).

The second parameter is the name of the exported function that resides inside the injected DLL that is to be called after the DLL is loaded into the target process.  There are two options here; "patch" and "patch_once", and they are case-sensitive.  The options differ in only one way--"patch" will cause Color Clutch's DLLs to self-inject to all processes spawned by the process you initially inject to, and all processes spawned by them, indefinitely.  If you don't want this, use "patch_once", which has identical behavior to "patch" on older versions of Color Clutch (pre v0.3).  The "patch" behavior on current versions is the recommended default, and NOT "patch_once".

The "patch" behavior is also needed if you want to use an (un)official launcher for games, e.g. Texmod.  To use Color Clutch with Texmod and a game, just start Texmod (or whatever other launcher) directly from the injector, and then use Texmod (or that other launcher) as you normally would.  In Texmod's case, just select the mods you want and the game within Texmod and launch it from Texmod, and both Texmod and Color Clutch should work flawlessly in the game, not counting any bugs present in Texmod.

The third parameter is the last required parameter, and it specifies the full path to the target application.  This application will be executed by the injector, and MUST include the full path to the application.  The same rules pertaining to quoting paths that were mentioned in the paragraph describing the first parameter also apply here.

Lastly, if you require or desire parameters to be passed to the target executable, place them at the end.  They as passed to the process exactly as they appear after the previous parameter.


+---------+
| Example |
+---------+

I've included some example batch files that you can (and will need to) edit to suit your needs in the examples subdirectory.  Simply right-click them in Windows Explorer and select "edit" to do so, and then double-click them to execute them.  I'll also list one example here, with additional explanation.

Example: Guild Wars (example-d3d9.bat)
"C:\Program Files (x86)\cclutch\inject.exe" "C:\Program Files (x86)\cclutch\cclutch_ix.dll" patch "C:\Program Files (x86)\Guild Wars\Gw.exe"

This example assumes you've extracted cclutch to "C:\Program Files (x86)\".  First we have the full path to our injector, guaranteeing that the batch file will run the injector regardless of where the batch file is located (assuming the injector stays put where it is).  If the batch file is in the same directory as the injector, simply specifying "inject.exe" will work.

Next, we have the full path to the injected DLL, which is "C:\Program Files (x86)\cclutch\cclutch_ix.dll".  We use the cclutch_ix.dll because Guild Wars is a Direct3D 9 game.

Then we have our function to call, "patch".  It does not need to be quoted.  This will inject the DLL into all processes the target process spawns, in addition to the target process itself.  For Guild Wars, this is used to avoid manually restarting the application when there is an update to the game (needed if "patch_once" had been used), which causes it to restart itself.  The "patch" option is also the recommended default.

Lastly, we have the full path to the target exe, and this example assumes that Guild Wars is installed in "C:\Program Files (x86)\Guild Wars\".  Edit the path as you need for various games, and create a new batch file for each game.

Also, if we needed to pass parameters to "Gw.exe", we could tack them on at the end of the command line.


+-----+
| FAQ |
+-----+

Q: I want to keep the icon of my target program, but still start it from a batch file.  Can I do this, and how?

A: Yes, start by creating a shortcut to the batch file in explorer.  Right click your shortcut, and click "Properties", then "Change Icon..." under the "Shortcut" tab.  Click OK to acknowledge the warning, and then click "Browse..." to find your target exe (or any other app or resource that contains the icon you want to use).  Select the icon in it and then click "OK" twice, and place the shortcut in the start menu or wherever you want.


Q: I hear a beep when I start my application using Color Clutch.  What's going on?

A: In the unlikely event of an error, Color Clutch will beep during startup.  Try using the debugging DLLs to see what's going on.  Read the Debugging section of the readme for more information.


+-----------+
| Debugging |
+-----------+

It doesn't work?  Here are a few steps to try, in order.

1: Ensure you have the "Visual Studio 2008 SP1 Redistributable Package (x86)" installed.  You can download this @ http://www.microsoft.com/downloads/details.aspx?familyid=a5c84275-3b97-4ab7-a40d-3802b2af5fc2&displaylang=en if you don't have it already.  Note that this may be installed already, as many applications or driver packages do so automatically.  However, attempting to install from the included link should not harm your system if you already have it installed.

2: Run the injector or batch file as an administrator.  I believe this is only actually needed if you are using the debug DLLs (as they potentially place debug logs in system directories, e.g. "C:\Program Files\Some Game\"), but I am not entirely sure, and it may depend on your UAC settings if not run as an admin.  If you are running it from the command line, make sure that cmd.exe is run as an administrator.  If you are running it from a batch file, or a shortcut, simply right click the file/shortcut and select "Run as administrator".

3: Are you sure you're using the correct DLL for the application?  Make sure the app is rendering using the version of Direct3D (DirectX) that you think it is.  The easiest way to find out is looking at the game requirements, as well as your OS and graphics card.  The lowest of all three is what's being used.  E.g., if your game supports DirectX 9, you're on Windows 7 (supports up to D3D11), and you have an ATI Radeon 4000 series (supports up to Direct3D 10), you should be using the cclutch_ix.dll, because the game limits you to Direct3D 9.

4: Reboot.  Some graphics card drivers have bugs.  For instance, at one point, my Radeon 5850 running the 10.6 drivers would revert to the default sRGB gamma ramps for basically any full screen D3D game even with Color Clutch working, inexplicably.  Rebooting has fixed this (well, at least temporarily).

5: Try different versions of drivers for your graphics card.  I cannot speak for nVIDIA cards, but drivers for my Radeon 5850 are hit-or-miss, and some lose calibration when others don't, with everything else being equal.  Newer drivers are not always better with respect to color calibration!

6: Use the included debug DLLs.  Simply specify one of the DLLs in the debug folder when injecting, instead of those in the same folder as the injector.  Then, when executed, the target app will place one or more log files (named the process name, then a dash, followed by the process identifier) in the same directory as the target app.  You should see text in this file, including at least one call to SetGammaRamp/SetGammaControl.  If you don't see any files, make sure you are running the injector with administrative privileges.  I ask that you attach the contents of these files, if possible, when you submit a bug report.


+---------+
| Caveats |
+---------+

As Color Clutch intercepts functions related to gamma settings in order to maintain color, in-game gamma settings will not work.  However, a properly calibrated monitor should not need to adjust these settings anyway.

Color Clutch currently only supports 32-bit applications.  A 64-bit port will be made when I have a 64-bit game with which to test.

Injecting DLLs into processes and overwriting areas of the IAT and/or overwriting function code might trigger anti-cheat tools to accidentally detect Color Clutch as a cheat.  I take no responsibility for any consequences--see the disclaimer section for more information.

Some AV (AntiVirus) software may detect the injector as malicious software.  While no malicious DLLs are included in the Color Clutch project or distributions thereof, it's certainly not impossible for it to be used by other, malicious software.  See the disclaimer.

I am unsure how well Unicode characters are supported in .bat files.  If you need to use Unicode characters, for paths or parameters, and it doesn't work in a batch file, try manually entering in the entire command line in cmd.exe.

The injector does not verify all the things it should (paths, file existence, etc.).  Some work has been done to correct this, but it's incomplete, and work should continue for future releases.

There may be games that use another method to change gamma and cause loss of color calibration (the GDI).  These should cause loss of color calibration regardless of whether or not the game is run in a windowed mode, and are currently not supported by Color Clutch.  However, I do not know of any games that fall into this category, yet.

I have a limited amount of games to test with.  I can't promise this works with every game.  In fact, the Direct3D 11 version is completely untested, until I can get my hands on a Direct3D 11 game.  If you really, really, really want it to work with a certain game and it doesn't, first see the debugging section of the readme, and if all else fails, tell me where I can download a free demo or a free full version LEGALLY (no warez or cracks please), and I'll try my best to get it working.


+---------+
| Credits |
+---------+

Many thanks to the following people/groups for their contributions to the project:

ASUS
- For providing me with a monitor with a terrible blue color cast not fixable via monitor settings

X-Rite
- For making my ASUS monitor usable

Drew_Benton @ The Code Project
- Injector base code @ http://www.codeproject.com/KB/threads/completeinject.aspx

Roverturbo @ Unknown Cheats
- D3D9 base code @ http://www.uc-forum.com/forum/anti-cheat-bypass/55985-direct3d9-interface-hooking.html

P47R!CK @ Game Deception
- D3D10 base code @ http://forum.gamedeception.net/threads/16050-Starterkit-for-Direct-3D-10

Various people in #winapi @ Freenode
- For locating or providing documentation for old versions of DirectX

Last but not least, Microsoft
- For DirectX behavior, which is the whole reason this project exists in the first place.
- For NOT making documentation on old versions of DirectX available to developers on MSDN


+---------+
| Contact |
+---------+

If you just want to say thanks, give it a thumbs up on the SourceForge Project Page, or write a review there.

If you want to submit a bug report, documentation/web error, or even just a typo somewhere, please post it under the bugs section on the tracker page @ http://sourceforge.net/tracker/?group_id=332983 (NOT the forums, as I do not monitor those), and be sure to attach your debugging log(s) (see the debugging section) as a file attachment or copy/paste.  Feature requests should also go under the appropriate category in the tracker.

If you really need to get a hold of me for some other reason, email me at my SourceForge address: yoitsmeremember AT users.sf.net.  Please send all DMCA notices and other legal threats to fuck AT you.gov.


+------------+
| Disclaimer |
+------------+

I make NO legal claims about the stability or functionality of this software or any other software it might modify the functionality of.  I also do not deny that the injector could be used for malicious purposes (though I do not believe any part of Color Clutch does anything inherently malicious).  As such, AntiVirus (AV) software may detect it as a virus, and other malicious software could potentially abuse parts of Color Clutch for malicious purposes.  Disable or reconfigure (including exemptions for any portion of Color Clutch) AntiVirus software AT YOUR OWN RISK.

Also injecting DLLs into other processes, modifying import address tables (IATs), and modifying function code has been known to be used in many cheats (or "hacks") for games or other applications.  While this does not hook any of the functions that cheats commonly do, that does NOT mean that Color Clutch could not accidentally be detected as a cheat.  I TAKE NO RESPONSIBILITY FOR KICKS, BANS, LOSS OF LICENSE OR PROPERTY, OR ANY OTHER ADVERSE EFFECTS ASSOCIATED WITH COLOR CLUTCH!

See the license for more information.


+---------+
| License |
+---------+

Color Clutch - Color holding utility for various versions of Direct3D
Copyright (C) 2011 yoitsmeremember AT users.sf.net

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.


+-------+
| Legal |
+-------+

Microsoft, Windows, Microsoft Windows, DirectX, Direct3D, and Visual Studio are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

StarCraft and Blizzard Entertainment are trademarks or registered trademarks of Blizzard Entertainment, Inc. in the U.S. and/or other countries.

Valve and Left 4 Dead are trademarks and/or registered trademarks of Valve Corporation.

Guild Wars is a trademark or registered trademark of NCsoft Corporation.

Anno and Anno 1404 are trademarks of Sunflowers GmbH in the U.S. and/or other countries.

ASUS is a trademark of ASUSTeK Computer Inc.

X-Rite is a registered trademark of X-Rite, Inc. 

ATI, Radeon, and combinations thereof are trademarks and/or registered trademarks of Advanced Micro Devices, Inc.

NVIDIA is a registered trademark of NVIDIA Corporation.


~end~