Merge pull request #1 from Unity-Technologies/Documentation

Documentation update

Author: frostebite

Documentation/(v2)-Adobe-Photoshop.md

@@ -0,0 +1,42 @@
+Please note that using Photoshop for grading isn't recommended as it only has very limited capabilities when it comes to 32bit editing.
+
+### Step 1
+
+Export the current frame in Log as EXR without color grading applied.
+
+![Export Log EXR](images/export-exr-log.png)
+
+
+
+### Step 2
+
+Open the previously exported EXR file in Photoshop. It should look like a Log footage.
+
+### Step 3
+
+Add a non-destructive color lookup adjustment layer to your image and use the `Unity Log To Linear` LUT that you'll find in `/PostProcessing/Textures/Cubes/`.
+
+![Photoshop Log to Linear LUT](images/photoshop-log-lut.png)
+
+
+### Step 4
+
+You can now start grading your image. Make sure you only do global color operation through the use of non-destructive adjustment layers. Local operators, filters or any effect that has an effect on neighbor pixels (e.g. blur) can't be stored in LUTs.
+
+### Step 5
+
+Once you're done, export a CUBE by going to `File -> Export -> Color Lookup Tables` and use the following settings:
+
+![Photoshop Generate LUT](images/photoshop-gen-lut.png)
+
+Save the resulting file somewhere in your `Assets` folder.
+
+### Step 6
+
+Back in Unity, it will detect the CUBE and automatically convert it to a `Texture3D` asset. Grab this texture and populate the `Lookup Texture` field in the color grading effect.
+
+![Color Grading LUT](images/color-grading-external-lut.png)
+
+And you're done. You can keep grading in Photoshop and override the previously saved CUBE file, Unity will automatically update the `Texture3D` used for real-time grading.
+
+Volume blending with external LUTs is, of course, supported out-of-the-box.

Documentation/(v2)-DaVinci-Resolve.md

@@ -0,0 +1,41 @@
+Before you can work in Resolve you'll need a one-time setup step: copy all the CUBE files from `/PostProcessing/Textures/Cubes/` to Resolve's LUT folder. You can find this folder by opening Resolve, going to `Project Settings -> Color Management` and clicking `Open LUT Folder`. We recommend you put them into a separate folder, say `Unity`, for easier access later on. Don't forget to click on `Update List` after you've copied the LUTs.
+
+Let's go over the workflow to grade Unity scenes in Resolve.
+
+### Step 1
+
+Export the current frame in Log as EXR without color grading applied.
+
+![Export Log EXR](images/export-exr-log.png)
+
+### Step 2
+
+Open the previously exported EXR file in Resolve. It will look wrong, but that's expected. Resolve, by default, will display EXR files in linear mode. Go to `Project Settings -> Color Management` and set the `3D Video Monitor Lookup Table` to `Linear to sRGB`. The EXR should now look like a Log footage.
+
+![Resolve Project Settings](images/resolve-project-settings.png)
+
+### Step 3
+
+In the node view or the color editing panel, right-click the only color grading node there is and assign the `Unity Log To Linear` 3D LUT to it. It should now look exactly like it does in the Editor.
+
+![Resolve Log to Linear](images/resolve-log-lut.png)
+
+### Step 4
+
+You can now start grading your image. Use as many node as you'd like to move between color spaces but make sure you only do global color operations. Local operators & filters can't be store in LUTs.
+
+### Step 5
+
+Once you're done, export a CUBE by right-clicking the clip and choosing `Generate 3D LUT (CUBE)`. Save the resulting file somewhere in your `Assets` folder.
+
+![Resolve Generate LUT](images/resolve-gen-lut.png)
+
+### Step 6
+
+Back in Unity, it will detect the CUBE and automatically convert it to a `Texture3D` asset. Grab this texture and populate the `Lookup Texture` field in the color grading effect.
+
+![Color Grading LUT](images/color-grading-external-lut.png)
+
+And you're done. You can keep grading in Resolve and override the previously saved CUBE file, Unity will automatically update the `Texture3D` used for real-time grading.
+
+Volume blending with external LUTs is, of course, supported out-of-the-box.

Documentation/(v2)-External-LUT-authoring.md

@@ -0,0 +1,8 @@
+The color grading effect has been improved a lot in v2. One of its new feature is the ability to author 3D LUTs in external DCC tools like Adobe's Photoshop, DaVinci's Resolve, The Foundry's Nuke etc and import CUBE LUTs straight into Unity.
+
+This feature requires support for Texture3D and compute shaders.
+
+This guide won't go over color grading theory so you should already be familiar with at least one of the softwares in this guide. We'll only focus on the proper setup for creating CUBEs in external software (with sRGB displays as target), importing & using them into Unity.
+
+* [[DaVinci Resolve|(v2)-DaVinci-Resolve]]
+* [[Adobe Photoshop|(v2)-Adobe-Photoshop]]

Documentation/Ambient-Occlusion.md

@@ -0,0 +1,63 @@
+The **Ambient Occlusion** post-processing effect approximates [Ambient Occlusion](http://en.wikipedia.org/wiki/Ambient_occlusion) in real time as a full-screen post-processing effect. It darkens creases, holes, intersections and surfaces that are close to each other. In real life, such areas tend to block out or occlude ambient light, hence they appear darker.
+
+Note that the **Ambient Occlusion** effect is quite expensive in terms of processing time and generally should only be used on desktop or console hardware. Its cost depends purely on screen resolution and the effects parameters and does not depend on scene complexity as true ambient occlusion would.
+
+> **TODO:** before/after screenshot
+
+The effect comes with two modes:
+
+- Scalable Ambient Obscurance
+- Multi-scale Volumetric Occlusion
+
+## Scalable Ambient Obscurance
+
+This is a standard implementation of ambient obscurance that works on non modern platforms. If you target a compute-enabled platform we recommend that you use the **Multi-scale Volumetric Occlusion** mode instead.
+
+![Scalable Ambient Obscurance](images/ssao-1.png)
+
+### Properties
+
+| Property     | Function                                                     |
+| :------------ | :------------------------------------------------------------ |
+| Intensity    | Degree of darkness produced by the effect.                   |
+| Radius       | Radius of sample points, which affects extent of darkened areas. |
+| Quality      | Defines the number of sample points, which affects quality and performance. |
+| Color        | Tint of the ambient occlusion.                               |
+| Ambient Only | Enables the ambient-only mode in that the effect only affects ambient lighting. This mode is only available with the Deferred rendering path and HDR rendering. |
+
+### Performances
+
+Beware that this effect can be quite expensive, especially when viewed very close to the camera. For that reason it is recommended to favor a low `Radius` setting. With a low `Radius` the ambient occlusion effect will only sample pixels that are close, in clip space, to the source pixel, which is good for performance as they can be cached efficiently. With higher radiuses, the generated samples will be further away from the source pixel and won’t benefit from caching thus slowing down the effect. Because of the camera’s perspective, objects near the front plane will use larger radiuses than those far away, so computing the ambient occlusion pass for an object close to the camera will be slower than for an object further away that only occupies a few pixels on screen.
+
+Dropping the `Quality` setting down will improve performances too.
+
+Generally speaking, this effect should not be considered on mobile platforms and when running on consoles we recommend using the **Multi-scale Volumetric Occlusion** mode as it's much faster there and looks better in most cases.
+
+### Requirements
+
+- Depth & Normals textures
+- Shader model 3
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.
+
+## Multi-scale Volumetric Occlusion
+
+This is a more modern version of ambient occlusion heavily optimized for consoles and desktop platforms. It generally looks better and runs faster than the other mode on these platforms but requires compute shader support.
+
+![Multi-scale Volumetric Occlusion](images/ssao-2.png)
+
+### Properties
+
+| Property           | Function                                                     |
+| :------------------ | :------------------------------------------------------------ |
+| Intensity          | Degree of darkness produced by the effect.                   |
+| Thickness Modifier | Modifies the thickness of occluders. This increases dark areas but can potentially introduces dark halos around objects. |
+| Color              | Tint of the ambient occlusion.                               |
+| Ambient Only       | Enables the ambient-only mode in that the effect only affects ambient lighting. This mode is only available with the Deferred rendering path and HDR rendering. |
+
+### Requirements
+
+- Compute shader support
+- Shader model 4.5
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.

Documentation/Anti-aliasing.md

@@ -0,0 +1,91 @@
+The **Anti-aliasing** effect offers a set of algorithms designed to prevent aliasing and give a smoother appearance to graphics. Aliasing is an effect where lines appear jagged or have a “staircase” appearance (as displayed in the left-hand image below). This can happen if the graphics output device does not have a high enough resolution to display a straight line.
+
+**Anti-aliasing** reduces the prominence of these jagged lines by surrounding them with intermediate shades of color. Although this reduces the jagged appearance of the lines, it also makes them blurrier.
+
+> **TODO:** before/after screenshot
+
+The Anti-aliasing algorithms are image-based. This is very useful when traditional multisampling (as used in the Editor’s [Quality settings](https://docs.unity3d.com/Manual/class-QualitySettings.html)) is not properly supported or when working with specular-heavy PBR materials.
+
+The algorithms supplied in the post-processing stack are:
+
+- Fast Approximate Anti-aliasing (FXAA)
+- Subpixel Morphological Anti-aliasing (SMAA)
+- Temporal Anti-aliasing (TAA)
+
+They are set per-camera on the **Post-process Layer** component.
+
+## Fast Approximate Anti-aliasing
+
+**FXAA** is the cheapest technique and is recommended for mobile and other platforms that don’t support motion vectors, which are required for **TAA**.
+
+![Fast Approximate Anti-aliasing](images/aa-1.png)
+
+### Properties
+
+| Property   | Function                                                     |
+| :--------- | :----------------------------------------------------------- |
+| Fast Mode  | A slightly lower quality but faster variant of FXAA. Highly recommended on mobile platforms. |
+| Keep Alpha | Toggle this on if you need to keep the alpha channel untouched by post-processing. Else it will use this channel to store internal data used to speed up and improve visual quality. |
+
+### Performances
+
+`Fast Mode` should be enabled on mobile & Nintendo Switch as it gives a substantial performance boost compared to the regular mode on these platforms. PS4 and Xbox One slightly benefit from it as well but on desktop GPUs it makes no difference and the regular mode should be used for added visual quality.
+
+### Requirements
+
+- Shader Model 3
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.
+
+## Subpixel Morphological Anti-aliasing
+
+**SMAA** is a higher quality anti-aliasing effect than **FXAA** but it's also slower. Depending on the art-style of your game it can work as well as **TAA** while avoiding some of the shortcomings of this technique.
+
+![Subpixel Morphological Anti-aliasing](images/aa-2.png)
+
+### Properties
+
+| Property | Function                                         |
+| :-------- | :------------------------------------------------ |
+| Quality  | The overall quality of the anti-aliasing filter. |
+
+### Performances
+
+Lowering the `Quality` setting will make the effect run faster. Using **SMAA** on mobile platforms isn't recommended.
+
+### Known issues and limitations
+
+- SMAA doesn't support AR/VR.
+
+### Requirements
+
+- Shader Model 3
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.
+
+## Temporal Anti-aliasing
+
+**TAA** is a more advanced anti-aliasing technique where frames are accumulated over time in a history buffer to be used to smooth edges more effectively. It is substantially better at smoothing edges in motion but requires motion vectors and is more expensive than **FXAA**. Due to this it is recommended for desktop and console platforms.
+
+![Temporal Anti-aliasing](images/aa-3.png)
+
+### Properties
+
+| Property            | Function                                                     |
+| :------------------- | :------------------------------------------------------------ |
+| Jitter Spread       | The diameter (in texels) inside which jitter samples are spread. Smaller values result in crisper but more aliased output, whilst larger values result in more stable but blurrier output. |
+| Stationary Blending | The blend coefficient for stationary fragments. Controls the percentage of history sample blended into final color for fragments with minimal active motion. |
+| Motion Blending     | The blending coefficient for moving fragments. Controls the percentage of history sample blended into the final color for fragments with significant active motion. |
+| Sharpness           | TAA can induce a slight loss of details in high frequency regions. Sharpening alleviates this issue. |
+
+### Known issues and limitations
+
+- Not supported on GLES2 platforms.
+
+### Requirements
+
+- Motion vectors
+- Depth texture
+- Shader Model 3
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.

Documentation/Auto-Exposure.md

@@ -0,0 +1,45 @@
+In ocular physiology, adaptation is the ability of the eye to adjust to various levels of darkness and light. The human eye can function from very dark to very bright levels of light. However, in any given moment of time, the eye can only sense a contrast ratio of roughly one millionth of the total range. What enables the wider reach is that the eye adapts its definition of what is black.
+
+This effect dynamically adjusts the exposure of the image according to the range of brightness levels it contains. The adjustment takes place gradually over a period of time, so the player can be briefly dazzled by bright outdoor light when, say, emerging from a dark tunnel. Equally, when moving from a bright scene to a dark one, the “eye” takes some time to adjust.
+
+Internally, this effect generates a histogram on every frame and filters it to find the average luminance value. This histogram, and as such the effect, requires [Compute shader](https://docs.unity3d.com/Manual/ComputeShaders.html) support.
+
+> **TODO:** before/after screenshot
+
+![Auto Exposure](images/autoexposure.png)
+
+### Properties
+
+**Exposure** settings:
+
+| Property              | Function                                                     |
+| :--------------------- | :------------------------------------------------------------ |
+| Filtering             | These values are the lower and upper percentages of the histogram that will be used to find a stable average luminance. Values outside of this range will be discarded and wont contribute to the average luminance. |
+| Minimum               | Minimum average luminance to consider for auto exposure (in EV). |
+| Maximum               | Maximum average luminance to consider for auto exposure (in EV). |
+| Exposure Compensation | Middle-grey value. Use this to compensate the global exposure of the scene. |
+
+**Adaptation** settings:
+
+| Property   | Function                                                     |
+| :---------- | :------------------------------------------------------------ |
+| Type       | Use Progressive if you want the auto exposure to be animated. Use Fixed otherwise. |
+| Speed Up   | Adaptation speed from a dark to a light environment.         |
+| Speed Down | Adaptation speed from a light to a dark environment.         |
+
+### Details
+
+Use the `Filtering` range to exclude the darkest and brightest part of the image. To compute an average luminance you generally don’t want very dark and very bright pixels to contribute too much to the result. Values are in percent.
+
+`Minimum`/`Maximum` values clamp the computed average luminance into a given range.
+
+You can also set the `Type` to `Fixed` if you don’t need the eye adaptation effect and it will behave like an auto-exposure setting.
+
+It is recommended to use the **Light Meter** [monitor](https://github.com/Unity-Technologies/PostProcessing/wiki/Debugging) when setting up this effect.
+
+### Requirements
+
+- Compute shader
+- Shader model 5
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.

Documentation/Bloom.md

@@ -0,0 +1,44 @@
+**Bloom** is an effect used to reproduce an imaging artifact of real-world cameras. The effect produces fringes of light extending from the borders of bright areas in an image, contributing to the illusion of an extremely bright light overwhelming the camera or eye capturing the scene.
+
+**Lens Dirt** applies a fullscreen layer of smudges or dust to diffract the Bloom effect. This is commonly used in modern first person shooters.
+
+> **TODO:** before/after screenshot
+
+![Bloom](images/bloom.png)
+
+### Properties
+
+**Bloom** settings:
+
+| Property         | Function                                                     |
+| :---------------- | :------------------------------------------------------------ |
+| Intensity        | Strength of the Bloom filter.                                |
+| Threshold        | Filters out pixels under this level of brightness. This value is expressed in gamma-space. |
+| Soft Knee        | Makes transition between under/over-threshold gradual (0 = hard threshold, 1 = soft threshold). |
+| Diffusion        | Changes extent of veiling effects in a screen resolution-independent fashion. |
+| Anamorphic Ratio | Emulates the effect of an anamorphic lens by scaling the bloom vertically (in range [-1,0]) or horizontally (in range [0,1]). |
+| Color            | Tint of the Bloom filter.                                    |
+| Fast Mode        | Boost performances by lowering the effect quality.           |
+
+**Dirtiness** settings:
+
+| Property  | Function                                              |
+| --------- | ----------------------------------------------------- |
+| Texture   | Dirtiness texture to add smudges or dust to the lens. |
+| Intensity | Amount of lens dirtiness.                             |
+
+### Details
+
+With properly exposed HDR scenes, `Threshold` should be set to ~1 so that only pixels with values above 1 leak into surrounding objects. You’ll probably want to drop this value when working in LDR or the effect won’t be visible.
+
+### Performances
+
+Lowering the `Diffusion` parameter will make the effect faster. The further away `Anamorphic Ratio` is from 0, the slower it will be. On mobile and low-end platforms it is recommended to enable `Fast Mode` as it gives a significant boost in performances.
+
+Finally, smaller lens dirt textures will result is faster lookup and blending across volumes.
+
+### Requirements
+
+- Shader model 3
+
+See the [Graphics Hardware Capabilities and Emulation](https://docs.unity3d.com/Manual/GraphicsEmulation.html) page for further details and a list of compliant hardware.