# Scene Analyzer Overview

# Scene Analyzer feature list

The Analyzer analyzes a Candera Scene Graph and its performance of a 2D or 3D Candera project. It supports:

<div class="contents" id="bkmrk-scene-graph-view-1-d"><div class="contents"><div class="textblock">- Scene Graph View <sup>1</sup>
- Detailed information about the Scene Graph <sup>1</sup>
- Benchmarks related to Scene Graph <sup>1</sup>
- Measurement and data presentation of render processes <sup>2</sup>
- Online – Experiments <sup>1</sup>
- Measurement of key performance indicators <sup>1</sup>
- Storage of measured data

</div></div></div><sup>1</sup> Features available during an online connection with appropriate targets   
<sup>2</sup> Features traced during an online connection with appropriate targets and analyzed afterwards

# Measurement Concepts

#### **Introduction**

##### <a class="anchor" id="bkmrk--11"></a>Measurement Concepts

The Analyzer measurement module allows the user to analyze measurements performed and recorded on the host simulation or target.

It is important to differentiate between the concept of a recorder and the concept of a recording. A recorder is a means to record something, as a DVD recorder is a means to record a DVD.

#### **Recorders** 

The concept of recorders lies at the heart of the Analyzer performance log recording and analysis.

Examples are recorders to record

<div class="contents" id="bkmrk-every-point-in-time%2C"><div class="contents"><div class="textblock">- Every point in time, a new frame starts (an Event Recorder)
- How long it takes an OpenGL call (e.g. glDrawArray) to return to the caller (a Timing Recorder)
- The current CPU or GPU load (a Value Recorder)

</div></div></div>In order to cover these three main areas of interest (events, durations, values), the following six recorder classes were defined:

<div class="contents" id="bkmrk-event-recorder-timin"><div class="contents"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[Event Recorder](https://doc316en.candera.eu/link/268#bkmrk-event-recorder)</span>
- <span style="color: rgb(230, 126, 35);">[Timing Recorder](https://doc316en.candera.eu/link/268#bkmrk-timing-recorder)</span>
- <span style="color: rgb(230, 126, 35);">[Asynchronous Timing Recorder](https://doc316en.candera.eu/link/268#bkmrk-asynchronous-timing-)</span>
- <span style="color: rgb(230, 126, 35);">[Cumulative Timing Recorder](https://doc316en.candera.eu/link/268#bkmrk-cumulative-timing-re)</span>
- <span style="color: rgb(230, 126, 35);">[Value Recorder](https://doc316en.candera.eu/link/268#bkmrk-value-recorder)</span>
- <span style="color: rgb(230, 126, 35);">[Cumulative Value Recorder](https://doc316en.candera.eu/link/268#bkmrk-cumulative-value-rec)</span>

</div></div></div>Every recorder has the following properties:

<div class="contents" id="bkmrk-name%3A-a-name-unique-"><div class="contents"><div class="textblock">- Name: A name unique in the recorders class
- Class: The class to which he belongs

</div></div></div><div class="contents" id="bkmrk--3"><div class="contents"><div class="textblock">---

</div></div></div>#### <a class="anchor" id="bkmrk--13"></a>Recorder Classes

##### <a class="anchor" id="bkmrk--14"></a>Event Recorder

Event Recorders are the simplest recorders. They just record an event at a given point in time.

##### <a class="anchor" id="bkmrk--15"></a>Timing Recorder

Timing Recorders are used to measure durations. Therefore, begin- and end time of a timing recording may differ.

##### <a class="anchor" id="bkmrk--16"></a>Asynchronous Timing Recorder

An Asynchronous Timing Recorder is a timing recorder that starts recording in one execution block and may end in a different one.

##### <a class="anchor" id="bkmrk--17"></a>Cumulative Timing Recorder

A Cumulative Timing Recorder does not keep track of every single timing it was used to record. Instead, it sums up all durations recorded and also keeps track of the number of recordings.

##### <a class="anchor" id="bkmrk--18"></a>Value Recorder

A Value Recorder is used to record a value at a point in time. These values may be signed or unsigned long values.

Values may have the following relationship:

<div class="contents" id="bkmrk-unrelated.-two-recor"><div class="contents"><div class="textblock">- Unrelated. Two recorded values in succession have no relationship.
- Differential. Only the difference after the last recording is recorded.
- Absolute. The full value is always recorded.

</div></div></div>Example for value relationships:

An application records memory consumption and uses a recorder for this task. The application allocates first 1000kb and then 500kb. At the end, the total (absolute) consumption is 1500kb.

<div class="contents" id="bkmrk-when-using-a-differe"><div class="contents"><div class="textblock">- When using a differential Value Recorder, the application would first record the value 1000 and then the value 500.
- When using an absolute Value Recorder, the application would have to first record 1000 and then 1500 to achieve the same effect.

</div></div></div>##### <a class="anchor" id="bkmrk--19"></a>Cumulative Value Recorder

A Cumulative Value Recorder, similar to a Cumulative Timing Recorder, does not keep track of every value it was used to record, but sums up all values and counts the times something was recorded.

#### **Recordings** 

A recording represents actual data recorded, e.g. one new frame event recorded at 1000 ms after system startup. Depending on the recorder used, the following is recorded:

<div class="contents" id="bkmrk-a-signed-or-unsigned"><div class="textblock">- A signed or unsigned long value
- An Event
- A Duration

</div></div>#### **Separation/Interpretation of Data** 

##### <a class="anchor" id="bkmrk--20"></a>Separation of Data and Interpretation Information

In order to gain flexibility, performance log data and the information about how they have to be interpreted and displayed are separated. This separation is reflected on the file system level: performance log data is stored in .perflog files and the meta-information for interpretation is stored in an XML file (PerfDataConfig.xml). The meta-information comprises the following:

<div class="contents" id="bkmrk-the-name-to-use-for-"><div class="contents"><div class="textblock">- The name to use for display
- The foreground color to use for display
- The background color to use for display
- For value recorders:   
    &gt; If the values have to interpreted as signed or unsigned   
    &gt; The relationship of the values (Absolute, Differential, Unrelated)
- For cumulative value recorders:   
    &gt; If the values have to interpreted as signed or unsigned

</div></div></div>The meta-information can be edited using the View Configuration Dialog (see Section <span style="color: rgb(230, 126, 35);">[View Configuration Dialog](https://doc316en.candera.eu/link/271#bkmrk-configuration%C2%A0)</span>).

#### **Views - Filtering - Sampling**

##### <a class="anchor" id="bkmrk--21"></a>Views

A view shows certain aspects of the overall recorded information and thus helps the user to focus on the information he needs to see.

See also:

<div class="contents" id="bkmrk-measurement-views"><div class="contents"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[Measurement Views](https://doc316en.candera.eu/link/271#bkmrk-measurement-views)</span>

</div></div></div>##### <a class="anchor" id="bkmrk--22"></a>Filtering

Each view except Dashboard View and Treemap View allow filtering to display the desired recordings only. Every filtering-enabled view supports filtering by a means of its own and filtering will be described in the corresponding sections. Filtering is always done before sampling.

##### <a class="anchor" id="bkmrk--23"></a>Sampling

Sampling is, similar to filtering, a means to reduce the amount of data displayed. A filtering expression can be arbitrary, whereas a sample always contains all (not-filtered) recordings between two given points in time.

What is or is not contained in a sample is defined by the sampling strategy in use. There are currently two sampling strategies available:

<div class="contents" id="bkmrk-event-sampling-strat"><div class="contents"><div class="textblock">- Event Sampling Strategy
- Duration Sampling Strategy

</div></div></div>If an event sampling strategy is used, all recordings between two events of the same type belong to the same sample (e.g. all recordings between two occurrences of the "New Frame" event). The duration sampling strategy combines all recordings that are e.g. in the first 1000 ms after recording started into one sample.

See also:

<div class="contents" id="bkmrk-sampling-0"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[Sampling](https://doc316en.candera.eu/link/271#bkmrk-sampling%C2%A0)</span>

</div></div>#### **File Filter**   


##### <a class="anchor" id="bkmrk--24"></a>File Filter Overview

A performance log can contain a huge amount of recordings. More recordings lead to a more detailed information about the own system.   
However loading millions of recordings into the Analyzer also leads to a dull application with a barely comprehensible dataset.   
A good way to reduce the amount of data is to filter recordings away which are not useful in the current analysis.   
This step is done during the loading process of a file and is an optional feature.   
In general the loading speed will not be reduced due to the additional filtering effort but the Analyzer will work more smoothly and the data will be concreted to the requested analysis.

#### <a class="anchor" id="bkmrk--25"></a>Open Filtered File

##### <a class="anchor" id="bkmrk--26"></a>GUI Overview

The GUI has two tabs which both contain filter. The first tab (General) contains timespan changing filter.   
The second tab (Recorder) contains a filter to show or hide recordings.   
At the bottom of the window is a information area. It shows a brief overview how a filter is meant to be used.   
This information area can be toggled off, so it will not show any more.

<div drawio-diagram="1172"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676512394.png" alt=""/></div>

<div class="contents" id="bkmrk--6"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--28"></a>Time Range Filter

The time range filter is the most basic filter. You select the exact time range which will be loaded. There is a start and an end time. Everything before the start and after the end time will be truncated during loading. This filter applies to all other filter.   
Other filter will operate on the remaining subset of recordings.

##### <a class="anchor" id="bkmrk--29"></a>Recorder Count Filter

The recorder count is a filter which indirectly influences the time range. The concept of this filter is to only show data starting from a specific recording and ending after this recorder type appeared a defined amount of times.   
The filter is split a recorder list and two options.   
Within the recorder list a recorder can be selected. This recorder is used for the occurrence count. The recorders are listed as annotated recorders. So the selection is limited to a recorder subtype.   
The option Offset defines the amount of skipped recordings of the selected recorder at the beginning.   
The option Hit Count defines how often the recorder occurs. Afterwards the loading of file stops.   
When the hit count is reached this last recording will still be loaded.

Typical use case:   
Select Event: New Frame   
Offset: 10   
Hit Count: 5   
Result: Skips the first 10 frames; shows 4 frames and the occurrence of the 5th new frame event.

<div drawio-diagram="1173"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676512426.png" alt=""/></div>

<div class="contents" id="bkmrk--8"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--31"></a>Recorder Count Filter

The recorder selection filter is used to hide specific recorder (sub-)types.   
A type is based on recorder type and recorder ID. The subtype of such a recorder takes the annotations into account. The different subtypes or a whole type can be (un-)selected. An unselected recorder will not be loaded. Its nested recordings will be moved to the recording above.   
Brief example:   
A duration recording (A) contains two occurrences of another duration recording (B).   
Recording B contains additional recordings (C). Unselecting the recorder of recording B will hide all occurrences of B.   
The additional recordings C will be moved to A as its parent.

<div drawio-diagram="1174"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676512445.png" alt=""/></div>

<div class="contents" id="bkmrk--10"></div>

# Measurement User Interface

#### **User Interface** 

The User Interface is divided in 3 areas:

<div class="contents" id="bkmrk-ribbon-bar-view-area"><div class="contents"><div class="textblock">- Ribbon bar
- View area
- Status bar

</div></div></div>The ribbon bar is subdivided into groups of controls dedicated to a specific task - ribbon groups. The View Ribbon Group for example allows configuring the display of, opening of, and switching between views.

<div drawio-diagram="1185"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676513010.png" alt=""/></div>

<div class="contents" id="bkmrk--1"><div class="contents"><div class="textblock">  
</div></div></div>Analyzer allows Performance Logs to be viewed from different vantage points (views). Each view abstracts from the total amount of data and information to allow the user to easier concentrate on and find the information he searches.

The following views are supported and described in the subsequent sections:

<div class="contents" id="bkmrk-performance-dashboar"><div class="contents"><div class="textblock">- <span style="color: rgb(230, 126, 35);">[Performance Dashboard View:](https://doc316en.candera.eu/link/271#bkmrk-performance-dashboar-0)</span> An overview of key performance indicators
- <span style="color: rgb(230, 126, 35);">[Chart View:](https://doc316en.candera.eu/link/271#bkmrk-chart-view)</span> A view of the trajectories of all value recordings
- <span style="color: rgb(230, 126, 35);">[Time Bars View:](https://doc316en.candera.eu/link/271#bkmrk-time-bars-view)</span> A chronological as well as hierarchical view of all recordings
- <span style="color: rgb(230, 126, 35);">[Grid Views:](https://doc316en.candera.eu/link/271#bkmrk-grid-view)</span> Views in table form   
    &gt; Flat View: A flat view on all recordings   
    &gt; Hierarchical View: A hierarchical (nested) view on all recordings
- <span style="color: rgb(230, 126, 35);">[Treemap View:](https://doc316en.candera.eu/link/271#bkmrk-treemap-view) </span>A nested view of the timing recorders Access to opening and switching between views, as well as configuration of views is provided by the View Ribbon Group.

</div></div></div><div drawio-diagram="1186"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676513032.png" alt=""/></div>

<div class="contents" id="bkmrk--3"><div class="textblock">  
</div></div>#### **Application Menu**   


The application menu holds commands for opening and closing a performance log, as well as exporting performance log data.

<div drawio-diagram="5307"><img src="https://doc316en.candera.eu/uploads/images/drawio/2024-02/drawing-5-1708678940.png" alt=""/></div>

<div class="contents" id="bkmrk--6"><div class="textblock">  
</div></div>#### **Configuration**   


The display of performance logs can be configured using the Performance Log Configuration dialog. The dialog can be opened from the "View" Ribbon Group.

The configuration dialog (depicted in Figure 4) allows the configuration of recording appearances in views as well as how the recordings are interpreted.

On the left side of the dialog, there is a list of all recorder names used. The recorder names displayed are fully qualified, consisting of the recorder class as prefix and the display name of the recorder. On the right side, the properties of the currently selected recorder are displayed and can be changed.

Changeable for all recorders are the following properties:

<div class="contents" id="bkmrk-name%3A-the-name-of-th"><div class="contents"><div class="textblock">- Name: The name of the recorder displayed in all views
- Foreground color: Text color for recordings in Time Bars View
- Background color: Background color for recordings in Time Bars View, Color for trajectory of recordings in Chart View

</div></div></div>Changeable properties for value recorders are:

<div class="contents" id="bkmrk-data-values-are-sign"><div class="contents"><div class="textblock">- Data values are signed: The displayed values are treated as signed values
- Value relationship:   
    &gt; Unrelated: Recorded values are unrelated   
    &gt; Differential: The recorded values are only the difference from the last recorded value, not the total (absolute) value.   
    &gt; Absolute: The values recorded are always equal to the absolute values.

</div></div></div><div drawio-diagram="1188"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514012.png" alt=""/></div>

<div class="contents" id="bkmrk--9"><div class="textblock">  
</div></div>#### **Performance Log Export**   


##### <a class="anchor" id="bkmrk--86"></a>Export of Performance Log

The export of the currently open performance log is available via the application menu.

Currently, exporting of performance log data is supported in the following formats:

<div class="contents" id="bkmrk-microsoft-excel-2007"><div class="contents"><div class="textblock">- Microsoft Excel 2007 (XLSX)
- Comma Separated Values (CSV)

</div></div></div>Since Excel worksheets allow only a limited number of rows, data is distributed over several worksheets. Using this approach, a theoretical total number of 65000x255 rows can be stored in one Excel file. The export of data takes some time, so please be patient.

#### **Sampling**   


The figure shows the Ribbon Group for sampling. All sampling functionality is available via these controls.

<div drawio-diagram="1189"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514083.png" alt=""/></div>

<div class="contents" id="bkmrk--13"><div class="contents"><div class="textblock">  
</div></div></div>Usage of sampling requires two steps:

<div class="contents" id="bkmrk-configuration-of-sam"><div class="contents"><div class="textblock">- Configuration of sampling for a given view. The sampling configuration dialog can be opened via the "Configure" button.
- Enabling of sampling for the view. Sampling can be enabled via the "enable" checkbox

</div></div></div>Navigation between samples is supported by the navigation buttons in the Sampling Ribbon Group or keyboard shortcuts (see the end of this document for a list).   
Also, the user can directly jump to a desired sample by pressing the "Goto Sample" button and specifying the desired sample in the provided dialog.

<div drawio-diagram="1190"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514099.png" alt=""/></div>

<div class="contents" id="bkmrk--15"><div class="textblock">  
</div></div>#### **<span style="color: rgb(0, 0, 0);">Measurement Views</span>**


##### **<span style="color: rgb(0, 0, 0);">Performance Dashboard View</span>**

The Performance Dashboard View is the first view, automatically displayed when opening a performance log. It displays recordings of up to four Value Recorders. The actual Value Recorders used here can be customized. After installation, however, CPU load, GPU load and memory allocations are displayed (if available). The figure shows a typical Dashboard View.

<div drawio-diagram="1191"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514715.png" alt=""/></div>

<div class="contents" id="bkmrk--18"><div class="contents"><div class="textblock">  
</div></div></div>For every chart, the x-axis represents the elapsed time and the y-axis a value scale. To the right of each chart, there is a legend for the values displayed in this chart. There are no interactions possible with this view type. Only the values are displayed upon hovering over graphs.

##### <span style="color: rgb(0, 0, 0);">**Chart View**</span>

A Chart View, as shown in the figure displays only Value Recordings.

<div drawio-diagram="1192"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514801.png" alt=""/></div>

<div class="contents" id="bkmrk--21"><div class="contents"><div class="textblock">  
</div></div></div>On the x-axis, a time scale is displayed, on the y-axis a common scale for all values. To the right there is a legend for the values currently displayed.

Below the x-axis and to the right of the y-axis, there are so-called zoom bars. They allow the user to zoom-in to as well as pan the chart. Panning is also allowed by left-clicking the chart and dragging it to the left or the right.

By pressing the left shift button, clicking the left mouse button, and dragging the mouse, a part of the chart can be selected for zooming in.

Hovering over a trajectory or a marker displays a tooltip with information about the corresponding value.

<div class="contents" id="bkmrk--22"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--92"></a>Associated Ribbon Group

<div drawio-diagram="1193"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514818.png" alt=""/></div>

<div class="contents" id="bkmrk--24"><div class="contents"><div class="textblock">  
</div></div></div>The Chart Ribbon Group comprises UI elements for configuring the currently active Chart View:

<div class="contents" id="bkmrk-filtering-is-availab"><div class="contents"><div class="textblock">- Filtering is available via the "Filter" button
- Chart interpolation settings are available from the combo box.

</div></div></div>The following interpolations are supported:

<div class="contents" id="bkmrk-scatter%3A-no-interpol"><div class="contents"><div class="textblock">- Scatter: No interpolation is performed; only markers are displayed
- Scatter Line: Simple line interpolation is performed by connection successive markers
- Scatter Spline: Spline interpolation is used.

</div></div></div>##### <a class="anchor" id="bkmrk--94"></a>Filtering

Filtering allows the user to reduce the set of displayed Value Recorders to a desired subset. The shows the recorder filter editor opened via the "Filter" button in the Chart Ribbon Group.

<div drawio-diagram="1194"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514833.png" alt=""/></div>

<div class="contents" id="bkmrk--27"><div class="contents"><div class="textblock">  
</div></div></div>En- and disabling of filters is immediately reflected in the chart.

<div class="contents" id="bkmrk-%22invert%22-inverts-the"><div class="contents"><div class="textblock">- "Invert" inverts the current selection of recorders,
- "Set All" enables all recorders,
- "Reset All" disables all recorders in the current Chart View.

</div></div></div>##### Sampling

Sampling is available via the Sampling Ribbon Group. See section "Filtering" on page <span style="color: rgb(230, 126, 35);">[Views - Filtering - Sampling](https://doc316en.candera.eu/link/268#bkmrk-views---filtering---)</span> for details.

##### **<span style="color: rgb(0, 0, 0);">Grid View</span>**

Flat and Hierarchical Grid Views allow display of all recordings in a grid similar to Microsoft Excel. Table 1 lists and explains the displayed columns.

##### <a class="anchor" id="bkmrk--98"></a>Grid View Columns

<div class="contents" id="bkmrk-column-header-title-"><div class="contents"><div class="textblock"><table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse; width: 800px; border-width: 1px; border-spacing: 0px;" width="900"><tbody><tr bgcolor="#d4d4d4"><th style="border-width: 1px; padding: 5px;" width="25%">**Column Header**</th><th style="border-width: 1px; padding: 5px;" width="75%">**Title Description**</th></tr><tr><td style="border-width: 1px; padding: 5px;">\#</td><td style="border-width: 1px; padding: 5px;">Sequence number of the recording. Numbering starts at zero.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Recorder #</td><td style="border-width: 1px; padding: 5px;">Sequence number of the recorder. This is the number of the recorder in the sequence of recorders with same class and name. Numbering starts at zero.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Recorder Class</td><td style="border-width: 1px; padding: 5px;">The class of the recorder. See section 4.1.1 for a list of available recorder classes.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Recorder Name</td><td style="border-width: 1px; padding: 5px;">The unique name of the recorder within its class</td></tr><tr><td style="border-width: 1px; padding: 5px;">Recording Begin</td><td style="border-width: 1px; padding: 5px;">The time, this recording started. Unit is milliseconds.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Recording End</td><td style="border-width: 1px; padding: 5px;">The time, this recording ended. Unit is milliseconds.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Recording Duration</td><td style="border-width: 1px; padding: 5px;">The difference between Recording Begin and Recording End. Unit is milliseconds.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Self Duration</td><td style="border-width: 1px; padding: 5px;">The amount of time, this recording contributed to the recorded duration (if nested). Unit is milliseconds.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Effective Duration</td><td style="border-width: 1px; padding: 5px;">Depending on the recorder class, the effective duration yields the following:

- Cumulative Timing Recording: The accumulated duration
- Asynchronous Timing Recording: The asynchronous duration
- Other recorder classes: The self duration

Unit is milliseconds.

</td></tr><tr><td style="border-width: 1px; padding: 5px;">Time To Next Recording</td><td style="border-width: 1px; padding: 5px;">Unit is milliseconds.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Annotation</td><td style="border-width: 1px; padding: 5px;">A string enabling further differentiation between Recordings with same class and same name. The OpenGL timing recorder uses annotations e.g. to differentiate between calls of different functions.</td></tr><tr><td style="border-width: 1px; padding: 5px;">Call Count</td><td style="border-width: 1px; padding: 5px;">Depending on the recorder class, the call count yields the following: - Cumulative Timing Recorder: The number of recordings of this recorder
- Cumulative Value Recorder: The number of recordings of this recorder
- Other recorder classes: No value

</td></tr><tr><td style="border-width: 1px; padding: 5px;">Value</td><td style="border-width: 1px; padding: 5px;">Depending on the recorder class, the value yields the following: - Value Recorder The value
- Otherwise no value

</td></tr><tr><td style="border-width: 1px; padding: 5px;">Absolute Value</td><td style="border-width: 1px; padding: 5px;">Depending on the recorder class, the absolute value yields the following: - Cumulative Value Recorder The absolute (up until then cumulated) value
- Other recorder classes no value

</td></tr></tbody></table>

</div></div></div>##### <a class="anchor" id="bkmrk--99"></a>Filtering

Filtering in the grid views is available via the grid column headers as depicted in Figure 11. The filtering options are:

<div drawio-diagram="1195"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676514987.png" alt=""/></div>

<div class="contents" id="bkmrk--32"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--101"></a>Grid Filtering Options

<div class="contents" id="bkmrk-filter-option-descri"><div class="contents"><div class="textblock"><table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse; width: 800px; border-width: 1px; border-spacing: 0px;" width="900"><tbody><tr bgcolor="#d4d4d4"><th style="border-width: 1px; padding: 5px;" width="20%">**Filter Option**</th><th style="border-width: 1px; padding: 5px;" width="65%">**Description**</th><th style="border-width: 1px; padding: 5px;" width="15%">**Only Numeric**</th></tr><tr><td style="border-width: 1px; padding: 5px;">All</td><td style="border-width: 1px; padding: 5px;">Displays all recordings</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Custom</td><td style="border-width: 1px; padding: 5px;">Displays a dialog for constructing a custom filter expression</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Empty</td><td style="border-width: 1px; padding: 5px;">Display all recordings that contain no value in this column</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Not Empty</td><td style="border-width: 1px; padding: 5px;">Display all recordings that contain a value</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Below Average</td><td style="border-width: 1px; padding: 5px;">All recordings that have values below average in this column</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr><tr><td style="border-width: 1px; padding: 5px;">Above Average</td><td style="border-width: 1px; padding: 5px;">All recordings that have values above average in this column</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr><tr><td style="border-width: 1px; padding: 5px;">Lower 10</td><td style="border-width: 1px; padding: 5px;">The 10 lowest values in this column</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr><tr><td style="border-width: 1px; padding: 5px;">Upper 10</td><td style="border-width: 1px; padding: 5px;">The ten highest values in this column</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr><tr><td style="border-width: 1px; padding: 5px;">Lower 10-Quantile</td><td style="border-width: 1px; padding: 5px;">In descriptive statistics, a 10-quantile (also known as decile) is any of the nine values that divide the sorted data into ten equal parts, so that each part represents 1/10 of the sample or population.   
Thus, the lower 10-Quantile is the 1st decile and contains the lowest 10% of data, i.e. the 10th percentile.</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr><tr><td style="border-width: 1px; padding: 5px;">Upper 10-Quantile</td><td style="border-width: 1px; padding: 5px;">The upper 10-Quantile is the 10th decile and contains the highest 10% of data.</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr></tbody></table>

</div></div></div><div class="contents" id="bkmrk-summaries"><div class="contents"><div class="textblock"><a class="anchor" id="bkmrk--102" style="font-size: 1.4em; font-weight: 400; background-color: rgb(255, 255, 255);"></a><span style="color: rgb(34, 34, 34); font-size: 1.4em; font-weight: 400;">Summaries</span></div></div></div>Summaries are small evaluations over values in one column. Summaries can be en- and disabled via the grid column headers.

<div drawio-diagram="1196"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515039.png" alt=""/></div>

<div class="contents" id="bkmrk--36"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--104"></a>Grid View Summary Options

<div class="contents" id="bkmrk-summary-option-descr"><div class="contents"><div class="textblock"><table border="1" cellpadding="5" cellspacing="0" style="border-collapse: collapse; width: 800px; border-width: 1px; border-spacing: 0px;" width="900"><tbody><tr bgcolor="#d4d4d4"><th style="border-width: 1px; padding: 5px;" width="20%">**Summary Option**</th><th style="border-width: 1px; padding: 5px;" width="65%">**Description**</th><th style="border-width: 1px; padding: 5px;" width="15%">**Only Numeric**</th></tr><tr><td style="border-width: 1px; padding: 5px;">Count</td><td style="border-width: 1px; padding: 5px;">Number of rows displayed</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Average</td><td style="border-width: 1px; padding: 5px;">The average over all displayed values</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr><tr><td style="border-width: 1px; padding: 5px;">Maximum</td><td style="border-width: 1px; padding: 5px;">The highest value</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Minimum</td><td style="border-width: 1px; padding: 5px;">The lowest value</td><td style="border-width: 1px; padding: 5px;">No</td></tr><tr><td style="border-width: 1px; padding: 5px;">Sum</td><td style="border-width: 1px; padding: 5px;">The sum over all values</td><td style="border-width: 1px; padding: 5px;">Yes</td></tr></tbody></table>

</div></div></div>##### <a class="anchor" id="bkmrk--105"></a>Grouping

A grouping is a planned arrangement of all recordings by values in one column. Using this feature, it is possible to impose a hierarchical structure on the recordings. Grouping is accomplished by dragging a column header to the group-by-area. By default the group by area is collapsed.

<div drawio-diagram="1197"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515075.png" alt=""/></div>

<div class="contents" id="bkmrk--39"><div class="contents"><div class="textblock">  
</div></div></div>In order to restore the group by area, left-click on it or drag a column header and drop in on the collapsed group by area.

<div drawio-diagram="1198"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515112.png" alt=""/></div>

<div class="contents" id="bkmrk--41"><div class="contents"><div class="textblock">  
</div></div></div>Groupings can be chained, i.e. the recordings can first be grouped by values of one column, than by values of another column, and so on. The next figure shows recordings first grouped by recorder class and then by recorder name in order to collect all OpenGL recorders in one group.

<div drawio-diagram="1199"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515132.png" alt=""/></div>

<div class="contents" id="bkmrk--43"><div class="textblock">  
</div></div>##### <span style="color: rgb(0, 0, 0);">**Time Bars View**</span>

Time Bars View displays all recordings arranged along a timeline. Below the actual time bars, there is a scrollbar for panning the displayed time frame. The time ruler is situated between time bars and the scrollbar. Here, time values in milliseconds and a cursor with the current time under the mouse pointer are displayed.

These icons are used to distinguish the different recorder classes:

<div class="contents" id="bkmrk-time-recording-value"><div class="contents"><div class="textblock"><table border="0" cellspacing="10" style="width: 40.3704%; height: 237.969px;"><tbody><tr style="height: 83.1875px;" valign="middle"><td style="width: 20.7951%; height: 83.1875px;">[![measurement_timebar-icon_1.PNG](https://doc316en.candera.eu/uploads/images/gallery/2023-02/scaled-1680-/measurement-timebar-icon-1.PNG)](https://doc316en.candera.eu/uploads/images/gallery/2023-02/measurement-timebar-icon-1.PNG)

<div class="image">  
</div></td><td style="width: 78.8847%; height: 83.1875px;">Time Recording</td></tr><tr style="height: 66.3906px;" valign="middle"><td style="width: 20.7951%; height: 66.3906px;">[![measurement_timebar-icon_2.PNG](https://doc316en.candera.eu/uploads/images/gallery/2023-02/scaled-1680-/measurement-timebar-icon-2.PNG)](https://doc316en.candera.eu/uploads/images/gallery/2023-02/measurement-timebar-icon-2.PNG)

</td><td style="width: 78.8847%; height: 66.3906px;">Value Recording</td></tr><tr style="height: 28.7969px;" valign="middle"><td style="width: 20.7951%; height: 28.7969px;">[![measurement_timebar-icon_3.PNG](https://doc316en.candera.eu/uploads/images/gallery/2023-02/scaled-1680-/measurement-timebar-icon-3.PNG)](https://doc316en.candera.eu/uploads/images/gallery/2023-02/measurement-timebar-icon-3.PNG)

</td><td style="width: 78.8847%; height: 28.7969px;">Event Recording</td></tr><tr style="height: 29.7969px;" valign="middle"><td style="width: 20.7951%; height: 29.7969px;">[![measurement_timebar-icon_4.PNG](https://doc316en.candera.eu/uploads/images/gallery/2023-02/scaled-1680-/measurement-timebar-icon-4.PNG)](https://doc316en.candera.eu/uploads/images/gallery/2023-02/measurement-timebar-icon-4.PNG)

</td><td style="width: 78.8847%; height: 29.7969px;">Asynchronous Recording</td></tr><tr style="height: 29.7969px;" valign="middle"><td style="width: 20.7951%; height: 29.7969px;">[![measurement_timebar-icon_5.PNG](https://doc316en.candera.eu/uploads/images/gallery/2023-02/scaled-1680-/measurement-timebar-icon-5.PNG)](https://doc316en.candera.eu/uploads/images/gallery/2023-02/measurement-timebar-icon-5.PNG)

</td><td style="width: 78.8847%; height: 29.7969px;">Cumulative Recording (timing or value)</td></tr></tbody></table>

</div></div></div><div drawio-diagram="1208"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515293.png" alt=""/></div>

<div class="contents" id="bkmrk--47"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--110"></a>Associated Ribbon Group

The next figure shows the ribbon group associated with the Time Bars View. It contains only one button for displaying the recorder filtering dialog.

<div drawio-diagram="1209"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515305.png" alt=""/></div>

<div class="contents" id="bkmrk--50"><div class="contents">  
</div></div>##### <a class="anchor" id="bkmrk--112"></a>Filtering, 

Filtering here works analogous to filtering in the Chart View. Via the "Filter" button on the associated ribbon group the filter editor dialog is opened. En- and disabling of filters is immediately reflected in the chart.

<div class="contents" id="bkmrk-%22invert%22-inverts-the-0"><div class="contents"><div class="textblock">- "Invert" inverts the current selection of recorders,
- "Set All" enables all recorders,
- "Reset All" disables all recorders in the current Chart View.

</div></div></div>##### Sampling

Sampling is not supported for the Time Bars View.

##### **Zooming**

<div class="contents" id="bkmrk-zooming-is-supported"><div class="contents"><div class="textblock">Zooming is supported via two mechanisms:  
</div></div></div><div class="contents" id="bkmrk-mouse-wheel-keyboard"><div class="contents"><div class="textblock">- Mouse wheel
- Keyboard shortcuts

</div></div></div>Point the mouse pointer to the time you wish to zoom into. By using the mouse wheel or pressing Ctrl and the "+" or "-" button, you can zoom in to or out of this point in time. See section <span style="color: rgb(230, 126, 35);">[Keyboard Shortcuts](https://doc316en.candera.eu/link/261#bkmrk-page-title)</span> for a list of all available keyboard shortcuts.

##### <span style="color: rgb(0, 0, 0);">**Treemap View**</span>

The Treemap View only displays timing recordings along with their nesting. The following figure depicts the Treemap View of a performance log.

<div drawio-diagram="1210"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676515425.png" alt=""/></div>

<div class="contents" id="bkmrk--56"><div class="contents"><div class="textblock">  
</div></div></div>This view shows all timing recordings ordered by decreasing recording duration. The timing recording with the highest performance impact on one nesting level is drawn in the upper left corner, the recording with the lowest impact in the lower right corner.

Left-clicking an item in the treemap drills into this item. Right-clicking an item returns to its parent.

##### <a class="anchor" id="bkmrk--116"></a>Filtering

Filtering is not available for the Treemap View.

##### <a class="anchor" id="bkmrk--117"></a>Sampling

Sampling is available via the Sampling Ribbon Group.

# Data Acquisition Overview

The monitoring system provides several different ways to collect and analyze measured data:

<div class="contents" id="bkmrk-offline-collection-o"><div class="contents"><div class="textblock">- Offline collection
- Online collection
- Analysis at runtime
- Offline-Analysis of collected data

</div></div></div>There are two different types of data which can be gathered:

<div class="contents" id="bkmrk-scene-graph-related-"><div class="contents"><div class="textblock">- Scene Graph related data
- Performance based data (Recordings) The Scene Graph related data grabs the actual Scene Graph. This is only available during an established connection between Analyzer and target application.

</div></div></div>The performance based data provides key performance indicators which gives information about the current performance on target application. Therefore, it is also used during an established connection. The performance based data also provides recordings which can be gathered during runtime of the application. These data are meant to be analyzed afterwards.

#### **Performance Data Recording**

In order to record performance data to be analyzed, the following means are provided:

##### <a class="anchor" id="bkmrk--2"></a>Dumping to Local Files

Candera supports dumping of performance data to local files on the target system.  
Refer to class

<div class="contents" id="bkmrk-%3Cfeatstd-root%3E-%5Cfeat"><div class="contents"><div class="textblock">- &lt;FEATSTD-ROOT&gt; \\featstd\\src\\FeatStd\\Monitor\\PerformanceRecording\\FileDumper.h.

</div></div></div>The Player part of CGI Studio Releases is preconfigured to use this class for periodically dumping performance logs to the local file system, i.e. to the same location the asset is being loaded from. It is only required to enable performance recording in the CGIApplication via the respective macro call during application initialization:

```
CANDERA_PERF_SET_ENABLED(true);
```

The generated performance log files need to be transferred to the host system running Analyzer manually.

##### <a class="anchor" id="bkmrk--3"></a>Online Transfer of Performance Data

As an alternative to local file dumping, Analyzer can be used to fetch performance logs via a TCP/IP or Serial connection, which is also used for running online experiments on the target. This way, a performance log can be stored already on the host system running Analyzer for further analysis.

<div class="contents" id="bkmrk-for-online-transfer%2C"><div class="contents"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">For online transfer, there is a buffer limit of 468,75 kB of data, so only the first 468,75 kB of data will be covered in the performance log.</p>

</dd></dl></div></div></div>For setting up the online connection between Analyzer and the target application, refer to section Analysis for more details. The Candera application needs to be in Paused Mode to get a log file via the "Online" tab of Analyzer. Note that "Enable Recording" flag must be enabled.

##### <a class="anchor" id="bkmrk--4"></a>Dumping to Memory

Analyzer supports dumping performance logs to memory (e.g. where no file system is available). Usage for recording is similar to dumping to local files.

Refer to class:

<div class="contents" id="bkmrk-%3Cfeatstd-root%3E-%5Cfeat-0"><div class="contents"><div class="textblock">- &lt;FEATSTD-ROOT&gt; \\featstd\\src\\FeatStd\\Monitor\\PerformanceRecording\\MemoryDumper.h.

</div></div></div>Performance Logs have to be transferred from memory on target to the host computer for usage in Analyzer. The transfer from target memory to a host file is target specific. With the INTEGRITY operating system, Multi can be used for this task.

####   
**Establishing connection**

A connection can be established with selecting a communication type, configuring it and start the connection. Both, target and host, have to be connected by this communication type. It is not restricted which system (target or host) has to be started first.

Currently provided online communication types are:

<div class="contents" id="bkmrk-tcpip-serial-port"><div class="contents"><div class="textblock">- TcpIp
- Serial port

</div></div></div>##### <a class="anchor" id="bkmrk--5"></a>Target Side:

To use the monitor on target side the following cmake flag is required:

```
FEATSTD_MONITOR_TYPE
```

The default value is

```
 FEATSTD_COM_TYPE_NONE 
```

which disables monitoring completely.

Depending on the chosen value additional settings will be added to cmake:

TcpIp:

```
FEATSTD_MONITOR_TCPIP_ADDRESS 
FEATSTD_MONITOR_TCPIP_PORT
FEATSTD_MONITOR_TCPIP_STACK_ENABLED
```

These settings are used to connect to a specific ip-address and a specific port.

Serial Port:

```
FEATSTD_MONITOR_SERIALPORT_ADDRESS
FEATSTD_MONITOR_SERIALPORT_BAUDRATE
```

The baudrate supports common baudrates whereas it is not guaranteed that the target fully supports the given baudrates.

When Player is used as simulation environment, it also asks for these settings. The Player does not know which communication type is in use, so it provides both. Selecting a different communication type as the application uses leads to errors and should be avoided. Nevertheless choosing new settings for given communication type is possible.

##### <a class="anchor" id="bkmrk--6"></a>Analyzer Side:

To connect the analyzer to a target or another simulation environment the right module has to be selected in the settings of analyzer. To reach this settings view: Ribbon-Tab: General -&gt; Settings -&gt; Monitoring -&gt; Module or Ribbon-Tab: Online -&gt; Select Com Type Select the desired communication type and as module Scene Analyzer.

To establish the connection click the Button start at Ribbon-Tab Online.

####   
**Offline Performance Data Analysis**

Once a performance log is opened via Open menu of Analyzer, features in the "Performance Log" tab of Analyzer are enabled.

Please refer to section Measurements for further details.

####   
**Usage of different Candera mechanisms**

##### <a class="anchor" id="bkmrk--7"></a>Offline Performance Data Analysis

The Analyzer supports different concepts of rendering. The two main concepts are a cyclic rendering concept and the render wakeup mechanism of courier applications. Last one triggers rendering only when graphical changes happened. Both of these concepts work with Analyzer, but there are some logical restrictions. For example: A cyclic rendering mode sends updates to the Analyzer on a regular base. When these updates stop for a certain time, the Analyzer can assume that the communication has troubles. The render wakeup mechanism on the other hand produces these update stops intentionally.

Therefore, handling render wakeup mechanism differs from cyclic concept: All updates and requests are only handled when rendering is triggered. Timeouts should be disabled which disables the earlier mentioned communication trouble checking. Enabling timeouts do not necessarily disconnect the communication but disables some features(e.g. pause) until the application triggers rendering process again. This includes KPI-Updates and Pause requests. Pressing pause results in a waiting phase until the rendering process is triggered. The pause mode works as usual.

####   
**Multithreaded performance logs**

Performance recording supports multithreaded recordings. To enable this feature, use the recordings/recorder equal to the single threaded variant. There is no additional code needed by default. However, there are some restrictions and helpful macros which should be kept in mind to avoid unwanted behavior. Normally, these are not required to use this feature. They should be used when displayed results in the analyzer are not expected.

##### <a class="anchor" id="bkmrk--8"></a>Synchronization of threads

It is advisable to synchronize the threads when writing the data from the performance log buffer to any destination (e.g. filedump, memorydump, data streaming). This prevents unstable data within the buffer as the other threads continue running even in the paused mode of an online connection with the analyzer tool. There are two solutions to synchronize the threads.

```
#include <Candera/System/Monitor/PerfMonPublicIF.h>
…
#define CANDERA_PERF_COLLECT_RECORDING_THREAD_SYNC_BARRIER
#define CANDERA_PERF_PRODUCE_RECORDING_THREAD_SYNC_BARRIER
```

The first macro should be used in the thread which dumps data. The macro MONITOR\_HANDLE\_PAUSED does that internally, so using the analyzer tool for a live connection does not require the call of the first macro. The second macro should be called in all the other threads which are using performance recordings. The second solution is to use a custom synchronization method of all threads.

<div class="contents" id="bkmrk-it-is-also-advised-t"><div class="contents"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">It is also advised to add the synchronization barrier outside of the top level recording of a thread. This prevents influences of nested recordings on the current dump but also on an additional dump – as the buffer will be cleared even if there are recordings which are not done recording yet.</p>

</dd></dl></div></div></div>##### <a class="anchor" id="bkmrk--9"></a>Restrictions

Some of the recorder types have to store information of a recording temporary until the recording itself has been completed. It is advisable to use own recorder (own ID and/or name) for each thread. Typical issues can occur with AsyncTimingRecorder and cumulative recorders as their data may be written and corrupted by multiple threads.

<div class="contents" id="bkmrk-in-most-cases-using-"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">In most cases using one recorder in multiple threads will not produce issues but it is not guaranteed to do so.</p>

</dd></dl></div></div>

# Analysis

#### **Concept** 

##### <a class="anchor" id="bkmrk--21"></a>Analysis Concept

The analysis module allows the user to conduct experiments and thereby discover performance bottlenecks.

These experiments can be performed on the host in a simulation or on the target.   
During an experiment, the host and target have to be connected. Currently, Analyzer only supports a connection via TCP/IP and Serial Port.

####   
**Preparations for Analysis** 

#### <a class="anchor" id="bkmrk--22"></a>Build Candera with Monitor enabled

[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]"), as well as the application you are writing, have to be configured via CMake. Point CMake to the source directory of your application and indicate a directory for binary generation. Then fire up configuration. For further instructions see <span style="color: rgb(230, 126, 35);">[Establishing connection](#bkmrk-establishing-a-conne)</span>.

For configuration of CGI Monitor for a binary [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") distribution, see section 0.

<div class="contents" id="bkmrk-"><div class="contents"><div class="textblock">  
</div></div></div>#### <a class="anchor" id="bkmrk--23"></a>Provide CPU and/or GPU load

In order to display a trend with key performance indicators (CPU load, GPU load, frame rate) on Linux, the proc file system has to be mounted.

This can be accomplished (if not already mounted) by adjusting / adding the corresponding entry under /etc/mtab or mounting the proc file system by hand with the following command:

```
mount /proc
```

CPU and GPU information have to be provided by drivers / kernel modules and are thus not available on every (Linux) platform.

<div class="contents" id="bkmrk--0"><div class="contents"><div class="textblock">  
</div></div></div>#### <a class="anchor" id="bkmrk--24"></a>Provide communication infrastructure

[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") is only pre-configured for communication with Analyzer, if you call the function Renderer::RenderAllCameras or Renderer2D::RenderAllCameras (or both).

Otherwise, you have to ensure, that

<div class="contents" id="bkmrk-connection-parameter"><div class="contents"><div class="textblock">- Connection parameters are set correctly
- A connection is established
- A [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application can be paused by Analyzer

</div></div></div>##### <a class="anchor" id="bkmrk--25"></a>Setting connection parameters

Communication parameters can be set, if necessary, using the following macro:

```
#include <Candera/System/Monitor/MonitorPublicIf.h>
MONITOR_PORT_CONFIGURE(address, port)
```

<div class="contents" id="bkmrk-note%3A-this-macro-nam"><div class="contents"><div class="textblock"><div class="fragment">  
</div><dl class="note"><dd><p class="callout info">This macro name has changed with v3.2. Previous version were named MONITOR\_TCPIP\_CONFIGURE.</p>

</dd></dl></div></div></div>The standard Player for use with the tunnel application under Windows presents a dialog for setting communication parameters after the asset library to load has been chosen. The tunnel sample application delivered with [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") now takes two additional parameters for TCP/IP address and port or for Serial Communication baudrate and com port. This macro has to be used before either MONITOR\_TRYCONNECT() or MONITOR\_HANDLE\_PAUSED(), otherwise the standard configuration will still remain.

##### <a class="anchor" id="bkmrk--26"></a>Establishing a connection

A connection can be established explicitly, if necessary, from application code, by using the following macro

```
#include <Candera/System/Monitor/MonitorPublicIf.h>
MONITOR_TRYCONNECT()
```

##### <a class="anchor" id="bkmrk--27"></a>Enabling the pausing of a Candera application

For Analyzer to be able to pause your application and the key performance indicators to be updated, the following macro has to be called every time, the drawing of a new frame begins:

```
#include <Candera/System/Monitor/MonitorPublicIf.h>
MONITOR_HANDLE_PAUSED()
```

####   
**Connecting with a Candera application** 

The procedure for setting up a connection between host and target is as follows:

<div class="contents" id="bkmrk-start-analyzer-confi"><div class="contents"><div class="textblock">1. Start Analyzer
2. Configure the communication server
3. Start the server via the Server Ribbon Group on the Online Ribbon Tab
4. Start the [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application, it will try to connect to the pre-configured port and IP-address

</div></div></div>Configuration, starting, and stopping of the analysis server are triggered from the server ribbon group as depicted in the following figure.

<div drawio-diagram="1231"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525023.png" alt=""/></div>

<div class="contents" id="bkmrk--2"><div class="contents"><div class="textblock">  
</div></div></div>Upon successful connection between Analyzer and the [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application, the [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application is in Running Mode. A successful connection is indicated by the status bar. The server state is displayed as Connected and the application state as "Running".

##### <a class="anchor" id="bkmrk--29"></a>Configuration

The communication server is configured using a configuration dialog accessed through the "Configure" button on the Server Ribbon Group. Figure 20 shows the configuration dialog for TCP/IP connections.

<div class="contents" id="bkmrk-ip-address-and-port%2C"><div class="contents"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">IP-address and port, where Analyzer should listen for incoming connection requests have to be set.</p>

</dd></dl></div></div></div><div drawio-diagram="5305"><img src="https://doc316en.candera.eu/uploads/images/drawio/2024-02/drawing-5-1708678414.png" alt=""/></div>

<div class="contents" id="bkmrk--4"><div class="contents"><div class="textblock">  
</div></div></div>Timeouts can be set in order to prevent the user interface from freezing indefinitely if the communication fails. Disabling these timeouts completely can lead to freezes and communication failures depending on application type, communication type and stability of connection.

####   
**Analysis Views** 

##### **Trend View** 

The Trend View shows successively recorded key performance indicators such as

<div class="contents" id="bkmrk-cpu-load-%28if-availab"><div class="contents"><div class="textblock">- CPU load (if available)
- GPU load (if available)
- Frame Rate

</div></div></div>It can be displayed via the View Ribbon Group of the Online Ribbon Tab.

<div drawio-diagram="1233"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525106.png" alt=""/></div>

<div class="contents" id="bkmrk--6"><div class="contents"><div class="textblock">  
</div></div></div>The following shows a Trend View for a host simulation. The color assignment for the performance indicators is currently fixed and as follows:

<div class="contents" id="bkmrk-frame-rate-%28red%29-cpu"><div class="contents"><div class="contents"><div class="textblock">- Frame Rate (red)
- CPU load (green)
- GPU load (blue)

</div></div></div></div><div drawio-diagram="1234"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525119.png" alt=""/></div>

<div class="contents" id="bkmrk--8"><div class="contents"><div class="textblock">  
</div></div></div>Mouse over the Trend View shows a clear button which resets the view.

Right-clicking the Trend View opens a context menu for

<div class="contents" id="bkmrk-closing-it-and-displ"><div class="contents"><div class="textblock">- closing it and
- displaying it always on top of every other window.

</div></div></div><div class="contents" id="bkmrk-gpu-load-availabilit"><div class="contents"><div class="textblock"><dl class="note"><dd><p class="callout info">GPU load availability is dependent on device capabilities.</p>

</dd></dl></div></div></div>The settings menu also provides settings for trends:

<div drawio-diagram="1236"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525160.png" alt=""/></div>

<div class="contents" id="bkmrk--10"><div class="contents"><div class="textblock">  
</div></div></div>These settings allow to set the update rate and the history length of trends. IT is possible to change these values on the fly without restarting, pausing or changing the communication

#####   
**Scene Graph View** 

The Scene Graph View allows analysis of the scene graph during paused mode.

<div drawio-diagram="1238"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525192.png" alt=""/></div>

<div class="contents" id="bkmrk--12"><div class="contents"><div class="textblock">  
</div></div></div>This view is divided vertically by a splitter into two sections:

<div class="contents" id="bkmrk-a-camera-list-on-top"><div class="contents"><div class="textblock">- A camera list on top and
- A tree view of a scene graph below.

</div></div></div>The tree view shows the scene graph associated with the selected camera in the camera list.

The following commands are available via a toolbar on top of the Scene Graph View:

**Refresh:**

<div class="contents" id="bkmrk-this-command-is-alwa"><div class="contents"><div class="textblock">- This command is always available in paused mode.
- Fetches the scene graphs from the [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application and displays it. Node expansion and selected nodes are preserved.

</div></div></div>**Node Grid:**

<div class="contents" id="bkmrk-this-command-is-avai"><div class="contents"><div class="textblock">- This command is available in paused mode, if a camera was selected from the camera list.
- Displays all information transferred for the scene graph of the selected camera in a grid.

</div></div></div>**Measure Rendering:**

<div class="contents" id="bkmrk-this-command-is-avai-0"><div class="contents"><div class="textblock">- This command is available in paused mode, if a camera was selected from the camera list.
- Measures the rendering times of individual nodes and displays the render times along with static scene graph information in a grid

</div></div></div>The properties of a selected node are displayed in the <span style="color: rgb(230, 126, 35);">[Properties View](#bkmrk-properties-view%C2%A0)</span>.

#####   
**Properties View** 

Depending on the scene graph node selected in the Scene Graph View, different properties are displayed.

For each node, the following properties are displayed:

<div class="contents" id="bkmrk-name%3A-the-name-of-th"><div class="contents"><div class="textblock">- **Name:** The name of the node, if available, a blank field otherwise
- **[Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") Type:** The type of the node (e.g. Mesh or Group)

</div></div></div><div drawio-diagram="1243"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525374.png" alt=""/></div>

<div class="contents" id="bkmrk--14"><div class="textblock">  
</div></div>#### **Guards** 

Guards are a means to switch a [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application from running to paused mode.

We differentiate between two flavors of guards:

<div class="contents" id="bkmrk-conditional-guards-u"><div class="contents"><div class="textblock">- Conditional Guards
- Unconditional Guards

</div></div></div>Conditional guards are triggered, when a condition is met. Currently, only one conditional guard (based on measured frames per second) is supported. If the measured frames per second fall below a specified value, the guard is triggered, if it has been enabled, and the [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application enters the paused mode.

Unconditional guards can be set in application code via the use of the following macros:

```
#include <Candera/System/Monitor/MonitorPublicIf.h>
MONITOR_FORCE_PAUSED(groupId)
```

Guards are combined in guard groups. Each guard group has a unique id (the guard group ids are defined in the include file MonitorTypes.h).

<div drawio-diagram="1246"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525406.png" alt=""/></div>

<div class="contents" id="bkmrk--16"><div class="contents"><div class="textblock">  
</div></div></div>All guards can be en- and disabled. Additionally, the number of frames per second can be set for a FPS guard.

####   
**Performance Log Transfer** 

During an active connection to a [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application, a performance log can be transferred from the target to the host via the communication channel used.

There are two flavors of performance log transfer:

<div class="contents" id="bkmrk-recording-until-the-"><div class="contents"><div class="textblock">- Recording until the recording buffer is full and explicit transfer of the buffer content
- Continuous streaming of performance log data to a specified file

</div></div></div>##### <a class="anchor" id="bkmrk--37"></a>Single Buffer Recording and Transfer

Caution has to be taken to use only one of the following means of performance log recording

<div class="contents" id="bkmrk-record-to-file-on-de"><div class="contents"><div class="textblock">- Record to file on device
- Record to memory buffer on device

</div></div></div>If both flavors of recording are enabled, unpredictable effects may occur.

Recording to memory buffer is enabled via the Enable Recording checkbox of the Performance Log Ribbon Group.

<div drawio-diagram="1248"><img src="https://doc316en.candera.eu/uploads/images/drawio/2023-02/drawing-4-1676525450.png" alt=""/></div>

<div class="contents" id="bkmrk--18"><div class="contents"><div class="textblock">  
</div></div></div>After the memory buffer has been filled (approx. 1 sec), the buffer contents can be transferred to the host and stored in a file by clicking the "Get Log" button, also located in the Performance Log Ribbon Group.

##### <a class="anchor" id="bkmrk--39"></a>Performance Log Streaming

Performance log streaming is the continuous recording and transfer for performance log data from a [Candera](http://dev.doc.cgistudio.at/APILINK/namespace_candera.html "[DataBinding_RefTypeSample]") application to Analyzer.   
Streaming is enabled by first enabling recording via the Performance Log Ribbon Group and then enabling streaming via the "Enable Streaming" checkbox. A storage location for the performance log data (file) is asked.

After provision of this information, performance log data is continuously streamed from target to host and appended to the specified file.

####   
**Global Experiments** 

Experiments allow the user to locate performance bottlenecks by intervening in the rendering process. By targeted change of rendering parameters, conclusions about the origins of performance issues can be drawn.

There are three different groups of experiments:

<div class="contents" id="bkmrk-3d-experiments-2d-ex"><div class="contents"><div class="textblock">- 3D experiments
- 2D experiments
- Custom experiments

</div></div></div>##### <a class="anchor" id="bkmrk--40"></a>2D/3D Experiments

The following experiments are available:

<div class="contents" id="bkmrk-2x2-textures-%283d-onl"><div class="contents"><div class="textblock">- 2x2 textures (3D only)
- Null Fragment Shader (3D only)
- Ignore Draw Calls

</div></div></div>The following figure shows the dialog for setting experiments. Currently, experiments can only be en- or disabled in Paused Mode.

<div drawio-diagram="5306"><img src="https://doc316en.candera.eu/uploads/images/drawio/2024-02/drawing-5-1708678756.png" alt=""/></div>

<div class="contents" id="bkmrk--20"><div class="contents"><div class="textblock">  
</div></div></div>##### <a class="anchor" id="bkmrk--42"></a>Using 2x2 textures

All textures are replaces with a 2x2 texture using a chess pattern.   
If the frame rate rises significantly after enabling 2x2 textures, there are likely too big textures in use.

##### <a class="anchor" id="bkmrk--43"></a>Null Fragment Shader Program

All shader programs are replaces with a default shader program whose fragment shader always produces the color red.   
If the frame rate rises significantly after enabling the null fragment shader, fragment shader may be to complex.

##### <a class="anchor" id="bkmrk--44"></a>Ignore Draw Calls

All draw calls are ignored, thereby simulating an infinitely fast GPU. If the frame rate does not rise significantly, the problem may be CPU-bound.

##### <a class="anchor" id="bkmrk--45"></a>Custom Experiments

Custom experiments are universally usable experiments. In general it is a table of functions which have a parameter (enable/disable). The analyzer can trigger function calls on these specified functions. An experiment state is false/disabled per default.

##### <a class="anchor" id="bkmrk--46"></a>Custom Experiments - Target side:

To use this feature, the following flag has to be set:

```
// Enables custom experiments
#define CANDERA_MONITOR_CUSTOM_EXPERIMENTS
```

This flag can be set within code when it were not enabled by cmake configuration.

<div class="contents" id="bkmrk-using-this-flag-requ"><div class="contents"><div class="textblock"><dl class="note"><dt></dt><dd><p class="callout info">Using this flag requires init-Call (next step). Compiler produces error without this init-Call.</p>

</dd></dl></div></div></div>The following sample code snippet has to be used in order to register a function as experiment:

```
//Adds macros for global experiments
#include <Candera/System/Monitor/GlobalExperimentPublicIF.h>
… 
// Function which can be triggered by analyzer
void SampleFunction(bool flag); 

// Initializes list – has to be outside of any namespace
//First param is amount of function pointer
//following parameters are function pointers
GLOBAL_EXPERIMENT_INIT_CUSTOM_LIST(1, SampleFunction)
```

The include adds the appropriate macros. To enable these custom experiments previously mentioned define has to be set.

<div class="contents" id="bkmrk-the-init-call-has-to"><div class="contents"><div class="contents"><div class="textblock"><dl class="note"><dd><p class="callout info">The Init-Call has to be placed outside of any namespace and function.</p>

</dd></dl></div></div></div></div>A callable function’s declaration is defined as:

```
void FunctionName(bool flag);
```

In general: A static function with no return value. The flag is set by analyzer. A function within namespaces and classes can be added but need full declaration. This function should never be called by custom code - otherwise undefined behavior. The next point explains a way to indirectly call such a function.

Calling a function pointer by target application  
If it is required to call a registered function pointer, use the following macro:

```
GLOBAL_EXPERIMENT_CALL_CUSTOM_EXPERIMENT(fct_ptr, value);
```

##### <a class="anchor" id="bkmrk--47"></a>Global Experiments - Analyzer:

The analyzer provides a view for global experiments. It contains three different areas for 2D, 3D and custom experiments. To enable or disable an experiment toggle the checkbox. Custom experiments are listed in the same order as they were added to list on target side (see <span style="color: rgb(230, 126, 35);">[Custom Experiments - Target side:](#bkmrk-custom-experiments--)</span> GLOBAL\_EXPERIMENT\_INIT\_CUSTOM\_LIST). If the list is wrong or not present, pause the application to update the experiments list.

Additionally it provides a reset button which is used to disable all experiments.