<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Bertrand Guay Paquet on Medium]]></title>
        <description><![CDATA[Stories by Bertrand Guay Paquet on Medium]]></description>
        <link>https://medium.com/@berniegp?source=rss-ebeb1c914806------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*O-Ei8Aa3cGpLZQzC</url>
            <title>Stories by Bertrand Guay Paquet on Medium</title>
            <link>https://medium.com/@berniegp?source=rss-ebeb1c914806------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Thu, 19 Nov 2026 03:44:33 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@berniegp/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Optimizing Burst matrix multiplications]]></title>
            <link>https://medium.com/toca-boca-tech-blog/optimizing-burst-matrix-multiplications-bfb301de80ce?source=rss-ebeb1c914806------2</link>
            <guid isPermaLink="false">https://medium.com/p/bfb301de80ce</guid>
            <category><![CDATA[job-system]]></category>
            <category><![CDATA[unity]]></category>
            <category><![CDATA[burst]]></category>
            <category><![CDATA[performance]]></category>
            <category><![CDATA[rendering]]></category>
            <dc:creator><![CDATA[Bertrand Guay Paquet]]></dc:creator>
            <pubDate>Thu, 20 Nov 2025 12:02:25 GMT</pubDate>
            <atom:updated>2025-11-20T17:57:08.479Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1010/1*IxPbwSqfHkLjLlGujStP9Q.jpeg" /><figcaption><em>Top of the line UI for the benchmark project</em></figcaption></figure><p>What if I told you that you can get 4.5x performance gains for matrix multiplications in Unity’s Burst with a few code tweaks? And I don’t mean the basic “use [BurstCompile]” optimization, but gains on top of that.</p><p>I recently needed to optimize matrix multiplications in an inner loop that calculates skinning matrices from a bones hierarchy, so I looked deeper into the Burst compiler’s output to see if I could squeeze more out of the CPU. Matrix multiplications are used in many places, such as physics, positioning objects, and animation, so optimizations there can go a long way.</p><p>This article is a relatively deep dive into improving the Burst compiler’s output, primarily for mobile platforms with Arm’s AArch64 (e.g. Android, iPhone). I describe and analyze a journey of 7 performance improvement attempts.</p><p>Although you’ll get more out of this article if you have Arm assembly knowledge, you should be able to follow along most of the content if you have a basic familiarity with any assembly language. If not, you can always stick with the C# code, and perhaps you’ll find a new interest in learning more about assembly. There are links to external reference material in the text, and a list of references at the end.</p><h3>Test bench</h3><p>The benchmark code is fairly minimal with a short method with a configurable number of matrix multiplications over a configurable number of matrix pairs. InputData is a struct that holds all inputs and outputs to make passing parameters around easier.</p><p>MatrixCount controls the number of matrix results to compute so we can get <a href="https://docs.unity3d.com/ScriptReference/Unity.Profiling.ProfilerMarker.html">profiler marker</a> values that aren’t too small. Very small timing values are more susceptible to jittering. Also, when benchmarking several algorithms in the same frame, large enough matrix counts ensure that the CPU cache can’t hold matrices accessed by the previous algorithms. To be on the safe-side, I vary the execution order each frame, and <a href="https://en.wikipedia.org/wiki/Thrashing_%28computer_science%29#Other_uses">thrash the cache </a>between the algorithms to expel any remaining cached matrices.</p><p>MultiplicationCount drives the number of mathematical operations for each matrix. Varying this number gives a more complete performance picture.</p><p>MatrixSourceA, MatrixSourceB and Result are of type NativeArray&lt;Matrix4x4&gt;. Such matrices could come from Transform components for example.</p><p>Here’s the reference method used for performance comparisons. Again, note that we start with a Burst-compiled method. The inner loop has a somewhat contrived way logic to access a different matrix for each iteration, but without causing a random memory access each time, which would cause many CPU cache misses.</p><pre>[BurstCompile]<br>public static void Matrix4x4(ref InputData data)<br>{<br>   for (int i = 0; i &lt; data.MatrixCount; i++)<br>   {<br>       Matrix4x4 matrix = data.MatrixSourceA[i];<br>       for (int j = 0; j &lt; data.MultiplicationCount; j++)<br>       {<br>           // Use a different matrix for each inner loop iteration<br>           var otherMatrix = data.MatrixSourceB[math.max(0, i - j)];<br>           matrix *= otherMatrix;<br>       }<br><br><br>       data.Result[i] = matrix;<br>   }<br>}</pre><p>All the results presented here are median values for 100+ frames on Android with a not-so-recent Samsung Galaxy A20e and ARMV8a as the target architecture.</p><h4>Calling Burst methods</h4><p>To further minimize external factors on performance, I <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/csharp-calling-burst-code.html">call the Burst methods</a> on the main thread instead of using jobs. That’s Unity’s officially recommended way to run Burst methods on the main thread.</p><p>Note that the <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/aliasing-noalias.html">NoAlias attribute</a> on the fields of InputData is especially important with this approach.</p><blockquote>In most use cases, you won’t need to use the [NoAlias] attribute. You don’t need to apply it to a struct definition that already has a [NativeContainer] attribute or to fields in job structs because in these cases Burst infers the no-alias information.</blockquote><p>Since we’re not using jobs, we need to use the <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/aliasing-noalias.html">NoAlias attribute</a> for best results, otherwise Burst might generate extra (slower) code to handle memory region overlaps.</p><pre>[ReadOnly] [NoAlias] public NativeArray&lt;Matrix4x4&gt; MatrixSourceA;</pre><h3>Attempt 1 — Mathematics package</h3><p>With Burst and mathematical operations, the first step is to use the <a href="https://docs.unity3d.com/Packages/com.unity.mathematics@1.3">Unity Mathematics package</a>:</p><blockquote>Unity Mathematics is a C# math library that provides vector types and math functions that have a shader-like syntax, similar to SIMD or HLSL. The Burst compiler uses Unity Mathematics to compile C#/IL code into highly efficient native code.</blockquote><p>So we’ll use math.mul instead of Matrix4x4.operator* for the matrix multiplications.</p><pre>[BurstCompile]<br>public static void MathematicsPkg(ref InputData data)<br>{<br>   for (int i = 0; i &lt; data.MatrixCount; i++)<br>   {<br>       // Conversion from Matrix4x4 to float4x4<br>       float4x4 matrix = data.MatrixSourceA[i];<br>       for (int j = 0; j &lt; data.MultiplicationCount; j++)<br>       {<br>           // Conversion<br>           float4x4 otherMatrix = data.MatrixSourceB[math.max(0, i - j)];<br>           matrix = math.mul(matrix, otherMatrix);<br>       }<br><br><br>       data.Result[i] = matrix; // Implicit conversion to Matrix4x4<br>   }<br>}</pre><p>As expected, this already gives a good speedup.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*BAbSj8Arc-DI-NRSd3G64Q.png" /><figcaption><em>Speedup with Unity’s Mathematics package</em></figcaption></figure><p>In the C# code, there are two significant changes:</p><ol><li>The matrix multiplications are done inline instead of with a function call, which avoids copying matrix values on the stack as function parameters.</li><li>The matrices are converted from Matrix4x4 to float4x4.</li></ol><p>The generated assembly in the <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/editor-burst-inspector.html">Burst Inspector</a> shows the details.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/896/1*WAlvABO3WiDqCZ2TVC3BGA.png" /><figcaption><em>Assembly comparison for inner loop</em></figcaption></figure><p>The speedup graph is relatively flat because the cost of the original function call is orders of magnitude larger than anything else.</p><h3>Attempt 2 — Burst attributes</h3><p>Since the inner loop uses lots of floating point operations, the [BurstCompile] parameter <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/compilation-burstcompile.html#floatmode">FloatMode</a> is very relevant.</p><pre>[BurstCompile(FloatMode = FloatMode.Fast)]<br>public static void FloatModeAttrib(ref InputData data)</pre><p>Another very good speedup for virtually no work.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*A6iop3sDdLWVanMQdBUZPQ.png" /><figcaption><em>Speedup with Burst attributes</em></figcaption></figure><p>The performance gains come from fewer assembly instructions for the matrix multiplications. FloatMode.Fast allows Burst to rearrange SIMD operations which in turn allows it to merge sequences of FADD and FMUL instructions into FMLA (<a href="https://en.wikipedia.org/wiki/Multiply%E2%80%93accumulate_operation#Fused_multiply%E2%80%93add">fused multiply-add</a>). The excellent <a href="https://developer.arm.com/documentation/102159/0400/Matrix-multiplication">Matrix multiplication section of Arm’s Neon Programmer Guide for Armv8-A</a> explains how this works.</p><p>The speedup increases asymptotically with the number of multiplications since we only optimized the inner loop. The non-multiplication related code is identical, and it’s proportionally more significant than it was in the previous attempt.</p><h3>Attempt 3 — NativeArray casts</h3><p>The optimizations from the previous two attempts are probably well-known. Now we’ll start with less well-known (or even new?) optimizations.</p><p>If this sentence from the first attempt caused you to raise an eyebrow, you were on to something:</p><blockquote>The matrices are converted from Matrix4x4 to float4x4.</blockquote><p>Both types contain 16 float values, with the same column major order (and no other field). They’re identical in memory! <em>There should be nothing to convert.</em> However, the Burst compiler doesn’t quite act fully on this equivalence sadly. We can enlighten it if we reinterpret (i.e. cast) the NativeArray parameters from Matrix4x4 to float4x4.</p><p>The NativeArray local variables also provide a second smaller optimization (see code comments). In the previous attempts, we reference the arrays directly from ref InputData data inside the loops. Since that’s a ref type, the arrays could in theory change at any time (i.e. in another thread). Therefore Burst inserts an extra memory access for each loaded matrix to lookup its array field.</p><p>So this is caveat #2 of calling Burst methods directly. Since those calls require ref (or in) struct parameters, we need to make sure that the compiler can deduce inputs that don’t change during the method’s execution. Burst jobs sidestep this issue because their data is stored directly in structs, not references to structs.</p><pre>[BurstCompile(FloatMode = FloatMode.Fast)]<br>public static void NativeArrayCasts(ref InputData data)<br>{<br>   // &quot;Cast&quot; from NativeArray&lt;Matrix4x4&gt; to NativeArray&lt;float4x4&gt;<br>   var sourceA = data.MatrixSourceA.Reinterpret&lt;float4x4&gt;();<br>   var sourceB = data.MatrixSourceB.Reinterpret&lt;float4x4&gt;();<br>   var result = data.Result.Reinterpret&lt;float4x4&gt;();<br>   for (int i = 0; i &lt; data.MatrixCount; i++)<br>   {<br>       // float4x4 matrix = data.MatrixSourceA.ReinterpretLoad&lt;float4x4&gt;(i);<br>       // ^ Other alternative, but not as efficient here as reinterpreting the<br>       // array because InputData is a ref type<br>       float4x4 matrix = sourceA[i];<br>       for (int j = 0; j &lt; data.MultiplicationCount; j++)<br>       {<br>           float4x4 otherMatrix = sourceB[math.max(0, i - j)];<br>           matrix = math.mul(matrix, otherMatrix);<br>       }<br>      <br>       result[i] = matrix;<br>   }<br>}</pre><p>Yet another significant speedup from a one-liner, nice!</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*zHIapmaLP-T8h3dDaChzsw.png" /><figcaption><em>Speedup with NativeArray casts</em></figcaption></figure><p>The assembly of the previous attempt has 8 LDP (load pair of registers) instructions in the inner loop. Notice how the destination register names start with s (e.g. s16), which means 8 <strong>s</strong>ingle float value pair loads. In other words, it missed out on the ability to load full float4 matrix columns in each SIMD&amp;FP register (i.e. floating point and vector operation registers).</p><p>As the Neon guide explains, we only need 2 LDP instructions to load the 4 matrix columns of otherMatrix. We’re now loading pairs of full float4 values (e.g. in q16 and q17 registers) for each LDP instruction.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/809/1*y5cGsvfIKurr8WoXJs0DrQ.png" /><figcaption><em>Assembly comparison for inner loop</em></figcaption></figure><h3>Attempt 4 — Micro optimizations</h3><p>At this point, the largest slow-downs are removed, but looking closely at the assembly shows a few more opportunities:</p><ul><li>Similarly to the arrays in the previous attempt, the fields data.MatrixCount and data.MultiplicationCount are reloaded from the struct’s memory on every loop iteration, even though their value doesn’t change. We can load these values once (in plentiful registers) instead.</li><li>Forward iteration in the outer loop requires an ADD and CMP instruction. Reverse iteration (i.e. towards 0) can use a single SUBS (note the S suffix) instruction that both decrements and <a href="https://developer.arm.com/documentation/102374/0103/Program-flow---generating-condition-code">generates a program flow condition code</a>. We won’t use reverse iteration for the inner loop because matrix multiplications aren’t commutative.</li></ul><pre>[BurstCompile(FloatMode = FloatMode.Fast)]<br>public static void MicroOptimizations(ref InputData data)<br>{<br>   var sourceA = data.MatrixSourceA.Reinterpret&lt;float4x4&gt;();<br>   var sourceB = data.MatrixSourceB.Reinterpret&lt;float4x4&gt;();<br>   var result = data.Result.Reinterpret&lt;float4x4&gt;();<br>  <br>   // Move loop control struct fields to local variables<br>   int matrixCount = data.MatrixCount;<br>   int multiplicationCount = data.MultiplicationCount;<br>   for (int i = matrixCount - 1; i &gt;= 0; i--) // Reverse loop<br>   {<br>       float4x4 matrix = sourceA[i];<br>       for (int j = 0; j &lt; multiplicationCount; j++)<br>       {<br>           float4x4 otherMatrix = sourceB[math.max(0, i - j)];<br>           matrix = math.mul(matrix, otherMatrix);<br>       }<br>      <br>       result[i] = matrix;<br>   }<br>}</pre><p>The gains aren’t as impressive this time, and they seem more susceptible to noise, but it’s still a consistent win.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*Bc78sI6NSIsM4Yx3U0IFqA.png" /><figcaption><em>Speedup with micro optimizations</em></figcaption></figure><p>We’ll switch gears in the next 3 attempts. But before we do, a quick digression.</p><h3>Custom assembly in Burst</h3><p>As part of my research for this article, I wanted to try to inject hand-coded assembly into a Burst method. I had two goals in mind:</p><ol><li>Test if replacing pairs of LDP instructions with a single LD1 instruction, as shown in the Neon guide’s matrix multiplication code sample, would be faster. While <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/csharp-burst-intrinsics-neon.html">Burst provides the </a><a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/csharp-burst-intrinsics-neon.html">vld1 intrinsic</a> for Arm, several variations of it are missing, including the one I needed that fills 4 vector registers with 4 floats each.</li><li>Simply to see if I could do it. I couldn’t find any information out there about this process so it became an extra challenge to make it work.</li></ol><p>Briefly, the results are:</p><ol><li>Failure! LD1 was consistently slower. The <a href="https://developer.arm.com/documentation/109757/latest/">Cortex-A75 Software Optimization Guide</a> offers a possible explanation with LD1 having higher latency, which can impede instruction pipelining.</li><li>Success! It’s definitely more fiddly than <a href="https://en.cppreference.com/w/cpp/language/asm.html">inline assembly in C++</a>, but it’s possible.</li></ol><p>The <a href="https://developer.arm.com/documentation/102159/0400/Load-and-store---example-RGB-conversion">RGB conversion example</a> in the Neon guide uses the LD3 instruction which isn’t available either in Burst 1.8 as of writing. Conceivably, custom assembly could potentially offer performance gains in that scenario. However, the better long-term path would probably be to get Unity to add that intrinsic to Burst!</p><h4>How to use custom assembly in Burst</h4><p>For reference, here’s an overview of the steps to inject custom assembly in a Burst method of an Android build. The steps should be similar with lib_burst_generated.dll on Windows. I haven’t found information about this elsewhere so perhaps it’ll prove useful in the future.</p><ol><li>Add a long enough Burst method with a recognizable name.</li><li>In Unity, <a href="https://docs.unity3d.com/6000.2/Documentation/Manual/android-export-process.html">export the Android project</a>.</li><li>Locate the Burst-compiled library unityLibrary/src/main/jniLibs/arm64-v8a/lib_burst_generated.so. Note that it contains (Dwarf) debugging symbols at this stage.</li><li>Locate the start of the Burst method’s assembly in the library file. You can do this with readelf -Ws lib_burst_generated.so | grep MyMethod to get the method’s virtual address, followed by readelf -WS lib_burst_generated.so | grep ‘\[13]’ (13 is the number of the .text section) to get the section’s virtual address and file offset. The first byte of the method in the file is at file_offset + method_VMA - section_VMA.</li><li>Modify the assembly with a hex editor, a script, etc. Make sure that the new assembly isn’t longer than the original or you’ll overwrite unrelated code. Shorter is fine. Tip: <a href="https://github.com/NationalSecurityAgency/ghidra">Ghidra</a> is pretty good at exploring binaries and applying patches.</li><li>Open the project in Android Studio and build it.</li></ol><p>In theory, it should be possible to integrate all these steps as part of a build pipeline.</p><p>One final warning: in case you’re looking for binary instruction patterns based on what you read in the Burst Inspector, know that the instructions in the compiled binary are sometimes slightly reordered.</p><h3>Affine matrices</h3><p>So far we’ve dealt with general 4x4 matrices. However most matrices from “regular use” of Unity (i.e. mostly all except perspective projection) are <a href="https://en.wikipedia.org/wiki/Affine_transformation">affine matrices</a>. Combinations of translation, scaling, rotation, and shearing produce this type of matrix (e.g. a Transform component’s matrix).</p><p>For our purposes, their most interesting property is that the last row is [0, 0, 0, 1]. We can exploit this knowledge to further optimize matrix multiplications and reduce the size of each matrix in memory. Here are the AffineTransform fields, which flatten down to 4 float3 values.</p><pre>public struct AffineTransform : IEquatable&lt;AffineTransform&gt;, IFormattable<br>{<br>   /// &lt;summary&gt;<br>   /// The rotation and scale part of the affine transformation.<br>   /// &lt;/summary&gt;<br>   public float3x3 rs;<br><br><br>   /// &lt;summary&gt;<br>   /// The translation part of the affine transformation.<br>   /// &lt;/summary&gt;<br>   public float3 t;</pre><p>From here on we’ll assume that all source matrices (and therefore results) are affine. Note also that the following speedup graphs are comparisons with the “micro optimizations” attempt 4, not a rolling “vs previous attempt” as above.</p><h3>Attempt 5 — Optimized affine multiplication</h3><p>As we’ve seen above, the assembly for a 4x4 matrix multiplication is 16 vector instructions. Each one multiplies a column of matrix A by one of the 16 values in matrix B. The fixed last row of an affine matrix means that we can skip some operations and get the same result.</p><p>Let’s replace math.mul with a new custom shorter MulAffine method. Technically, the method requires only matrix B be affine to get correct results; matrix A can be any type of matrix.</p><pre>[MethodImpl(MethodImplOptions.AggressiveInlining)]<br>private static float4x4 MulAffine(float4x4 a, float4x4 bAffine)<br>{<br>   return math.float4x4(<br>       a.c0 * bAffine.c0.x + a.c1 * bAffine.c0.y + a.c2 * bAffine.c0.z,<br>       a.c0 * bAffine.c1.x + a.c1 * bAffine.c1.y + a.c2 * bAffine.c1.z,<br>       a.c0 * bAffine.c2.x + a.c1 * bAffine.c2.y + a.c2 * bAffine.c2.z,<br>       a.c0 * bAffine.c3.x + a.c1 * bAffine.c3.y + a.c2 * bAffine.c3.z + a.c3);<br>}</pre><p>Shaving off 4 of the 16 multiplication instructions in the inner loop pays off.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*5oTAFdykOIgwY5rYBNpF6w.png" /><figcaption><em>Speedup with custom affine multiply</em></figcaption></figure><p>Onwards!</p><h3>Attempt 6 — AffineTransform source</h3><p>What if we stored only the 12 meaningful elements of each matrix in memory? The Mathematics package conveniently supplies the AffineTransform type, along with specialized operations for the type. One such example is the math.mul method.</p><p>I’ll skip the code here which only changes the element type of all arrays to AffineTransform. Loading 12 floats from memory instead of 16 and fewer instructions for the multiplication is bound to be a win right?</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*CqyZGK620ZSaOsFcbzHOYg.png" /><figcaption><em>Speedup (slowdown) with AffineTransform</em></figcaption></figure><p>Wrong… A quick look at the assembly shows why. The compiler inserts many instructions to deal with the mismatch between the float3 columns of AffineTransform and the CPU’s float4-sized vector registers.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/582/1*h7O4Fb84xTNxE7tRAa6OmQ.png" /><figcaption><em>Assembly of inner loop</em></figcaption></figure><p>But not all is lost…</p><h3>Attempt 7 — Intrinsics to the rescue</h3><p>As observed, the float3 columns of AffineTransform aren’t optimal for the CPU’s 128-bit vector registers. There’s no speed advantage to using those registers partially since the operations that operate on them take the same amount of time.</p><p>The first intuition is that in terms of the number of vector registers uses, there’s really no difference between a 4x4 and an affine (i.e. 3x4) matrix; the last vector element of each affine matrix’s column just becomes padding that’s later discarded.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/738/1*5KJvePs99iLhqcM59EQfDw.png" /><figcaption><em>Affine matrix in memory</em></figcaption></figure><p>We can load 3x128 bit vectors once and use <a href="https://developer.arm.com/documentation/102159/0400/Permutation---Neon-instructions?lang=en#md492-permutation---neon-instructions__extraction-instructions">Neon EXT instructions</a> to rearrange the data in 4 vector registers.</p><p>The second intuition is that otherMatrix in the inner loop doesn’t even need to be an actual matrix (4x4 or affine). With the vectorized multiplication, each element of the right side matrix is used separately as a scalar. So let’s take advantage of the float4x3 type to hold those matrix elements tightly packed in 3 vector registers, and use a custom multiplication method adjusted to match the type.</p><p>Here’s the inner loop code that uses <a href="https://docs.unity3d.com/Packages/com.unity.burst@1.8/manual/csharp-burst-intrinsics.html">Burst intrinsics</a> to optimize loading the initial matrix and storing the multiplication result.</p><pre>[BurstCompile(FloatMode = FloatMode.Fast)]<br>public static void AffineTransformIntrinsics(ref InputData data)<br>{<br>   // Use float4x3 to directly load matrices in 3 128-bit vectors<br>   // (i.e. 3 x float4)<br>   var sourceA = data.MatrixSourceAffineA.Reinterpret&lt;float4x3&gt;();<br>   var sourceB = data.MatrixSourceAffineB.Reinterpret&lt;float4x3&gt;();<br>   var result = data.ResultAffine.Reinterpret&lt;float4x3&gt;();<br>   int matrixCount = data.MatrixCount;<br>   int multiplicationCount = data.MultiplicationCount;<br>   for (int i = 0; i &lt; matrixCount; i++)<br>   {<br>       float4x3 affineMatrixPacked = sourceA[i];<br>      <br>       // Each column&#39;s float4 is [row0, row1, row2, PAD]<br>       // Note: extracting this to a separate method leads to suboptimal code.<br>       // Compiler bug?<br>       float4x4 matrix;<br>       if (IsNeonSupported)<br>       {<br>           // Note: element ordering in a v128 is [3, 2, 1, 0]<br>           v128 matrixPacked_0_3 = ToV128(affineMatrixPacked.c0);<br>           v128 matrixPacked_4_7 = ToV128(affineMatrixPacked.c1);<br>           v128 matrixPacked_8_11 = ToV128(affineMatrixPacked.c2);<br>          <br>           matrix = new float4x4(affineMatrixPacked.c0,<br>               ToFloat4(vextq_s32(matrixPacked_0_3, matrixPacked_4_7, 3)),<br>               ToFloat4(vextq_s32(matrixPacked_4_7, matrixPacked_8_11, 2)),<br>               ToFloat4(vextq_s32(matrixPacked_8_11, matrixPacked_8_11, 1)));<br>       }<br>       else<br>       {<br>           // Desktop didn&#39;t need intrinsics to get optimal assembly<br>           // Note: explicit shuffle() (currently) gives better results than <br>           // swizzling<br>           // e.g. float4(affineMatrixPacked.c0.w, affineMatrixPacked.c1.xyz)<br>           var c1 = math.shuffle(affineMatrixPacked.c0, affineMatrixPacked.c1,<br>               math.ShuffleComponent.LeftW, math.ShuffleComponent.RightX,<br>               math.ShuffleComponent.RightY, math.ShuffleComponent.RightZ);<br>           var c2 = math.shuffle(affineMatrixPacked.c1, affineMatrixPacked.c2,<br>               math.ShuffleComponent.LeftZ, math.ShuffleComponent.LeftW,<br>               math.ShuffleComponent.RightX, math.ShuffleComponent.RightY);<br>           var c3 = math.shuffle(affineMatrixPacked.c2, affineMatrixPacked.c2,<br>               math.ShuffleComponent.LeftY, math.ShuffleComponent.LeftZ,<br>               math.ShuffleComponent.LeftW, math.ShuffleComponent.LeftX);<br>           matrix = new float4x4(affineMatrixPacked.c0, c1, c2, c3);<br>       }<br><br><br>       for (int j = 0; j &lt; multiplicationCount; j++)<br>       {<br>           // We don&#39;t need the &quot;proper&quot; matrix type for multiplication.<br>           // All floats are used separately so any type with 12 floats works.<br>           float4x3 otherMatrix = sourceB[math.max(0, i - j)];<br>           matrix = MulAffine(matrix, otherMatrix);<br>       }<br><br><br>       // Reverses the unpacking/loading from above<br>       // Note: strangely, extracting this part to a separate method is fine.<br>       result[i] = AffineFloat4x4ToPackedAffine(matrix);<br>   }<br>}</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/1018/1*Y4L2Szx8U0G6M3257BMW4Q.png" /><figcaption><em>Speedup with Burst intrinsics</em></figcaption></figure><p>Very good improvements over the previous attempt at using the AffineTransform type! It’s still not as fast as attempt 5 with 4x4 matrices, which shows that for this algorithm, <em>on this particular device</em>, performance is probably bound more by the number of instructions than memory accesses.</p><h3>Results summary</h3><p>Here’s an overview of all attempts in a single graph.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*anuCyevXcpzgjrgM5m-8vg.png" /><figcaption><em>Algorithm speedup summary — Mobile</em></figcaption></figure><p>The first two speedups were both the largest and the most easily achieved. They’re essentially about following Burst best practices.</p><p>However there were still a lot of performance gains available from “helping” the Burst compiler get around some hurdles as the next two attempts show.</p><p>The next big gain came from reducing the number of vector multiplication operations to multiply two affine matrices together. It’s a drop-in replacement for the math.mul method to use where appropriate, while avoiding the slowdown from using the AffineTransform type directly.</p><p>Lastly, storing the matrices as affine in memory first gave a significant slowdown, but we were able to overcome most of it with intrinsics. Keep in mind that reducing memory usage (~25% here) can be a valuable gain on its own, so that lower multiplication performance could be worth it depending on the situation.</p><h4>Desktop results</h4><p>Here’s a summary of performance on desktop, without a detailed analysis of each attempt like above.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*ocu5WREGrJwe4TAiL7WWeg.png" /><figcaption><em>Algorithm speedup summary — Desktop</em></figcaption></figure><p>While the type mismatch observed in <strong>AffineTransform</strong> hits hard, once we reach the intrinsics version (actually, some well chosen math.shuffle calls are enough on desktop), it becomes the fastest alternative.</p><p>I’ll make an educated guess that since the clock speed is 2.2x faster on desktop, the bottleneck of the short inner loop is memory access rather than float/ALU instructions, so loading 12 floats instead of 16 (3 vs 4 vmovu instructions) has a greater effect than on mobile.</p><h3>Conclusion</h3><p>When I started working on this article I didn’t expect it would become so involved. My starting point was to share information about the speedup from NativeArray “casts”, but then surprisingly many more facets and possibilities appeared. It’s been a very interesting journey learning a lot more about AArch64 and ARMv8-A, as well as its Neon SIMD instruction set, the structure of ELF files, and getting more familiar with reverse engineering in Ghidra.</p><p>My main take-aways from this research are:</p><ul><li>Significant performance gains are possible when working with affine matrices, but be cautious of using the AffineTransform type itself.</li><li>A sufficiently advanced (Burst) compiler could automatically deduce several of the optimizations I described. Maybe it will eventually. It could be useful to add a math.ShuffleComponent.DontCare value for math.shuffle as a compiler hint so it can pick whatever “padding” vector element is most efficient with the current instruction set.</li><li>In some scenarios I examined, the Burst compiler was able to produce more efficient assembly for x86–64 than for Arm. So it’s possibly even more relevant to inspect the Burst Inspector for mobile platforms.</li><li>While Unity recommends not using jobs to execute Burst methods on the main thread, there’s a number of subtle caveats from doing that. I’m not entirely sure that the added complexities are worth the possible minor optimization of directly calling Burst methods.</li><li>It’s possible to inject hand-written assembly into Burst methods, but the maintenance cost of that approach could be (too) high. Use sparingly if at all.</li></ul><p>It can be quite time consuming to optimize algorithms at this low-level, so I would suggest making sure it’s time well spent by profiling first (and also after!). It also pays off to know some details of the architecture that runs your code. Coming from x86 assembly, I found it surprisingly easy to pick up AArch64 assembly once I found the right learning resources.</p><p><em>Thanks to Victor for reviewing this post.</em></p><h3>References</h3><p><strong>Arm AArch64</strong></p><ul><li><a href="https://www.arm.com/architecture/learn-the-architecture/a-profile">Learn the Architecture — A-profile — Arm</a> ‒ Structured landing page with many guides for AArch64.</li><li><a href="https://developer.arm.com/documentation/102404/latest">Learn the architecture — Introducing the Arm architecture</a> ‒ High level overview of the Arm architecture.</li><li><a href="https://developer.arm.com/documentation/102374/latest/">Learn the architecture — A64 Instruction Set Architecture Guide</a> ‒ Introduction to the instruction set. Includes the function call standard and how arguments are passed with registers.</li><li><a href="https://developer.arm.com/documentation/107829/latest/">Getting Started with Arm Assembly Language</a> ‒ Basics of using assembly in practice.</li><li><a href="https://developer.arm.com/documentation/dui0801/latest/">Arm Compiler armasm User Guide</a> ‒ Guide for Arm’s compiler and programmer-focused instruction set reference.</li><li><a href="https://developer.arm.com/documentation/ddi0602/latest">Arm A-profile A64 Instruction Set Architecture</a> ‒ More detailed instruction set reference, including instruction encoding.</li><li><a href="https://github.com/ARM-software/abi-aa/blob/main/aapcs64/aapcs64.rst">Procedure Call Standard for the Arm 64-bit Architecture (AArch64)</a> ‒ Detailed description of the standard for calling functions.</li><li><a href="https://developer.arm.com/documentation/ddi0487/latest">Arm Architecture Reference Manual for A-profile architecture</a> ‒ Everything you could want to know in a single very long document.</li><li><a href="https://henrydwright.co.uk/arm64-assembly-part-1.html">How to train your (snap)dragon — part 1 — assembling the team</a> ‒ Short third-party guide for an “Hello World” in assembly on arm64 Windows.</li></ul><p><strong>Arm’s Neon SIMD instruction set</strong></p><ul><li><a href="https://developer.arm.com/documentation/102159/latest">Neon Programmer Guide for Armv8-A Coding for Neon</a> ‒ Overview of the SIMD Neon instruction set. Includes a <a href="https://developer.arm.com/documentation/102159/latest/Matrix-multiplication">matrix multiplication example</a>.</li><li><a href="https://developer.arm.com/architectures/instruction-sets/intrinsics/#f:@navigationhierarchiessimdisa=[Neon">Arm Neon Intrinsics reference</a> ‒ Filterable list of all intrinsics with descriptions.</li></ul><p><strong>Burst</strong></p><ul><li><a href="https://developer.arm.com/documentation/102556/latest/">Using Neon C# intrinsics with Unity Burst</a> ‒ Arm guide to using their intrinsics with Burst.</li><li><a href="https://www.youtube.com/watch?v=BpwvXkoFcp8">Intrinsics: Low-level engine development with Burst — Unite Copenhagen</a></li><li><a href="https://www.youtube.com/watch?v=QkM6zEGFhDY">ECS Track: Deep Dive into the Burst Compiler — Unite LA</a></li><li><a href="https://gametorrahod.com/analyzing-burst-generated-assemblies/">Analyzing Burst generated assemblies</a></li></ul><p>And lastly, a very good 25 part series from <a href="https://devblogs.microsoft.com/oldnewthing/author/oldnewthing">Raymond Chen</a> on many practical topics of AArch64. I couldn’t find a landing page for the series, so here are all the links:</p><ul><li><a href="https://devblogs.microsoft.com/oldnewthing/20220726-00/?p=106898">The AArch64 processor (aka arm64), part 1: Introduction — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220727-00/?p=106907">The AArch64 processor (aka arm64), part 2: Extended register operations — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220728-00/?p=106912">The AArch64 processor (aka arm64), part 3: Addressing modes — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220729-00/?p=106915">The AArch64 processor (aka arm64), part 4: Addition and subtraction — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220801-00/?p=106922">The AArch64 processor (aka arm64), part 5: Multiplication and division — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220802-00/?p=106927">The AArch64 processor (aka arm64), part 6: Bitwise operations — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220803-00/?p=106941">The AArch64 processor (aka arm64), part 7: Bitfield manipulation — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220804-00/?p=106945">The AArch64 processor (aka arm64), part 8: Bit shifting and rotation — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220805-00/?p=106948">The AArch64 processor (aka arm64), part 9: Sign and zero extension — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220808-00/?p=106953">The AArch64 processor (aka arm64), part 10: Loading constants — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220809-00/?p=106955">The AArch64 processor (aka arm64), part 11: Loading addresses — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220810-00/?p=106958">The AArch64 processor (aka arm64), part 12: Memory access and alignment — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220811-00/?p=106963">The AArch64 processor (aka arm64), part 13: Atomic access — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220812-00/?p=106968">The AArch64 processor (aka arm64), part 14: Barriers — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220815-00/?p=106975">The AArch64 processor (aka arm64), part 15: Control transfer — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220817-00/?p=106998">The AArch64 processor (aka arm64), part 16: Conditional execution — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220818-00/?p=107005">The AArch64 processor (aka arm64), part 17: Manipulating flags — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220819-00/?p=107020">The AArch64 processor (aka arm64), part 18: Return address protection — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220822-00/?p=107032">The AArch64 processor (aka arm64), part 19: Miscellaneous instructions — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220823-00/?p=107041">The AArch64 processor (aka arm64), part 20: The classic calling convention — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220824-00/?p=107043">The AArch64 processor (aka arm64), part 21: Classic function prologues and epilogues — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220825-00/?p=107050">The AArch64 processor (aka arm64), part 22: Other kinds of classic prologues and epilogues — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220826-00/?p=107059">The AArch64 processor (aka arm64), part 23: Common patterns — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220829-00/?p=107066">The AArch64 processor (aka arm64), part 24: Code walkthrough — The Old New Thing</a></li><li><a href="https://devblogs.microsoft.com/oldnewthing/20220830-00/?p=107069">The AArch64 processor (aka arm64), part 25: The ARM64EC ABI — The Old New Thing</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=bfb301de80ce" width="1" height="1" alt=""><hr><p><a href="https://medium.com/toca-boca-tech-blog/optimizing-burst-matrix-multiplications-bfb301de80ce">Optimizing Burst matrix multiplications</a> was originally published in <a href="https://medium.com/toca-boca-tech-blog">Toca Boca Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Debug Shader Graph shaders with symbols]]></title>
            <link>https://medium.com/toca-boca-tech-blog/debug-shader-graph-shaders-with-symbols-2c66aed62a59?source=rss-ebeb1c914806------2</link>
            <guid isPermaLink="false">https://medium.com/p/2c66aed62a59</guid>
            <category><![CDATA[pix]]></category>
            <category><![CDATA[unity]]></category>
            <category><![CDATA[shader-in-unity]]></category>
            <category><![CDATA[renderdoc]]></category>
            <category><![CDATA[rendering]]></category>
            <dc:creator><![CDATA[Bertrand Guay Paquet]]></dc:creator>
            <pubDate>Fri, 23 May 2025 06:49:44 GMT</pubDate>
            <atom:updated>2025-05-23T06:49:44.971Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*xbe2xpJkZSrfpPC1nkL8_g.png" /><figcaption>RenderDoc debugging session</figcaption></figure><p>RenderDoc is an awesome tool for graphics development and Unity has a convenient <a href="https://docs.unity3d.com/Manual/RenderDocIntegration.html">RenderDoc integration</a> to make it a breeze to capture frames in the Editor.</p><p>When I implement new graphics features in our game or debug existing ones, I frequently rely on this tool to make sense of what I see in the game. <a href="https://docs.unity3d.com/Manual/FrameDebugger.html">Unity’s frame debugger</a> is really good for many uses, but RenderDoc provides a lot more information and tools to go deeper. Most recently I used it to investigate a rendering bug where some lights in the game were way brighter than expected.</p><p>One of its many analysis features is <a href="https://renderdoc.org/docs/how/how_debug_shader.html">debugging shaders</a> which allows you to see exactly what a shader does and inspect the value of variables at any point. However, for the best shader debugging experience, you’ll really want to <a href="https://docs.unity3d.com/Manual/SL-DebuggingD3D11ShadersWithVS.html">add this preprocessor directive to your shaders</a>:</p><pre>#pragma enable_d3d11_debug_symbols</pre><p>For shaders authored as HLSL files, it’s easy to add this line directly in your source file.</p><p>Sadly there’s no built-in way to add a preprocessor directive to Shader Graph shaders in Unity. In this article I show various ways to work around this limitation.</p><h3>Why bother?</h3><p>Without the pragma directive you’ll be limited to the shader disassembly view when you debug a shader.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/954/0*TJcgJxNICTHq2iKR" /><figcaption><em>Shader debugging in disassembly</em></figcaption></figure><p>While it’s certainly powerful, and if you’re debugging shaders, you’ll likely sooner or later need to read disassembled code, it’s a vastly more pleasant and efficient developer experience with symbols for functions and variables. Shader Graph’s generated HLSL code is notoriously verbose and difficult to navigate, so it’s a big time-saver to not have to manually map the generated HLSL code to the assembly instructions in the debugger.</p><p>Here’s what it looks like with symbols:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*dhufMCl2J40rSWKM" /><figcaption><em>Shader debugging with symbols!</em></figcaption></figure><p>I certainly have a much easier time understanding exactly what a shader is doing by stepping through a “real” execution flow. It’s also a great way to explore Unity’s shader library to know the exact effect of material properties and how rendering algorithms work.</p><h3>Option 1 — Export and duplicate a shader</h3><p>This first option is quite cumbersome, and it’s likely the first one you’ll encounter elsewhere.</p><ol><li>Select the Shader Graph asset.</li><li>Select <strong>View Generated Shader</strong> or <strong>Copy Shader</strong> and create a shader file with the generated code.</li><li>Edit the shader to add #pragma enable_d3d11_debug_symbols.</li><li>Use the modified shader in your material(s).</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/562/0*lPsomzZftBKizfSv" /><figcaption><em>Shader Graph export</em></figcaption></figure><p>This works but it has an important downside:</p><ul><li>Materials don’t use the Shader Graph shader anymore, so anytime you modify the “original” shader, you need to redo these steps.</li><li>This doesn’t affect the default pipeline shaders.</li></ul><h3>Option 2 — One-line change to Shader Graph</h3><p>It turns out that the Shader Graph package already has everything in place to easily inject #pragma enable_d3d11_debug_symbols into all shaders it generates. To make use of it, follow these steps:</p><ol><li><a href="https://docs.unity3d.com/Manual/CustomPackages.html#EmbedMe">Embed</a> the Shader Graph package in the packages folder (or modify it directly in Library/PackageCache for a quick test).</li><li>Locate and modify the GenerateShaderPass <a href="https://github.com/Unity-Technologies/Graphics/blob/ddab622555c94976a715d3733fd1cd249834aeba/Packages/com.unity.shadergraph/Editor/Generation/Processors/Generator.cs#L790">method</a> in com.unity.shadergraph/Editor/Generation/Processors/Generator.cs (see below).</li><li>Modify, reimport, or re-save the shader(s) you’re interested in. Or restart Unity at worst. Otherwise Shader Graph won’t re-generate the shaders to add the pragma directive.</li></ol><pre>// Enable this to turn on shader debugging<br>bool debugShader = false; // &lt;== Set this to true<br>if (debugShader)<br>{<br>   passPragmaBuilder.AppendLine(&quot;#pragma enable_d3d11_debug_symbols&quot;);<br>}</pre><p>This approach is still somewhat annoying because it requires taking the Shader Graph package out of the regular package manager flow. However it does make all shaders debuggable very easily if that’s what you want.</p><p>Wouldn’t it be awesome if someone at Unity spent a few minutes to add a <a href="https://docs.unity3d.com/6000.1/Documentation/Manual/custom-scripting-symbols.html">scripting define symbol</a> that sets the debugShader variable to true? A Shader Graph setting somewhere would be even better of course.</p><h3>Option 3 — Inject pragmas via Shader Graph’s custom function node</h3><p>Luckily for us, the string type of the <a href="https://docs.unity3d.com/Packages/com.unity.shadergraph@17.3/manual/Custom-Function-Node.html">custom function node</a> doesn’t do much input validation, so we can take advantage of that to do the equivalent of <a href="https://en.wikipedia.org/wiki/SQL_injection">SQL injection</a> in our shaders. You simply need to add a custom function node that contains some kind of no-op function along with the desired pragma directive, and connect it to your graph.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/445/0*2TIes0sSCop42F6x" /><figcaption><em>Pragma custom function node</em></figcaption></figure><p>The generated shader then includes the pragma directive neatly embedded in the source code. The function body with the closing and opening curly braces tricks Shader Graph into closing the scope of the node’s function body so the pragma directive ends up in the top scope. The last line opens a new empty function body scope to “consume” the node’s closing curly brace.</p><pre>// Graph Functions<br><br><br>void pragma_debug_float(float3 In, out float3 Out){<br>  Out = In;<br>}<br><br><br>#pragma enable_d3d11_debug_symbols<br><br><br>void CloseCurlyDummy() {<br>}</pre><p>You can take it a step further and create a reusable passthrough shader sub graph that outputs its input unchanged. You can then add it as a node in any shader to add the pragma directive.</p><p>A Vector3 type is convenient because most shaders have a Vector3 position that you can connect to it. It really doesn’t matter what you put in there though. Just use something that fits well in your project’s shader structure.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/926/0*gAZNplkLydQGYT1u" /><figcaption><em>Same thing in a reusable shader sub graph asset</em></figcaption></figure><p>To take it one <em>more</em> step further, instead of setting the pragma directive directly inside the custom function node, you can use the #include_with_pragmas directive to include another HLSL file. You then put the#pragma enable_d3d11_debug_symbols directive in that other file so you can easily toggle it on and off. It’s essentially the <a href="https://docs.unity3d.com/6000.1/Documentation/Manual/shader-include-directives.html">example Unity gives in their documentation</a> shoehorned into Shader Graph.</p><p>Be aware though that Shader Graph won’t keep track of changes to the included HLSL file automatically to regenerate your shaders. That’s because there’s no asset link between the shaders and the HLSL include file. Make sure to trigger shader generation manually as described above, or link the include file asset to the sub graph through another custom function node with the file type.</p><h3>Happy debugging</h3><p>That’s it! Hopefully one of these methods helps you get the most out of RenderDoc’s shader views until Unity adds a built-in way to set preprocessor directives in Shader Graph shaders.</p><p>I should also mention that if you work with Microsoft’s PIX, this same process <a href="https://docs.unity3d.com/Manual/DebuggingShadersWithPIX.html">makes your shaders debuggable</a> in that tool.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2c66aed62a59" width="1" height="1" alt=""><hr><p><a href="https://medium.com/toca-boca-tech-blog/debug-shader-graph-shaders-with-symbols-2c66aed62a59">Debug Shader Graph shaders with symbols</a> was originally published in <a href="https://medium.com/toca-boca-tech-blog">Toca Boca Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Hack Days at Toca Boca]]></title>
            <link>https://medium.com/toca-boca-tech-blog/hack-days-at-toca-boca-2d0249d35d54?source=rss-ebeb1c914806------2</link>
            <guid isPermaLink="false">https://medium.com/p/2d0249d35d54</guid>
            <category><![CDATA[unity]]></category>
            <category><![CDATA[game-development]]></category>
            <category><![CDATA[hackathons]]></category>
            <dc:creator><![CDATA[Bertrand Guay Paquet]]></dc:creator>
            <pubDate>Thu, 20 Mar 2025 08:35:58 GMT</pubDate>
            <atom:updated>2025-03-20T08:35:58.386Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-QVtN2Deis_V_O4jYzCR1w.png" /><figcaption>“Protest” signs prototype</figcaption></figure><p>We recently had Hack Days in the Toca Boca Days team, and it was a huge success! I was one of the event organizers so I’ll share how we organized it, and some lessons we learned along the way.</p><p>There’s a bit of self-interest here as well because I’m very keen to promote Hack Days at Toca Boca so they can become a staple of our studio’s playful culture. And I may (along with a few others) have repeatedly nagged our producers to set time aside for the event…</p><h3>What are Hack Days?</h3><p>They’re a few days to a week that we take out of our normal production schedule for everyone on the team to work on a project of their choice. This dedicated time provides a fantastic opportunity for trying out new ideas for the game, team building, and dipping your toes in skills and areas outside of your normal responsibilities (if you want to!). It’s similar in many ways to an internal <a href="https://en.wikipedia.org/wiki/Game_jam">game jam</a> or <a href="https://en.wikipedia.org/wiki/Hackathon">hackathon</a>.</p><p>Hack Days usually imply a lot of self-organization by the team. On a fundamental level they mostly do away with top-down direction to let everyone freely choose what they work on, who they work with, how they work, and their goals.</p><p>These events have a very different vibe than the usual work day, and even more so if they’re in-person. Seeing everyone laser focused on their goals and helping each other out is very inspiring.</p><p>The end result of Hack Days projects can take many forms, and studio leadership can decide how to shape that with how much direction they give. More on this topic below.</p><h3>January 2025 Hack Days</h3><p>Our Hacks Days were scheduled for Wednesday January 15th. Our team’s campus days are Mondays and Wednesdays so it was appropriate to kick-off the event in-person on a Wednesday and continue remotely on Thursday.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*c-hvR4RFgCrZoWpG" /><figcaption><em>Hack Days schedule</em></figcaption></figure><p>As an added twist, a recent studio reorganization and some new initiatives meant that a good number of people joined the team only the week before. Therefore onboarding people onto the project became a more important dimension for us.</p><h3>Preparation phase</h3><p>Planning started the week before the event so we had to act really fast. Our leadership team provided a brief to set the stage and inspire participants. We weren’t looking for finished products, but rather prototypes to prove (or disprove!) ideas.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*sVfRMifCM3V2ELdi" /><figcaption><em>Setting some direction</em></figcaption></figure><p>After we assembled the organizing team, we immediately started preparation work so that everyone could hit the ground running on Wednesday morning.</p><h3>Ideation</h3><p>The first step was to generate ideas. We used Slack and good old fashioned discussion around the water cooler. Many people already had personal notes of ideas, so it was easy to come up with a lot of ideas.</p><p>On Monday, we added a second more structured step for people to choose what they’ll work on. Project leads added their idea to a Miro board to start forming teams.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1000/0*U2ii0EGhopR7Po2v" /><figcaption><em>Project card template and example, with Care Bear lending a hand</em></figcaption></figure><p>While we insisted a bit on the “leading” part when presenting this board, it was also perfectly fine to later pivot and join forces on another project.</p><p>We also had two more areas for people to write their name and craft:</p><ul><li>To state that they’re looking for a project.</li><li>To make themselves available to support other projects during the Hack Days. We tried to keep this group of people small so the majority would work on a project.</li></ul><h3>Learning resources</h3><p>Many people in the team don’t usually code in their day job (e.g. artists, designers), and while several others do, they don’t normally work on gameplay (e.g. backend, infra). We also had several new joiners who were still onboarding.</p><p>It was important for us to make the Hack Days an accessible experience, and our gameplay organizers really rose to the challenge! They did a fantastic job preparing workshops to set up a development environment and learn the basics of working on the game with a magic wand “<a href="https://en.wikipedia.org/wiki/%22Hello,_World!%22_program">hello world</a>” tool.</p><p>We also prepared documentation in a “cheat sheet” focused on the participants’ tasks. For example, we had a howto section with the following sub-sections:</p><ul><li><strong>Develop:</strong> A curated set of links to tutorials related to our tools theme such as “How to create a player tool”.</li><li><strong>Test:</strong> Streamlined instructions on how to run the game in Unity, both in single player and multiplayer.</li><li><strong>Deploy:</strong> Instructions to deploy a build to a test server and connect to it from a mobile phone.</li></ul><figure><img alt="" src="https://cdn-images-1.medium.com/max/587/0*XvqwI7KjwrbBLXLx" /><figcaption><em>The “Test” part of the howto documentation</em></figcaption></figure><h3>Hacking phase</h3><p>By Wednesday the hype was very high and everyone was eager to get started, so we kept our kick-off short.</p><p>We stressed again that we’re not expecting production quality code, and that it was perfectly fine (and expected!) to take shortcuts. If any project ended up on our product roadmap, it was clear that we’d redo the code “properly” mostly from scratch.</p><p>Us organizers then stayed in the main room to assist anyone needing help. With the upfront preparation work we did we only needed to lightly assist two people.</p><p>We truly witnessed an amazing level of self-organization from the team, which just shows how much highly aligned and motivated teams can accomplish.</p><h3>Demos</h3><p>Monday was an in-person demo session for every team to present their project. This meant that Friday was now awkwardly positioned between Hack Days activities, so it too “unofficially” became part of the Hack Days for most people.</p><p>In the first part of the demo, every team had a single slide to quickly present their project. A few included video recordings. The second part was a show and tell. We separated the teams into groups of 3 or 4 teams each with a 15 minute slot. During that time, everyone else could walk around the place to learn about and try out each team’s project.</p><p>After this internal demo session, we also presented the projects to the rest of Toca Boca over the course of several weeks during our regularly scheduled studio-wide Friday demo sessions.</p><h3>Lessons learned</h3><p>This was the first Hack Days at Toca Boca in over two years, and the first for most participants. This meant that we didn’t work against a pre-established structure or expectations.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*6UiaYRMrA0pgLpin" /><figcaption><em>Small sample of our feedback, with a very Swedish ask for fika!</em></figcaption></figure><p>Here are some highlights from our observations and the feedback we received:</p><ul><li>The majority of projects were solo or quasi-solo teams.</li><li>The preparation workshops were helpful and appreciated.</li><li>Some were hesitant about adding ideas to the board before the hack days.</li><li>In-person on campus was appreciated. Many would have loved more in-person time.</li><li>Two (three) days was a tad short, but we also discussed that too much time can also dilute that sense of urgency that forces focus.</li><li>Self-organization worked surprisingly well.</li><li>Fast prototyping was popular, and productive given all the cool hacks.</li><li>The Hack Days should be a single block of days, not with Friday in between as we did.</li><li>We might want to reconsider the show &amp; tell format of the demo. Perhaps extend it a bit and have both a structured presentation, and then a more open-ended demo session.</li></ul><p>Some of these learnings were more or less predictable as essentially a consequence of the very short time we had to prepare before the Hack Days. So it’s also a learning in itself to allow at least 2–3 weeks of lead time ahead of the Hack Days.</p><p>For example, on the third point above, with more lead time we could have a longer brainstorming period, or even a brainstorming workshop, before the point at which people commit to leading or joining a project.</p><h3>Personal reflections</h3><p>In this section I’ll add further thoughts and reflections of my own based on this and prior similar experiences.</p><h3>Direction and tone</h3><p>I believe that it’s very important to establish clear goals for the Hack Days because everything else follows from that.</p><p>Some questions to help frame this are:</p><ul><li>Is the primary goal to quickly generate and prototype product-oriented ideas?</li><li>Do we want to do team building or reward the team for achieving objectives?</li><li>Are we comfortable with people experimenting on areas that aren’t product-oriented, purely as a learning activity?</li></ul><p>It’s important to strike a balance with direction because too much can risk losing the participants’ passion and feeling of personal ownership. It can be valuable to integrate quick prototyping into the regular production process, but in my opinion that’s a different thing with a different mindset.</p><h3>Demo format</h3><p>Sharing results is essential for Hack Days. It forces a reflection on what the team achieved, shares knowledge, inspires others, and ultimately holds everyone accountable. Accountability here doesn’t mean delivering a specific result in the allotted time. It’s about giving it our all and sharing our findings for everyone to benefit from.</p><p>Recorded demos work quite well because they become an artifact that we can refer to in future and share with others. It’s also a neat way to enforce presentation time constraints.</p><p>In addition to the more obvious parts, a great demo should highlight:</p><ul><li>Challenges, solutions, learnings, pivots, etc. encountered.</li><li>Where applicable, next steps to take the idea to the next level, and the envisioned benefits.</li></ul><h3>Epilogue</h3><p>An often overlooked question is what happens to all these prototypes that participants poured all their energy and creativity into. At a minimum event organizers or sponsors need to set realistic expectations that not everything will be released in the game in the short term, if ever.</p><p>In addition, I believe that there’s potential for big benefits, especially in the longer term, to “close the loop” on the product-oriented prototypes. This step should show that each one was at least considered, and share any appraisal regarding their future potential for production.</p><p>I’ve heard of some ideas where “winning” project teams continue to work on their idea to bring it into the game, however I’ve yet to see that work out in practice. It brings production planning challenges and can significantly affect how people approach Hack Days.</p><p>I’d love to hear and learn about experiences where this path worked out though!</p><h3>Aha! moment for the team</h3><p>Beyond their tangible output, the Hack Days proved that our team has the ability to produce compelling and creative results <em>very</em> quickly, begging the question of why we don’t have the same velocity in the project.</p><p>I don’t think that anyone could have predicted the magnitude and impact of this key result in our team. The Hack Days sparked numerous workshops to explore how we can improve our production processes to be more efficient and able to <a href="https://en.wikipedia.org/wiki/Fail_fast_(business)">fail faster</a>. We shouldn’t underestimate how the Hack Days provide an opportunity to critically look at some of our development processes in a new light.</p><p>Obviously the prototypes <em>are hacks</em> not suitable for production, but that doesn’t diminish their usefulness. In fact, we even adapted our feature development process to add an explicit early prototype phase. It should allow us to quickly prove that new features can actually provide a fun and enjoyable player experience before we commit more resources to them.</p><h3>Closing words</h3><p>I love Hack Days. I love the energy, the creativity, and the passion on display at these events. And of course I love them even more when they’re a Hack <em>Week</em> instead of Hack Days!</p><p>I’m very happy with the results of the January edition, and we impressed many with the number of new feature prototypes we produced in such a short time. In fact it was so successful, both in terms of approach and achieved results, that it inspired our leadership team to adapt how we develop features for the whole project.</p><p>Here’s hoping for the next event in the not too distant future!</p><p><em>Thanks to my Hack Days co-organizers Aron, Dani, Erik, Fabien, Robert, and Victor! And thanks to Dan for an insightful review.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2d0249d35d54" width="1" height="1" alt=""><hr><p><a href="https://medium.com/toca-boca-tech-blog/hack-days-at-toca-boca-2d0249d35d54">Hack Days at Toca Boca</a> was originally published in <a href="https://medium.com/toca-boca-tech-blog">Toca Boca Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[The case of the marketing Git branch]]></title>
            <link>https://medium.com/toca-boca-tech-blog/the-case-of-the-marketing-git-branch-d4aca7adb3a2?source=rss-ebeb1c914806------2</link>
            <guid isPermaLink="false">https://medium.com/p/d4aca7adb3a2</guid>
            <category><![CDATA[unity]]></category>
            <category><![CDATA[project-management]]></category>
            <category><![CDATA[git]]></category>
            <dc:creator><![CDATA[Bertrand Guay Paquet]]></dc:creator>
            <pubDate>Mon, 03 Mar 2025 10:22:42 GMT</pubDate>
            <atom:updated>2025-03-03T10:33:36.887Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*phI9srCBAadzxTeo3Z_JRQ.png" /><figcaption>Toca Boca Days’ version of “This is fine”</figcaption></figure><p>Last week my colleague and I spent the better part of a day trying to untangle an unfortunate situation where Git branches used and managed by our Toca Boca Days marketing team ended up in a bad state. It became essentially impossible to merge the latest changes from our main development branch into marketing’s branch.</p><p>And of course this happened a few days before marketing needed to prepare an important presentation with the latest game content! Suddenly this “other branch I’m vaguely aware of” became a top priority to deal with.</p><p>I want to pause here for a moment. While I call the problematic branch “the marketing branch” for discussion purposes, I am <strong>not</strong> blaming the marketing team <strong>at all</strong> for how we ended up where we were.</p><p>Many factors compounded to create this “perfect storm”, and in retrospect we in the game team haven’t been as proactive as we could to prevent some of the issues we faced. More on these topics below.</p><h3>What’s the marketing branch anyway?</h3><p>We’re lucky to have a really talented technical marketing team at Toca Boca. They make some really cool demo reels and other promotional material directly using the game’s Unity project and assets.</p><p>We develop the game with a focus on mobile devices because that’s our target platform. Unity has many solutions to make it easy to ship a game on multiple platforms, but there are still platform-specific bits and bobs in our code base to optimize the experience for mobile (as any game probably has).</p><p>The marketing team mostly want to produce assets meant for non-game use such as on websites and social media platforms. Here are a few examples of things that they therefore need to tweak:</p><ul><li>Some code changes and “hacks” to unlock things not directly available in the game.</li><li>Several scenes and an avatar customization preset library to reuse across campaigns.</li><li>Adapt the resolution, field of view, UI, and framerate for their target asset format.</li><li>Extra packages and tools to generate action scenes and record them.</li></ul><p>The marketing Git branch is where we store all these marketing-specific changes. The intent is that it stays roughly in sync with the main branch through more or less regular merges from the main branch.</p><p>This approach is the equivalent of the well known <a href="https://www.atlassian.com/git/tutorials/comparing-workflows/gitflow-workflow">main and development branch Git strategy</a> with a long-running development (i.e. marketing) branch that we never intend to merge back in the main branch.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*vPQOXpoXhqh34zOt" /><figcaption><em>Main and marketing branches, the theory</em></figcaption></figure><p>You could argue that all this could live directly into our main branch hidden away in separate folders or behind configuration options. That’s certainly valid criticism, but we get some interesting benefits with our approach:</p><ul><li>The marketing team can work at a different pace, and with a much greater tolerance for breakages than the game team.</li><li>We can relax various processes and automated checks that we have on the main branch which would needlessly slow down the marketing team.</li><li>The Unity project of the game team is leaner because it doesn’t include marketing’s changes and assets.</li><li>There’s no possibility of “cross contamination” where marketing assets or code changes make their way into the game since they’re completely separate.</li></ul><h3>The naive merge from the main branch</h3><p>Back to the task at hand of merging the latest changes from the main branch into the marketing branch…</p><p>It had been about 4 months since the last merge from the main branch. That could’ve been worrying in itself, but there hadn’t been that many changes to the marketing branch since that last merge, so it shouldn’t have been nearly as bad as this when we attempted to merge…</p><pre>$ git status<br>You have unmerged paths.<br>  (fix conflicts and run &quot;git commit&quot;)<br>  (use &quot;git merge --abort&quot; to abort the merge)<br><br>Unmerged paths:<br>  (use &quot;git add/rm &lt;file&gt;...&quot; as appropriate to mark resolution)<br> both modified:   .ci/README.md<br> <br> ... and 1294 more merge conflicts :’(</pre><p>Ouch! Aside from all the “expected” conflicts, there were a ton of conflicts from files such as a CI readme that we knew the marketing team hadn’t changed.</p><h3>Unravelling the nightmarish merge</h3><p>Firstly, the marketing branch had an unfortunately complex Git history. We learned that in fact there were <em>two</em> marketing branches running more or less in parallel over the past months. The “main” one had shifted back and forth, and there were a number of criss-cross branch merges. That’s not ideal and we’ll improve the branch setup in the future.</p><p>We use Google’s Cloud Build platform to automatically build the game and run unit tests on our GitHub pull requests. I don’t have the details, but there’s some limitation in this integration that causes builds to fail when branches become “too big”, which is around 100 commits.</p><p>We haven’t found the time yet to fix this occasional annoyance, primarily because the relatively easy (though not ideal) workaround is to squash commits in a problematic branch and force push it (or open a new pull request).</p><p>In our case however, we had a “too big” branch episode in a pull request that targeted the marketing branch. Unfortunately, that pull request also included a merge commit which was the last merge from the main branch 4 months ago.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1yIWDeXonjHUoxcW" /><figcaption><em>The “lost” merge commit</em></figcaption></figure><p>When we squashed the mkt-feature branch, the “Merge main” Git commit along with the other red square commits became a single commit. Git relies on merge commits to facilitate future branch merges, but now we didn’t have that anymore in Git’s commit history.</p><p>After that, at some point after the “lost” merge commit, the marketing branch also cherry-picked a commit from the main branch to pull in new game content. Whoever chose this approach presumably did so because they were on a tight schedule and faced a monstrous merge conflict when they tried to merge main.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*f4VwdcMYoRD06peJ" /><figcaption><em>A cherry-pick on top</em></figcaption></figure><p>Of course that made any <em>future </em>attempt at merging main even harder.</p><p>And <em>on top of all that</em>, we recently migrated our repository to <a href="https://git-lfs.com/">Git LFS</a> because we needed to trim down its size. To achieve this we used <a href="https://github.com/newren/git-filter-repo">git-filter-repo</a>. After careful planning and a good number of test runs, that worked out quite well. The tool essentially rewrote our entire Git history to make it as if we used LFS from the start. We then force pushed all the migrated branches to GitHub.</p><p>The problem for our merge mission is that the rewritten Git history only includes non-deleted branches in GitHub, and of course we automatically delete pull requests branches on GitHub when they’re merged…</p><h3>Emerging victorious</h3><p>At some point we tried a <a href="https://www.scootersoftware.com/home#merge">3-way folder merge in Beyond Compare</a> to compare the main and marketing directory trees, with the last known “correct” merge point as the comparison base. We made some good progress down this road, but we eventually realized that it would be a very slow approach with a high risk of data loss.</p><p>Along the way, we also realized that there must have been a merge commit hidden somewhere. With Git’s file history, we quickly found the “Squashed” commit that was way larger than the others. The associated pull request didn’t help us find the “lost” merge parent commit though because it was force-pushed over.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/649/0*Ogib33KOsXImejHq" /><figcaption><em>GitHub taunting us</em></figcaption></figure><p>GitHub was taunting us with the 29f6fb5 commit hash that contained the information we wanted, but no way of restoring it. After 4 months of course we couldn’t rely on anyone having that stashed away in their local Git reflog.</p><p>Luckily, we found another closed pull request with a copy of the deleted branch <em>prior</em> to the “big squash” that we were able to restore in GitHub. That <em>did</em> contain the merge parent commit. Success!</p><p>Unluckily, as I mentioned above, this deleted branch has <em>not</em> been migrated to LFS, which meant that this merge parent commit didn’t exist anymore in the repository. So we couldn’t “simply” re-apply all the marketing branch branches from after the “big squash” commit on top of that restored branch. However the commit message did allow us to find the corresponding post-LFS migration merge parent commit.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*UCccD4C2gyORxzXB" /><figcaption><em>Fixed marketing branch</em></figcaption></figure><p>Once we figured out what happened to the marketing branch, we fixed everything in a few hours with a lot of manual work following these 9 simple steps:</p><ol><li>Create a new work branch on the last recorded merge commit in the marketing branch.</li><li>Merge the main branch from the commit of the “lost” merge. Fix merge conflicts and compilation errors, and check that things work in Unity.</li><li>Checkout the squashed mkt-feature branch commit in another folder.</li><li>Compare the folders from the two previous steps to manually reapply the changes from the mkt-feature branch, excluding the main merge which we have from step 3, to the work branch.</li><li>Cherry-pick 8 “clean” commits from the marketing branch that came after that.</li><li>Afterwards, the marketing branch’s history criss-crosses a lot, so manually squash with a folder comparison all the following changes up to the cherry-picked commit from main.</li><li>Merge the main branch again, this time from the cherry-picked commit. Fix merge conflicts and compilation errors, and check that things work in Unity.</li><li>Once more manually squash with a folder comparison all the changes after the cherry-pick up to the latest commit of the marketing branch.</li><li>Merge the latest main. Fix merge conflicts and compilation errors, and check a bit more thoroughly that marketing’s changes still work in Unity.</li></ol><p>Easy right?</p><h3>Lessons learned</h3><p>There’s quite a lot to take away from this Git adventure.</p><p>First I don’t think anyone could have done it alone. There were so many compounding factors at play so no one had all the information to untangle the mess. In the end we needed a lot of organizational and project knowledge, a good folder comparison tool, Git expertise, and a lot of time.</p><p>Regarding Git LFS, ideally use it from the beginning of the project. And if it’s not there from the beginning, the longer the wait, the harder the migration will be. Teams grow, more dependent processes get established, Git’s history expands, etc. There’s little <em>technical</em> challenge from running the Git LFS migration tool itself. It’s the challenges specific to the organization that can consume a lot of time. I’ll admit that for small enough teams that work on more “simple” projects, a migration can be relatively painless.</p><p>Long-lived parallel Git branches are treacherous. In a previous role, I maintained my own long-lived branch for some disruptive code changes that couldn’t be merged back to the main branch for a few months. It was still a bit painful, but it went as well as it could. Before I embarked on that journey, I spent significant time researching the best approach to manage my parallel branch effectively which paid off.</p><p>The best course of action is to avoid long-lived branches when you can. In the case of our marketing branch, it’s clear to me that we in the game team need to invest time to define clear guidance for the marketing team so we don’t find ourselves in a similar position later.</p><p>And once we have these guidelines, that will be the topic of a future blog post!</p><p><em>Thanks to Víctor Guerrero Corbi for teaming-up with me on this adventure!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=d4aca7adb3a2" width="1" height="1" alt=""><hr><p><a href="https://medium.com/toca-boca-tech-blog/the-case-of-the-marketing-git-branch-d4aca7adb3a2">The case of the marketing Git branch</a> was originally published in <a href="https://medium.com/toca-boca-tech-blog">Toca Boca Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Unity’s TransformAccessArray — internals and best practices]]></title>
            <link>https://medium.com/toca-boca-tech-blog/unitys-transformaccessarray-internals-and-best-practices-2923546e0b41?source=rss-ebeb1c914806------2</link>
            <guid isPermaLink="false">https://medium.com/p/2923546e0b41</guid>
            <category><![CDATA[rendering]]></category>
            <category><![CDATA[job-system]]></category>
            <category><![CDATA[unity]]></category>
            <category><![CDATA[performance]]></category>
            <dc:creator><![CDATA[Bertrand Guay Paquet]]></dc:creator>
            <pubDate>Fri, 08 Nov 2024 13:05:11 GMT</pubDate>
            <atom:updated>2026-01-20T14:32:30.895Z</atom:updated>
            <content:encoded><![CDATA[<h3>Unity’s TransformAccessArray — internals and best practices</h3><p>I recently adopted rendering code that makes heavy use of Unity jobs with TransformAccessArray from a colleague who’s changing teams. I already knew about TransformAccessArray and saw it used, but I’d never had the opportunity to fully understand how they work.</p><p>It’s a bit of an uphill battle because there’s not much material published about them and the <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccessArray.html">documentation for the struct</a> is very sparse. The most informative documentation pages I found as of writing are <a href="https://docs.unity3d.com/ScriptReference/Jobs.IJobParallelForTransform.html">IJobParallelForTransform</a> and the child pages of <a href="https://docs.unity3d.com/ScriptReference/Jobs.IJobParallelForTransformExtensions.html">IJobParallelForTransformExtensions</a>, but even these are somewhat slim.</p><p>So this situation turned into the perfect opportunity to explore some internals of Unity’s job system to better understand how TransformAccessArray and IJobParallelForTransform work, especially in combination with “regular” transform accesses on the main thread (i.e. outside of jobs). I found some very interesting results that I want to share in this post.</p><p>What follows is an explanation of some of <a href="#d9b3">TransformAccessArray‘s internals</a>, a <a href="#016a">job test script</a>, analysis of a few <a href="#204b">job</a> <a href="#ac4f">usage</a> <a href="#7b55">patterns</a>, and <a href="#987c">best practices</a> derived from these observations. I also included a short <a href="#c46c">Unity improvement wishlist</a> to boost the performance of the job system.</p><p>Let’s dive in!</p><h3>TransformAccessArray internals</h3><p>Jobs in <a href="https://docs.unity3d.com/Manual/job-system-overview.html">Unity’s job system</a> can only use <a href="https://learn.microsoft.com/en-us/dotnet/framework/interop/blittable-and-non-blittable-types">blittable data types</a>, which means they don’t have access to managed types such as Transform and MeshRenderer. In terms of safety, this restriction allows the Unity engine to protect against data races where a worker would write data in memory while another worker or the main thread accesses the same memory location.</p><p>TransformAccessArray instances provide a way to get around this limitation to access transforms inside jobs, both for reading and writing. At its core, this functionality relies on Unity’s internal C++ TransformHierarchy class. At <a href="https://www.youtube.com/watch?v=W45-fsnPhJY&amp;t=796s">13:14 of the <strong>Unite Berlin 2018 — Unity’s Evolving Best Practices</strong> talk</a>, there’s a still very relevant discussion of this class. The following quote is very important to understand how TransformAccessArray works:</p><blockquote>There is one transform hierarchy structure for each root transform in your scene.</blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/404/1*Q94ikOiSPiAYQgOs5F1wng.png" /><figcaption><em>Transform roots in a scene hierarchy</em></figcaption></figure><p>From here on I’ll use the terms transform hierarchy and <a href="https://docs.unity3d.com/ScriptReference/Transform-root.html">transform root</a> somewhat interchangeably.</p><p>If we combine the above with this snippet from the <a href="https://docs.unity3d.com/ScriptReference/Jobs.IJobParallelForTransformExtensions.Schedule.html">IJobParallelForTransform.Schedule method documentation</a>, we can already get an intuition that the two aspects are related:</p><blockquote>This method parallelizes access to transforms in different hierarchies. Transforms with a shared root object are always processed on the same thread.</blockquote><p>The <a href="https://docs.unity3d.com/ScriptReference/Jobs.IJobParallelForTransformExtensions.ScheduleReadOnly.html">ScheduleReadOnly method</a> eases the scheduling restriction:</p><blockquote>This method provides better parallelization because it can read all transforms in parallel instead of just parallelizing over different hierarchies.</blockquote><p>When you create a TransformAccessArray instance with an array of transforms, Unity internally reorders it for efficient access. The transforms are first grouped by their transform root. Then the transforms that share the same root are sorted together to optimize iteration speed based on how their shared transform hierarchy stores them internally.</p><p>When Unity executes a IJobParallelForTransform job, the order in which it calls the Execute method with TransformAccess instances can therefore be very different from the original order in the TransformAccessArray‘s transform array. That’s where the index argument comes in handy. It allows you to map a specific call to the Execute method to its corresponding transform element in the original transform array. If you noticed the internal TransformAccessArray.GetSortedToUserIndex method and wondered what it’s about, this is it.</p><p>Importantly, TransformAccessArray doesn’t copy any transform data for reading or writing in jobs. There is no buffer or temporary storage unless you implement one yourself in some other way. This direct access is the main benefit of using them.</p><p>But it also means that there’s one more bit of theory to examine before we look at how everything comes together concretely.</p><h4>Synchronization of transform hierarchy access</h4><p>As mentioned above, Unity’s job system is quite restrictive about what data you can access in jobs. In terms of a TransformAccessArray and the TransformHierarchy instances it implicitly provides access to, it means that Unity has some mechanisms to avoid problems with concurrent modifications to transforms and reading stale values. Its data <a href="https://en.wikipedia.org/wiki/Synchronization_(computer_science)">synchronization</a> method, known as fences internally, avoids potential <a href="https://en.wikipedia.org/wiki/Race_condition">race conditions</a> from the main and worker threads accessing the same transforms concurrently.</p><p>Unity’s granularity to protect access to transforms is the transform hierarchy. In other words, all the transforms that share the same transform root also share the same fence. When a job that uses a TransformAccessArray is scheduled, Unity delays all other accesses to any transform that shares a transform root with the job until it completes. This means any transform that has the same transform root as any transform in the TransformAccessArray. Let’s illustrate with an example.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/403/1*rKw25Q3GlFgpQiiZPZgTlg.png" /><figcaption><em>Two jobs that operate on the same transform hierarchy</em></figcaption></figure><p>The image above shows how two jobs that don’t access the same transforms still have a transform hierarchy in common. If <strong>Job A</strong> is scheduled before <strong>Job B</strong>, <strong>Job B</strong> doesn’t start until <strong>Job A</strong> completes. <strong>Job A</strong> needs to complete in its entirety, even if its remaining job batches use only different transform hierarchies. This blocking behavior affects the following scenarios:</p><ul><li>Other IJobParallelForTransform jobs, even read-only ones.</li><li>Read or write access to a transform from the main thread, such as in a MonoBehaviour C# script.</li><li>Any other access to transforms, such as in animations and skinned mesh renderers.</li></ul><p>When jobs are blocked they simply remain in the job execution queue. When the main thread is blocked, such as when it calls the <a href="https://docs.unity3d.com/ScriptReference/Unity.Jobs.JobHandle.Complete.html">JobHandle.Complete</a> method or attempts to access a transform that an unfinished job uses, it can become idle or resort to <a href="https://en.wikipedia.org/wiki/Work_stealing">work stealing</a> where possible. Work stealing means that the main thread picks up a job ready for execution and executes it. The reasoning behind this is that it’s better for the main thread to do something than stay idle, but it has important consequences discussed later in this article.</p><h3>TransformAccessArray test script</h3><p>I wrote the following test script to derive much of the information I presented above and to validate my understanding of TransformAccessArray in different synthetic job scenarios. No game would ever do this sequence of operations right after another exactly in this way, but it’s still a great way to simulate a wide range of real-world scenarios.</p><p><em>(code optimized for display on Medium’s narrow width)</em></p><pre>using System.Threading;<br>using Unity.Jobs;<br>using Unity.Profiling;<br>using UnityEngine;<br>using UnityEngine.Jobs;<br><br>public class TransformAccessArrayTest : MonoBehaviour<br>{<br>   [SerializeField] [Range(1, 100)] private uint hierarchyRootsCount = 2;<br><br>   [Tooltip(&quot;Transform count in each transform hierarchy root&quot;)]<br>   [SerializeField] [Range(1, 100)] private uint hierarchyDepth = 4;<br><br>   [Tooltip(&quot;How long to delay the start of the TransformJob&quot;)]<br>   [SerializeField] private int delayJobStartMs;<br><br>   [Tooltip(&quot;Per-Transform job time&quot;)]<br>   [SerializeField] private int jobRuntimeMs = 1;<br>  <br>   [SerializeField] [Range(-1, 100)] private int desiredJobCount = -1;<br>   [SerializeField] private bool scheduleAsReadOnlyJob;<br>  <br>   [Tooltip(&quot;Schedule a second read-only IJobParallelForTransform job&quot;)]<br>   [SerializeField] private bool addParallelReadOnlyJob;<br><br>   [Tooltip(&quot;Applies to read-only jobs only&quot;)]<br>   [Range(1, 100)] [SerializeField] private int readonlyJobBatchSize = 2;<br>  <br>   [SerializeField] private bool readTransformsAfterJob = true;<br>   [SerializeField] private bool writeTransformsAfterJob;<br><br>   GameObject[] generatedGameObjects;<br>   TransformAccessArray accessArray;<br><br>   static readonly ProfilerMarker markerBefore = new(&quot;BeforeJobScheduled&quot;);<br>   static readonly ProfilerMarker markerReadAfter = new(&quot;ReadAfterJobScheduled&quot;);<br>   static readonly ProfilerMarker markerWriteAfter = new(&quot;WriteAfterJobScheduled&quot;);<br><br>   void OnValidate() =&gt; Cleanup();<br>   void OnDestroy() =&gt; Cleanup();<br><br>   void Cleanup()<br>   {<br>       if (generatedGameObjects != null)<br>       {<br>           for (int i = generatedGameObjects.Length - 1; i &gt;= 0; i--)<br>               Destroy(generatedGameObjects[i]);<br><br>           generatedGameObjects = null;<br>           if (accessArray.isCreated)<br>               accessArray.Dispose();<br>       }<br>   }<br><br>   void Update()<br>   {<br>       // Support dynamically changing parameters in the Editor<br>       if (!accessArray.isCreated)<br>           CreateTransformArray();<br>      <br>       // Write to the transforms from the main thread<br>       using (markerBefore.Auto())<br>       {<br>           foreach (var go in generatedGameObjects)<br>               go.transform.position += new Vector3(0.000001f,0, 0);<br>       }<br><br>       var delayJobHandle = delayJobStartMs &lt;= 0 ? default :<br>           new DelayJob() { DelayMs = delayJobStartMs }.Schedule();<br>       var transformJob = new TransformJob() { JobRuntimeMs = jobRuntimeMs };<br><br>       // Set the optional DelayJob as a job dependency of TransformJob<br>       if (scheduleAsReadOnlyJob)<br>       {<br>           transformJob.ScheduleReadOnly(accessArray, readonlyJobBatchSize, delayJobHandle);<br>       }<br>       else<br>       {<br>           transformJob.Schedule(accessArray, delayJobHandle);<br>       }<br><br>       // Schedule a second read-only job<br>       if (addParallelReadOnlyJob)<br>       {<br>           new ReadOnlyJob() { JobRuntimeMs = jobRuntimeMs }<br>               .ScheduleReadOnly(accessArray, readonlyJobBatchSize, delayJobHandle);<br>       }<br><br>       // Fake some work so the loops below can&#39;t be removed as no-ops<br>       var position = Vector3.zero;<br>       if (readTransformsAfterJob)<br>       {<br>           using var _ = markerReadAfter.Auto();<br>           foreach (var go in generatedGameObjects)<br>               position += go.transform.position;<br>       }<br>      <br>       if (writeTransformsAfterJob)<br>       {<br>           using var _ = markerWriteAfter.Auto();<br>           position = Vector3.Min(position * 0.0000001f, Vector3.one * 0.1f);<br>           foreach (var go in generatedGameObjects)<br>               go.transform.position = position;<br>       }<br>   }<br><br>   void CreateTransformArray()<br>   {<br>       generatedGameObjects = new GameObject[hierarchyRootsCount * hierarchyDepth];<br>       var transforms = new Transform[hierarchyRootsCount * hierarchyDepth];<br>       var transformsIndex = 0;<br>       for (int i = 0; i &lt; hierarchyRootsCount; i++)<br>       {<br>           var parent = new GameObject($&quot;generated_{i}&quot;);<br>           generatedGameObjects[transformsIndex] = parent;<br>           transforms[transformsIndex++] = parent.transform;<br>          <br>           // Not technically a depth, but it has the same impact<br>           // for Unity&#39;s job scheduling<br>           for (int j = 0; j &lt; hierarchyDepth - 1; j++)<br>           {<br>               var child = new GameObject($&quot;{parent.name}_{j}&quot;);<br>               child.transform.SetParent(parent.transform);<br>               generatedGameObjects[transformsIndex] = child;<br>               transforms[transformsIndex++] = child.transform;<br>           }<br>       }<br><br>       accessArray = new TransformAccessArray(transforms, desiredJobCount);<br>   }<br>}<br><br>struct DelayJob : IJob<br>{<br>   public int DelayMs;<br>   public void Execute() =&gt; Thread.Sleep(DelayMs);<br>}<br>  <br>struct TransformJob : IJobParallelForTransform<br>{<br>   public int JobRuntimeMs;<br>   public void Execute(int i, TransformAccess t) =&gt; Thread.Sleep(JobRuntimeMs);<br>}<br>  <br>// Use a second type to easily identify it in the profiler<br>struct ReadOnlyJob : IJobParallelForTransform<br>{<br>   public int JobRuntimeMs;<br>   public void Execute(int i, TransformAccess t) =&gt; Thread.Sleep(JobRuntimeMs);<br>}</pre><p>When it starts, the script generates a hierarchy of game objects based on the <strong>Hierarchy Roots Count</strong> and <strong>Hierarchy Depth</strong> properties.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/847/1*yr4JZgZ6XiWgg62PW15xpw.png" /><figcaption><em>Script properties and the generated scene game objects</em></figcaption></figure><p>The following sequence diagram shows what the Update method does and the yellow boxes illustrate the effect of some of the script’s properties.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/948/0*G7LbHOpOnjPvncc7" /><figcaption><em>Sequence diagram of jobs and actions</em></figcaption></figure><p>If you enable the <strong>Add Parallel Read Only Job</strong> property, the script schedules a second IJobParallelForTransform job named <strong>ReadOnlyJob</strong> directly after step number two in the diagram. To keep the script simple, this job accesses the same TransformAccessArray as the <strong>TransformJob</strong>, but the results are the same if they use separate TransformAccessArray instances, as long as they access the same transform hierarchies.</p><p>The <strong>DelayJob</strong> job is an optional job dependency from the TransformAccessArray job(s). This allows us to simulate scenarios where the latter consumes output from another job, even though there isn’t any actual output in this test script.</p><p>Let’s analyze a few scenarios with Unity configured to use 4 worker threads with the -job-worker-count 4 command line option.</p><h4>TransformAccessArray job with job dependency</h4><p>In this scenario we use 2 transform roots with 4 transforms each. The test script schedules a <strong>DelayJob</strong> which is a dependency to both the <strong>TransformJob</strong> and <strong>ReadOnlyJob</strong> jobs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*jbR6utd1Fs3yXQcH" /><figcaption><em>Settings for TransformAccessArray job with job dependency</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*1i4HqVLfC98K7x-x" /><figcaption><em>Profiler capture for TransformAccessArray job with job dependency</em></figcaption></figure><p>From this profiler capture we can make several observations.</p><p>The main thread is blocked in <strong>ReadAfterJobScheduled</strong> because it attempts to read data from transforms used in <strong>TransformJob</strong> and <strong>ReadOnlyJob</strong>. Note that the main thread is blocked even though it tries to read data during <strong>DelayJob </strong>which isn’t a IJobParallelForTransform. This is because <strong>TransformJob</strong> is already scheduled for execution at which point it “sets” itself as a dependency of the transform hierarchy’s synchronization fence.</p><p>When the main thread is blocked, the profiler capture demonstrates both of the blocked main thread behaviors described above. The thread first runs, or work-steals, the <strong>DelayJob</strong>. It’s then idle while the other jobs run on worker threads. This specific behavior isn’t deterministic and varies between frames.</p><p>Despite a <strong>Desired Job Count</strong> of 8 and 8 total transforms for the jobs to operate on, there are only 2 <strong>TransformJob</strong> job batches. This lower number than requested is because it only accesses two transform hierarchies. Non read-only jobs don’t execute in parallel on the same transform hierarchy. The <strong>ReadOnlyJob</strong> however can concurrently access transforms in the same transform hierarchy and is therefore split in 4 job batches because the <strong>Read Only Batch Size</strong> is 2.</p><h4>Multiple read-only transform accesses</h4><p>We use the same transform configuration in this scenario. However this time <strong>TransformJob</strong> and <strong>ReadOnlyJob</strong> are read-only jobs, and there’s no <strong>DelayJob</strong> (more on that in the next section). In other words, after the initial write access in the <strong>BeforeJobScheduled</strong> profiler marker, the script only accesses transforms with read-only methods.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*v57hkDi_sGsXQW6n" /><figcaption><em>Settings for multiple read-only transform accesses</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*Z0hY9dVTews161IA" /><figcaption><em>Profiler capture for multiple read-only transform accesses</em></figcaption></figure><p>The main thread is again blocked in <strong>ReadAfterJobScheduled</strong> as it attempts to read data from transforms used in <strong>TransformJob</strong> and <strong>ReadOnlyJob</strong>. I was surprised by this blocking behavior because all these accesses are read-only, and Unity is able to verify as much from the API calls in the script.</p><p>This is a missed opportunity for Unity to parallelize access to a shared resource from multiple read-only consumers. In theory Unity could let the main thread read transform data unhindered and run both read-only jobs in parallel instead of keeping threads idle.</p><h4>Deadlock warning!</h4><p><strong>Update: fixed in all current Unity versions: </strong><a href="https://issuetracker.unity3d.com/issues/the-editor-freezes-when-schedulereadonly-of-ijobparallelfortransform-with-dependency-is-used"><strong>UUM-86782</strong></a></p><p>As of writing, the following affects Unity versions 2022.3.31f1 to 2022.3.52f1, and 6000.0.3f1 and above.</p><p>If you set the <strong>Delay Job Start</strong> property to a non-zero value in the previous scenario, Unity will lock up and become unresponsive. The transform read accesses in <strong>ReadAfterJobScheduled</strong> never complete and are stuck in a deadlock situation.</p><p>This minimal sequence of events causes a deadlock:</p><ol><li>Schedule any job A.</li><li>Use the ScheduleReadOnly method to schedule a IJobParallelForTransform job B with a dependency on job A.</li><li>From the main thread, read the position of a transform included in the TransformAccessArray given to job B.</li></ol><p>While a common jobs scenario, this bug is likely intermittent and difficult to diagnose in real-world scenarios because it depends on the exact timing of things.</p><p>When we look at occurrences of “Application Not Responding” (ANR) for our Toca Boca Days game, the most common callstacks we see are precisely in code that accesses transforms. Since we make heavy use of the IJobParallelForTransform.ScheduleReadOnly feature there’s a good chance that I stumbled upon the root cause of those hangs while researching TransformAccessArray. Bonus!</p><p>For reference, the Unity ticket is <a href="https://issuetracker.unity3d.com/issues/the-editor-freezes-when-schedulereadonly-of-ijobparallelfortransform-with-dependency-is-used">UUM-86782</a>.</p><h4>Single root transform</h4><p>Let’s look at one more scenario with a single root transform with many children. We also leave the <strong>Desired Job Count</strong> to -1 which lets Unity pick a default value for us.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*R_dghwtvGHFewS_0" /><figcaption><em>Settings for a single root transform</em></figcaption></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*T58DTzZoRhQDCHeW" /><figcaption><em>Profiler capture for a single root transform</em></figcaption></figure><p>As before, the main thread is blocked in <strong>ReadAfterJobScheduled</strong>.</p><p>Since <strong>TransformJob</strong> isn’t scheduled as read-only, and there’s a single transform hierarchy for the whole TransformAccessArray, Unity doesn’t distribute the job across multiple worker threads which leads to a very long job run time.</p><p>As expected the <strong>ReadOnlyJob</strong> isn’t limited by the number of transform hierarchies and gets split in 4 smaller units. Note however that in my tests some frames have 4 concurrent <strong>ReadOnlyJob</strong> jobs while others have 5. This variability between frames for read-only jobs is because the TransformParallelForLoopStruct.Execute method, which is the starting point of the job in C# for each thread, <a href="https://github.com/Unity-Technologies/UnityCsReference/blob/2022.3/Runtime/Jobs/Managed/IJobParallelForTransform.cs">calls</a> JobsUtility.GetWorkStealingRange to greedily grab or steal from another thread the next batch of work (i.e. work range) until all work is exhausted. Since the order in which the threads reach this code is nondeterministic, in theory we could see anywhere between 1 and 5 threads executing the job.</p><h3>TransformAccessArray job performance best practices</h3><p>Here are some recommendations based on my research and analysis that can help to get the most out of TransformAccessArray jobs as of Unity 2022.3.52f1 and 6000.0.26f1.</p><p>There’s a lot to be said about general best practices for the job system. However the focus here is best practices specifically for jobs that access transforms. I’ll still give the general recommendation to make use of the <a href="https://docs.unity3d.com/Manual/com.unity.burst.html">Burst compiler</a> in your jobs. It’s not part of my example code because it wasn’t relevant to my research, but you should almost always use it in real jobs.</p><p>Whenever a job needs to only read transforms (i.e not write), make sure to use the IJobParallelForTransform.ScheduleReadOnly method to schedule it. When you do so, the job gets better parallelization opportunities. However, do read the “Deadlock warning!” section because there’s a pretty serious bug in current versions of Unity.</p><p>Break up deep transform hierarchies in multiple transform roots as much as possible. Avoid at all costs the “folder” hierarchy anti-pattern to group a large number of game objects under a single root transform. This recommendation can give significant performance gains in many parts and systems of Unity. For jobs that use a TransformAccessArray specifically, you can get gains from these aspects:</p><ul><li>More opportunities to parallelize non-read-only jobs. The job system doesn’t distribute these jobs to more workers than there are transform roots.</li><li>It’s less likely that a job (read-only or not) causes unintended main thread stalls or generates “implicit” job dependencies from accessing transforms in the same transform hierarchy as another job. Remember that as long as a job accesses any transform in a transform hierarchy that a previous job also accesses, the latter job blocks execution of the former until it’s complete, even if it’s read-only.</li></ul><p>Study the behavior of jobs in your game in the profiler on the actual target hardware or something representative of it. The performance bottlenecks can be completely different on different platforms and build configurations. If you see parts of the frame where fewer workers than expected are active on a TransformAccessArray job, check for the situations that limit parallelization, and review the <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccessArray-ctor.html">desiredJobCount</a> and <a href="https://docs.unity3d.com/ScriptReference/Unity.Jobs.LowLevel.Unsafe.JobsUtility.ScheduleParallelForTransformReadOnly.html">innerloopBatchCount</a> parameters you use. You should aim for small enough values to keep all workers busy, but large enough to avoid workers spending time grabbing or stealing work too often. There’s no single correct value here. To help you reason about this topic, consider that Unity defaults to 32 minimum transforms per job invocation for non-readonly jobs, and that the maximum number of batches of work (i.e. work ranges) for all types of parallel jobs is 16.</p><p>Where possible, prefer to use local space transform data such as <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccess-localPosition.html">localPosition</a> and <a href="http://getlocalpositionandrotation/">GetLocalPositionAndRotation</a> over world space transform data such as <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccess-position.html">position</a> and <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccess-localToWorldMatrix.html">localToWorldMatrix</a>. This recommendation extends to interactions with transforms in all situations, not only in jobs. Transform hierarchies store local space transform matrices for each transform so local space values are directly available. In comparison, Unity recursively multiplies the local space transform matrices of all parents to compute world space values, and it does so each time you request them. This process is dramatically slower than direct access to local space values, and gets more costly as the number of parent transforms increases. If you must work with world space values, limit the number of calls you use and take advantage of <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccess.GetPositionAndRotation.html">GetPositionAndRotation</a> and <a href="https://docs.unity3d.com/ScriptReference/Jobs.TransformAccess.SetPositionAndRotation.html">SetPositionAndRotation</a>.</p><p>Reuse TransformAccessArray instances between frames; don’t needlessly recreate them. WIth each new instance, Unity allocates memory, prepares state and sorts transforms which takes time. For example, if you need to remove a transform from the array, use the <a href="https://docs.unity3d.com/2022.3/Documentation/ScriptReference/Jobs.TransformAccessArray.RemoveAtSwapBack.html">TransformAccessArray.RemoveAtSwapBack</a> method instead of recreating the array. However there’s a caveat with regards to fences. When you mutate an existing TransformAccessArray, Unity triggers a synchronization point that waits for all previous jobs that use the same array to complete. So make sure you don’t introduce implicit job dependencies just for the sake of reusing arrays.</p><p>Don’t use the transforms in a TransformAccessArray to store intermediary data between jobs. Compared to other options, transform access in jobs is comparatively slower, incurs the risk of main thread stalls, and provides fewer parallelization opportunities. Ideally, only read transform data from jobs when you need the latest values, and only write to a transform from jobs at most once in a frame. Consider dedicated TransformAccessArray jobs that only extract and output transform values, with temporary <a href="https://docs.unity3d.com/ScriptReference/Unity.Collections.NativeArray_1.html">NativeArray</a>s to store the intermediary transform data for your calculations. This strategy can drastically improve the parallelization of your jobs.</p><p>Be aware of transform access patterns in your game to avoid stalls, especially on the main thread. This recommendation is probably the most difficult to both diagnose and implement, but the impact can be significant. The main thread is usually on the <a href="https://en.wikipedia.org/wiki/Analysis_of_parallel_algorithms">critical path</a> of frames, so it’s important to understand which transform hierarchies the TransformAccessArray jobs operate on, as well as when you access these same transform hierarchies on the main thread. As we’ve seen in the scenarios above, in the worst case the main thread blocks as it attempts to access one of these transform hierarchies shortly after it schedules a job that also accesses the same transform hierarchy. The specific solutions vary, but a general tactic is to carefully plan when you access transforms on the main thread during the frame, and rework the transform hierarchies to better fit the job execution graph.</p><h3>Unity job system performance wishlist</h3><p>While writing this article I came across some limitations in Unity that I believe could be improved with no or minimal API changes. If implemented, these could provide performance gains to users in some common scenarios in a seamless way. If any Unity job system engineers are reading, it’d be great to hear your thoughts!</p><p>In my opinion Unity should allow concurrent read-only access to a transform hierarchy from the main thread and from jobs. I’m sure there are good reasons why this isn’t available at the moment, but concurrent read-only access to a shared resource is a very common pattern in parallel programming, and in most environments it’s more efficient than read-write access. In theory Unity could implement this improvement without any API change because the read-only semantics already exist.</p><p>Another wish is to break up the “monolithic” dependency of TransformAccessArray jobs on all the transform hierarchies they access. Currently a job won’t start until <em>all</em> previous jobs that access <em>any</em> of the transform hierarchies it needs are completed.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/600/1*mVoeXY42lSdFkDSGQU_7lQ.png" /><figcaption><em>Two jobs with a common transform hierarchy</em></figcaption></figure><p>In the above diagram, <strong>Job A</strong> accesses one transform hierarchy, and <strong>Job B</strong> accesses the same transform hierarchy plus several more. Because of this overlap of a single transform hierarchy, <strong>Job B</strong> doesn’t start at all until <strong>Job A</strong> completes, even if <strong>Job A</strong> isn’t an explicit dependency of <strong>Job B</strong>. Of course in this simplistic example it’s possible to break up <strong>Job B</strong> in two parts to unblock its execution partially: one part, blocked by <strong>Job A</strong>, that accesses the common transform hierarchy and the second unblocked part that accesses the rest. However this approach quickly becomes unwieldy in non-trivial scenarios.</p><p>Unity could instead handle this complexity seamlessly for users. Since TransformAccessArray instances already group their transforms by transform root, it should be possible for Unity to split jobs behind the scenes into as many parts as there are transform hierarchies. Each part would be free to start execution as soon as the fence on its transform hierarchy is unblocked. However this could potentially come with some subtle differences in how work batch sizes are treated, but the potential performance gains could be worthwhile.</p><p>Lastly, I haven’t looked too closely into an actual implementation, but perhaps transform hierarchies should cache the last computed value of a transform’s localToWorldMatrix, which is essentially the basis of all other world space transform values. It’s probably calculated over and over in most TransformAccessArray jobs that access world space values, and this cost increases for each extra nested transform level.</p><h3>Conclusion</h3><p>Parallel programming is always tricky and Unity adds a few twists that are important to know about to squeeze the most performance out of its jobs system. The different scenarios in this post reproduce situations you’re likely to encounter in your games, albeit with much more surrounding complexity.</p><p>Interestingly my investigation also revealed a potential deadlock situation in the job system that I expect to be quite common in actual games <strong>(Update: now fixed)</strong>. It certainly looks like it’s the case for the Toca Boca Days game I work on, so hopefully my bug report will become a fix that benefits the wider Unity community.</p><p>And again, at the risk of sounding like a broken record, before you embark on complex optimizations, first profile your game to identify where its actual bottlenecks are!</p><p><em>Thanks to Fredrik Bergljung for your support and to an anonymous tech reviewer!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=2923546e0b41" width="1" height="1" alt=""><hr><p><a href="https://medium.com/toca-boca-tech-blog/unitys-transformaccessarray-internals-and-best-practices-2923546e0b41">Unity’s TransformAccessArray — internals and best practices</a> was originally published in <a href="https://medium.com/toca-boca-tech-blog">Toca Boca Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Controlling Unity’s rendering order — why and how]]></title>
            <link>https://medium.com/toca-boca-tech-blog/controlling-unitys-rendering-order-why-and-how-3c2bb1da8e78?source=rss-ebeb1c914806------2</link>
            <guid isPermaLink="false">https://medium.com/p/3c2bb1da8e78</guid>
            <category><![CDATA[rendering]]></category>
            <category><![CDATA[unity]]></category>
            <category><![CDATA[urp]]></category>
            <category><![CDATA[unity-hdrp]]></category>
            <dc:creator><![CDATA[Bertrand Guay Paquet]]></dc:creator>
            <pubDate>Thu, 26 Sep 2024 08:01:33 GMT</pubDate>
            <atom:updated>2025-11-19T20:14:30.776Z</atom:updated>
            <content:encoded><![CDATA[<figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*LSKQyaeo-Z-ETM0kE7SJrw.png" /><figcaption>ChatGPT’s take on a good header image for this post’s topic</figcaption></figure><p>A colleague recently asked for advice on how to control the order in which Unity renders objects in the game. His question motivated me to do a deep dive into how Unity defines the rendering order of objects for a camera, and to share the results of my research here.</p><p>This post is already quite long so I’ll keep its focus on conceptual and reference information.</p><p>While the description in Unity’s manual isn’t exhaustive, it does a good job of describing the <a href="https://docs.unity3d.com/Manual/built-in-rendering-order.html">rendering order in the Built-in Render Pipeline</a>. However the Universal Render Pipeline (URP), and other Scriptable Render Pipelines (SRPs), use a different sorting algorithm, and they offer much more possibilities to control rendering with features such as custom render passes.</p><p>I’m not aware of any comprehensive reference that explains all the sorting criteria that affect the rendering order, so that’s what this post aims to be! I’ll focus on URP in Unity 2022.3 LTS and Unity 6, but most of the information below applies to the High Definition Render Pipeline (HDRP) as well.</p><p>For convenience I embedded numerous links to relevant Unity documentation.</p><h3>Why control Unity’s rendering order</h3><p>Let’s first state that most of the time you probably don’t need to worry about the specific rendering order of objects in your scene. URP renders opaque objects before transparent objects, makes sure to render its other features such as decals at the appropriate time, and uses a reasonable default rendering order to provide good performance. The depth buffer also makes sure that the opaque objects nearest to the camera hide those behind them.</p><p>However, you might need to customize URP’s default rendering order to achieve a visual effect or to improve the performance of your game. An example of a visual effect is stencil shadows, for which you need to render shadow volumes to the stencil buffer, and then use the results to apply shadows to the scene in a full screen pass.</p><p>To improve performance, it’s sometimes beneficial to render large opaque occluders first so they write to the depth buffer. The depth buffer is then primed to more efficiently use depth tests to reduce the number of pixel shader executions necessary to render other objects in the scene.</p><p>What you’ll need really depends on the specific features and characteristics of your game.</p><p>If you want to control the rendering order to improve performance, make sure to profile your GPU performance beforehand to validate your assumptions. And don’t forget to also profile afterwards to confirm that you did in fact improve things. Additional complexity is only worth it if it measurably achieves gains!</p><p>It’s also important to familiarize yourself with the performance characteristics of your target platform or platforms. <a href="https://en.wikipedia.org/wiki/Tiled_rendering">Tile-based deferred rendering</a> (TBDR) GPUs for example have significantly different performance best practices compared to discrete desktop GPUs.</p><p>What that said, let’s dive in!</p><h3>Macro control of rendering order with render passes</h3><p>With URP you can customize the rendering order via <a href="https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@17.0/manual/customizing-urp.html">custom render passes</a>. I won’t go into depth about how to use them because there are many other great resources out there that cover that topic. And in particular URP’s documentation team really improved that area in the past year!</p><p>I qualify render passes as “macro control” here because they typically serve to control the rendering state and rendering order of a subset of objects. In other words, at a high level render passes do the following:</p><ul><li>Inject themselves into the rendering pipeline in an injection point, normally based on <a href="https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@14.0/api/UnityEngine.Rendering.Universal.RenderPassEvent.html">RenderPassEvent</a>.</li><li>Optionally define inputs and outputs, such as the render target.</li><li>Use <a href="https://docs.unity3d.com/ScriptReference/Rendering.FilteringSettings.html">FilteringSettings</a> to select a subset of the objects included in the current camera’s <a href="https://docs.unity3d.com/ScriptReference/Rendering.CullingResults.html">CullingResults</a>. This optionally reduces which objects to render from those left after frustum culling, occlusion culling, layer masking and LOD level masking.</li><li>Set the required rendering state and global shader variables.</li><li>Schedule draw commands to render objects.</li></ul><p>Other typical uses of custom render passes are full screen effects, blit the framebuffer to a texture, and other framebuffer manipulations. These use-cases still need to be executed at a specific point in the frame, but they often don’t render more than one or a few objects; often only a full screen quad (or triangle).</p><p>To learn more about custom render passes, I recommend looking into the <a href="https://docs.unity3d.com/Manual/FrameDebugger.html">Frame Debugger</a> and the relevant parts of URP’s C# source code. It’s a good source of inspiration for your own render passes. <a href="https://github.com/Unity-Technologies/Graphics/blob/2022.3/staging/Packages/com.unity.render-pipelines.universal/Runtime/Passes/RenderObjectsPass.cs">RenderObjectsPass.cs</a>, which implements the <a href="https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@14.0/manual/renderer-features/renderer-feature-render-objects-landing.html">Render Objects Renderer Feature</a>, is a good starting point.</p><p>The <a href="https://github.com/Unity-Technologies/Graphics/blob/2022.3/staging/Packages/com.unity.render-pipelines.universal/Runtime/UniversalRenderer.cs#L519">UniversalRenderer.Setup</a> method is a bit of a behemoth at around 800 lines of code, but it’s interesting to learn how URP orchestrates all its render passes. Set a breakpoint in there and follow the execution flow. It can help clarify some detailed information that’s hard to come by in documentation, such as which exact conditions activate a depth prepass, or precisely when URP copies the depth buffer to a depth texture in a frame.</p><h3>Rendering order of objects inside a rendering pass</h3><p>In addition to the “macro” ordering with render passes described above, Unity also sorts rendered objects inside a single pass. The sorting algorithm considers many criteria and you can control which ones to apply to draw calls in a render pass with the <a href="https://docs.unity3d.com/ScriptReference/Rendering.DrawingSettings-sortingSettings.html">DrawingSettings.sortingSettings</a> property.</p><p>Technically, the boundaries of individual sets of objects that are sorted together aren’t tied to a rendering pass itself. It’s instead a <a href="https://docs.unity3d.com/ScriptReference/Rendering.RendererList.html">RendererList</a> that defines those boundaries. In other words, all objects in the RendererList of a draw call are rendered before all objects in other draw commands scheduled after it. For example, if a render pass adds two commands to draw RendererLists, all objects from the first draw command are collectively rendered before those in the second draw command.</p><p>You create RendererList instances in render passes either explicitly for use with <a href="https://docs.unity3d.com/ScriptReference/Rendering.CommandBuffer.DrawRendererList.html">CommandBuffer.DrawRendererList</a> or implicitly through one of the <a href="https://docs.unity3d.com/ScriptReference/Rendering.ScriptableRenderContext.DrawRenderers.html">ScriptableRenderContext.DrawRenderers</a> methods that each create a RendererList internally. While currently more verbose, the former option has the benefit that you add draw commands directly to a specific CommandBuffer that you can manage.</p><p>You can select some of the criteria that Unity uses to sort rendered objects for your own render passes with the <a href="https://docs.unity3d.com/ScriptReference/Rendering.SortingSettings-criteria.html">SortingSettings.criteria</a> property. The complete list of criteria ordered by priority is below. Where applicable I specified the <a href="https://docs.unity3d.com/ScriptReference/Rendering.SortingCriteria.html">SortingCriteria</a> enum flag that activates a criteria. When Unity compares two objects, if they have an equal value for a criteria, it continues the comparison with the next active criteria in the list.</p><ol><li>SortingCriteria.SortingLayer: Sorting layer and order from the <a href="https://docs.unity3d.com/ScriptReference/Renderer-sortingLayerID.html">Renderer.sortingLayerID</a> and <a href="https://docs.unity3d.com/ScriptReference/Renderer-sortingOrder.html">Renderer.sortingOrder</a> properties.<br> - Note that the sorting layer here refers to the <a href="https://docs.unity3d.com/ScriptReference/SortingLayer.html">SortingLayer</a> property, not <a href="https://docs.unity3d.com/ScriptReference/GameObject-layer.html">GameObject.layer</a>.<br> - Unity’s documentation describes <a href="https://docs.unity3d.com/Manual/class-TagManager.html#SortingLayers">sorting layers</a> only in the context of sprites, but you can still use them for other renderer types via scripts.</li><li>SortingCriteria.RenderQueue: Render queue from the <a href="https://docs.unity3d.com/ScriptReference/Material-renderQueue.html">Material.renderQueue</a> or <a href="https://docs.unity3d.com/ScriptReference/Shader-renderQueue.html">Shader.renderQueue</a> properties.</li><li>SortingCriteria.RendererPriority: Renderer priority from the <a href="https://docs.unity3d.com/ScriptReference/Renderer-rendererPriority.html">Renderer.rendererPriority</a> property.</li><li>SortingCriteria.BackToFront: Back to front sorting based on the distance from the camera.<br> - Typically used to render transparent objects.<br> - When distances are equal, Unity uses these subcriteria:<br> a) <a href="https://docs.unity3d.com/Manual/class-SortingGroup.html">Sorting group</a>. Unity refers to them only in the context of sprites, but you can still use them for other renderer types too.<br> b) UI canvas order with <a href="https://docs.unity3d.com/ScriptReference/Canvas-sortingOrder.html">Canvas.sortingOrder</a>.<br> c) Material index in the <a href="https://docs.unity3d.com/ScriptReference/Renderer-materials.html">mesh renderer’s material array</a>, for renderers with multiple materials.</li><li>SortingCriteria.QuantizedFrontToBack: Rough front to back sorting.<br> - Typically used for opaque objects to improve Z-culling.<br> - Sorts by bucket based on the top mantissa bits of the floating point distance. So for example distances of 42 and 57 land in the same bucket, and are considered equal.<br> - Turned off by default for Tile Based Deferred Rendering GPUs with the default value of <a href="https://docs.unity3d.com/ScriptReference/Rendering.OpaqueSortMode.html">Rendering.OpaqueSortMode</a> (see below).</li><li>SortingCriteria.OptimizeStateChanges: Sort by drawing state to reduce state changes, including shader changes. The sub-criteria are:<br> - Whether the shader and renderer are compatible with the <a href="https://docs.unity3d.com/Manual/SRPBatcher.html">SRP batcher</a>.<br> - Type of renderer. In the C++ code the enum type is RendererType. The most interesting renderer types are:<br> a) Individual classes that derive from <a href="https://docs.unity3d.com/ScriptReference/Renderer.html">Renderer</a> such as MeshRenderer and SpriteRenderer.<br> b) Internal “intermediate renderer” such as a UI canvas batch and those generated from the <a href="https://docs.unity3d.com/ScriptReference/Graphics.RenderMesh.html">Graphics.RenderMesh</a> method.<br> c) <a href="https://docs.unity3d.com/Manual/batch-renderer-group.html">BatchRendererGroup</a>.<br> - <a href="https://docs.unity3d.com/ScriptReference/LODFadeMode.html">LODFadeMode</a> for objects in LOD Groups.<br> - <a href="https://docs.unity3d.com/Manual/static-batching.html">Static batching</a> state. If both objects have static batching active, there’s a further sort by material, static batch, and mesh position in the static batch.<br> - <a href="https://docs.unity3d.com/ScriptReference/Renderer-lightmapIndex.html">Renderer.lightmapIndex</a> which is the index of the baked lightmap.<br> - Material. This check uses an approximation based on the shader’s <a href="https://docs.unity3d.com/ScriptReference/Object.GetInstanceID.html">instance id</a>, a hash of the material’s shader keywords, and the material’s instance id.<br> - Mesh. The details of this step depend on factors such as renderer type and usage of static batching.</li><li>SortingCriteria.CanvasOrder: UI canvas order with <a href="https://docs.unity3d.com/ScriptReference/Canvas-sortingOrder.html">Canvas.sortingOrder</a>.</li><li>Render node index, or the order in which objects were added to the queue of objects to render.</li><li>Index of the <a href="https://docs.unity3d.com/Manual/SL-Pass.html">shader pass</a>.</li></ol><p><em>(Apologies for the list formatting; Medium doesn’t support nested lists)</em></p><p>If you have access to Unity’s C++ source code, a good starting point to inspect the code of the sorting algorithm is RenderObjectSorter::operator().</p><p>The SortingCriteria.BackToFront and SortingCriteria.QuantizedFrontToBack flags are normally not used together. Another noteworthy detail is that the distances used for sorting can be calculated from an arbitrary point, not only from the “real” camera position. Refer to <a href="https://docs.unity3d.com/ScriptReference/Rendering.SortingSettings.html">Rendering.SortingSettings</a> for more information. This can be useful if you want to reuse a <a href="https://docs.unity3d.com/ScriptReference/Rendering.CullingResults.html">CullingResults</a> instance and render it with a different distance sorting from another point of view.</p><p>URP uses a different default combination of sorting criteria for opaque objects and transparent objects.</p><p>Objects in the <a href="https://docs.unity3d.com/ScriptReference/Rendering.RenderQueueRange-transparent.html">transparent render queue range</a> use <a href="https://docs.unity3d.com/ScriptReference/Rendering.SortingCriteria.CommonTransparent.html">SortingCriteria.CommonTransparent</a> which includes these criteria: SortingLayer, RenderQueue, BackToFront, and OptimizeStateChanges.</p><p>Opaque objects use <a href="https://docs.unity3d.com/ScriptReference/Rendering.SortingCriteria.CommonOpaque.html">SortingCriteria.CommonOpaque</a> which includes these criteria: SortingLayer, RenderQueue, QuantizedFrontToBack, OptimizeStateChanges, and CanvasOrder. QuantizedFrontToBack is a special case. URP deactivates it by default on mobile platforms with Tile-based deferred rendering GPUs because the CPU performance cost of sorting by distance usually outweighs any GPU performance gains. URP also deactivates it for cameras with the <a href="https://docs.unity3d.com/ScriptReference/Camera-opaqueSortMode.html">Camera.opaqueSortMode</a> property set to <a href="https://docs.unity3d.com/ScriptReference/Rendering.OpaqueSortMode.NoDistanceSort.html">NoDistanceSort</a>.</p><p>However as stated above, you can use any combination of sorting criteria in your own custom render passes.</p><h4>Rendering order for the BatchRendererGroup API</h4><p>If you’re interested in the topic of rendering order from a performance point of view, there’s a good chance that you’re also interested in Unity’s <a href="https://docs.unity3d.com/Manual/batch-renderer-group.html">BatchRendererGroup</a> (BRG), which is a <a href="https://unity.com/blog/engine-platform/batchrenderergroup-sample-high-frame-rate-on-budget-devices">high-performance</a> lower-level Unity API to submit draw commands.</p><p>The BRG API introduces additional considerations that apply to the sorting criteria I described above.</p><p>Pay close attention to terms in use because they can get confusing:</p><ul><li>A BatchDrawCommand instance is a C# instance of the BatchDrawCommand struct.</li><li>A BatchDrawCommand instance also contains instances, or visible instances. They are instances inside a BatchRendererGroup batch that become individual draw commands for the GPU.</li></ul><p>It’s quite a mouthful, but I hope this helps to disambiguate things!</p><p>The most important thing to understand about rendering order in BRG is that Unity doesn’t sort the individual instances contained in a single <a href="https://docs.unity3d.com/ScriptReference/Rendering.BatchDrawCommand.html">BatchDrawCommand</a>. The visibleOffset and visibleCount properties of a command define a slice of the <a href="https://docs.unity3d.com/ScriptReference/Rendering.BatchCullingOutputDrawCommands-visibleInstances.html">BatchCullingOutputDrawCommands.visibleInstances</a> array that it will draw. The rendering order of the elements in the slice is the same as in the slice itself.</p><p>To sort BatchDrawCommand instances by depth, use the <a href="https://docs.unity3d.com/ScriptReference/Rendering.BatchDrawCommandFlags.HasSortingPosition.html">BatchDrawCommandFlags.HasSortingPosition</a> flag and set <a href="https://docs.unity3d.com/ScriptReference/Rendering.BatchDrawCommand-visibleCount.html">BatchDrawCommand.visibleCount</a> to 1. In other words this means that each rendered object has its own BatchDrawCommand instance.</p><p>The fact that the BRG API doesn’t sort the instances in a BatchDrawCommand might seem like a limitation, but it’s actually a powerful feature. It allows you to leverage high-performance Burst jobs to sort the instances inside a draw command with any criteria you need. You’re even free to reuse the contents of the visibleInstances array to keep the same sorting order from one frame to the next if that fits your use-case.</p><p>Unity does however sort each BatchDrawCommand instance with other BatchDrawCommand instances and other objects rendered without BRG as described in the previous section.</p><p>In Unity 2022.3, the following sorting criteria work differently for BRG’s BatchDrawCommands:</p><ul><li>SortingCriteria.RendererPriority:<br> - rendererPriority is always 0.</li><li>The <a href="https://docs.unity3d.com/ScriptReference/Rendering.BatchDrawCommand-sortingPosition.html">BatchDrawCommand.sortingPosition</a> property establishes the distance of a BatchDrawCommand instance, taken as a whole, for the purposes of sorting it by distance.</li><li>SortingCriteria.BackToFront:<br> - Sorting groups and UI canvas order don’t apply. They don’t really make sense in the context of BRG anyway.<br> - Material index is always 0 since BRG doesn’t use multi-material.</li><li>SortingCriteria.OptimizeStateChanges:<br> - The Mesh sorting criteria doesn’t apply.</li><li>SortingCriteria.CanvasOrder:<br> - Not used, or rather the order is always set to 0.</li></ul><p>Unity 6 adds the following BRG features:</p><ul><li>Since <a href="https://unity.com/de/releases/editor/alpha/2023.3.0a3">Unity 2023.3.0a3</a> (which later becomes Unity 6), you can now use the BatchDrawCommandFlags.HasSortingPosition flag with BatchDrawCommands that contain more than one instance.</li><li><a href="https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.BatchFilterSettings-rendererPriority.html">BatchFilterSettings.rendererPriority</a> to set the renderer priority of a BatchDrawCommand instance for sorting.</li><li><a href="https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.BatchFilterSettings-batchLayer.html">BatchFilterSettings.batchLayer</a> in combination with <a href="https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.FilteringSettings-batchLayerMask.html">FilteringSettings.batchLayerMask</a> adds new filtering capabilities:<br> - Assign a batchLayer to batches, similarly to <a href="https://docs.unity3d.com/6000.0/Documentation/ScriptReference/Rendering.BatchFilterSettings-renderingLayerMask.html">BatchFilterSettings.renderingLayerMask</a> to filter them inside a CullingResults instance.<br> - Since objects not rendered with BRG are in batch layer 0, you can use that as a criteria to differentiate BatchDrawCommands from other types of draw commands.</li></ul><p>As an aside, as of writing, <a href="https://docs.unity3d.com/ScriptReference/Rendering.BatchFilterSettings-allDepthSorted.html">BatchFilterSettings.allDepthSorted</a> doesn’t actually do anything in any released Unity version despite what the documentation suggests. For now Unity’s code only has a “TODO” comment where it could potentially be useful. The description of this property got me scratching my head for a while and I still don’t understand its intent. So I’m sharing this random fact here in case it helps someone else!</p><h3>Set the render queue of a material in URP</h3><p>How to set the render queue of a material in URP depends on a few factors. Since the <a href="https://docs.unity3d.com/Packages/com.unity.render-pipelines.universal@17.0/manual/unlit-shader.html#advanced">current documentation for this area</a> as of writing is somewhat incomplete, I’ll provide additional details here.</p><p>In the <strong>Editor</strong>, URP provides some convenience features to manage the Material.renderQueue property.</p><p>URP’s default behavior is to automatically control the render queue. In that case, the Inspector displays the <strong>Sorting Priority</strong> property, which becomes an offset to the material’s “base” render queue. If the material has a <strong>Surface Type</strong> property in its <strong>Surface Options</strong>, URP uses it to determine the base render queue. Otherwise the base render queue is the shader’s render queue.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/514/0*ncD9yTNJmUPWcSEv" /><figcaption>Automatic render queue control with a Shader Graph shader</figcaption></figure><p>The Inspector displays the <strong>Sorting Priority</strong> property differently if the shader isn’t a Shader Graph shader, but the behavior is the same.</p><p>For materials that use Shader Graph shaders, the Inspector also provides a user override render queue control behavior. In that mode, URP lets you explicitly set the material’s render queue.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/516/0*DED96n06_eCyp3WX" /><figcaption>User override render queue control</figcaption></figure><p>At <strong>runtime</strong>, the convenience features described don’t apply, and you can directly set the render queue of a material with the Material.renderQueue property.</p><p>As a side-note, HDRP manages material render queues in a similar way to implement the <a href="https://docs.unity3d.com/Packages/com.unity.render-pipelines.high-definition@17.0/manual/Renderer-And-Material-Priority.html">transparent material sorting priority</a> feature. HDRP then translates the sorting priority into a positive or negative offset to the applicable “base” render queue of the material based on HDRenderQueue.Priority.</p><h3>Rendering order best practices</h3><p>With so many options to control Unity’s rendering order, it’s easy to wonder which ones you should use and when. Every part I described above is there for a reason, and there are too many scenarios to list them all. So let’s focus on a few aspects to keep in mind to pick an appropriate strategy.</p><p>First, if you use or plan to use the BatchRendererGroup API, review the differences with “classical” Unity rendering so as to avoid an incompatibility. In particular Unity 2022.3 ignores Renderer.rendererPriority in BatchDrawCommands. BRG does however provide many more sorting possibilities to implement any custom rendering order you need. Prefer Burst jobs for any large or complex sorting requirements for better performance.</p><p>For sprites and UI, the most usual options are well documented and you should strive to use what’s already available to maintain greater developer familiarity and compatibility with other assets.</p><p>To implement an effect that needs to order several draw commands, possibly each drawing several objects, I would prefer a custom render pass for more control. If you use whole framebuffer operations such as blit, or need to overwrite rendering state such as the stencil state, a custom render pass is likely your only option.</p><p>However if you only need to order the rendering of objects inside an existing URP pass such as DrawTransparentObjects, or if you don’t have anyone available to implement a custom pass, you can get pretty far with the sorting layer or render queue properties, or a combination of them. Instead or in addition to sorting layers, you can also consider the Renderer.rendererPriority property to order Renderer instances, but keep in mind the BRG compatibility note above.</p><p>Whichever option you pick, I strongly recommend that you document the resulting sorting strategy at least at a high level! It’s not necessarily easy to piece together after the fact from a collection of assets.</p><p>Sorting layers exist at the Renderer level, whereas the render queue is a material and shader construct. The appropriate option depends on your specific ordering needs. For example, if you make use of the render queue to order rendering, you’ll need to duplicate materials or use <a href="https://docs.unity3d.com/Manual/materialvariant-landingpage.html">material variants</a> to order objects that share the same material.</p><h3>Conclusion</h3><p>This post explored all the criteria that Unity considers to sort rendered objects. There are many options available if you need to control Unity’s sorting algorithm, but you can usually focus on a small subset for the task at hand.</p><p>In closing, I’ll repeat that if your interest in this topic is to improve performance, make sure to profile before you decide that changing the rendering order is the right optimization to implement!</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3c2bb1da8e78" width="1" height="1" alt=""><hr><p><a href="https://medium.com/toca-boca-tech-blog/controlling-unitys-rendering-order-why-and-how-3c2bb1da8e78">Controlling Unity’s rendering order — why and how</a> was originally published in <a href="https://medium.com/toca-boca-tech-blog">Toca Boca Tech Blog</a> on Medium, where people are continuing the conversation by highlighting and responding to this story.</p>]]></content:encoded>
        </item>
    </channel>
</rss>