Name: Screen Effects
Version: 1.0
Date: 7/14/2008
Category: Visual Effects
Requirements: Oblivion Patch 1.2.0.214, Oblivion Script Extender 0015 or higher (OBSE)
Included Requirements: Oblivion Graphics Extender (OBGE)
Author(s): quetzilla
Source: www.tesnexus.com


Description
===========
Enables mods to easily control several visual effects:

* Brightness
* Shadows Intensity
* Highlights Intensity
* Contrast
* Saturation
* Graduated Filter Magnitude
* Posterization
* Fullscreen Blur

NOTE: If you have a somewhat low-end computer and find that the mod is slowing your FPS, you may want to open up the ScreenEffects.fx file (found in Data/Shaders/) with a text editor, and scroll to the bottom where you will find instructions on how to descrease the blur quality.

If you are not a modder/scriptwriter, you can skip to the Install section, or you can read the Details section below to see how easy it is to make your own mod to use and control the above visual effects!


Details
=======
IMPORTANT! Read ALL of these instructions to avoid causing widespread panic and mayhem for users!

This is the core .esm file that allows modders to create a plethora of possible shader effects for use in their mods. It provides any script with the capability to control the settings mentioned in the Description section. Version 1.0 improves this interface by giving each mod its own settings to control and then combines the settings from each client mod for the final result.

IMPORTANT! To access the controls in your own scripts make sure that ScreenEffects.esm has a checkmark next to it when loading your mod in the Construction Set.

Before your mod can control the visual effects, you must add a control item for each effect you want to be able to change to the appropriate control stack. For example, if you want to be able to control the Brightness, first you need to create an inventory item in the Construction Set and give it a UNIQUE editorID, for example: MyModBrightness. Any item that can be added to an inventory will work, but later I will explain why you might want to choose one in specific. The Name field of the item doesn't matter, but you will want to make sure to put something there that you will recognize.

Now that you have your MyModBrightness item, you would then put the following code in the initialization section of the script for your mod:

SCBrightnessStack.additem MyModBrightness 1

'SCBrightnessStack' is a container from ScreenEffects.esm into which all control items for brightness from each mod are kept and tracked.

With the control item added to the control stack, you are now able to change the brightness, which is tracked by the weight of your control item. To set the brightness to twice as much as normal you would do:

setweight 2 MyModBrightness

When the above line is called by the game the brightness will instantly be doubled. Also note that since the Weight controls the value, you can set the weight of the object to be the value you want as default while your mod is active.

IMPORTANT! OBSE allows changes to properties of items, but changes do not save when you save the game. For this reason you will need to reapply your settings whenever a save game is loaded (which you can check easily with GetGameLoaded). Because of this you will probably also want to have your own variables to store what the current settings SHOULD be so that you know what to set them to on game load. See the scripts in the example mod, Screen Controls, to see one way to do this.

Among the 8 settings provided there are two subtypes which relate to how the settings are combined: Multiplier settings and Max-Value settings. To combine the values from all client mods for a Multiplier Setting, all of the weights of the control items are multiplied together, so that if two mods set the brightness to 2 (double), the total brightness will be 4 (quadruple!). Multiplier settings have a default value of 1.0.

To combine the values from all client mods for a Max-Value setting, only the maximum value from all the control items is used. So with two mods, if one mod sets the Fullscreen Blur level to 0.5 and another mod sets it to 2.2, the final Blur level will be 2.2. Max-Value Settings have a default value of 0.0.

Multiplier Settings:
Brightness
Shadows
Highlights
Contrast
Saturation

Max-Value Settings:
Graduated Filter Magnitude
Posterization
Fullscreen Blur

IMPORTANT! Because Multiplier settings are multiplied together, setting one of them to ZERO will cause the result to be ZERO no matter what any other mods have set it to! In the case of Contrast and Brightness this will cause the screen to go completely GREY or BLACK. Make sure NOT to set the starting weight of a Contrast or Brightness control item in the construction set to ZERO to keep that from happening!

Finally there is one last cool trick you get to play with, with is automated fading. If you make your control item as a Weapon item I have provided a script, aaSCVariableFadeScript, that you can attach to the weapon, and this will allow you to set the 'Target Value' that you want a particular setting to be, and the script will automatically fade from the current value to the new value. This is controlled by adjusting certain properties of the Weapon Item itself:

Damage: If this is set to 0, fading will be disabled. Since only Weapons have the Damage property, attaching the aaSCVariableFadeScript to a non-weapon item will not do anything

Reach: This is the property that stores the Target Value. Every frame the Fade script will set the Weight valuem closer and closer to the Reach value until they are exactly the same. When choosing the default Weight value for a control you will want to make sure the Weight and the Reach are the same.

Speed: This controls how fast the value will fade from the current value to the Target Value (Reach). IMPORTANT! If you leave this at zero then the value will never fade to the Target Value! A value of 1.0 here means that it takes 1 second to increase or decrease the value by 1.0. So if the current value is 2.5 and the Reach is 3.0, with Speed set to 1.0 it will take half a second to fade to 3.0.

Remember, you can adjust all three of these via script to enable or disable fading, as well as adjust the speed of the fading, etc.

Lastly, the names of the control stack containers to which the proper control items should be added are:
SCBrightnessStack
SCShadowsStack
SCHighlightsStack
SCContrastStack
SCSaturationStack
SCGFMagStack
SCPosterizeStack
SCBlurMagStack

There are a lot of possible visual effects that you can create via the settings provided. For examples make sure to check out the screenshots section on the TESNexus page for this mod. In the future I may add more controls, such as hue shifting as well as desaturation of individual colors.

If you run into any problems or just have questions, drop by the official forum thread (just search for Screen Effects at the bottom to find it).


Further Notes about Mods and ScreenEffects
==========================================
* Screen Effects must always be installed first, before any mods depending on it, so make sure to tell your users that in the readme file for your mod
* It would be a good idea to print a message to the console after the lines in your script that add the control items to the control stack containers, as a common problem for users is that they have installed things in the improper order. Printing a message when this is done makes it much easier to determine what potential problems are.
* It may be helpful to provide users with some way to re-execute the lines that add the control items to the control stack containers to aid in solving these problems.


Upgrading from Previous Versions
================================
IMPORTANT! Before installing this version you MUST make a clean save! Disable the old ScreenEffects.esm in the launcher/OBMM/Wrye Bash, as well as any mods that used the previous version, then start Oblivion and make a new save. Do this for each saved game that you want to use the new version with. ONLY THEN should you install the new version and enable it!


Install
=======
IMPORTANT! Before installing make sure you have all of these installed:

(download separately): Oblivion Patch 1.2.0.214, Oblivion Script Extender 0015 or higher (OBSE)

1. Extract this archive to any folder and then copy the contents to Oblivion's Data
folder.
2. Start Oblivion Launcher, click Data Files, and enable the .esp file(s).


Uninstall
=========
WARNING: Uninstalling this mod will cause any client mods to stop functioning!

1. Start Oblivion Launcher, click Data Files, uncheck the .esp file(s).
2. Delete the files/folders associated with this mod.

Oblivion\Data\ScreenEffects.esm
Oblivion\Data\ScreenEffects readme.txt
Oblivion\Data\Shaders\ScreenEffects.fx

If you have no other OBGE plugins, you can also delete:
Oblivion\Data\Plugins\obge.dll


Incompatibility
===============
May produce *slightly* weird effects when used in conjunction with other OBGE shader mods depending on the order the shaders are loaded in. The effects will probably not be noticeable.


Known Issues or Bugs
====================
None yet.


History
=======
1.0, 2008/07/12 - Updated to 1.0, internal engine completely revamped with new effects and full client mod intercompatiblity.
0.90, 2008/04/01 - Initial release.


Contact
=======
You can find me on the official Elder Scrolls forums as 'qzilla'
You can find me on TESNexus as 'quetzilla'

If you need to get in touch with me for some reason, PLEASE use the official forums, as I cannot check the comments pages for all of my mods very often.


Credits
=======
Thanks to tombofsoldier for the initial idea and request.
Thanks to lupo_fangs for the graduated filter code.
Thanks to Timeslip for OBGE and help with HLSL on the OVEP thread.
Thanks to Bethesda for creating Oblivion.
Thanks to LHammonds for the Readme Generator this file was based on.


Tools Used
==========
FX Composer 2 - http://developer.nvidia.com/object/fx_composer_home.html
TES4Gecko - http://www.tesnexus.com/downloads/file.php?id=8665
TES Construction Set - http://www.elderscrolls.com/downloads/updates_utilities.htm
Readme Generator - http://lhammonds.game-host.org/obmm/tools_readme_generator1.asp


Licensing/Legal
===============
You must contact me and obtain my permission before re-packaging any part of
this mod. If I do not respond within 6 weeks, feel free to do whatever you
like with this mod.