Convert to markdown and modernize it

Crementif 2019-05-04 22:12:25 +02:00
parent edbc8a0072
commit 5160ff6c2c
2 changed files with 170 additions and 464 deletions

@ -0,0 +1,170 @@
Graphic packs are like upscaling 3D in emulators but with more features.
Anyone can make one (assuming they have the necessary know-how) and
users can download and install them. In the options of Cemu, individual
graphic packs can then be enabled or disabled. Additionally, multiple
graphic packs can be active for the same game as long as they don't
interfere with each other, and different games can be activated at the
same time. You can mix and match according to your own personal
preference.
**What graphic packs are able to do:**
* Change the game's internal resolution
* Increase the resolution and quality of shadows
* Modify or remove post-processing effects
* Workarounds for graphic bugs until there's a proper solution
* Change lighting related aspects of the game
* Custom Anti-Aliasing
* Better LOD Bias
* Modify game files
* Run 30fps games in 60fps (via Cemuhook)
* Modify aspect ratio (via Cemuhook)
* And much more...
**From a technical standpoint, graphic packs allow the following:**
* Overwrite certain texture properties (like the resolution)
* Overwrite shaders (very powerful since almost everything that gets drawn on the screen uses shaders)
* Replace game files (such as replacing Link with Zelda)
* Modify game code (via Cemuhook)
## Create a graphic pack
A graphic pack is a folder with the the name of the game. This graphic pack repository exclusively uses pascal case, suffixed by the graphic packs function, separated by an underscore. For example: `NameOfGame_Resolution`.
It'll always need to have a `rules.txt` included with this. Optionally, this folder can also contain custom shaders (files ending with `_vs.txt` or `_ps.txt`) or a `patches.txt` file (which are used by Cemuhook).
### Rules
This is the core file of any graphic pack, since rules.txt contains information about the graphic pack, the games it is applied to. Optionally, you can also find presets or texture redefines here that can modify texture properties. Everything after a `#` character is considered a comment. There's also the singular `vsyncFrequency` rule, which is used in some graphic packs that deal with framerates.
**An example from a section of a resolution pack**
```ini
[Definition]
titleIds = 00050000101C9300,00050000101C9400,00050000101C9500
name = Resolution
path = "Minecraft: Wii U Edition/Graphics/Resolution"
description = Changes the game's resolution.
version = 3
[Preset]
name = 1280x720 (Default)
$width = 1280
$height = 720
$gameWidth = 1280
$gameHeight = 720
[Preset]
name = 3840x2160
$width = 3840
$height = 2160
$gameWidth = 1280
$gameHeight = 720
# TV Resolution
[TextureRedefine]
width = 1280
height = 720
formats = 0x0000001a,0x00000011,0x00000820
overwriteWidth = ($width/$gameWidth) * 1280
overwriteHeight = ($height/$gameHeight) * 720
```
There are the four sections: `[Definition]`, `[Preset]`, `[Control]` and `[TextureRedefine]`. Let's take a closer look at each one of these.
| name | description |
|-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| titleIds | List of one or multiple titleIds (unique game indentifier) which are used to determine for which games this pack is active. |
| name | Name which appears in Cemu's "Graphic packs" window. Setting it to a short, identifiable name is recommended. (ex: Resolution) |
| path | Path which appears in Cemu's "Graphic packs" window. Setting it with the game's name is recommended, followed by it's category and name, all separated by slashes (ex: "The Legend of Zelda: Breath of the Wild/Graphics/Resolution") |
| description | The description of what the pack does. |
| version | Version 3 is used since Cemu 1.13.0 and must always be set. |
| name | description |
|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name | The name of this preset, which appears in this graphic pack's preset dropdown in Cemu's "Graphic packs" window. |
| $[variable] | A set variable for the preset. Can be width, height, scale multiply, bloom strength, etc. (ex: $width, $height, $multiply, $strength). You can have multiple variables in each preset of course. |
| name | description |
|----------------|------------------------------------------------------|
| vsyncFrequency | Sets the VSync frequency to any value that you want. |
| name | description |
|--------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| width | The width of the texture that you want to modify. |
| height | The height of the texture that you want to modify. |
| formats | The formats of the textures must match any of these ('0x' prefix denotes hexadecimal format, can contain multiple formats separated by comma). |
| overwriteLodBias | Overwrites the game's lod bias. Typical valid values are in range -16.0 to 16.0. |
| overwriteRelativeLodBias | Add value to game's lod bias rather than overwriting it. Typical valid values are in range -16.0 to 16.0. |
| depth | Unknown usage |
| tilemodes | Unknown usage |
| formatsExcluded | If any of the filter settings above are omitted they are not evaluated. This allows you to write a rule that, for example, only filters for the width of a texture but not the height. |
| tileModesExcluded | Skips CPU-generated textures, generally used by videos (ex. Xenoblade Chronicles X, Bayonetta 2). |
| overwriteFormat | Replaces all the formats under this resolution (unless included/excluded via formats/excludeFormats) with the one defined here. |
| overwriteDepth | Unknown usage |
| overwriteWidth | Like filter settings you can omit individual overwrite settings. This allows to selectively overwrite the width but not the height etc. |
| overwriteHeight | Like filter settings you can omit individual overwrite settings. This allows to selectively overwrite the height but not the width etc. |
## Possible formats
| Texture Name | Code |
|-----------------------|-------|
| R8_UINT | 0x101 |
| R8_SNORM | 0x201 |
| R8_SINT | 0x301 |
| R4_G4_UNORM | 0x002 |
| R16_UNORM | 0x005 |
| R16_UINT | 0x105 |
| R16_SNORM | 0x205 |
| R16_SINT | 0x305 |
| R16_FLOAT | 0x806 |
| R8_G8_UNORM | 0x007 |
| R8_G8_UINT | 0x107 |
| R8_G8_SNORM | 0x207 |
| R8_G8_SINT | 0x307 |
| R5_G6_B5_UNORM | 0x008 |
| R5_G5_B5_A1_UNORM | 0x00a |
| R4_G4_B4_A4_UNORM | 0x00b |
| A1_B5_G5_R5_UNORM | 0x00c |
| R32_UINT | 0x10d |
| R32_SINT | 0x30d |
| R32_FLOAT | 0x80e |
| R16_G16_UNORM | 0x00f |
| R16_G16_UINT | 0x10f |
| R16_G16_SNORM | 0x20f |
| R16_G16_SINT | 0x30f |
| R16_G16_FLOAT | 0x810 |
| D24_S8_UNORM | 0x011 |
| X24_G8_UINT | 0x111 |
| D24_S8_FLOAT | 0x811 |
| R11_G11_B10_FLOAT | 0x816 |
| R10_G10_B10_A2_UNORM | 0x019 |
| R10_G10_B10_A2_UINT | 0x119 |
| R10_G10_B10_A2_SNORM | 0x219 |
| R10_G10_B10_A2_SINT | 0x319 |
| R10_G10_B10_A2_SRGB | 0x419 |
| R8_G8_B8_A8_UNORM | 0x01a |
| R8_G8_B8_A8_UINT | 0x11a |
| R8_G8_B8_A8_SNORM | 0x21a |
| R8_G8_B8_A8_SINT | 0x31a |
| R8_G8_B8_A8_SRGB | 0x41a |
| A2_B10_G10_R10_UNORM | 0x01b |
| A2_B10_G10_R10_UINT | 0x11b |
| D32_FLOAT_S8_UINT_X24 | 0x81c |
| X32_G8_UINT_X24 | 0x11c |
| R32_G32_UINT | 0x11d |
| R32_G32_SINT | 0x31d |
| R32_G32_FLOAT | 0x81e |
| R16_G16_B16_A16_UNORM | 0x01f |
| R16_G16_B16_A16_UINT | 0x11f |
| R16_G16_B16_A16_SNORM | 0x21f |
| R16_G16_B16_A16_SINT | 0x31f |
| R16_G16_B16_A16_FLOAT | 0x820 |
| R32_G32_B32_A32_UINT | 0x122 |
| R32_G32_B32_A32_SINT | 0x322 |
| R32_G32_B32_A32_FLOAT | 0x823 |
| BC1_UNORM | 0x031 |
| BC1_SRGB | 0x431 |
| BC2_UNORM | 0x032 |
| BC2_SRGB | 0x432 |
| BC3_UNORM | 0x033 |
| BC3_SRGB | 0x433 |
| BC4_UNORM | 0x034 |
| BC4_SNORM | 0x234 |
| BC5_UNORM | 0x035 |
| BC5_SNORM | 0x235 |

@ -1,464 +0,0 @@
Graphic packs are like upscaling 3D in emulators but with more features. Anyone can make one (assuming they have the necessary know-how) and users can download and install them. In the options of Cemu, individual graphic packs can then be enabled or disabled. Additionally, multiple graphic packs can be active for the same game as long as they don't interfere with each other, and different games can be activated at the same time. You can mix and match according to your own personal preference.
==What graphic packs are able to do==
*Change the game's internal resolution
*Increase the resolution and quality of shadows
*Modify or remove post-processing effects
*Workarounds for graphic bugs until there's a proper solution
*Change lighting related aspects of the game
*Custom Anti-Aliasing
*Better LOD Bias
*Modify game files
*Run 30fps games in 60fps (via Cemuhook)
*Modify aspect ratio (via Cemuhook)
From a technical standpoint, graphic packs allow the following:
*Overwrite certain texture properties (like the resolution)
*Overwrite shaders (very powerful since almost everything that gets drawn on the screen uses shaders)
*Replace game files (such as replacing Link with Zelda)
*Modify game code (via Cemuhook)
==Create a graphic pack==
A graphic pack is a folder with the the name of the game without spaces. For example: <code>NameOfGame</code>
In this folder is the txt file <code>rules.txt</code>.
===Rules===
rules.txt contains information about the graphic pack, the games it is applied to, the presets it contains and one or multiple rules that can modify texture properties. Everything after a <code>#</code> character is considered a comment.
Note: While not necessary, knowledge about engines, rendering concepts, graphic effects etc. is helpful when trying to create your own graphic packs.
Here is a example of a rules.txt
<pre>
[Definition]
titleIds = 00050000101C9300,00050000101C9400,00050000101C9500
name = Resolution Changer
path = "The Legend of Zelda: Breath of the Wild/Resolution"
description = Changes the game's resolution.
version = 3
[Preset]
name = 1920x1080
$width = 1920
$height = 1080
[Preset]
name = 2560x1440
$width = 2560
$height = 1440
[Control]
vsyncFrequency = 144
[TextureRedefine]
width = 1280
height = 720
formatsExcluded = 0x431 # exclude intro background texture
overwriteFormat = 0x1f
tileModesExcluded = 0x1
overwriteWidth = $width
overwriteHeight = $height
</pre>
There are the four sections: [Definition], [Preset], [Control], and [TextureRedefine]. Under these sections are some variables that can be changed.
====Section: [Definition]====
{| class="wikitable"
!colspan="2"|Variables in the section [Definition]
|-
!<small>variable</small>
!<small>description</small>
|-
|<pre>titleIds</pre>
|List of one or multiple titleIds (unique game indentifier) which are used to determine for which games this pack is active.
|-
|<pre>name</pre>
|Name which appears in Cemu's "Graphic packs" window. Setting it to what the pack does is recommended. (ex: Resolution Changer)
|-
|<pre>path</pre>
|Path which appears in Cemu's "Graphic packs" window. Setting it with the game's name is recommended. (ex: "The Legend of Zelda: Breath of the Wild/Resolution")
|-
|<pre>description</pre>
|The description of what the pack does.
|-
|<pre>version</pre>
|Version 3 is used since Cemu 1.13.0 and must always be set.
|}
====Section: [Preset]====
{| class="wikitable"
!colspan="2"|Variables in the section [Preset]
|-
!<small>variable</small>
!<small>description</small>
|-
|<pre>name</pre>
|The name of the preset.
|-
|<pre>$variable</pre>
|A set variable for the preset. Can be width, height, scale multiply, bloom strength, etc. (ex: $width, $height, $multiply, $strength)
|}
====Section: [Control]====
{| class="wikitable"
!colspan="2"|Variables in the section [Control]
|-
!<small>variable</small>
!<small>description</small>
|-
|<pre>vsyncFrequency</pre>
|Sets the VSync frequency to any value that you want.
|}
====Section: [TextureRedefine]====
After the [Preset] or [Control] section one or more texture redefines can follow. Below is a description of what it does and how it works.
This rule type can be used to overwrite certain texture properties, like the resolution or format. There are two parts to each rule:<br>
*The filter settings - The rule will only apply to textures when the original texture properties match the values given by the filter settings.
*The overwrite settings - If a texture matches the filter, these properties are applied. The idea is that via these rules you can tell Cemu which textures to modify and how to modify them.
Note that texture rules are applied upon creation of the texture. Multiple rules can apply to the same textures as long as they don't interfere with each other (e.g. one rule to set the width/height and another rule to set the format)
{| class="wikitable"
!colspan="2"|Variables in the section [TextureRedefine]
|-
!<small>variable</small>
!<small>description</small>
|-
|<pre>width</pre>
|The width of the texture that you want to modify
|-
|<pre>height</pre>
|The height of the texture that you want to modify
|-
|<pre>formats</pre>
|Texture format must match any of these ('0x' prefix denotes hexadecimal format, can contain multiple formats separated by comma)
|-
|<pre>overwriteLodBias</pre>
|Overwrites the game's lod bias. Typical valid values are in range -16.0 to 16.0
|-
|<pre>overwriteRelativeLodBias</pre>
|Add value to game's lod bias rather than overwriting it. Typical valid values are in range -16.0 to 16.0
|-
|<pre>depth</pre>
|Unknown usage
|-
|<pre>tilemodes</pre>
|Unknown usage
|-
|<pre>formatsExcluded</pre>
|If any of the filter settings above are omitted they are not evaluated. This allows you to write a rule that, for example, only filters for the width of a texture but not the height.
|-
|<pre>tileModesExcluded</pre>
|Skips CPU-generated textures, generally used by videos (ex. Xenoblade Chronicles X, Bayonetta 2)
|-
|<pre>overwriteFormat</pre>
|Replaces all the formats under this resolution (unless included/excluded via formats/excludeFormats) with the one defined here.
|-
|<pre>overwriteDepth</pre>
|Unknown usage
|-
|<pre>overwriteWidth</pre>
|Like filter settings you can omit individual overwrite settings. This allows to selectively overwrite the width but not the height etc.
|-
|<pre>overwriteHeight</pre>
|Like filter settings you can omit individual overwrite settings. This allows to selectively overwrite the width but not the height etc.
|}
=== Common use case example===
Many games run in 1280x720 resolution and we would like to use a textureRule to upscale those games to 1920x1080 or 2560x1440. <br>
Here is how it would look:
<pre>
[Preset]
name = 1920x1080
$width = 1920
$height = 1080
[Preset]
name = 2560x1440
$width = 2560
$height = 1440
[TextureRedefine]
width = 1280
height = 720
overwriteWidth = $width
overwriteHeight = $height
</pre>
This rule applies to all textures that have a resolution of 1280x720 and overwrites their resolution to whatever preset is chosen. Depending on the game, this might suffice for simple upscaling. However, since the filter settings in this example are very loose (only width and height is checked) the rule might catch unwanted textures. Some games use background or splash screen textures that have the same resolution as the intended screen resolution. Since Cemu resets the contents of a texture if any rule is applied, you would end up with a black background. A workaround for this is to use the texture dump feature of Cemu and figure out more exact filters.
===Modifying Game Files===
With Cemu 1.15.0, it's possible to use graphic packs as a way of applying game mods. In order to apply game mods using graphic packs, you need to set it up just like SDCaffine (content folder with the modified files inside that folder).
<pre>
Splatoon_Mod_TakorokaFlipMesh/content/model/Hed_CAP002.szs
Splatoon_Mod_TakorokaFlipMesh/rules.txt
</pre>
===List of all texture formats===
{| class="wikitable"
!name
!value
|-
|R8_UNORM
|0x00000001
|-
|R8_UINT
|0x00000101
|-
|R8_SNORM
|0x00000201
|-
|R8_SINT
|0x00000301
|-
|R4_G4_UNORM
|0x00000002
|-
|R16_UNORM
|0x00000005
|-
|R16_UINT
|0x00000105
|-
|R16_SNORM
|0x00000205
|-
|R16_SINT
|0x00000305
|-
|R16_FLOAT
|0x00000806
|-
|R8_G8_UNORM
|0x00000007
|-
|R8_G8_UINT
|0x00000107
|-
|R8_G8_SNORM
|0x00000207
|-
|R8_G8_SINT
|0x00000307
|-
|R5_G6_B5_UNORM
|0x00000008
|-
|R5_G5_B5_A1_UNORM
|0x0000000a
|-
|R4_G4_B4_A4_UNORM
|0x0000000b
|-
|A1_B5_G5_R5_UNORM
|0x0000000c
|-
|R32_UINT
|0x0000010d
|-
|R32_SINT
|0x0000030d
|-
|R32_FLOAT
|0x0000080e
|-
|R16_G16_UNORM
|0x0000000f
|-
|R16_G16_UINT
|0x0000010f
|-
|R16_G16_SNORM
|0x0000020f
|-
|R16_G16_SINT
|0x0000030f
|-
|R16_G16_FLOAT
|0x00000810
|-
|D24_S8_UNORM
|0x00000011
|-
|X24_G8_UINT
|0x00000111
|-
|D24_S8_FLOAT
|0x00000811
|-
|R11_G11_B10_FLOAT
|0x00000816
|-
|R10_G10_B10_A2_UNORM
|0x00000019
|-
|R10_G10_B10_A2_UINT
|0x00000119
|-
|R10_G10_B10_A2_SNORM
|0x00000219
|-
|R10_G10_B10_A2_SINT
|0x00000319
|-
|R10_G10_B10_A2_SRGB
|0x00000419
|-
|R8_G8_B8_A8_UNORM
|0x0000001a
|-
|R8_G8_B8_A8_UINT
|0x0000011a
|-
|R8_G8_B8_A8_SNORM
|0x0000021a
|-
|R8_G8_B8_A8_SINT
|0x0000031a
|-
|R8_G8_B8_A8_SRGB
|0x0000041a
|-
|A2_B10_G10_R10_UNORM
|0x0000001b
|-
|A2_B10_G10_R10_UINT
|0x0000011b
|-
|D32_FLOAT_S8_UINT_X24
|0x0000081c
|-
|X32_G8_UINT_X24
|0x0000011c
|-
|R32_G32_UINT
|0x0000011d
|-
|R32_G32_SINT
|0x0000031d
|-
|R32_G32_FLOAT
|0x0000081e
|-
|R16_G16_B16_A16_UNORM
|0x0000001f
|-
|R16_G16_B16_A16_UINT
|0x0000011f
|-
|R16_G16_B16_A16_SNORM
|0x0000021f
|-
|R16_G16_B16_A16_SINT
|0x0000031f
|-
|R16_G16_B16_A16_FLOAT
|0x00000820
|-
|R32_G32_B32_A32_UINT
|0x00000122
|-
|R32_G32_B32_A32_SINT
|0x00000322
|-
|R32_G32_B32_A32_FLOAT
|0x00000823
|-
|BC1_UNORM
|0x00000031
|-
|BC1_SRGB
|0x00000431
|-
|BC2_UNORM
|0x00000032
|-
|BC2_SRGB
|0x00000432
|-
|BC3_UNORM
|0x00000033
|-
|BC3_SRGB
|0x00000433
|-
|BC4_UNORM
|0x00000034
|-
|BC4_SNORM
|0x00000234
|-
|BC5_UNORM
|0x00000035
|-
|BC5_SNORM
|0x00000235
|}
===Shader replacement===
Wii U's GPU supports a fully programmable pipeline. Meaning each drawcall is associated with a vertex and pixel shader and an optional geometry shader.
Cemu's graphic pack feature allows to overwrite individual shaders giving control over many aspects of a game's render pipeline.
In order to get access to the shaders that are used by Cemu you can enable the debug option 'Dump shaders' before or while a game is running.
Since the shaders generated by Cemu are translated from low-level binary instructions they contain little to no human-readable information. You likely won't be able to figure out what a shader does just by looking at it's source.
Therefore it is recommended to use third-party tools like Nvidia's NSIGHT or AMD's GPU PerfStudio to do realtime graphics debugging while a game is running in Cemu.
Once you have located a shader that you want to edit, you can copy it from the dump/shaders/ directory into your graphics pack. You then can make any adjustments you want to the shader source. Any GLSL compilation errors will be written to log.txt
====Use shader editing to fix bloom, blur or other scaling issues====
<i>This guide assumes that you know how to install and use Nsight to debug Cemu. Read the tutorial in Clarity's readme.txt for more info about how to install Nsight and start games with it. This tutorial is very basic and having prior knowledge of shaders or OpenGL is very handy as this tutorial just gives some handles, hopefully. If something isn't clear, you can ask in the official Cemu discord's graphic pack channel.</i>
#Get the vertex shader (usually the one that needs fixing, however if that doesn't give any results you can try the pixel shader that's used) by using Nsight's preview to get to the event and using the events tab to see which vertex shader gets used in the event that applies the bloom.
#Sometimes these shaders look very familiar and use the <code>uf_remappedVS[0]</code> which makes it very easy, just divide those by the scale (and find the axis', uf_remappedVS[0].x doesn't have to be the X, but it's usually like that). Sometimes they're paired (or are standalone) with things like weird random hex values like `intBitsToFloat(0x3fb) `, which could be a good indicator which line of variables you'll need to change. Other times, it's just an annoying shader and you'll need to try and try again until you've got the right section and then see how to change them correctly. Pixel shaders usually get fixed by trial and error. Most of the time you'll need to divide that variable by 3 for 4k, 2 for 1440p.
#Get the shader (with vertex shader you don't have to as they always end with <code>_0000000000000000_vs.txt</code>, just prefix that with the part from the shader, e.g. <code>// shader 315d61ad21f97614</code>) and create a text file named (using the previous info) <code>315d61ad21f97614_0000000000000000_vs.txt</code> and put the edited shader code in there with the changed variables.
#Optional if you don't want to make it public: Now you run the game and check if the shader is working (check Cemu's log.txt if you don't see any change, there might be an error). Don't forget to enable the graphic pack ;). If the static resolution works and you want to put them into this repository, you'll need to convert it to use the build script. You'll need to put in some extra code, so copy and paste this at the top of the shader file.
<pre>
<?php
include 'Source/functions.php';
$fullWidth = $argv[1];
$fullHeight = $argv[2];
$scaleFactorX = always_decimal_format($fullWidth / 1280.0);
$scaleFactorY = always_decimal_format($fullHeight / 720.0);
?>
</pre> You'll have to change those resolution numbers to the native res of the game.
You also have to put in a section like
<pre>
const float resXScale = <?=$scaleFactorX?>;
const float resYScale = <?=$scaleFactorY?>;
</pre><b>under</b> the name of the shader, so under the line that, for example, says <code>// shader 315d61ad21f97614</code>. Now you use <b>resXScale</b> and <b>resYScale</b> to change those variables instead of the static value you had previously. You can now make a pull request to this repository or give it to some folks in the discord that can upload these if you don't have/want a github account.
====Scaling pesky integer uf_remapped blocks====
Rules.txt doesnt always take care of values that are referenced in integer uf_remapped. Fixing them takes a lot of poking around.. But if you just want to throw enough crap against the wall to see what sticks, you can convert all of them and use divide and conquer to sort out what breaks
<b>RegEx Search for PS and VS</b>
<code> ([\+\-] intBitsToFloat\(uf_remapped(?:PS|VS)\[([0-9]|[1-9][0-9])\]\.[xyzw]\)) </code>
<b>Call-back</b>
<code>\1 /resXScale </code>
<b>Example</b>
<pre>
R126f.y = (PV0f.y + intBitsToFloat(uf_remappedPS[0].y) + R8f.x);
will match
+ intBitsToFloat(uf_remappedPS[0].y)
and replace with
R126f.y = (PV0f.y + intBitsToFloat(uf_remappedPS[0].y) /resXScale + R8f.x);
</pre>
<b>RegEx Search for common XYZ lookup</b>
<code>(intBitsToFloat\(uf_remapped(?:PS|VS)\[(?:[0-9])\]\.[xyzw]\))(,intBitsToFloat\(uf_remapped(?:PS|VS)\[(?:[0-9])\]\.[xyzw]\))(,intBitsToFloat\(uf_remapped(?:PS|VS)\[(?:[0-9])\]\.[xyzw]\))</code>
<b>Call-back</b>
<code>\1/resXScale \2/resXScale \3/resXScale</code>