Unity Legacy to High Definition Render Pipeline conversion tutorial
The HDRP uses a new set of Shaders and new lighting units, both of which are incompatible with the built-in Unity rendering pipeline. To upgrade a Unity Project to HDRP, you must first convert all of the Materials and Shaders in your Project, and then edit your individual Light settings accordingly.
This tutorial explains the HDRP upgrade process using a sample Scene containing Assets from Unity’s Viking Village Asset package. To get the Scene used in this example, download this LegacyScene package.
Setting up the High Definition Render Pipeline (HDRP)
First, add the HDRP package to your existing Project:
In the Unity Editor, open the Package Manager window (menu: Window > Package Manager).
In the menu at the top of the window, change the package list, located in the top left, to All packages. Then, select Advanced > Show Preview Packages. Now, find and select the Render-Pipelines.High-Definition package, and click Install.
Next, create and set up a High Definition Render Pipeline Asset.
Create an HDRP Asset by selecting Assets > Create > Rendering > High Definition Render Pipeline Asset.
Open the Graphics Settings window (menu: Edit > Project Settings > Graphics).
Assign the High Definition Render Pipeline Asset to the Scriptable Render Pipelines Settings field, at the top of the window. To do this, click the radio button and select the Asset from the list, or drag the Asset into the field.
After installing the HDRP package and assigning the HDRP Asset, your Scene will not render correctly (see screenshot below). This is because the Scene still uses the built-in Shaders. The following section shows you how to upgrade these built-in Shaders to an HDRP-compatible shader .
To upgrade the Materials in your Scene to HDRP-compatible Materials, navigate to Edit > Render Pipeline and select one of the following options:
Upgrade Project Materials to High Definition Materials: Converts all compatible Materials in your Project to HDRP Materials.
Upgrade Selected Materials to High Definition Materials: Converts Materials that are currently selected in the Project window.
If your Project contains any custom Materials or Shaders then this script will not automatically update them to HDRP. You must convert these Materials and Shaders manually.
Firstly, you need to change your Color Space to Linear. Navigate to Edit > Settings > Player and, in the Other Settings section, set the Color Space to Linear.
The HDRP uses physical Light units to control the intensity of Lights. This means that these units will not match the arbitrary units that the built-in render pipeline uses.
So, in the case of the example Scene, start by adding a Directional Light to represent the main, natural light in this Scene: the Moon. A full Moon, on a clear night sky, has a luminous flux of around 0.25 Lux.
Disable all other Lights in the Scene to exclusively see the effect of the Light representing the Moon.
HDRP handles the Sky in a differently to the built-in render pipeline, to allow you to alter Sky parameters dynamically at run time using the Volume script.
Select GameObject > Rendering > Scene Settings and adjust the following settings for best effect:
HD Shadow Settings : The maximum shadow distance and the directional shadow cascade settings.
Visual Environment : The Sky and Fog type of your Scene.
Procedural Sky : This is a port of the legacy procedural Sky and contains the same settings.
Exponential Fog : The default Fog, that can handle fields such as Density, Color Mode, Fog Distance, and Fog Height.
Additionally, the GameObject also has a Baking Sky component, that references the Volume’s procedural Sky. This component passes the Sky data to the lightmapper and only one should ever be present in the Scene at any time. Otherwise, Unity will exclusively use the first loaded Baking Sky component, and a warning in shown in the console.
Below are the values used for this example’s Procedural Sky:
The Procedural Sky’s light intensity is expressed as Exposure and Multiplier. To convert to Lux, set exposure to 0 Exposure Value (EV) and use the Multiplier as the Lux value. To create believable visuals in this example, set the Multiplier to 0.02 Lux. You can increase the value to 0.05 to make the Scene more visible, while still being low enough to be plausible.
At this point, you can Generate Lighting in this Scene to create light bounces and directional soft shadows. Go to Window > Rendering > Lighting Settings and, near the bottom of the Scene tab, click Generate Lighting.
Fire-lit torches are usually around 100 to 140 Lumen so set the Intensity of the Point Lights in the Sene to somewhere between these two values, and make sure you set their Mode to Baked. Baked lighting allows you to use smooth shadows baked into lightmaps.
You’ll also notice that the Light Cookie no longer works. That’s because HDRP uses standard textures as Light Cookies, and handles colored cookies. Simply change the cookie texture (named "TorchCookie") import settings to these:
Texture Type to default
Texture Shape to Cube
Mapping to Latitude-Longitude Layout (Cylindrical)
Disable sRGB (Color Texture)
Alpha Source to None
Disable Border Mip Maps
Wrap Mode to Clamp
Click Generate Lighting again. The Scene now looks like this:
Press the Play button and you will see the following in your Game window:
If you compare this to the legacy screenshot, the changes may not be obvious. This is because this example does not use any of the new HDRP-specific Material features such as anisotropy, subsurface scattering, or parallax occlusion mapping, and the original Materials were already PBR compliant.
Converting the template Scene
The 3D With Extras template Scene is another Scene that is interesting to test the conversion process on. You can get the Project by opening Unity Hub, creating a new Project, and selecting 3D With Extras from the Template drop-down. After you create and open the Project, you will see the following Scene:
Like with the previous conversion example, import the HDRP package (menu: Window > Package Manager), and run the converter (Edit > Render Pipeline).
You must modify some of the GameObjects in the Scene so they behave correctly:
Add an Auto Exposure effect to the Post Process Volume script attached to the Post-process Volume GameObject (Add effect > Unity > Auto Exposure).
Enable the Minimum (EV), Maximum (EV) and Exposure Compensation settings and then set them to the following values:
This accommodates the high difference in light exposition values (Min and Max) and the overall high exposure.
The conversion process may have altered the size of the Reflection Probes. If so, alter the Box Size field for each Reflection Probe until they match the size of the area they are in.
Set the Intensity of the Light representing the Sun (the Light attached to the Directional Light GameObject in the Scene) to 100000.
Create a Scene Settings GameObject (GameObject > Rendering > Scene Settings) and set the sky Exposure to 0 and the Multiplier to 20000.
Set the intensity of the Light attached to the Spot Light GameObject to 17000. This is because there are two 8500 lumen lamps. Enable Angle Affect Intensity to compensate for the spot angle and its reflector.
Correct the Light cookie (Spotlight_Cookie), as shown in the cookie correction section in the previous example.
Set the emissive intensity of the light bulb Material (LightBulb_Mat) to 13.05. Click on the Emissive Color picker and manually enter 13.05 into the __Intensity __field. This value is much lower than the others because the emission color intensity uses EV units and the other values use Lumen. To convert between the two, see the following formulas. Exposure Value is a scale of powers of 2. This means that
x EV = 2 ^ x Lumenand
y Lumen is ln( y EV ) / ln( 2 )
13.05 EV is: 2 ^ 13.05 = 8480 Lumen therefore
8480 Lumen is: ln( 8480 ) / ln( 2 ) = 13.05 EV
- Click Generate Lighting to re-bake the lighting.
You should now have a Scene similar to this:
Note how the lighting is different from the original screenshot, and from the original HDRP template. The HDRP template examples were made to look good but were not realistic, whereas this Scene uses physically correct light values: an afternoon direct sun with no clouds in the sky is much brighter than even the best professional construction spotlight. However, the spotlight is still casting light and shadows on the side of the wall.
Converting Materials manually
The HDRP Material converter automatically converts Legacy Standards and Unlit Materials to HDRP Lit and Unlit Materials respectively. This section describes the steps the converter takes, to help you convert custom Materials manually.
The mask map
The Legacy Standard to Lit conversion process combines the different Material maps of the Legacy Standard into the separate RGBA channels of the mask map in the HDRP Lit Material.
Metallic goes in the Red channel
Occlusion goes in the Green channel
Detail Mask goes in the Blue channel
Smoothness goes in the Alpha channel
The detail map
The Legacy Standard to Lit conversion process combines the different detail maps of the Legacy Standard into the separate RGBA channels of the detail map in the HDRP Lit Material. It also adds a smoothness detail too.
Albedo is desaturated and goes in the Red channel
Normal Y goes in the Green channel
Smoothness goes in the Blue channel
Normal X goes in the Alpha channel
The process blends detail albedo and smoothness with the base values using an overlay function, similar to the process you would use in image editing software, like Photoshop.