Merge pull request #1805 from jasonrandrews/review

Refine content for render graph optimization learning path, including…

Author: jasonrandrews

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/_index.md

@@ -7,34 +7,34 @@ cascade:
 
 minutes_to_complete: 30
 
-who_is_this_for: Application developers who wish to improve graphics performance.
+who_is_this_for: Mobile application developers who wish to improve graphics performance.
 
 learning_objectives:
-    - Understand Frame Advisor's Render Graph view
-    - Use the Render Graph view to identify and resolve performance issues in your application
+    - Understand Frame Advisor's Render Graph view.
+    - Use the Render Graph view to identify and resolve performance issues in your application.
 
 prerequisites:
-    - An installed copy of Frame Advisor, part of Arm Performance Studio. [You can download Arm Performance Studio for free.](https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio#Downloads)
-    - A supported Android device, if you wish to analyze your own applications.
-    - Some basic familiarity with Frame Advisor. To get started, read [“Frame Advisor”](../ams/fa) in _Get started with Arm Performance Studio for Mobile_.
+    - Frame Advisor, part of Arm Performance Studio, installed. Refer to the [Arm Performance Studio](/install-guides/ams/) install guide. 
+    - If you wish to analyze your own applications you will need a supported Android device.
+    - Some basic familiarity with Frame Advisor. Review the [Frame Advisor](/learning-paths/mobile-graphics-and-gaming/ams/fa/) section in [Get started with Arm Performance Studio for mobile](/learning-paths/mobile-graphics-and-gaming/ams/).
 
 author: Mark Thurman
 
 further_reading:
     - resource:
-        title: Frame Advisor user guide
+        title: Frame Advisor User Guide
         link: https://developer.arm.com/documentation/102693/latest/
         type: documentation
     - resource:
-        title: Arm Performance Studio (main site)
+        title: Arm Performance Studio
         link: https://developer.arm.com/Tools%20and%20Software/Arm%20Performance%20Studio%20for%20Mobile
         type: website
     - resource:
-        title: Learning path – Get started with Arm Performance Studio for mobile
+        title: Get started with Arm Performance Studio for mobile
         link: https://learn.arm.com/learning-paths/mobile-graphics-and-gaming/ams/fa
         type: website
     - resource:
-        title: Learning path – Analyze a frame with Frame Advisor
+        title: Analyze a frame with Frame Advisor
         link: https://learn.arm.com/learning-paths/mobile-graphics-and-gaming/analyze_a_frame_with_frame_advisor
         type: website
     - resource:

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/_review.md

@@ -10,7 +10,7 @@ layout: learningpathall
 
 Your first step is to identify which parts of your application are limited by GPU performance.
 
-[Arm Streamline](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) is a good place to start. This is included as another part of Arm Performance Studio.
+[Streamline Performance Analyzer](https://developer.arm.com/Tools%20and%20Software/Streamline%20Performance%20Analyzer) is a good place to start, it is included in Arm Performance Studio.
 
 ### Setting up Streamline
 
@@ -23,36 +23,34 @@ If you have an Arm GPU, basic configuration is simple:
 If you have some other GPU, or want more control over the data collected, you'll need to select GPU counters manually:
 - Select the “Use advanced mode” checkbox.
 - Click the “Select counters” button to open the Counters window.
-- Inside the Counters window, select the counters you wish to analyze. (The Arm website has [details of counters available on Arm GPUs](https://developer.arm.com/documentation#numberOfResults=48&q=Performance%20Counters&sort=relevancy&f:@navigationhierarchiesproducts=[IP%20Products,Graphics%20and%20Multimedia%20Processors,Mali%20GPUs]).)
+- Inside the Counters window, select the counters you wish to analyze. [Reference Guides are available for Arm GPUs](https://developer.arm.com/documentation#numberOfResults=48&q=Performance%20Counters&sort=relevancy&f:@navigationhierarchiesproducts=[IP%20Products,Graphics%20and%20Multimedia%20Processors,Mali%20GPUs]).
 - Close the Counters window.
 
-For more details, refer to the [“Get Started with Streamline” tutorial](https://developer.arm.com/documentation/102477/0900/Overview), or [“Starting a capture”](https://developer.arm.com/documentation/101816/0905/Capture-a-Streamline-profile/Starting-a-capture) in the Arm Streamline user guide.
+For more details, refer to the [Get Started with Streamline](https://developer.arm.com/documentation/102477/0900/Overview) tutorial, or [Starting a capture](https://developer.arm.com/documentation/101816/0905/Capture-a-Streamline-profile/Starting-a-capture) in the Arm Streamline User Guide.
 
 ### Capturing GPU data in Streamline
 
 Once you have chosen GPU counters, click the “Start capture” button to begin your capture.
 
-Streamline will produce a graph showing the most GPU-heavy parts of your application (see [“Timeline overview”](https://developer.arm.com/documentation/101816/0905/Analyze-your-capture/Timeline-overview?lang=en) in the Arm Streamline user guide).
+Streamline will produce a graph showing the most GPU-heavy parts of your application. Refer to the [Timeline overview](https://developer.arm.com/documentation/101816/0905/Analyze-your-capture/Timeline-overview?lang=en) in the Arm Streamline User Guide.
 
 ## Capturing a render graph
 
 Now that you have identified areas of your application that you want to optimize, you can turn from Streamline to Frame Advisor.
 
-To ask Frame Advisor to capture data relating to the problem areas you have seen:
+Ask Frame Advisor to capture data relating to the problem areas you have observed:
 
 - Click “Capture new trace” in Frame Advisor's launch screen
 - Connect to your application
 - In the Capture screen, select the number of frames you wish to capture
 - When you've reached the GPU-heavy part of the application run, click “Capture”, then “Analyze” to advance to the Analysis screen
 
-For more details, refer to [the “Frame Advisor” section](../../ams/fa) of “Get started with Arm Performance Studio for mobile”.
-
 ## Viewing the render graph
 
 Observe that part of the Frame Advisor window is labelled “Render Graph”. This contains the render graph relating to the frames you asked Frame Advisor to analyze.
 
-For the purpose of this Learning Path, we will assume that you've captured the following render graph:
+Assume that you've captured the following render graph:
 
-![An inefficient render graph in need of optimization#center](inefficient-render-graph.svg "Figure 2. An inefficient render graph in need of optimization")
+![An inefficient render graph in need of optimization#center](inefficient-render-graph.svg "An inefficient render graph in need of optimization")
 
-In the next section, we will use this graph to illustrate some common application faults.
+In the next section, you will use this graph to understand some common application faults.

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/generating-a-render-graph-for-your-application.md

@@ -28,7 +28,7 @@ To find which API calls your application uses to start transfer workloads:
 - Now move to the API Calls view (labelled “API Calls”)
 - Observe the API calls in use.
 
-## Problem: Inefficient clear routines
+## Problem: inefficient clear routines
 
 `vkCmdClearColorImage()` is an inefficient way to clear an image.
 
@@ -38,6 +38,6 @@ A more efficient way to clear an image attachment is to clear the attachment at
 - Attach the `VkAttachmentDescription` to a `VkRenderPassCreateInfo`
 - Supply this to API `vkCreateRenderPass()`
 
-## Problem: Inefficient image resolutions
+## Problem: inefficient image resolutions
 
-[In the previous section](../textures-with-excessive-resolution), we looked at an issue where unnecessarily large textures were inputs to a render pass. Similar problems can be seen in the context of transfer operations, which should operate over the smallest practicable area. To achieve this, change the values in the `VkBufferCopy` structure passed to `vkCmdCopyBuffer()`.
+In the previous section, you saw an issue where unnecessarily large textures were inputs to a render pass. Similar problems can be seen in the context of transfer operations, which should operate over the smallest practicable area. To achieve this, change the values in the `VkBufferCopy` structure passed to `vkCmdCopyBuffer()`.

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/inefficient-transfer-workloads.md

@@ -12,9 +12,9 @@ Some textures used in your application may be unnecessarily large.
 
 Frame Advisor provides an easy way to detect this situation. It shows the resolution of the image being rendered in each execution node.
 
-There is an example of this in the render graph we looked at in a previous section:
+There is an example of this in the render graph you looked at in a previous section:
 
-![Textures with excessive resolution#center](excessive-resolution.png "Figure 1. Textures with excessive resolution")
+![Textures with excessive resolution#center](excessive-resolution.png "Textures with excessive resolution")
 
 This graph shows three execution nodes, through which data flows from left to right. These are:
 
@@ -26,5 +26,5 @@ The resolution given in the top left-hand corner of the execution nodes reduces
 
 ## Solution
 
-Make the computation shown in the graph produce the smaller final texture from smaller input textures. In this example, try to reduce the resolution of the inputs to Render Pass 0 (`RP0`).
+Make the computation shown in the graph produce the smaller final texture from smaller input textures. In this example, reduce the resolution of the inputs to Render Pass 0 (`RP0`).
 

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/textures-with-excessive-resolution.md

@@ -6,17 +6,15 @@ weight: 4
 layout: learningpathall
 ---
 
-So that we can use render graphs to find application faults, we must first understand what they are telling us.
-
 ## Components of a render graph
 
 Here's the graph from the previous section:
 
-![An inefficient render graph in need of optimization#center](inefficient-render-graph.svg "Figure 1. An inefficient render graph in need of optimization")
+![An inefficient render graph in need of optimization#center](inefficient-render-graph.svg "An inefficient render graph in need of optimization")
 
-Notice that a basic level, render graphs consist of _boxes_ and _arrows_:
+At a basic level, render graphs consist of _boxes_ and _arrows_:
 
-* Boxes, formally called _nodes_, represent rendering operations and resources (in other words, processing operations and data). We formally refer to nodes for rendering operations as _execution nodes_.
+* Boxes, formally called _nodes_, represent rendering operations and resources. Nodes for rendering operations are formally called  _execution nodes_.
 * Arrows, formally called _edges_, show the movement of data between rendering operations.
 
 Render graphs describe rendering performed by the GPU while it is constructing a single frame. This rendering starts and ends with resources. As a result of graphs being read from left to right:
@@ -33,7 +31,7 @@ In a suboptimally-generated frame, there may be other outputs which are not sent
 
 ## Graph nodes in detail
 
-Let's take a closer look at what can be represented in a node on the render graph.
+Take a closer look at what can be represented in a node on the render graph.
 
 ### Render passes
 
@@ -46,7 +44,7 @@ Render passes transform sets of input images into sets of output images using a
 Within each execution node representing a render pass, Frame Advisor gives information such as:
 
 - The resolution of the texture being rendered
-- A list of the attachments passed to the render pass and the name of each of these attachments.
+- A list of the attachments provided to the render pass and the name of each of these attachments.
 - The number of API draw calls within the render pass.
 
 {{% notice Tip %}}
@@ -55,11 +53,11 @@ When you click an execution node, such as a render pass, Frame Advisor navigates
 
 ### Other types of execution node
 
-The graph also shows a transfer node, colored blue. This is labelled ”Tr…”
+The graph also shows a transfer node, colored blue, and labelled ”Tr…”.
 
-![A transfer node#center](transfer-node.png "Figure 3. A transfer node")
+![A transfer node#center](transfer-node.png "A transfer node")
 
-Transfer nodes represent data movement between resource locations in memory. They are discussed in more depth in [a later problem-solving section](../inefficient-transfer-workloads).
+Transfer nodes represent data movement between resource locations in memory. 
 
 You may also see other types of execution node. For example, you may see compute nodes if your application uses compute shaders.
 
@@ -69,7 +67,9 @@ Resource nodes show inputs and outputs of the execution nodes. They are shown as
 
 There are different types of resource node:
 
-- The swapchain: this represents the output of the computation. There is one swapchain on every graph. ![A swapchain node#center](swapchain-node.png "Figure 4. A swapchain node")
-- [Textures](https://www.khronos.org/opengl/wiki/Texture): In the graph, these are marked with a leading letter `T`. ![A texture node#center](texture-node.png "Figure 5. A node for texture 1")
-- [Render buffers](https://www.khronos.org/opengl/wiki/Renderbuffer_Object): Like textures, these represent images. The title of render buffer nodes begins with letters `RB`. The title ends with a code indicating the class of render buffer – for example, `.s` for stencil and `.d` for depth. ![A render buffer node#center](render-buffer-node.png "Figure 6. A node for render buffer 1, representing depth. Figure 1 also contains a render buffer node representing a stencil.")
+- The swapchain: this represents the output of the computation. There is one swapchain on every graph. ![A swapchain node#center](swapchain-node.png "A swapchain node")
+- [Textures](https://www.khronos.org/opengl/wiki/Texture): these are marked with a leading letter `T`. ![A texture node#center](texture-node.png "A node for texture 1")
+- [Render buffers](https://www.khronos.org/opengl/wiki/Renderbuffer_Object): Like textures, these represent images. The title of render buffer nodes begins with letters `RB`. The title ends with a code indicating the class of render buffer – for example, `.s` for stencil and `.d` for depth. ![A render buffer node#center](render-buffer-node.png "A node for render buffer 1, representing depth") 
+
+The original render graph also contains a render buffer node representing a stencil.
 

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/understanding-your-render-graph.md

@@ -16,9 +16,9 @@ This excerpt shows a render pass (`RP0`) which writes three output resources to
 
 The texture is fed into another execution node, `Tr2`. This is a transfer node, number 2. From here, the data ultimately makes its way into the swapchain – and is therefore seen by the user.
 
-The renderbuffer nodes `RB1.d` and `RB1.s` are different. They are not sent to another execution node. Instead, they are unused.
+The renderbuffer nodes `RB1.d` and `RB1.s` are different. They are not sent to another execution node, they are unused.
 
-*This wastes both bandwidth and power.*
+This wastes both bandwidth and power.
 
 ## Solution
 

content/learning-paths/mobile-graphics-and-gaming/render-graph-optimization/unused-resources.md

@@ -8,16 +8,18 @@ layout: learningpathall
 
 ## Problem
 
-Your application might contain execution nodes which are _entirely_ unnecessary. For example:
+Your application might contain execution nodes which are _entirely_ unnecessary. 
 
-![An unnecessary execution node (highlighted)#center](unused-execution-node.png "Figure 1. An unnecessary execution node (highlighted)")
+For example, look at the render graph below:
 
-This is a more extreme version of the problem discussed in [the previous section](../unwanted-outputs). There, we looked at execution nodes which produced _some_ outputs which are unnecessary. Here, _all_ outputs are unnecessary.
+![An unnecessary execution node (highlighted)#center](unused-execution-node.png "An unnecessary execution node (highlighted)")
 
-*It therefore follows that the computation producing the output is itself unnecessary.*
+This is a more extreme version of the problem discussed in the previous section. Previously, you saw execution nodes which produced _some_ outputs which are unnecessary. Here, _all_ outputs are unnecessary.
+
+You can conclude that the computation producing the output is unnecessary.
 
 ## Solution
 
-The solution is similar to that in the previous section. Remove any API calls which represent the unused computation.
+Remove any API calls which represent the unused computation.
 
-*Be careful, however: your application may be using an apparently “unused” output of an execution node in a later frame.*
+Be careful, your application may be using an apparently “unused” output of an execution node in a later frame.