Commit 540dec49 authored by Ulf Hermann's avatar Ulf Hermann
Browse files

Doc: Details for Scene Graph profiler



There seems to be a demand for more details on the events shown in the
scene graph profiler. This change should handle that.

Change-Id: I1de95a7168d9af98d75c163bb10e56699895c7fc
Reviewed-by: default avatarLeena Miettinen <riitta-leena.miettinen@digia.com>
Reviewed-by: default avatarKai Koehne <kai.koehne@theqtcompany.com>
parent fa4c8fbd
......@@ -151,7 +151,7 @@
\table
\header
\li Event Type
\li Event Category
\li Description
\li Minimum Qt Version
\li Qt Quick Version
......@@ -257,6 +257,207 @@
\endtable
\section2 Analyzing Scene Graph Events
In order to understand the scene graph category, it's important to
understand how the Qt Quick scene graph works. See
\l {Qt Quick Scene Graph} and \l {Qt Quick Scene Graph Renderer} for a
detailed description. The following events are reported in the
\gui {Scene Graph} category. Not all events are generated by all render
loops. In the Windows and Basic render loops everything runs in the same
thread and the distinction between GUI thread and render thread is
meaningless.
If you set the environment variable QSG_RENDER_TIMING, you get a textual
output of similar, but slightly different timings from the application
being profiled. For easier orientation, the differences are listed below.
\table
\header
\li Event Type
\li Thread
\li Render Loop Types
\li Label in output of QSG_RENDER_TIMING
\li Description
\li Caveats
\row
\li \gui {Polish}
\li GUI
\li Threaded, Basic, Windows
\li polish
\li Final touch-up of items before they are rendered using
QQuickItem::updatePolish().
\li Versions of Qt prior to Qt 5.4 record no polish times for the basic
render loop and incorrect ones for the windows render loop.
\row
\li \gui {GUI Thread Wait}
\li GUI
\li Threaded
\li lock
\li Executing slots connected to the QQuickWindow::afterAnimating()
signal and then locking the render thread's mutex before waiting on
the same mutex at \gui {GUI Thread Sync}. If this starts long
before \gui {Render Thread Sync}, there is \e free time in the GUI
thread you could be using for running additional QML or JavaScript.
\li None
\row
\li \gui {GUI Thread Sync}
\li GUI
\li Threaded
\li blockedForSync
\li The time the GUI thread is blocked, waiting for the render thread
to synchronize the QML state into the scene graph.
\li None
\row
\li \gui {Animations}
\li GUI
\li Threaded, Windows
\li animations
\li Advancing animations in the GUI thread. The basic render loop does
not drive animations in sync with the rendering. This is why no
animation events will be shown when using the basic render loop.
Watch the \gui {Animations} category to see animation timing in
this case.
\li None
\row
\li \gui {Render Thread Sync}
\li Render
\li Threaded, Basic, Windows
\li Frame rendered ... sync
\li Synchronizing the QML state into the scene graph using
QQuickItem::updatePaintNode().
\li None
\row
\li \gui {Render}
\li Render
\li Threaded, Basic, Windows
\li Frame rendered ... render
\li Total time spent rendering the frame, including preparing and
uploading all the necessary data to the GPU. This is the \e gross
render time. Do not confuse it with the \e net \gui{Render Render}
time below.
\li With versions of Qt prior to Qt 5.5, the gross render time and the
below breakup of render times may be misaligned by some
microseconds due to different, unsynchronized timers being used to
measure them. For example \gui {Render Preprocess} might seem to
start before \gui {Render Thread Sync} is finished.
\row
\li \gui {Swap}
\li Render
\li Threaded, Basic, Windows
\li Frame rendered ... swap
\li Swapping frames after rendering.
\li The output of swap times triggered by setting QSG_RENDER_TIMING is
incorrect for the basic render loop and versions of Qt prior to
Qt 5.4. The QML profiler shows the correct swap times.
\row
\li \gui {Render Preprocess}
\li Render
\li Threaded, Basic, Windows
\li time in renderer ... preprocess
\li Calling QSGNode::preprocess() on all nodes that need to be
preprocessed. This is part of the gross \gui {Render} step.
\li May not be properly aligned with \gui {Render} with versions of Qt
prior to Qt 5.5.
\row
\li \gui {Render Update}
\li Render
\li Threaded, Basic, Windows
\li time in renderer ... updates
\li Iterating and processing all the nodes in the scene graph to update
their geometry, transformations, opacity, and other state. In the
\gui {Render Thread Sync} stage, each node is updated separately
with state from the GUI thread. In \gui {Render Update}, all the
nodes are combined to create the final scene. This is part of the
gross \gui {Render} step.
\li May not be properly aligned with \gui {Render} with versions of Qt
prior to Qt 5.5.
\row
\li \gui {Render Bind}
\li Render
\li Threaded, Basic, Windows
\li time in renderer ... binding
\li Binding the correct framebuffer for OpenGL rendering. This is part
of the gross \gui {Render} step.
\li May not be properly aligned with \gui {Render} with versions of Qt
prior to Qt 5.5.
\row
\li \gui {Render Render}
\li Render
\li Threaded, Basic, Windows
\li time in renderer ... rendering
\li The actual process of sending all the data to the GPU via OpenGL.
This is part of the gross \gui {Render} step.
\li May not be properly aligned with \gui {Render} with versions of Qt
prior to Qt 5.5.
\row
\li \gui {Material Compile}
\li Render
\li Threaded, Basic, Windows
\li shader compiled
\li Compiling GLSL shader programs.
\li None
\row
\li \gui {Glyph Render}
\li Render
\li Threaded, Basic, Windows
\li glyphs ... rendering
\li Rendering of font glyphs into textures.
\li Versions of Qt prior to Qt 5.4 report incorrect times for these
events.
\row
\li \gui {Glyph Upload}
\li Render
\li Threaded, Basic, Windows
\li glyphs ... upload
\li Uploading of glyph textures to the GPU.
\li Versions of Qt prior to Qt 5.4 report incorrect times for these
events.
\row
\li \gui {Texture Bind}
\li Render
\li Threaded, Basic, Windows
\li plain texture ... bind
\li Binding a texture in the OpenGL context using glBindTextures.
\li None
\row
\li \gui {Texture Convert}
\li Render
\li Threaded, Basic, Windows
\li plain texture ... convert
\li Converting the format and downscaling an image to make it suitable
for usage as a texture.
\li None
\row
\li \gui {Texture Swizzle}
\li Render
\li Threaded, Basic, Windows
\li plain texture ... swizzle
\li Swizzling the texture data on the CPU if necessary.
\li None
\row
\li \gui {Texture Upload}
\li Render
\li Threaded, Basic, Windows
\li plain texture ... upload / atlastexture uploaded
\li Uploading the texture data to the GPU.
\li None
\row
\li \gui {Texture Mipmap}
\li Render
\li Threaded, Basic, Windows
\li plain texture ... mipmap
\li Mipmapping a texture on the GPU.
\li None
\row
\li \gui {Texture Delete}
\li Render
\li Threaded, Basic, Windows
\li plain texture deleted
\li Deleting a texture from the GPU that became unnecessary.
\li None
\endtable
\section1 Viewing Events
The \gui Events view displays the number of times each binding, create,
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment