[Android 2.1+][03.10.2011][v3.2] Chainfire3D [ROOT][OpenGL ES 2.0+]

INSTALL ON HC/ICS/JB AT YOUR OWN PERIL ! - ITS NOT SUPPOSED TO WORK ON THOSE

SGS2 USERS: Upgrading to KG1 (2.3.4) or newer ROM will fix additional graphics glitches, if you are running an older SGS2 ROM.

About
Chainfire3D is an intermediary OpenGL driver. What does that mean? It means that Chainfire3D sits between your apps and the graphics drivers, and can intercept and/or change commands between the two. It has some built-in functions, and can be further extended with plugins to provide extra functionality.

Features
- CF3D OpenGL driver

- NightMode (inspired by Jeff Sharkey, more info here)
--- Handy shortcut to toggle on/off
--- Supports red, green, blue, amber, salmon and custom (pro only) modes

- Global OpenGL manipulation
--- Reduce texture size
--- Reduce texture quality
--- Unroll textures
--- BGRA emulation
--- Load plugins
--- Replace shaders
--- (Pro) Disable Chainfire3D detection
--- (Pro) Dump all shaders
--- (Pro) Force depth buffer size (EGL)
--- (Pro) Force MSAA (MultiSample Anti-Aliasing) (EGL)

- (Pro) OpenGL manipulation on a per-app bases
- (Pro) Fix market settings
- (Pro) Manage installed plugins and shaders
- (Pro) Backup and restore settings, plugins and shaders

A bit more detail about some features

NightMode
NightMode reduces the number of colors on your screen, which on OLED screens saves a lot of battery. The various modes (especially red) are also great in low-light conditions, as they have less effect on your night-vision than a full-color screen

Generic note about textures
The features below are only used if a texture format is supported. Natively Chainfire3D only supports raw textures, but these can be extended through plugins.

Reduce texture size
This essentially cuts (supported) textures' resolution in half, which usually reduces memory use (4x) and improves performance, at the cost of slightly reducing texture quality. This is not compatible with all apps! For many 3D apps, this works, as the GPU stretches the graphics, but it does not work for many 2D apps.

Reduce texture quality
This converts 32-bit textures to 16-bit textures, reducing memory use (2x). This will lower texture quality, but for many games the difference isn't even visible. Whether this is actually faster or slower depends on your hardware.

Unroll textures
Converts non-32-bit textures to 32-bit. This should not influence texture quality, but it does use more memory. On some hardware this is faster than using 16-bit textures.

Disable BGRA emulation
Some GPU's do not support BGRA - in this case, Chainfire3D emulates BGRA support. Developers may not expect this (i.e., hardcode features for a specific GPU) and it may cause issues. If red and blue appear swapped in-app or in-game, enable this feature, and see if it helps.

Disable Chainfire3D detection
For compatibility reasons, Chainfire3D announces to applications that it is being used. Using this feature you can turn that off.

Depth buffer (per-app only)
Some apps expect a certain depth buffer size. Without setting this, they may not run (at all). This feature should only be used if an app specifically requires it - there is a good chance apps will NOT run if you change this setting the wrong way.

MSAA (MultiSample Anti-Aliasing) (per-app only)
Enabling MSAA drastically improves image quality at the cost of performance. Lines/edges become much smoother. Available options are automatic (the app decides), 4x, and 16x. Most apps don't enable MSAA themselves at all. The ARM Mali 400 MP (used in the SGS2) can even do 4xMSAA at no performance cost. Note that if your GPU does not support the level of MSAA requested, the app will likely not start at all.

Fix market settings
Plugins may add support for various features not normally supported by your hardware. Market, however, only reports the functionality your hardware provides. Using this feature, Chainfire3D will adjust Market so it also shows apps that require the features provided by the plugins. This is not useful without the plugins

Backup and restore settings
Backup and restore all app settings, plugins, shaders, etc to/from your SD card

Plugins / API
At the moment, the Plugin API is rather limited, but it does allow for some rather interesting plugins like Tegra2 / PowerVR / ATI texture emulation (see the API docs a post below). The idea is to further improve Chainfire3D so Plugins can manipulate the entire OpenGL data stream.

Shaders
From version v1.9, you can replace app's shaders with your own modified versions. See a few posts down for further details.

Pro version
As outlined above, the Pro version adds a little bit of functionality. Purchasing it will support my efforts.

Pro version - warez
Chainfire3D Pro is available from some warez sites, if you feel like ripping me off However I should warn you that none of those versions actually work as the real Pro version does.

Requirements
- OpenGL ES 2.0 (every 1ghz+ phone has this)
- SuperUser / Root
- Writable /system (it will try to remount system as read/write when needed, but the changes need to stick between reboots)
- S-OFF ?
- Having root access from recovery is a big plus to solve problems if you run into them (run "/system/lib/cf3d_uninstall.sh" as root to remove the driver and restore the old one)

CF3D driver installation
There is some risk involved, so you should have either root access in recovery, a CWM backup, or a firmware to flash handy. Nevertheless, the driver has been tested and found working on the following devices:

- HTC HD2
- Samsung Galaxy S
- Samsung Galaxy Tab 7"
- Samsung Galaxy S II
- Samsung Epic 4G
- Motorola Atrix 4G
- Motorola Droid 2
- LG Optimus 2X
- Google Nexus S

It's likely to work on far more devices. So far nobody has reported a failed install, so that's good. Doesn't mean problems can't happen.

Download

Market link (mobile): market://details?id=eu.chainfire.cf3d

Market link (desktop): https://market.android.com/details?id=eu.chainfire.cf3d



Note: If you were running the "CF3D :: NightMode" application earlier, you should uninstall it before installing this.

OpenGL Configuration Guide

So how does one configure Chainfire3D the best way possible ? It is easy if you know what you are doing. By default, you want to enable as little as possible.

Basics
As stated, you want to enable as little as possible to make apps work the way you want, as the more you enable, the more CPU Chainfire3D will use to do the work.

IMPORTANT #1: Simply enabling all the options is counterproductive, unless you know you need them all.

IMPORTANT #2: Enabling both "Reduce texture quality" and "Unroll textures" is quite a silly thing to do. Read their descriptions, and think about it for a minute

Both options are available because performance-wise, on some hardware one is better, while on other hardware the other is better.

IMPORTANT #3: "Reduce texture size" is NOT compatible with a LOT of apps. If you are seeing weird things, this setting is likely the problem.

(1) When starting out, you simply shouldn't enable anything. When running an app, and it doesn't work as expected, first go into the configuration and see if there is a plugin (only) you can use to make it work better.

(2) If there is no plugin or you are not satisfied with it, try the "Reduce texture quality" option to see if it improves performance. This is the most "compatible" option to use. Though texture memory use is cut in half, often you don't see a big difference (or any difference at all even) in the end-result being displayed on screen.

(3) Alternatively, try the "Unroll textures" option. Be sure to UNcheck the "Reduce texture quality" option when using this.

(4) As last resort, use the "Reduce texture size" option. While this option greatly reduces memory usage and can have an awesome speed improvement as result, it is NOT compatible with a LOT of apps.

(5) If performance is adequate, try enabling the MSAA feature to improve visual quality.

Specifics - Free version
In the free version, you can only configure the "default" settings, so you'll likely be in the Chainfire3D configuration tool a lot. I strongly advise that when you are NOT using Chainfire3D for something specific, you disable all the options. This is better for system performance.

Specifics - Pro version
In the pro version, I strongly advise disabling ALL the options under "default" settings, and ONLY use "per-app" configuration. This will greatly reduce the chance of conflicting settings between different apps, which does actually happen a lot ! It is also the best possible configuration you can have performance-wise.

Plugins / API

Currently available plugins

There are currently no plugins available from my hand, but it appears somebody has compiled and released libGLEMU_NVIDIA, libGLEMU_QUALCOMM, and libGLEMU_POWERVR plugins. You may find them if you search for them

WARNING: I did not write, compile, or release these plugins, and thus I cannot vouch for their quality, or that they don't do anything evil to your device. You should also be aware that they may not be legal to use in your area.

Plugin installation
Plugins are .so files called libGLEMU_xxxxx.so . They should be wrapped in a libGLEMU_xxxxx.zip file. Simply put this zip file on your /sdcard, and use the "Install Plugin" option in Chainfire3D.

API
Attached is a zip file containing some information "by example" on how to build plugins. Read the README.TXT file!

Shaders

About
This might sound like voodoo to some of you, don't worry. Modern OpenGL bases apps and games run programs on the GPU (graphics card) to render the image on screen. These can be quite complicated, and they are not always compatible between different GPUs. Chainfire3D allows you to replace apps' built-in shaders with modified ones. This can potentially fix a number of issues with various apps.

Currently available shaders (ordered by release date)

SGS2 - Riptide GP - Modification by Chainfire. Disables Cube Mapping, makes the game playable

Desire HD - Riptide GP - Modification by scukoemo. Fixes rider lighting issues.

SGS2 - Backbreaker THD - Modification by Chainfire. Fixes error messages, does not fix actual display corruption

Desire HD - Riptide GP v1.1 - Modification by Pr0tEct0.

SGS2 - Riptide GP v1.1 - Modification by crypticc

Shader installation
Shaders are .shader files called xxxxx_xxxxx.shader . They should be wrapped in a shaders_xxxxx.zip file. Simply put this zip file on your /sdcard, and use the "Install Shader" option in Chainfire3D. Be sure to force kill the app you are installing shaders for - that app needs to be restarted for the shaders to be applied. TIP: Going into the per-app settings for an app and changing any setting (and back) will kill the target app.

Shaders - How to modify them (ADVANCED TECH USERS)

This post assumes you know a little bit about OpenGL and shaders. Not a lot, mind you, the shaders I modified I did with no prior knowledge of shaders.

Getting the original shaders
Chainfire3D will automatically detect shaders that do not properly compile, and dump that shader to "/data/data/eu.chainfire.cf3d/files/shaders/processname_crc32.error_dump" and "...error_log". This will generate quite a bit of output in logcat, so you know it happens. In (for example) DDMS, filter on "Chainfire3D" to see only these messages.

The error_log file contains the error message from the GPU, while the error_dump contains the shader source code. (Note that there may be too many newlines).

If the shaders do compile, but they do not actually work (or link - watch logcat to see this happen), the shaders will NOT be automatically dumped. You have to dump them manually. You can do this by going into Chainfire3D per-app OpenGL configuration and enable the "Dump all shaders" option. Chainfire3D will now dump every shader the target app attempts to compile. The file name is the same, but it's extension is ".dump" instead of ".error_dump".

Modifying the shaders
You can simply ADB pull the files out of the "/data/data/eu.chainfire.cf3d/files/shaders/" directory. Handy tip: if you do not specify a filename, ADB will pull the entire directory.

Now you can simply modify the shader files with a text editor. You may have to convert the files from unix-newline format to windows-newline format. Warning: See the limitations section, you also need to convert the files BACK to unix-newline format!

Testing the shaders
Obviously, you will need to kill the target app first, then you can push the shaders back to the device at the same location. IMPORTANT: replacement shaders need to have the ".shader" extension, instead of ".dump" or ".error_dump". Keep the rest of the filename exactly the same. If you do this correctly, Chainfire3D will replace the apps' shader with the one you just put on the device.

To let Chainfire3D be able to use the shader, note that you must also chmod 666 the file on the device.

Packaging the shaders
So you fixed issues with an app for a certain GPU by modifying a number of shaders. It'd be a shame if you kept it for yourself. Packaging them up is simple: just throw the ".shader" files in a ZIP file, and name the ZIP file as follows:

"shaders_device_targetapp_version.zip"

For example, the SGS2 shader fix for Riptide GP would be something like: "shaders_sgs2_riptide_gp_v1.zip"

Releasing the shaders
Simply post a new post in this thread, attach the shaders (or put them on a file hosting site and link them), and put the details about this shader in that post. Then PM me that you released said shaders (with a link to the post) and I can add them to the list.

Limitations
Please note the following shader limitations:

- Dumps are at most 64 KB. If the shader is larger, it will only be a partial dump
- Shader replacements must be < 64 KB
- Shader replacements must use unix-newlines
- Shader replacements must have < 16384 lines
- Each line in a shader replacement must be < 1024 characters