User's Manual

From OBGE - Oblivion Graphics Extender

Jump to: navigation, search

Contents

Downloads

Installation

OBGEv3 has a few prerequisites that must be installed prior to installing and using OBGEv3. These are:

Make sure that you have first downloaded and installed the prerequisites. This readme assumes that you are only interested in installing the OBGEv3 Core package for the OBGEv3 OBSE plugin. If you are also interested in using the OBGEv3 project shaders, download the OBGEv3 Shaders package from the project TES Nexus page and follow the instructions in its ReadMe.

Once you have installed the prerequisites, download from the TES Nexus page the OBGEv3 Core package, then do the following to install OBGEv3 correctly:

  • If you have obge.dll or DepthTest.dll in your Data/OBSE/plugins folder, remove them.
  • If you have any effects from v2 installed, backup and remove them.
  • Extract the contents of the OBGEv3 Core package to your Oblivion\Data directory. Answer yes to any merge or overwrite prompts.

The files in the "Extras" folder are:

  • d3dx9_31.dll - If you are using the legacy compiler and your game crashes, move this to your Oblivion game folder.
  • d3dx9_41.dll - If when you launch Oblivion, the shaders you have applied have no visible effect, and your OBGEv2.log reports that this file is missing, move it to your Oblivion game folder.
  • textures and shaders folders - These contain some example shaders that can be useful in testing that OBGEv3 works and are also useful examples for writing shaders. You don't need to install them to use OBGEv3.

The config file

When you first run OBGEv2 it will create a file called OBGE.ini in your "My Documents\My Games\Oblivion" folder. You can edit this file to change the behaviour of OBGE.

OBGE v2

[Serialization]
bSaveData=1			# Remembers the shaders loaded in by mods when you save the game.
bLoadData=1			# Loads in the shaders previously saved in a save game.
[PluginInterOp]
bEnableInterOp=0		# This setting current doesn't do anything. However in the future it will
				# allow other OBSE plug-ins to access OBGEv2.
[Shaders]
bNoShadersInMenus=0		# Turns off the shader system whenever a menu is displayed.
bUseShaderList=1		# Turns on or off the reading of the ShaderList.txt file.
sShaderListFile=data\shaders\shaderlist.txt
bUseLegacyCompiler=0		# This will use the old version of Microsoft's HLSL compiler. It may give
				# a speed increase for older graphics cards. If the game crashes when using
				# this setting then copy the d3dx9_31.dll from the extras folder into your
				# oblivion game folder (the one with oblivion.exe in it).
bRenderHalfScreen=0		# Only renders the shaders to the right hand side of the screen. This is
				# useful for comparing the shader with the normal rendered screen.
[General]
bEnabled=1			# Setting this to 0 will disable the plug-in but still process the script
				# commands (they just won't do anything).
[DepthBuffer]
bUseDepthBuffer=1		# Turns on and off the creation of a readable depth buffer.
bUseRAWZfix=0			# Activates a fix for graphics cards that use the RAWZ depth buffer format.
[ScreenBuffers]
iBufferTexturesNumBits=16	# This allows you to set the bit depth of the frame buffers used by the
				# shaders. Different bit depths may increase the accuracy and speed of some
				# shaders. Valid settings are 8, 16 and 32. If your card doesn't support a
				# certain bit depth then the next lowest is tried. Some users that have had
				# issues with input lag when using OBGEv2 have reported that lowering this
				# value solves their issues.

OBGE v3

[Serialization]
bSaveData=1			# Remembers the shaders loaded in by mods when you save the game.
bLoadData=1			# Loads in the shaders previously saved in a save game.
[PluginInterOp]
bEnableInterOp=0		# This setting current doesn't do anything. However in the future it will
				# allow other OBSE plug-ins to access OBGEv3.
[Shaders]
bUseShaderOverride=1		# Enable the use of shader-overrides
bSaveShaderOverride=1		# Store the results of the JIT-compiles for later use
sShaderOverrideDirectory=data\shaders\override\
bCompileSources=1		# JIT-compile source files, if this isn't enabled it's necessary to
				# installed deployed binaries
bOptimize=1			# compiler option to enable optimization, may save an instruction or two
bMaximumSM=0			# upgrades shaders to the maximum model the device supports
bUpgradeSM1X=0			# upgrades 1.X shader to 2.0, that is consistent with DirectX 9c where
				# 1.X shaders are deprecated
bRuntimeSources=1		# enables shader to be replaced at runtime, it's needed for LOD-shaders
bUseLegacyCompiler=1
[Effects]
bNoShadersInMenus=0
bUseEffectList=1
sEffectListFile=data\shaders\shaderlist.txt
sEffectDirectory=data\shaders\
bUseLegacyCompiler=0
bRenderHalfScreen=0
bOptimize=1			# compiler option to enable optimization, may save an instruction or two
bPurgeOnNewGame=0		# re-compile shader when a game is loaded, this may be usefull if you edit
				# the effects and you don't want to use the SD
bTailEffects=0			# put effect-list at the end of the pipline, effects run after HDR/Blur,
				# may improve performance, this was the OBGEv2-method
bFreezeTweaks=0			# freezes all user-adjustable constant in the effects, yields performance
				# improvements from 0-20% depending on the effects specifics
[General]
bEnabled=1			# Setting this to 0 will disable the plug-in but still process the script
				# commands (they just won't do anything).
bEnabledDW=1			# Enables the use of the shader-developer (DW==DeveloperWindow). The window
				# will pop up automatically if you are in window-mode. The SD will not
				# function in fullscreen-mode regardless.
bEnabledLOD=0			# Enables the use of LOD-system, is only functional with installed LOD-files
 
[DepthBuffer]
bUseDepthBuffer=1		# Turns on and off the availability of a readable depth buffer.
bUseRAWZfix=0			# Activates a fix for graphics cards that use the RAWZ depth buffer format.
[ScreenBuffers]
iBufferTexturesNumBits=0	# This allows you to set the bit depth of the frame buffers used by the
				# shaders. Different bit depths may increase the accuracy and speed of some
				# shaders. Valid settings are any positive or negative integer describing
				# the bit-depth you want. Positive numbers correspond to fp-bitdepth and
				# negative to int-bitdepth. If your card doesn't support a certain bit depth
				# then the next lowest is tried. Some users that have had issues with input
				# lag when using OBGEv2 have reported that lowering this value solves their
				# issues.
iBufferZDepthNumBits=0
iBufferRawZDepthNumBits=0
iReflectionMapSize=0		# The absolute or relative size of the reflection-map. Integers correspond
				# to an absolute square dimension, a real number between 0.0 and 1.0
				# corresponds to a fraction of the current game-resolution. 0 will take the
				# current width of the game.
iWaterDisplacementSize=0	# The square dimension of the displacement-maps for water.
iWaterHeightmapSize=0		# The square dimension of the height-maps for water.
iAutoGenerateMipMaps=2		# Generate mip-maps for rendertarget automatically. Some effects needs this
				# to speed up processing. Also the reflection-map can be correctly accessed
				# with reduced LOD per higher distance. The number is the ID of the
				# filtering method. 1 is POINT, 2 is LINEAR.
[Textures]
bPurgeOnNewGame=0
iSamplerAnisotropy=4		# enables Anisotropic filtering if above 1
fSamplerLODBias=-1.0		# applies a LOD-bias in case of Anisotropic filtering
bSamplerDeGamma=0		# applies reverse gamma correction x^-2.2 to all loaded texures (excluding
				# rendertargets)
bSamplerReGamma=0		# re-applies gamma correction x^2.2 in the final rendertarget
 
[Meshes]
bPurgeOnNewGame=1
 
[LOD]
iFarNearTiles=5			# 1st level LOD tile-quad size, not in use currently
iFarFarTiles=7			# 2nd level LOD tile-quad size, not in use currently
iFarInfTiles=11			# 3rd level LOD tile-quad size, not in use currently

The shaderlist

In the shaderlist-file you define the effects which are known to OBGE and subsequently to plugins which can request that information from OBGE.

Prior to 3.1 the effects' source-code referenced in the list will be loaded and then compiled, which may take some time (with bOptimize=1 it may be really long). If none of the bPurge*-options is enabled this compiling happens once per Oblivion-instance, save-game loading should be quite fast.

In 3.1 we got proper effect-binary caching, which means compiling happens once per install, and once per every change you make in the files (it checks the timestamps). This allows you to basically throw all of the effects into the list without any negative impact on speed. This also ensures that you can use the plugin or other extensions properly with all effects.

  • "=0" means the effect is compiled but not applied
  • "=1" means the effect is compiled and applied
[Ambient Occlusion]
Volumetric_SSAO.fx=0
Volumetric_SSII.fx=0
Volumetric_SSGI.fx=0
Ring_SSAO.fx=0
Ring_SSAO-q.fx=0
CrysisAO.fx=0
HBAO.fx=1
HDAO.fx=0
 
[Lighting]
Godrays05.fx=0
Godrays06.fx=0
LightShafts_PCS.fx=1
 
[Filtering]
NormalFilterAA.fx=0
DLAA.fx=0
FXAA2.fx=0
FXAA3.fx=0
MLAA.fx=0
MDLAA.fx=0
MFXAA.fx=0
SMAA.fx=1
 
[Depth of Field]
Shaped_Bokeh_DoF.fx=0
Bokeh_Hexagon_DoF.fx=1
Bokeh_Circle_DoF.fx=0
Pseudo_Bokeh_DoF.fx=0
CrysisDoF.fx=0
DepthOfField.fx=0
 
[Misc]
CelShader+EdgeAA.fx=0
ColorEffects.fx=0
ColorMood.fx=0
ENBColorEffect.fx=0
HLSLbleachbypass.fx=0
HLSLColorGrading02.fx=0
HLSLColorGrading03.fx=0
HLSLvignette.fx=0
obsharpen.fx=0
Toon.fx=0
LensEffects.fx=0
Film16.fx=0
SmartSat.fx=0
Technicolor3.fx=0

The "[]"-sections are only properly ignored from 3.1 on, anyway they don't carry any particular meaning for OBGE, it's just a convenience. If you don't mind a few more messages in the log (like "can't load effect [Misc]"), you can use the section-markes also in 3.0, it won't affect the regular operation.

Beginning with 3.1 you can also use comment-markers:

[Misc]
; "=0" means the effect is compiled but not applied
; "=1" means the effect is compiled and applied
 
CelShader+EdgeAA.fx=0
; this is very nice, but the other does the same
ColorEffects.fx=0

This makes the syntax of the shaderlist.txt identical to Windows .ini files. This is a convenience for addon programmers, or if you have an ini-file editor. Note that the OBGE Shader Manager is not compatible with any of the syntax indroduced since 3.0.

Troubleshooting

How To Report Bugs Helpfully

Read this readme fully, as well as the Bethesda forum thread, especially the FAQs. If your problem is not answered there, do the following:

Supply the following:

  • Your Operating System.
  • Your graphics card.
  • The contents of your OBGEv2.log. This log is in your Oblivion directory.
  • The contents of your OBSE.log. This log is in your Oblivion directory.
  • The contents of your shaderlist.txt, if you are using one.

The above documents should be posted exactly how they appear in the file, in spoiler (ie. [spoiler]content[/spoiler]) tags.

In addition, if what you are experiencing is a graphical bug of some kind, you should supply screenshots. It has been noted that Oblivion's screenshot function may not work with OBGEv3 installed, so in that case use FRAPS or some other 3rd party screenshot tool. You can convert the image from .bmp to .jpg in Wrye Bash. Upload the screenshot and post a link to it, so we can see what your problem actually looks like.

If your bug is with a shader effect, and you have altered any variables within the shader, also post the lines on which you changed anything, exactly how they are in the shader, again in spoiler tags.

We can't really help all that well without the above information, as especially with graphical errors, it can hard to describe them in writing in a way that we will be able to understand what's going on.

Effects Extension

Installation

First, make sure you have downloaded and installed the 'OBGEv3 Core' package from the OBGEv3 and OBGEv3 project page here.

To then install the OBGEv3 effects and their support plugin, do the following:

  • Extract the contents of the OBGEv3 Standalone Effects package to your Oblivion\Data directory. Answer yes to any merge or overwrite prompts.
  • Activate the 'Oblivion Graphics Extender Support.esp' in the mod loader of your choice.

You will now be able to load and tweak effects using the support plugin. See below for how to use it, or for how to use the shaderlist method.

When upgrading between versions of the support plugin, a clean save procedure should be used, ie. make a save with no support plugin active and then install and activate the new support plugin. Note that this will cause your effects settings to be lost, so note them down somewhere.

Usage

You can control the effects'/shaders' parameters via the

Reference

Below is a list of all the effects available from the OBGE v2/v3 project on TES Nexus. The list does not include any shaders that may have been added since this readme was updated, or any shaders that are only available for download from the project's forum thread. Version numbers are taken from the version numbers within each shader file, and are not indicative of relative quality.

A few of the distributed files from the core contain code used either by the OBGE core logic itself or provide functionality for all of the other effects.

Uninstallation

Safe uninstallation of OBGEv3 effects and the support plugin should be as simple as deleting the files that you installed. However, if that causes problems for you, then below is a more thorough uninstallation procedure:

  • Set bSaveData=0 in your OBGE.ini, found in your My Documents\My Games\Oblivion folder.
  • Load your saved game in Oblivion, and then save in a new slot.
  • Deactivate the Support Plugin, and remove the added XML if you used the controller from kapaer
  • Load your saved game in Oblivion, and then save in a new slot.

To complete uninstallation of the OBGEv3 Standalone Effects package, delete:

  • All the OBGEv3 effects/shaders found in your Data\Shaders folder, except "TransferZ.fx", "Constants.fx" and the "includes" folder.
  • The support plugin, "Oblivion Graphics Extender Support.esp".
  • The texture file found at Data\Textures\ssao\RandomNoiseB.dds.
  • Don't delete includes.

Shader Modules

Installation

[to be written ...]

The significant settings to enable the use of shaders from modules are the following:

[Shaders]
bUseShaderOverride=1		# Enable the use of shader-overrides
bSaveShaderOverride=1		# Store the results of the JIT-compiles for later use
sShaderOverrideDirectory=data\shaders\override\
bCompileSources=1		# JIT-compile source files, if this isn't enabled it's necessary to
				# installed deployed binaries
bRuntimeSources=1		# enables shader to be replaced at runtime, it's needed for LOD-shaders

You can prevent the system from writing .vso/.pso files to the shader-overrride directory by disabling "bSaveShaderOverride" - in which case every loaded shader will be compiled on-the-fly whenever you start Oblivion. It's a bit slower then.

You can also prevent the system from updating existing .vso/.pso files by disabling "bCompileSources" - then the sources will never be used to create an updated version of the shaders, it will always just use the .pso/.vso files. The sources are still necessary though, as they are parsed for additional information.

To temporarily turn of the utilization of shaders you can disable "bUseShaderOverride" - which in effect turns the entire shader-patch off, though without gaining any speed as the patch is still in place. Only the Retro-Core is free of the patch itself.

Usage

Uninstallation

[to be written ...]

  • Delete all .vso/.pso files in shaders/overrride. This will work anytime even if you only decide to uninstall just a single module. The remaining modules will recreate their necessary files upon next invocation automatically.
  • Don't delete includes, EVER.

Uninstallation

Just run the uninstaller (after running the uninstallers of all other installed modules).

Manual

Safe uninstallation of OBGEv2/v3 should be as simple as deleting the files that you installed, the most important being Data\OBSE\Plugins\OBGEv2.dll.

However, if that causes problems for you, then below is a more thorough uninstallation procedure:

  • Set bSaveData=0 in your OBGE.ini, found in your My Documents\My Games\Oblivion folder.
  • Load your saved game in Oblivion, and then save in a new slot.
  • Delete your OBGEv2.dll and the Data\Shaders\RAWZfix.fx file, the entire Data\Shaders\override\ directory, as well as any files in the 'Extras' folder you installed.

You should now be able to run Oblivion without OBGEv2/v3 and avoid any problems. If you are still experiencing problems after following this procedure, seek further assistance in the official forum thread.