1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
|
/****************************************************************************
**
** Copyright (c) 2014 Digia Plc and/or its subsidiary(-ies).
** Contact: http://www.qt-project.org/legal
**
** This file is part of Qt Creator
**
**
** GNU Free Documentation License
**
** Alternatively, this file may be used under the terms of the GNU Free
** Documentation License version 1.3 as published by the Free Software
** Foundation and appearing in the file included in the packaging of this
** file.
**
**
****************************************************************************/
// **********************************************************************
// NOTE: the sections are not ordered by their logical order to avoid
// reshuffling the file each time the index order changes (i.e., often).
// Run the fixnavi.pl script to adjust the links to the index order.
// **********************************************************************
/*!
\contentspage {Qt Creator Manual}
\previouspage creator-analyze-mode.html
\page creator-qml-performance-monitor.html
\nextpage creator-valgrind-overview.html
\title Profiling QML Applications
To monitor the performance of an application in the QML Profiler:
\list 1
\li To be able to profile an application, you must set up QML debugging
for the project. For more information, see
\l{Setting Up QML Debugging}.
\li In the \gui Projects mode, select a \l{glossary-buildandrun-kit}
{kit} with Qt version 4.7.4 or later.
\note To profile applications on devices, you must install Qt 4.7.4
or later libraries on them.
\li Select \gui {Analyze > QML Profiler} to profile the current
application.
\li Select the
\inlineimage qtcreator-analyze-start-button.png
(\gui Start) button to start the application from the
QML Profiler.
\note If data collection does not start automatically, select the
\inlineimage qtcreator-analyzer-button.png
(\gui {Enable Profiling}) button.
\endlist
When you start analyzing an application, the application is launched, and
the QML Profiler immediately begins to collect data. This is indicated by
the time running in the \gui Elapsed field.
Data is collected until you select the \gui {Enable Profiling} button. Data
collection
takes time, and therefore, there might be a delay
before the data is displayed.
Do not use application commands to exit the application, because data is
sent to the QML Profiler when you select the \gui {Enable Profiling} button.
The application continues to run for some seconds, after which it is stopped
automatically. If you exit the application, the data is not sent.
Select the \gui {Disable Profiling} button to disable the automatic
start of the data collection when an
application is launched. Data collection starts when you select the button
again.
To save all the collected data, right-click any QML Profiler view to open
the context menu, and then select \gui {Save QML Trace}. To view the saved
data, select \gui {Load QML Trace}. You can also deliver the saved data to
other developers for examination or load data saved by them.
\section1 Attaching to Running Qt Quick Applications
To profile Qt Quick applications that are not launched by \QC, select
\gui {Analyze > QML Profiler (External)}. You must enable QML debugging for
the application in the project build settings. For more information, see
\l{Setting Up QML Debugging}.
In the \gui {QML Profiler} dialog, \gui Port field, specify the port to
listen to.
\section1 Analyzing Collected Data
The \gui Timeline view displays graphical representations of QML and
JavaScript execution and a condensed view of all recorded events.
\image qtcreator-qml-performance-monitor.png "QML Profiler"
Each row in the timeline (6) describes a type of QML events that were
recorded. Move the cursor on an event on a row to see how long it takes and
where in the source it is being called. To display the information only when
an event is selected, disable the \gui {View Event Information on Mouseover}
button (5).
The outline (10) summarizes the period for which data was collected. Drag
the zoom range (8) or click the outline to move on the outline. You can
also move between events by selecting the \gui {Jump to Previous Event} (1)
and \gui {Jump to Next Event} (2) buttons.
Select the \gui {Show Zoom Slider} button (3) to open a slider that you can
use to set the zoom level. You can also drag the zoom handles (9). To reset
the default zoom level, right-click the timeline to open the context menu,
and select \gui {Reset Zoom}.
\section2 Selecting Event Ranges
You can select an event range (7) to view the frame rate of events and to
compare it with the frame rate of similar events. Select the
\gui {Select Range} button (4) to activate the selection tool. Then click in
the timeline to specify the beginning of the event range. Drag the selection
handle to define the end of the range. The length of the range indicates the
frame rate of the event.
You can use event ranges also to measure delays between two subsequent
events. Place a range between the end of the first event and the beginning
of the second event. The \gui Duration field displays the delay between the
events in milliseconds.
To zoom into an event range, double-click it.
To remove an event range, close the \gui Selection dialog.
\section2 Understanding the Data
Generally, events in the timeline view indicate how long QML or JavaScript
execution took. Move the mouse over them to see details. For most events,
they include location in source code, duration and some relevant parts of
the source code itself.
You can click on an event to move the cursor in the code editor to the part
of the code the event is associated with.
The following types of events are displayed in the timeline view on one or
several rows. The availability of event types depends on the version of Qt
the application was compiled with, the version of Qt Quick it is using, and
whether \QC or \QCE is used to profile it.
\table
\header
\li Event Category
\li Description
\li Minimum Qt Version
\li Qt Quick Version
\li Enterprise Feature
\row
\li \gui {Pixmap Cache}
\li Displays the general amount of pixmap data cached, in pixels. In
addition, displays a separate event for each picture being loaded,
with specifics about its file name and size.
\li Qt 5.1
\li Qt Quick 2
\li Yes
\row
\li \gui {Scene Graph}
\li Displays the time when scene graph frames are rendered and some
additional timing information for the various stages executed to do
so.
\li Qt 5.1
\li Qt Quick 2
\li Yes
\row
\li \gui {Memory Usage}
\li Displays block allocations of the JavaScript memory manager.
Generally, the memory manager will reserve larger blocks of memory
in one piece and later hand them out to the application in smaller
bits. If the application requests single blocks of memory
surpassing a certain size, the memory manager will allocate those
separately. Those two modes of operation are shown as events of
different colors.
The second row displays the actual usage of the allocated memory.
This is the amount of JavaScript heap the application has actually
requested.
\li Qt 5.4
\li Qt Quick 2
\li Yes
\row
\li \gui {Input Events}
\li Displays mouse and keyboard events.
\li Qt 4.7.4
\li Qt Quick 1 or Qt Quick 2
\li Yes
\row
\li \gui Painting
\li Displays the time spent painting the scene for each frame.
\li Qt 4.7.4
\li Qt Quick 1
\li No
\row
\li \gui Animations
\li Displays the amount of animations that are active and the frame
rate that they are running at.
Information about render thread animations is displayed for
applications that are built with Qt 5.3 or later. Render thread
animations are shown in a separate row then.
\li Qt 5.0 (Qt 5.3)
\li Qt Quick 2
\li No
\row
\li \gui Compiling
\li Displays the time spent compiling the QML files.
\li Qt 4.7.4
\li Qt Quick 1 or Qt Quick 2
\li No
\row
\li \gui Creating
\li Displays the time spent creating the elements in the scene. In Qt
Quick 2, creation of elements takes place in two stages. The first
stage is for the creation of the data structures, including child
elements. The second stage represents the completion callbacks. Not
all elements trigger completion callbacks, though. The stages are
shown as separate events in the timeline.
For Qt Quick 2 applications compiled with versions of Qt before
5.2.1 only the creation of top-level elements is shown, as single
events.
\li Qt 4.7.4 (Qt 5.2.1)
\li Qt Quick 1 or Qt Quick 2
\li No
\row
\li \gui Binding
\li Displays the time when a binding is evaluated and how long the
evaluation takes.
\li Qt 4.7.4
\li Qt Quick 1 or Qt Quick 2
\li No
\row
\li \gui {Handling Signal}
\li Displays the time when a signal is handled and how long the
handling takes.
\li Qt 4.7.4
\li Qt Quick 1 or Qt Quick 2
\li No
\row
\li \gui JavaScript
\li Displays the time spent executing the actual JavaScript behind
bindings and signal handlers. It lists all the JavaScript functions
you may be using to evaluate bindings or handle signals.
\li Qt 5.3
\li Qt Quick 2
\li No
\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,
compile, JavaScript, or signal event is triggered and the average time it
takes. This allows you to examine which events you need to optimize. A high
number of occurrences might indicate that an event is triggered
unnecessarily. To view the median, longest, and shortest time for the
occurrences, select \gui {Extended Event Statistics} in the context menu.
Click on an event to move to it in the source code
in the code editor.
JavaScript events often duplicate bindings or signals, so you can show and
hide them by selecting \gui {Show JavaScript Events} in the context menu.
To show and hide QML events (\gui Create, \gui Compile, and \gui Signal),
select \gui {Show QML Events}.
\image qtcreator-analyzer-bindings.png "Events view"
The \gui Callers and \gui Callees panes show dependencies between events.
They allow you to examine the internal functions of the application.
The \gui Callers pane summarizes the QML events that trigger a binding.
This tells you what caused a change in a binding.
The \gui Callees pane summarizes the QML events that a binding triggers.
This tells you which QML events are affected if you change a binding.
Click on an event to move to it in the source code in the code editor.
When you select an event in the \gui Timeline view, information about it is
displayed in the \gui Events view. To view an event range in the \gui Events
view, select \gui {Limit Events Pane to Current Range} in the context menu
in the \gui Timeline view.
To copy the contents of one view or row to the clipboard, select
\gui {Copy Table} or \gui {Copy Row} in the context menu.
JavaScript events are shown in the \gui Events view only for applications
that use Qt Quick 2 and are compiled with Qt 5.3 or later. For applications
that use Qt Quick 2 and are built with Qt 5.0 or 5.1, you can view
information about JavaScript events in the separate \gui V8 view.
\section2 Viewing More Data
The QML JavaScript engine optimizes trivial bindings. The QML Profiler
may not receive all information about optimized bindings, and therefore,
it may display the text \gui {<bytecode>} and the message
\gui {Source code not available} in the \gui Callers and \gui {Callees}
panes.
To inspect the optimized bindings, turn off the QML optimizer by setting
the environment variable QML_DISABLE_OPTIMIZER to 1. To set the environment
variable for the current project in the project settings:
\list 1
\li Select \gui {Projects > Run}.
\li In \gui {Run Environment}, click \gui Add.
\li Add the QML_DISABLE_OPTIMIZER variable and set its value to 1.
\endlist
*/
|