Gears User Manual

GameOptim Gears is a performance analysis tool developed by GameOptim. It analyzes CPU and GPU performance on mobile platforms and is designed to help developers optimize application performance. Gears captures and analyzes applications without requiring SDK integration, enabling developers to quickly identify performance hotspots.

Features Gears mainly includes three core features:

Realtime Mode: Real-time monitoring functionality, primarily used to monitor performance data on mobile platforms.

Frame Capture Mode: Frame capture analysis functionality. It captures the rendering frame of the current application and performs detailed analysis.

File Import: Supports importing multiple types of data files and provides visualized data presentation.

Platform Support Supported platform for Gears: Windows Supported test devices: Android devices, emulators

Installation After extracting the compressed package, double-click the .msi file included in the package and follow the installation prompts to complete the installation.

Uninstallation Gears can be uninstalled through Apps & Features in the system settings.

Registration Users who have not yet registered can click Register at the bottom of the login page to go to the GameOptim official website and create an account.

Login Registered users can enter their phone number (or email) and password, check “I have read and agree to the Terms of Service and Privacy Policy”, and click Login to access the tool.

#1. Tools: The toolbar where you can configure ADB, Compiler, and Simulator settings.

#2. Check for Updates: When a new version is released, click Check for Updates to download and update to the latest version of Gears.

#3. Realtime Mode: Entry point for Realtime Mode.

#4. Frame Capture Mode: Entry point for Frame Capture Mode.

#5. Import File: Click Import File and select the target file to open it. The file will then appear in the Project History list. Currently, only performance data files with the “.realtime” extension and frame capture files with the “.capture” extension are supported (files with the same name will not be imported repeatedly).

#6. Project History: Displays all historical projects as well as imported projects.

If ADB has already been configured in the system environment variables, enabling Use Default ADB will automatically detect and use the ADB configured in the system environment. Otherwise, Gears will use the ADB provided within the tool by default.

If you need to use ADB from a specific directory, you can uncheck Use Default ADB and manually configure the ADB path.

Configure the local path of the Shader offline compiler. Download links for both Mali and Adreno offline compilers are provided at the bottom of the page.

Mali Offline Compiler Used for offline static analysis of Shader performance on Mali GPUs. The download and configuration steps are as follows:

(1) Click Mali at the bottom of the page. Versions prior to 7.0 can be downloaded from the redirected page.

Versions after 7.0 require downloading Arm Mobile Studio. After installation, malisc.exe can be found in the location shown in the figure below.

(2) Install the downloaded .exe file and enter the path of malisc.exe in the corresponding field.

Adreno Offline Compiler Used for offline static analysis of Shader performance on Adreno GPUs. The download and configuration steps are as follows:

Gears includes built-in tools Spirv-Cross and Glslang Validator, located in the directory:

Gears\bin\shadertools\spirv

Proper configuration of the (VK)Spirv-Cross and (VK)Glslang Validator paths is critical for shader debugging. Ensure that Gears can locate and use these tools to process shaders for Vulkan projects.

When using an emulator for testing, you need to enter the IP address + port number of the emulator in the Simulator Settings, then click Start Connection. After a successful connection, it will be displayed as shown in the figure below.

Click the “Select Device & Application” button in the upper-right corner to open the device and application panel.

Select the device to be tested in the “Select Device & Application” panel.(Physical devices support both USB mode and Wi-Fi mode for testing.)

The “Select Process” option allows performance testing for mini-games or specific processes within an application.(The currently running process will be highlighted.)

The “Launch APP” option allows direct performance testing of the application.

After selecting the device and application, hover the mouse over the phone icon in the lower-right corner to view the device information and the application currently selected for testing.

Once the connection is ready, select the performance metrics you want to test and click “Start Capture” to collect performance data for the selected application, as shown in the figure below.

If you want to archive the collected performance data, click “Stop Capture”, and then click the “Save” button, as shown in the figure below.

Select the path where the file will be saved, as shown below.

Click the “Open” button and select the file you want to open, as shown below.

In addition, the File option in the navigation bar also provides Open and Save functions, as shown below.

Click the “Export” button to export part of the statistical data and save it locally in CSV format.

After selecting the File Path, choose the Export All option to export part of the statistical data from the entire test dataset to the local device.

After selecting the File Path, choose the Export by Range option to export part of the statistical data from selected test data to the local device.

Export by Time: Export statistical data based on the selected start time and end time.

Export by Bookmark: Export statistical data based on the selected start bookmark and end bookmark.

The Data Comparison and Analysis feature enables users to visually compare multiple sets of test data and quickly identify performance differences and optimization opportunities. Key performance metrics—such as FPS, frame time, memory usage, CPU usage, and GPU usage—can be displayed within a single interface across different devices or scenarios, providing clear data support for performance optimization.

By selecting different data dimensions for deeper comparison, developers can easily identify performance bottlenecks, enabling precise decision-making and efficient optimization.

Main Interface

When Realtime Mode data exists in the Project History on the main interface, you can right-click the specified dataset and select “Comparison Analysis” to enter the comparison analysis interface.

If there is no Realtime Mode data in the project history, you can:

Realtime Mode

After entering Realtime Mode, you can select “Comparison Analysis” in the upper-left corner of the interface to enter the comparison analysis interface.

In the Comparison Analysis interface, you can select the test datasets to compare from the dropdown menu under each tab.Up to five test datasets can be compared simultaneously.

After selection, the system will display detailed comparison analysis results, providing strong support for optimization and troubleshooting.

Gears provides a bookmark range comparison feature, allowing precise comparison of identical bookmark ranges across different test datasets. This feature is particularly useful when focusing on performance data within specific gameplay stages.

For example, when analyzing multiple sets of game performance test data:

In this case, Gears will automatically identify the common bookmark range “Battle Start – Battle End” shared by datasets A, B, and C, and users can select this range for comparison analysis.

Bookmark ranges that are not shared across all datasets will not be included in the comparison scope.

Click “Peak Data” or “Average Data” on the left side of the comparison analysis interface to switch between peak values and average values for the test datasets.

Click the “Export” button on the right side of the comparison analysis interface to export all comparison data displayed in the interface (including peak values and average values) to a local CSV file, making it convenient for offline analysis and sharing.

The Custom Data feature helps developers flexibly record and analyze key performance metrics in their projects.

By integrating the Gears SDK into your project, you can call custom instrumentation functions at key points in the code to record specified performance data (such as resource loading time, logic execution duration, etc.).

When testing with Gears, this custom data can be synchronized to Gears in real time for display, allowing development teams to visually analyze performance and quickly locate the root causes of issues.

After updating Gears to version V1.0.7 or later, the following files can be found in the bin\sdk folder within the Gears installation directory.

Android Native

In the Android Native folder, you will find dynamic libraries for the arm64-v8a and armeabi-v7a architectures, as well as the header file Android Trace.h.

Unity SDK

The Unity folder contains the Gears SDK_Android.unitypackage file, which is used for performance testing in Unity projects.

Drag Gears SDK_Android.unitypackage into the Unity project, and import it to complete the integration.

Record Integer Values

Method Name: GameOptim Gears.Sample Purpose: Records integer data for a specified event.

Call Format:GameOptim Gears.Sample(string event Name, int val);

Parameter Description:

Display Format: (I)<event Name>

Record Floating-Point Values

Method Name: GameOptim Gears.Sample Purpose: Records floating-point data for a specified event.

Call Format:GameOptim Gears.Sample(string event Name, double val);

Parameter Description:

Display Format: (D)<event Name>

Start Sampling

Method Name: GameOptim Gears.Begin Sample

Purpose: Starts performance sampling for a specified code segment.

Call Format:GameOptim Gears.Begin Sample(string event Name);

Parameter Description:

Display Format: (S)<event Name>

Note: Must be used together with GameOptim Gears.End Sample.

End Sampling

Method Name: GameOptim Gears.End Sample

Purpose: Ends performance sampling for the current code segment and sends the duration data to Gears.

Call Format:GameOptim Gears.End Sample();

Note: Must be called in the same thread as GameOptim Gears.Begin Sample.

Add Bookmark

Method Name: GameOptim Gears.Add Tag

Purpose: Adds a bookmark for a specified event.

Call Format:GameOptim Gears.Add Tag(string tag Name);

Parameter Description:

Note: Ensure that the current bookmark name is different from the previous one.

The Logcat logging feature is a commonly used monitoring and debugging tool in daily development. By capturing and recording system log information in real time, it helps developers quickly identify and resolve issues within applications.

The Logcat window is located in the lower-right corner of the corresponding mode. Click the arrow to open it. The window can be dragged to resize, allowing more log content to be displayed.

Use the log switch button to enable or disable log capture. This helps flexibly control log streams and prevents irrelevant logs from interfering, improving debugging efficiency.

Clear the current log records with one click, helping clean up the view and ensuring that new log data can be displayed more clearly for analysis.

Click this button to quickly locate the folder where logs are stored. The complete logs are saved in the logcat.log file within this folder, making it convenient for later analysis and sharing.

This log file only records the logs generated during the most recent device connection. When the device is connected again, the logs from the previous connection will be cleared.

When enabled, this feature automatically scrolls to the latest generated logs, ensuring that developers can monitor logs in real time.

When disabled, you can freely scroll and browse historical logs.

After clicking this button, case sensitivity will be applied when filtering logs, enabling more precise log searches.

When enabled, log filtering will match only complete character sequences rather than partial matches, helping developers accurately locate specific log entries.

This feature supports multiple filtering conditions, including:

It also supports logical operators such as (), |, and & for complex filtering, enabling developers to quickly and accurately locate relevant logs.

Add Bookmark: Click the bookmark icon or double-click the timeline to add a bookmark.

Rename Bookmark: Right-click the bookmark and select “Rename” to rename it.

Set Bookmark Color: Right-click the bookmark and select “Set Color” to change its color.

Remove Bookmark: Right-click the bookmark and select “Remove Bookmark” to remove it from the timeline.

In the curve panel, use the left mouse button to drag and select a section of the curve, then right-click the selected area and click “Export Current Data”.

Select “Export by Time” to export the statistical data of the selected range to the local device.

Select Parameters:Click “Select Parameters” in the funnel icon at the upper-left corner of the parameter panel to select all testable performance parameters for the device with one click, avoiding the need to check them individually. You can also flexibly adjust parameter selections to meet different analysis needs.

Record Template:Click “Record Template” to save the currently selected performance parameters as a template, making it easy to reuse commonly used configurations.

Apply Template:Click “Apply Template” to quickly load a previously saved parameter template, eliminating the need for manual parameter selection and improving the efficiency of performance data collection.

Note: After updating to a new version, the default parameter configuration will be restored, and templates must be recorded again manually.

Double-click a screenshot to open an enlarged image window for viewing more details.

The popup window supports free resizing. Clicking any screenshot or any point on the curve will update the preview screenshot in real time, making it easier to view different scenarios and providing more intuitive visual support for performance analysis and troubleshooting.

This mode is designed to help developers more conveniently and accurately locate GPU-side rendering and performance issues.

Through this mode, developers can capture the current frame data from a running project, and then view and analyze it within Gears. This enables developers to understand what operations are executed and what processes occur during GPU rendering at the underlying level, allowing them to better optimize and resolve rendering-related issues.

In the Mode Selection dropdown menu located in the upper-right corner of the interface, select the device for frame capture. The system will then perform device initialization.

During initialization, two GameOptim Client applications will be installed on the device, and the application will automatically launch on the device.

After the device connects successfully, the device status indicator in the lower-right corner will turn green.

After the device connects successfully, click the “Select Application” button in the upper-right corner.

In the pop-up Application Selection window, select the application for frame capture and click “Select” to launch it.

Note: If the application does not appear in the list, please check whether the Debuggable property is enabled for the application.

After the application launches successfully, the “Capture Frame” button in the upper section of the interface will become clickable.

Click the “Capture Frame” button to capture the frame. Once the capture is successful, a capture success message will appear next to the device status pop-up window in the lower-right corner.

Note: Frame capture is only available when the mobile application's log interface displays FPS and frame count updating normally. If FPS and frame count are not displayed, you can click the refresh button next to the Capture Frame button.

After a successful capture, click the small arrow next to the “Capture Frame” button to view the captured frame files transferred to the local machine.

Bring the Gears application on the mobile device to the foreground, then double-click the capture file to load it. Wait until the loading process completes.

The Event Browser allows users to view all Open GL functions captured within the frame, as shown in the figure below.

The Event Browser module includes the following features:

Click this button and select a save path to export the event content as an HTML file to the local device.

Click this button to add a GPU time column in the list below, showing the GPU execution time for each operation.

Clicking the button again will refresh the GPU time calculations.

Select an event and click the Favorite button to bookmark the event.

Click the dropdown arrow on the right to view the bookmarked event IDs. Selecting an ID from the list will quickly navigate to the corresponding event.

This feature allows users to select which information is displayed in the event list.

Events in the list can be filtered using keywords or filtering conditions.

Click the button above to open a detailed description of the filtering keywords.

Click this button to display the Open GL API inspection window, which is hidden by default.

Click the Frame Graph panel on the right side of the Event Browser to view the overall rendering pipeline of the captured frame.

This feature provides a more intuitive view of dependency relationships between rendering nodes, helping developers identify rendering issues more quickly.

For example, if there are redundant Render Textures, the Frame Graph can easily help identify and locate the specific problem.

This feature can also display:

Mouse Controls

Operations within nodes are shown in the figure below.

As shown below, the Texture Viewer window is primarily used to assist in examining texture details.

Detailed information displayed on the right side includes:

Texture Viewer Toolbar Functions

Saves the current texture locally.

Enter coordinates and press Enter to jump to the corresponding location in the image.

Allows different color display modes for the texture.

Select and view different color channels of the image.

Change the background of the texture viewer (checkerboard background toggle).

Displays textures under different Mipmap levels (valid only when Mipmap is enabled).

Displays:

(valid only for cubemap or 3 D textures).

Displays the texture according to the viewer's resolution.

This dropdown menu adjusts the image zoom level.

Users can select different percentages to zoom in or out of the image for detailed inspection or overall preview.

Common zoom ratios include 100%, 150%, and 200%.

Flips the currently displayed image or texture vertically for more comfortable viewing.

Only applicable to Frame Buffer outputs.

Helps visualize pixel differences in textures where color gradation is subtle.

Texture Attributes Currently Available

For mesh resources, the Mesh Viewer provides a more intuitive visualization of mesh models, as shown below.

Mesh Viewer Functions

Saves the current mesh locally.

Opens the camera settings interface, allowing adjustment of:

This helps developers inspect and analyze the mesh more precisely.

Restores the camera to its default state, quickly resetting all adjustments.

Allows selection of different camera control modes.

Instancing rendering can be switched for viewing.The default mode is This Draw (the model corresponding to the current Draw Call).

Controls shading mode.None represents the default wireframe mode.

Displays the mesh in wireframe mode.

Highlights the currently selected mesh model.

If you want to see how the rendering result of a specific Draw Call is calculated, you can select that Draw Call and then click the Shader button.

The viewer window will display the compiled shader code used by that Draw Call (not the original source code).

When selecting VS or FS shaders, the right display window switches to the shader view.

The far-right panel shows the preview result after modifying the shader and re-rendering.

The lower-right area displays information about the Uniform parameters used by the current shader.

Shader Editor Functions

Click the Search button to open the search box for locating content within the shader code.

Click the Edit button to enter shader editing mode.

Four buttons will appear with the following functions:

Use the dropdown menu to select the GPU architecture for shader analysis.

Click Analyze to automatically open the analysis results window.

The Render State Viewer includes information such as:

It provides a detailed overview of pipeline states used during rendering, allowing users to quickly locate and analyze the rendering state of the current frame for further optimization.

Render State Viewer Features

Depth testing determines whether a pixel passes the depth buffer comparison.

Stencil testing further controls whether a pixel is rendered via stencil buffer checks.

The rasterization stage converts geometry into pixels.

Blending controls how new pixel colors are combined with existing colors.

Framebuffers

Target Blends

The viewport defines the size and position of the rendering region on the screen.

Scissor testing restricts rendering to a defined region.

The Rendering Resource Overview window contains the Texture tab, Buffer tab, and Shader tab, providing detailed information about rendering resources. This helps developers analyze resource usage and identify optimization opportunities to improve overall rendering performance.

The Timeline window at the top displays bar charts showing trends for:

It also visualizes resource usage across the timeline.

Timeline Features

On the right side of the timeline, users can switch between:

Interactions:

Hovering the mouse over a bar displays the corresponding performance statistics (such as Draw Call count or vertex count).

The inverted triangle symbol indicates the usage of the currently selected texture or shader. Clicking the symbol quickly jumps to the corresponding rendering event in the Event Browser.

Texture Usage

The inverted triangle icons display read, write, and clear operations in rendering, helping developers analyze performance.

These indicators help identify rendering complexity and potential performance bottlenecks.

Shader Usage

The inverted triangle symbols also visualize shader usage frequency across the timeline.

Frequent alternating shader calls may indicate high-frequency vertex and fragment processing, which could require optimization.

Note: Shader usage can be switched between VS and FS views in the Shader Viewer.

Both the File option in the navigation bar and the “Open” and “Save” buttons in the upper-left corner provide this functionality.

(1) Ensure that no other ADB connection processes are running besides Gears, such as Android Studio. You can also check the number of ADB processes in the Task Manager, or set the ADB path to your commonly used local ADB path in the project management interface under [Tools - Open Settings Panel].

(2) For some LG devices, the [Transfer Mode] must be set to [MIDI Device].

(3) In the device USB options, select File Transfer or Charge Only.

(4) The issue may also be caused by a faulty data cable. Try replacing it with another cable for testing.

(1) Check whether Developer Mode is enabled on the device.

(2) Check whether the USB connection mode supports file transfer.

(3) Check whether USB Debugging and USB Installation (required for Frame Capture mode) are enabled.

If your system is Windows 10 or later, follow these steps:

Go to Settings → System → Optional Features → Add a Feature, add Graphics Tools, wait for the installation to complete, restart the computer, and then reopen the Gears software.

Currently, emulators are only supported in Realtime Mode. Emulator configuration can be performed in [Tools] - [Simulator Settings].

After connecting to an emulator, physical devices cannot be detected. If you need to test with a physical device, you must disconnect the emulator in [Tools] - [Simulator Settings].

Frame Capture Mode does not currently support emulator testing.

In Realtime Mode, the available GPU performance parameters vary depending on the GPU model of the physical device, and emulators do not support GPU performance data collection.

If GPU performance data cannot be collected, try the following solutions:

(1) Ensure that the device is included in the GPU Counter supported list. For specific models, please refer to:https://www.GameOptim.com/main/supported.html

(2) For supported devices with Adreno GPUs running Android 12 or above, if GPU Counter data cannot be obtained, try enabling it using the following adb command:

adb shell "echo 1 > /sys/class/kgsl/kgsl-3d0/perfcounter"

However, some devices may not support this operation due to hardware manufacturer restrictions, such as Xiaomi devices.

(3) For supported devices with Mali GPUs, if GPU Counter data cannot be obtained, try restarting the device (it may require multiple attempts).

Please first confirm whether the application is a Debuggable package.

A Debuggable package is required for Frame Capture Mode because obtaining data from the underlying system layer requires this configuration, while other performance tests do not require it.

You can verify it in the terminal using the following command:

adb shell dumpsys package <package_name> | findstr DEBUGGABLE

If the output shows content similar to the example in the figure, it indicates that the application is a Debuggable package. If nothing is output, then it is not a Debuggable package.

Generally, when building with Unity Development Build, the Unity engine automatically adds the debuggable attribute to Android Manifest.xml.

For the final build, please ensure that the debuggable attribute in Android Manifest.xml is correctly configured.

You can use the following command to remove the frame capture information displayed in the top-left corner:

adb shell settings delete global gpu_debug_app

After using Frame Capture Mode, please execute the above command promptly to remove the frame capture information to avoid affecting the accuracy of application performance testing. This functionality will continue to be optimized in future versions.

If GPU execution time is not a primary concern, the device’s performance does not affect other captured data.

If Frame Capture Mode is unstable on devices with lower performance, consider using a higher-performance device for testing.

First, terminate the ADB process in Task Manager.

Then check the ADB path used by the system in the terminal, and update the ADB path in [Tools] - [ADB Settings] within Gears to the system ADB path.

adb shell settings delete global gpu_debug_app

to remove the frame capture information, in order to avoid affecting the accuracy of application performance testing.

We are continuously improving the device compatibility of Gears. However, according to current testing results, the compatibility rate reaches 94.6% in Realtime Mode and 80.4% in Frame Capture Mode.

Most compatibility issues occur on low-end devices, particularly in frame capture state and captured frame file viewing functionality.

If similar issues occur, we recommend switching to another test device or contacting us and providing your device model, so that we can further improve device compatibility.