Analysis

Contents List

• Concept 
  
• Preparations for Analysis 
  
• Connecting with a Candera application 
  
• Analysis Views 
  
  • Trend View 
    
  • Scene Graph View 
    
  • Properties View 
• Guards 
  
• Performance Log Transfer 
  
• Global Experiments

Concept 

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.

Back to the menu

Preparations for Analysis 

Build Candera with Monitor enabled

Candera, 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 Establishing connection.

For configuration of CGI Monitor for a binary Candera distribution, see section 0.

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.

Provide communication infrastructure

Candera 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

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)

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 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.

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()

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()

Back to the menu

Connecting with a Candera application 

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

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

Upon successful connection between Analyzer and the Candera application, the Candera 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".

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.

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 stablility of connection.

Back to the menu

Analysis Views 

• Trend View 
  
• Scene Graph View 
  
• Properties View 

Trend View 

The Trend View shows successively recorded key performance indicators such as

It can be displayed via the View Ribbon Group of the Online Ribbon Tab.

The following shows a Trend View for a host simulation. The color assignment for the performance indicators is currently fixed and as follows:

Mouse over the Trend View shows a clear button which resets the view.

Right-clicking the Trend View opens a context menu for

The settings menu also provides settings for trends:

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.

This view is divided vertically by a splitter into two sections:

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:

Node Grid:

Measure Rendering:

The properties of a selected node are displayed in the Properties View.

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:

Back to the menu

Guards 

Guards are a means to switch a Candera application from running to paused mode.

We differentiate between two flavors of guards:

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 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).

All guards can be en- and disabled. Additionally, the number of frames per second can be set for a FPS guard.

Back to the menu

Performance Log Transfer 

During an active connection to a Candera 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:

Single Buffer Recording and Transfer

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

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.

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.

Performance Log Streaming

Performance log streaming is the continuous recording and transfer for performance log data from a Candera 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.

Back to the menu

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:

2D/3D Experiments

The following experiments are available:

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

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.

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.

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.

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.

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.

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.

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);

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 Custom Experiments - Target side: 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.

Back to the menu