Move images to flutter/assets-for-api-docs (flutter/engine#53917)
27MB of images should not be in the source tree. Caveat: If you use VSCode's markdown preview, it does not support images outside the workspace. One solution to this would be to submodule the assets back into the assets folder - however that would break github rendering of images. Fixes flutter/flutter#151691
This commit is contained in:
John McDole
@@ -11,7 +11,7 @@
|
||||
--------------------------------------------------------------------------------
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
Impeller is a rendering runtime for Flutter with the following objectives:
|
||||
|
||||
|
||||
@@ -52,19 +52,19 @@ Open Android Studio. You can create a new blank project if you don't have one al
|
||||
> [!IMPORTANT]
|
||||
> This may be in a different location or missing depending on the exact version of Android Studio that you have installed. Start a new Android Studio project if you can't find this link.
|
||||
|
||||
|
||||
|
||||
|
||||
### Start a New Profiling Session
|
||||
|
||||
Click the plus button to start a new session, then look for the attached devices, then finally the name of the application to profile. It usually takes a few seconds for the drop downs to populate. The IDE will warn about the build not being a release build, but this doesn't impact the C++ engine so ignore it.
|
||||
|
||||
|
||||
|
||||
|
||||
### Capture a CPU Profile
|
||||
|
||||
Click on the CPU section of the chart highlighted below. This will open a side panel that allows you to select the type of profile. Choose "Callstack Sample Recording" and then hit "Record" to start the profile and "Stop" to end the profile
|
||||
|
||||
|
||||
|
||||
|
||||
### Analyze Raster performance
|
||||
|
||||
@@ -72,4 +72,4 @@ Samples will be collected from all threads, but for analyzing the engine perform
|
||||
|
||||
Select the raster thread by clicking on that area and then choose flame graph (or any of the other options). The flame graph can be navigated using `WASD` and the chart area expanded to make inspection easier.
|
||||
|
||||
|
||||
|
||||
|
||||
1
engine/src/flutter/impeller/docs/assets/README.md
Normal file
1
engine/src/flutter/impeller/docs/assets/README.md
Normal file
@@ -0,0 +1 @@
|
||||
Assets should be added [here](https://github.com/flutter/assets-for-api-docs/tree/main/assets/engine/impeller)
|
||||
@@ -129,7 +129,7 @@ pass.Draw();
|
||||
|
||||
And, in ~10 lines of C++ code and some simple GLSL, you should see a glorious red triangle. The compiler has done the heavy lifting of converting the GLSL to Metal Shading Language and figuring out the metadata to put together the pipeline for us.
|
||||
|
||||
|
||||
|
||||
|
||||
## Extra Credit
|
||||
|
||||
@@ -176,7 +176,7 @@ vertex_buffer_builder.AddVertices({
|
||||
|
||||
We should now see a triangle with each pixel shaded differently.
|
||||
|
||||
|
||||
|
||||
|
||||
### Uniforms
|
||||
|
||||
@@ -268,7 +268,7 @@ void main() {
|
||||
|
||||
And with that, you should see animated triangle shading.
|
||||
|
||||
|
||||
|
||||
|
||||
## Conclusion
|
||||
|
||||
|
||||
@@ -33,7 +33,7 @@ mint install lennet/FlameGraph
|
||||
|
||||
Use the Time Profiler Xcode template.
|
||||
|
||||
|
||||
|
||||
|
||||
Click the red dot to begin and record as much profile data as you want. Press stop to conclude the trace.
|
||||
|
||||
@@ -42,11 +42,11 @@ Select the thread to investigate, in this case you want `io.flutter.raster`.
|
||||
> [!IMPORTANT]
|
||||
> Make sure to select the trace root.
|
||||
|
||||
|
||||
|
||||
|
||||
Copy the trace with the keyboard shortcut (⇧⌘C) or the menu ("Edit" -> "Deep Copy").
|
||||
|
||||
|
||||
|
||||
|
||||
## Convert Profile to FlameGraph
|
||||
|
||||
@@ -58,4 +58,4 @@ FlameGraph --html output.html
|
||||
|
||||
A new browser tab will open with the Flame Graph. It may require some zooming to be useful.
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -27,7 +27,7 @@ related knobs and dials to turn. See `man MetalValidation`.
|
||||
Applications can optionally display a HUD that displays real-time information
|
||||
about Metal related performance.
|
||||
|
||||
|
||||
|
||||
|
||||
More documentation about the specific elements of the HUD is present on the
|
||||
[Apple developer site](https://developer.apple.com/documentation/xcode/monitoring-your-metal-apps-graphics-performance).
|
||||
|
||||
@@ -42,11 +42,11 @@ Make sure you have already set up an Xcode session by following the instructions
|
||||
in the wiki. Setup a test that opens a blank playground. With the playground
|
||||
running, click on the stylized `M` to capture a Metal frame.
|
||||
|
||||
|
||||
|
||||
|
||||
Give Xcode a few seconds to capture the frame and show the frame overview.
|
||||
|
||||
|
||||
|
||||
|
||||
Let’s figure out what the gauges of this car mean.
|
||||
|
||||
@@ -120,7 +120,7 @@ still not rendering anything in the playground.
|
||||
|
||||
An overview of all graphics memory usage is shown.
|
||||
|
||||
|
||||
|
||||
|
||||
Along with all the objects that occupy memory, their locations in different
|
||||
memory categorizations are also shown. Notice how the totals all add up to the
|
||||
@@ -130,7 +130,7 @@ memory storage mode for textures or buffers (private, managed, or memory-less).
|
||||
You can double click an object to inspect it and highlighting a texture should
|
||||
give you a preview of its contents.
|
||||
|
||||
|
||||
|
||||
|
||||
Do not underestimate the usefulness of filtering the results either by category
|
||||
name or resource name. You can filter by category by selecting the small
|
||||
@@ -138,7 +138,7 @@ circular callstack button next to the category. When you apply filters, the
|
||||
memory totals will update to reflect just filtered items. Here, there is 3 MB of
|
||||
device memory for managed textures.
|
||||
|
||||
|
||||
|
||||
|
||||
You can also apply freeform text filters to the resources using the text field
|
||||
highlighted by the second box. This is used by multiple Impeller subsystems. For
|
||||
@@ -167,7 +167,7 @@ gauges and pedals do. Let’s drive this car onto a quiet street.
|
||||
Let’s render a scene that actually renders something. But, let’s just render a
|
||||
solid red triangle in the playground.
|
||||
|
||||
|
||||
|
||||
|
||||
We notice two changes in the overview.
|
||||
|
||||
@@ -209,7 +209,7 @@ Let’s click on the `SolidFill Pipeline` in the example to analyze that pipelin
|
||||
All draw calls listed below that pipeline use the same programmable and fixed
|
||||
function pipeline configuration.
|
||||
|
||||
|
||||
|
||||
|
||||
You will get intimately familiar with this view when you set up a new pipeline
|
||||
state object in Impeller or try to reason about the correctness of one of the
|
||||
@@ -242,7 +242,7 @@ topology).
|
||||
|
||||
To inspect how each draw call is configured, select the call in the sidebar.
|
||||
|
||||
|
||||
|
||||
|
||||
To get an overview of the draw call, the Bound Resources section is the most
|
||||
useful view. Let’s ensure we understand each item.
|
||||
@@ -253,7 +253,7 @@ detail](#inspecting-the-pipeline-state-object).
|
||||
In the `Vertex` section, the `Geometry` lists how each vertex is transformed by
|
||||
the vertex shader.
|
||||
|
||||
|
||||
|
||||
|
||||
Here, you see how each vertex (three here since we are rendering a triangle) is
|
||||
transformed by the shader such that it ends up in the correct spot in normalized
|
||||
@@ -268,7 +268,7 @@ information about that buffer presented in a view appropriate for that stage.
|
||||
When I double click the buffer containing the uniform data, the following view
|
||||
is shown.
|
||||
|
||||
|
||||
|
||||
|
||||
Pay specific attention to the `Row` index. Impeller architecture doesn’t create
|
||||
small individual buffers for uniform data. All uniform data for a single render
|
||||
@@ -297,7 +297,7 @@ changes in the buffer indiscernible to you. Xcode helpfully selected the “Min
|
||||
Max” view for us. You can do the same for any attachment.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Debugging a Shader
|
||||
|
||||
@@ -331,7 +331,7 @@ for shader along with a button to show it where to find the relevant
|
||||
`.metallibsym` files. Click that button and a dialog will pop up showing the
|
||||
Metal libraries whose `.metallibsym` files could not be resolved.
|
||||
|
||||
|
||||
|
||||
|
||||
In the "External Source Search Paths" section, click the tiny `+` button at the
|
||||
bottom. In the file chooser dialog box that appears next, select all the
|
||||
@@ -345,7 +345,7 @@ sources in an outdated `.metallibsym` file.
|
||||
You may however also run into Xcode complaining about "Invalid UUID" errors.
|
||||
This is instead of the "No Source" errors as shown in the dialog above.
|
||||
|
||||
|
||||
|
||||
|
||||
The team has been unable to to find documentation for this type of error. But
|
||||
through trial-and-error, we have determined that the way to fix this is to set
|
||||
@@ -364,7 +364,7 @@ section as described in the section on [inspecting a single draw
|
||||
call](#inspecting-a-single-draw-call).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
At the bottom right corner of the attachment preview, you will see a disabled
|
||||
@@ -377,7 +377,7 @@ Once a valid texture element is highlighted, the `Debug` button should be
|
||||
enabled. Click it to debug that one invocation of the fragment shader used by
|
||||
that draw call.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
In the sidebar on the left, each step of execution of the fragment shader is
|
||||
@@ -407,7 +407,7 @@ described in the section on [inspecting a single draw
|
||||
call](#inspecting-a-single-draw-call).
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
In this view, the `Debug` button on the bottom right will be disabled unless a
|
||||
@@ -415,7 +415,7 @@ specific vertex in the geometry has been selected. Once you select the vertex
|
||||
whose vertex shader invocation you want to debug, the button should be enabled.
|
||||
Click it.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
In the sidebar on the left, each step of execution of the vertex shader is
|
||||
@@ -447,7 +447,7 @@ button at the bottom of the shader viewer that is typically disabled becomes
|
||||
enabled.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Click on that button to see what that invocation would look like had it used the
|
||||
@@ -469,12 +469,12 @@ updates.
|
||||
From either the frame insights or by selecting an API call on the object, open
|
||||
the call-stack to navigate to the code that made that call. Then add your label.
|
||||
|
||||
|
||||
|
||||
|
||||
When inspecting an API call, reveal the call-stack. This resource has already
|
||||
been labelled and you’ll find the call in `AllocatorMTL::CreateTexture`.
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
This trace-first approach of navigating an unfamiliar codebase is unreasonably
|
||||
|
||||
@@ -22,7 +22,7 @@
|
||||
|
||||
3. Start RenderDoc and (if necessary) select "Launch Application" button from the menu:
|
||||
|
||||
|
||||
|
||||
|
||||
On Linux, the executable is `qrenderdoc`.
|
||||
|
||||
@@ -45,7 +45,7 @@
|
||||
|
||||
5. For the frame you wish to capture, press `F12`, you will now be able to see the frame capture and inspect the state:
|
||||
|
||||
|
||||
|
||||
|
||||
_See also:_
|
||||
|
||||
|
||||
@@ -15,12 +15,12 @@ follow along.
|
||||
|
||||
In Xcode, `File -> New -> Project…`, select an empty project.
|
||||
|
||||
|
||||
|
||||
|
||||
Call it whatever you want, you are not going to check this into version control
|
||||
and the targets are going to be specific to your workflow.
|
||||
|
||||
|
||||
|
||||
|
||||
Save it outside the source tree. Since you are not going to check this in, you
|
||||
don’t want to accidentally delete it via a `git clean -fdx` when regenerating
|
||||
@@ -29,18 +29,18 @@ the licenses (ask me how I know).
|
||||
Create a new `External Build System` target in the empty project by clicking on
|
||||
the `+` icon at the bottom.
|
||||
|
||||
|
||||
|
||||
|
||||
Click through the defaults (it wants you to use `make`) to create the target, we
|
||||
are going to be modifying it later.
|
||||
|
||||
|
||||
|
||||
|
||||
Select the target you just created from the sidebar and in the `Info` tab, fill
|
||||
in the command you would use to bring the target up-to-date. In the example, I
|
||||
am building the Impeller unit-tests.
|
||||
|
||||
|
||||
|
||||
|
||||
If you wanted to instrument multiple targets and switch between them, you would
|
||||
add them here.
|
||||
@@ -50,20 +50,20 @@ however. You need to specify a Run Scheme for that. We’ll do that next.
|
||||
|
||||
Click the default scheme for the target.
|
||||
|
||||
|
||||
|
||||
|
||||
In the Pop-Up, click `Edit Scheme`.
|
||||
|
||||
|
||||
|
||||
|
||||
In the Info tab, select the executable you want to launch after the target has
|
||||
been updated by clicking on `Other…`.
|
||||
|
||||
|
||||
|
||||
|
||||
I want to launch the unit-tests harness. Select it in the `out` directory.
|
||||
|
||||
|
||||
|
||||
|
||||
Now, when you click `Product -> Run` in Xcode, the unit-tests target will be
|
||||
brought up to data and run.
|
||||
@@ -77,12 +77,12 @@ In the `Options` tab on the `Edit Scheme…` pop-up, in the `GPU Frame Capture`
|
||||
section, set API detection to `Metal` and check `Profile GPU trace after
|
||||
capture`.
|
||||
|
||||
|
||||
|
||||
|
||||
Then, in the `Diagnostics` tab on the `Edit Scheme…` pop-up, in the `Metal`
|
||||
section, enable `API Validation` and `Shader Validation`.
|
||||
|
||||
|
||||
|
||||
|
||||
On a side note, you may be tempted to enable all the other diagnostics. Be aware
|
||||
that some of those diagnostics need Xcode to be able to re-compile the
|
||||
@@ -105,7 +105,7 @@ instrument just the one test you want.
|
||||
|
||||
You also need to set the `--enable_playground` flag in order to do frame capturing.
|
||||
|
||||
|
||||
|
||||
|
||||
This is also the spot where you will add other command line arguments that will
|
||||
aid in your debugging. In that example, `–timeout=-1` will disable the Flutter
|
||||
|
||||
Reference in New Issue
Block a user