Official [SURVEY] URP Documentation & Guidelines Improvements

Wonderful someone is going to take on this challenge

setting up new projects, this is still a challenge for many as they don’t grasp the concept about how render pipeline asset files works.. if you could make a full document showing a relationship chat between render pipeline asset / global settings / quality levels explaining that the global apply within scene view and quality apply within game view plus show branch connections for other settings such as look Dev..

 

Most Unity documentation is based on the Unity version “Year”
this could be incorrect or not a good practice within SRP as one unity version may have multiple api versions within it, each api even within its own cycle have changes

 

Unity has very poor tracking in real-time about applicable api versions vs unity versions. most documentation unity does have for tracking api versions is incorrect due to the slow process to trickle down changes

 

ApiCompatibilityLevel .Net Framework
Unity - Scripting API: ApiCompatibilityLevel (unity3d.com)
Unity could use more documentation with what framework could be used showing a table based on unity version

 

Lets start off with:
Where are the new update logs for all new versions this year?
What is the policy behind updates?
Lighting system, main light, additional lights, vertex lighting differ wildly from built-in lighting. Will there be information on such critical information?
Why are we restricted in terms of render feature for cameras? We have no control over post process so we are expected to implement such features as render features. However, we have no control over toggling so we need to set cameras to have feature 1 enabled and 2 disabled and so on. For 5 features, we need up to 32 renderers.
Why is SRP forced on for later versions of URP? This breaks compatibility with the frame debug as we cannot see what values are given to an object due to batching. Breaking the batching is trivial but you can't do it for shaders provided by urp (unless urp is custom package) and it can't be done on deployed level. Previously it was easy to do so, just tick off srp batcher and debugging on devices were easy.

 

I have a 2d top down view game. Imagine a chess board but with many many more players. How do I cull a gameObject from one camera but not from the other. How would I write a code that allows me to cull only the white players pawns from the black players camera, but still allow the white player to be able to see them if both player's cameras are looking at the same spot at the same time?

- My game is intended to be multiplayer and have more than 32 players. As a result I can not use the layer system.
-I've tried to dig into the layer code to change it from a 32bit to 64bit but unity wont let you do that either. It just keeps reseting the code on me.
- I've looked at the cullingGroup.targetCamera forums/help docs and they all have silly codes like gameObj.SetActive(true) || false. Or set game obj color to red || blue... This isn't actually cull'ing anything it just changes prevents any&all cameras from being able to see the gameObj || changes the gameObj's color for all cameras.

im out of ideas here.

 

Hey man how do I update my assets to urp
This latest release doesn’t seem to have that option in edit,rendering
Upgrade project to urp thing

 

@Cristianamoraruu I would like to have clear URP Documentation & Guidelines sorted by platforms and it's fully tested and proved with the real machines/devices. Each platform has its own Documentation & Guidelines to tell u about the performance at this specific platform and how to improve the performance. Currently what I really want to know is the performance of each urp feature and how to improve the performance at mobile platforms i.e. Android and iOS.

One more thing I think is also really important is list down all the known issues of URP just like main Unity release changelog.

 

I'm very confused with the Blit and RenderTexture system in URP. What is the different between Blit from CommandBuffer, CoreUtils, and ScriptableRenderPass? What about RenderTexture, RenderTargetIdentifier, RenderTextureHandle, RTHandle, RTHandles(?!!). How do I convert between them, and how to migrate from the old things to the new? Can you just stop with the constant breaking changes? Just stop releasing thing that you aren't satisfied with.
Also, what is the best practice for managing persistence Render Textures in Custom Render Passes? All example I see are using GetTemporary.

 

Adding to what @Le_Tai said, I also struggled to figure out how to manipulate render textures in Single-Pass Instanced mode. Eventually, I learned that none of the public APIs could Blit in this mode and that I had to copy an internal version of Blit into my own code.

So,

• documentation around the newer, more challenging uses of SRP needs to be improved;
• example code specific to those challenging use cases like Single-Pass Instanced Blitting;
• code quality in general needs to be improved.

Beyond documentation and example code, it would also likely save the community much time and frustration to have a database of common, high-level descriptions of the current version's known shortcomings and an expert's thoughts on whether and how each shortcoming might best be worked around as the codebase evolves. This would help users (and maybe even Unity) to remain aware of cases where the good intentions of having an SRP aren't yet being fulfilled. Saving the community some of the frustration of discovering these shortcomings the hard way would probably go a long way.

For an example of such a shortcoming (I think?), please see my question here:
https://forum.unity.com/threads/alter-stereo-projection-matrices-in-urp-12-1.1275257

 

There's documentation..? I've just been reading the URP shader source...

I'm pretty sure there's no documentation at all for that. Worst of all, almost every update breaks something and it results in people messaging me for my asset store stuff to be fixed to work with some specific version of URP.

 

@Le_Tai @cdibbs see this ongoing thread for the state of SRP Blitting.

Since the start of that thread they have started working on a documentation page for blitting best practices. It will contain something similar to the information shared by Unity employees in the thread linked above.

 

I would love some included shader templates for URP. Currently (in URP 12.1.6) the right click dialog Create → Shader in the project window has the following templates:



All the .shader files here are templates from the built-in pipeline. I think it is about time that we have at least a URP Unlit Shader template. I understand that URP does not currently have a surface shader solution and that ImageEffect shaders aren't used either. However I hope there will be new templates once there is a surface shader solution and URP custom post processing is finalized.

The fact that the current templates do not go higher than shader target 3.0 and all use CG instead of HLSL is a good indicator of how badly we need an update.

Spoiler: NewSurfaceShader.shader

Shader "Custom/NewSurfaceShader"
{
Properties
{
_Color ("Color", Color) = (1,1,1,1)
_MainTex ("Albedo (RGB)", 2D) = "white" {}
_Glossiness ("Smoothness", Range(0,1)) = 0.5
_Metallic ("Metallic", Range(0,1)) = 0.0
}
SubShader
{
Tags { "RenderType"="Opaque" }
LOD 200

CGPROGRAM
// Physically based Standard lighting model, and enable shadows on all light types
#pragma surface surf Standard fullforwardshadows

// Use shader model 3.0 target, to get nicer looking lighting
#pragma target 3.0

sampler2D _MainTex;

struct Input
{
float2 uv_MainTex;
};

half _Glossiness;
half _Metallic;
fixed4 _Color;

// Add instancing support for this shader. You need to check 'Enable Instancing' on materials that use the shader.
// See https://docs.unity3d.com/Manual/GPUInstancing.html for more information about instancing.
// #pragma instancing_options assumeuniformscaling
UNITY_INSTANCING_BUFFER_START(Props)
// put more per-instance properties here
UNITY_INSTANCING_BUFFER_END(Props)

void surf (Input IN, inout SurfaceOutputStandard o)
{
// Albedo comes from a texture tinted by color
fixed4 c = tex2D (_MainTex, IN.uv_MainTex) * _Color;
o.Albedo = c.rgb;
// Metallic and smoothness come from slider variables
o.Metallic = _Metallic;
o.Smoothness = _Glossiness;
o.Alpha = c.a;
}
ENDCG
}
FallBack "Diffuse"
}

Spoiler: NewImageEffectShader.shader

Code (CSharp):

1. Shader "Hidden/NewImageEffectShader"
2. {
3.     Properties
4.     {
5.         _MainTex ("Texture", 2D) = "white" {}
6.     }
7.     SubShader
8.     {
9.         // No culling or depth
10.         Cull Off ZWrite Off ZTest Always
11.  
12.         Pass
13.         {
14.             CGPROGRAM
15.             #pragma vertex vert
16.             #pragma fragment frag
17.  
18.             #include "UnityCG.cginc"
19.  
20.             struct appdata
21.             {
22.                 float4 vertex : POSITION;
23.                 float2 uv : TEXCOORD0;
24.             };
25.  
26.             struct v2f
27.             {
28.                 float2 uv : TEXCOORD0;
29.                 float4 vertex : SV_POSITION;
30.             };
31.  
32.             v2f vert (appdata v)
33.             {
34.                 v2f o;
35.                 o.vertex = UnityObjectToClipPos(v.vertex);
36.                 o.uv = v.uv;
37.                 return o;
38.             }
39.  
40.             sampler2D _MainTex;
41.  
42.             fixed4 frag (v2f i) : SV_Target
43.             {
44.                 fixed4 col = tex2D(_MainTex, i.uv);
45.                 // just invert the colors
46.                 col.rgb = 1 - col.rgb;
47.                 return col;
48.             }
49.             ENDCG
50.         }
51.     }
52. }
53.  

Spoiler: NewUnlitShader.shader

Code (CSharp):

1. Shader "Unlit/NewUnlitShader"
2. {
3.     Properties
4.     {
5.         _MainTex ("Texture", 2D) = "white" {}
6.     }
7.     SubShader
8.     {
9.         Tags { "RenderType"="Opaque" }
10.         LOD 100
11.  
12.         Pass
13.         {
14.             CGPROGRAM
15.             #pragma vertex vert
16.             #pragma fragment frag
17.             // make fog work
18.             #pragma multi_compile_fog
19.  
20.             #include "UnityCG.cginc"
21.  
22.             struct appdata
23.             {
24.                 float4 vertex : POSITION;
25.                 float2 uv : TEXCOORD0;
26.             };
27.  
28.             struct v2f
29.             {
30.                 float2 uv : TEXCOORD0;
31.                 UNITY_FOG_COORDS(1)
32.                 float4 vertex : SV_POSITION;
33.             };
34.  
35.             sampler2D _MainTex;
36.             float4 _MainTex_ST;
37.  
38.             v2f vert (appdata v)
39.             {
40.                 v2f o;
41.                 o.vertex = UnityObjectToClipPos(v.vertex);
42.                 o.uv = TRANSFORM_TEX(v.uv, _MainTex);
43.                 UNITY_TRANSFER_FOG(o,o.vertex);
44.                 return o;
45.             }
46.  
47.             fixed4 frag (v2f i) : SV_Target
48.             {
49.                 // sample the texture
50.                 fixed4 col = tex2D(_MainTex, i.uv);
51.                 // apply fog
52.                 UNITY_APPLY_FOG(i.fogCoord, col);
53.                 return col;
54.             }
55.             ENDCG
56.         }
57.     }
58. }
59.  

Spoiler: New Custom Render Texture.shader

Shader "CustomRenderTexture/New Custom Render Texture"
{
Properties
{
_Color ("Color", Color) = (1,1,1,1)
_MainTex("InputTex", 2D) = "white" {}
}

SubShader
{
Blend One Zero

Pass
{
Name "New Custom Render Texture"

CGPROGRAM
#include "UnityCustomRenderTexture.cginc"
#pragma vertex CustomRenderTextureVertexShader
#pragma fragment frag
#pragma target 3.0

float4 _Color;
sampler2D _MainTex;

float4 frag(v2f_customrendertexture IN) : COLOR
{
float2 uv = IN.localTexcoord.xy;
float4 color = tex2D(_MainTex, uv) * _Color;

// TODO: Replace this by actual code!
uint2 p = uv.xy * 256;
return countbits(~(p.x & p.y) + 1) % 2 * float4(uv, 1, 1) * color;
}
ENDCG
}
}
}

 

@daneobyrd While that post by @ManueleB helps identify that Blit is fundamentally broken, it does almost nothing to address the core issue, which is that those of us needing capabilities in the affected LTS version(s) are SOL.

The crux of the issue is that functionality is pushed out without enough planning, testing, and documentation. Existing systems then become neglected as the focus is on finishing the new feature. Blitting in URP is a prime example of something that's fundamentally broken, not being fixed for LTS versions, but getting another API in a future version. The official solution is to update to the next latest version, praying that one of the other teams at unity didn't introduce a breaking change for something else you relied upon.

It's extremely frustrating, wastes massive time (which is deadly for tiny teams who don't have a dedicated engineer for each specialization) and shows a lack of forethought, and planning from the program managers. The next 2 week sprint unity does should consist of only feature architecture planning. Running a marathon by only looking at the next 100m is doomed to fail.

 

This is incorrect. There are many solutions for the current LTS versions, many of which are discussed in the thread. There is discussion of the SRP Blitter class that is being implemented with the transition to RTHandles in 2022 but that is separate.

I started that thread because of my own frustrations with blitting in URP. So while I sympathize with you, there are solutions and my impression is that there is work being done to address this (see the PRs linked in the aforementioned thread).

Additionally there is a new guide available in the Introduction to the Universal Render Pipeline for advanced Unity creators ebook starting on page 79.

 

Yes, there is a workaround discussed in the feedback thread that doesn't involve rolling versions forward or backwards, but unfortunately, myself and a few others (from what I've read) haven't managed to get the DrawXXX methods to it to work correctly. (Though I'm still hammering away at trying to make it work.)

I've read the book (it lives on my desktop), unfortunately the render feature example is for regular desktop/mobile Blit use, which as we know is incompatible with XR & SPI rendering in 2021.3.x.

I've also read, and re-read, multiple threads containing various combinations of the keywords, VR or XR, Single Pass Instanced, and Blit that my searching could find. Rolled Unity/packages forward, and backwards, implemented, and re-implemented the CommandBuffer.DrawMesh, and CommandBuffer.DrawProcedural API calls as well as raided several Git repos and the shader source files for insight; to limited success at best, or new broken features at worst. (Rolling forward (2022.1, to use RTHandles) breaks the InputSystem, as well as nukes certain nexted prefabs, rolling back creates OpenXR support limitations, and the current URP kills not only Blit, but also surface shaders to name a few.)

Please don't misinterpret me, I think the URP/HDRP concept is a great move forward for configurability. That said, the number of bugs, breaking changes, and partially refactored/re-implemented/documented API's found across multiple domains scream to me that more time should be spent in the planning, and testing phases. That's my feedback to Unity leadership, focus on fixing and refining what you have, give your engineers the time they need, and stop re-writing API's every 1-2 years introducing breaking changes and incomplete systems.

 

Please add a warning for the fact that users need to take care of putting the pipeline asset in both Graphics and Quality slots and to have the needed pipeline in both or the correct place etc

I have received so many support requests that was just an issue of a previous pipeline set in Quality and when using a new one in Graphics does not work.

This should have a huge warning and details right in the unity editor for clarification, as it is extremely confusing.

Even better have some checks when a pipeline is changed in either place, to warn that should also place it everywhere else probably, in the most common scenario.

That would cut my support tickets by 99% directly

 

You really hit the nail on the head!
I feel like I've been duped for investing myself in URP and unity up until this point. Next step now would be to go back to Built-in, forget about entities and all the goodies that the future holds or just look at another game engine instead of waiting for this to sort itself out.

But for now i won't give up, but i'll be damned if I one day lie on my deathbed cursing unity and the time it stole from me, out of all the things that matter in this world. (not a joke)

 

Hi, if you got black screens when using Blitter API, you can try using cmd.Blit() instead. It may have problems working with XR platforms but you can replace it with Blitter once its documentation is ready.

 

I wrote up my troubles and questions here - https://forum.unity.com/threads/urp-profiling-optimization.1436005/

Basically, having issues troubleshooting optimizations in URP coming from BRP because URP has changed fundamentally and there seems to be a disconnect in communicating that clearly to all types of users, especially those making 3D content.