feat(profiling): Integrate Tracy profiler by stephanmeesters · Pull Request #2202 · TheSuperHackers/GeneralsGameCode

stephanmeesters · 2026-01-27T22:12:00Z

Merge by rebase

This PR adds Tracy profiler to the CMake presets win32-profile and win32-vcpkg-profile.

A variable RTS_BUILD_OPTION_PROFILE_TRACY is added to enable Tracy. Enabling this will disable the old profiler.

It is not added to the vc6-profile because Tracy library can't compile against it. The preset mingw-w64-i686-profile is also skipped as this preset does not build yet (see #2163).

Library include

Tracy is added as a package to VCPKG (version 0.11.1) and as a CMake FetchContent_Declare (version 0.13.1). These are the latest available versions at the time. Unfortunately the VCPKG is old, but the VCPKG Github has PR's going to update Tracy to the latest version. The version 0.13.1 improves coloring immensely, which is important for at a glance seeing if we are render-bound of update-bound.

Tracy themselves recommend adding the library as a CMake include because the version of the library that is included in the game must match exactly with the version of their main executable tracy-profiler.exe. This can be guaranteed by building and copying tracy-profiler.exe to the build dir, however we can not do this right now as it requires a 64 bit compile.

What are we tracing?

Frame markers (start-end of each frame)
Zones
Logic frame number
Pathfinding count of paths and cells
Messages ("started game with map Alpine Assault" ..)

A number of zones were picked that capture the majority of processing time, and will hopefully be useful for profiling sessions.

Performance impact

Tracy itself has a negligible impact, however the frame capturing does have a minor impact (0.5ms average per frame). I have done my best to optimize the frame capturing by downscaling the backbuffer on the GPU side before copying to the CPU. It will be possible to simplify some of this code by moving from DX8 to DX9 and perhaps increase performance too.

Future work

It should be determined whether this will be sufficient to replace the old profiling code. At that point, and when all other profiles build, we can activate Tracy using only RTS_BUILD_OPTION_PROFILE. Other interesting things to trace would be a plot of the memory usage.

Todo

Replicate to Generals

Example of a capture. Render bound frame (top), update bound frame (bottom)

…uperHackers#2202)

…erHackers#2202)

…me end (TheSuperHackers#2202)

…heSuperHackers#2202)

…ells/paths to Tracy profiling (TheSuperHackers#2202)

greptile-apps · 2026-01-27T22:35:03Z

Greptile Overview

Greptile Summary

This PR integrates Tracy profiler (v0.13.1 via FetchContent, v0.11.1 via VCPKG) into the profiling build presets win32-profile and win32-vcpkg-profile. Tracy is enabled via the new RTS_BUILD_OPTION_PROFILE_TRACY CMake option, which mutually excludes the legacy profiler.

Key Changes

CMake Integration: Added cmake/tracy.cmake for FetchContent and modified cmake/config-build.cmake to conditionally link Tracy::TracyClient
Profile Header: Modified rts/profile.h to include Tracy headers when TRACY_ENABLE is defined, with no-op macro fallbacks for disabled builds
Instrumentation: Added profiling zones (ZoneScopedN, ZoneScopedNC) throughout the codebase covering:
- Game logic update loop and subsystems (ScriptEngine, AI, TerrainLogic, etc.)
- Render pipeline stages (scene rendering, UI, particles, shadows)
- Pathfinding with plots for cells and paths processed
Frame Capture: Implemented GPU-accelerated frame image capture in W3DDisplay with BGRA-to-RGBA pixel shader conversion and downscaling to 256x256
Frame Markers: Added FrameMark in GameClient::update() to delimit frame boundaries
Telemetry: Added TracyMessage calls on game start/end and TracyPlot for logic frame number and pathfinding metrics

Issues Found

Uninitialized pointers: Tracy member variables in W3DDisplay.h (m_tracyRenderTarget, m_tracySurfaceClass, m_tracyIntermediateTexture, m_tracySwizzleShader) are not initialized in the constructor, which could cause crashes if ResetTracyCaptureImage() is called before InitTracyCaptureImage()
Missing error handling: InitTracyCaptureImage() assumes all allocations succeed (render targets, surfaces, textures, shaders) without checking for failures, which could lead to null pointer dereferences in TracyCaptureImage()

The implementation is comprehensive and well-structured, but requires defensive null checks and member initialization to be production-ready.

Confidence Score: 3/5

This PR has critical uninitialized pointer issues that could cause crashes in Tracy-enabled builds
Score reflects well-designed Tracy integration with comprehensive instrumentation, but uninitialized member variables and missing error handling in frame capture code pose crash risks that must be addressed before merge
Pay close attention to W3DDisplay.h (uninitialized pointers) and W3DDisplay.cpp (missing error handling in InitTracyCaptureImage())

Important Files Changed

Filename	Overview
cmake/config-build.cmake	Adds `RTS_BUILD_OPTION_PROFILE_TRACY` option and conditionally links Tracy when enabled
Core/Libraries/Include/rts/profile.h	Adds Tracy header include and macro definitions with no-op fallbacks for disabled builds
GeneralsMD/Code/GameEngineDevice/Include/W3DDevice/GameClient/W3DDisplay.h	Declares Tracy frame capture methods and member variables for texture/surface management
GeneralsMD/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp	Implements Tracy frame capture with GPU-side downscaling and BGRA-to-RGBA pixel shader conversion
GeneralsMD/Code/GameEngine/Source/GameLogic/System/GameLogic.cpp	Adds Tracy zones throughout game logic update loop and plots for logic frame number

Sequence Diagram

sequenceDiagram
    participant GC as GameClient::update()
    participant GL as GameLogic::update()
    participant D as Display::draw()
    participant W3DD as W3DDisplay::draw()
    participant Tracy as Tracy Profiler
    
    Note over GC: Frame Start
    GC->>Tracy: FrameMark
    
    Note over GC,GL: Logic Update Phase
    GC->>GL: update()
    GL->>Tracy: ZoneScopedNC("GameLogic::update", green)
    GL->>Tracy: TracyPlot("LogicFrame", frameNumber)
    GL->>GL: ScriptEngine, TerrainLogic, AI, etc.
    Note over GL: Each subsystem wrapped in ZoneScopedN
    GL->>Tracy: TracyPlot("PathfindCells", cellCount)
    GL->>Tracy: TracyPlot("PathfindPaths", pathCount)
    
    Note over GC,W3DD: Render Phase
    GC->>Tracy: ZoneScopedNC("Render", blue)
    GC->>D: draw()
    D->>W3DD: draw()
    W3DD->>Tracy: ZoneScopedN zones for rendering stages
    W3DD->>W3DD: Render 3D scene, UI, particles
    W3DD->>W3DD: TracyCaptureImage()
    W3DD->>Tracy: FrameImage(pixels, width, height)
    
    Note over GC: Frame End

greptile-apps

_{2 files reviewed, 2 comments}

_{Edit Code Review Agent Settings | Greptile}

cmake/tracy.cmake

Core/Libraries/Include/rts/profile.h

Caball009 · 2026-01-28T16:27:40Z

Would you mind adding a few images or a short video to the first post?

stephanmeesters · 2026-01-29T19:52:20Z

Would you mind adding a few images or a short video to the first post?

Done. Added examples.

~~I've noticed that it's important to use -win otherwise the frame image capture will use your screen resolution and not the native game resolution so it's much slower... I've tested using 1080p~~

Nevermind I accidentally had DXVK DLL's in the binary dir and that changed the profile: the Render::VSync block was gone and the TracyFrameImage zone took longer to complete, while overall FPS was way up. I attributed whatever happened in the time after the rendering was complete to VSync but I'm not sure now.

…uperHackers#2202)

…erHackers#2202)

…me end (TheSuperHackers#2202)

…heSuperHackers#2202)

…ells/paths to Tracy profiling (TheSuperHackers#2202)

greptile-apps

_{5 files reviewed, 4 comments}

_{Edit Code Review Agent Settings | Greptile}

GeneralsMD/Code/GameEngineDevice/Include/W3DDevice/GameClient/W3DDisplay.h

GeneralsMD/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp

…uperHackers#2202)

…erHackers#2202)

…me end (TheSuperHackers#2202)

…heSuperHackers#2202)

…ells/paths to Tracy profiling (TheSuperHackers#2202)

xezon

Looks promising, but additional code polishing is required.

xezon · 2026-02-23T20:36:19Z

cmake/config-build.cmake

+            message(FATAL_ERROR "Tracy is enabled but Tracy::TracyClient was not found.")
+        endif()
+        target_compile_definitions(core_config INTERFACE
+                TRACY_ENABLE


Can merge with line above.

xezon · 2026-02-23T20:38:15Z

Core/Libraries/Include/rts/profile.h

+#define FrameMarkNamed(name) ((void)0)
+#define FrameImage(image, width, height, offset, flip) ((void)0)
+#define TracyMessage(txt, size) ((void)0)
+#define TracyIsConnected false


Use MACRO_CASE for macros

FrameMarkNamed , FrameImage, TracyMessage etc. are macros defined by Tracy and the code here are stubs of those macros when we don't include the Tracy library.

We could do MACRO_CASE like this (but you will get the ones emitted by Tracy too)

// when enabled #define TRACY_MESSAGE(text, size) TracyMessage(text, size) // when disabled #define TRACY_MESSAGE(text, size) ((void)0)

xezon · 2026-02-23T20:41:34Z

Core/Libraries/Include/rts/profile.h

+#define TRACY_FRAMEIMAGE_SIZE 256
+#else
 #include "../../Source/profile/profile.h"
+#define ZoneScopedN(name) ((void)0)


Please use abstracted names for profiler functions, so that we would be able to plugin different kinds of Profilers behind the same macros.

Find example here:
https://github.com/TheAssemblyArmada/Thyme/pull/801/changes

Ah OK will check that out

xezon · 2026-02-23T20:43:21Z

Core/CMakeLists.txt


+if(RTS_BUILD_OPTION_PROFILE AND RTS_BUILD_OPTION_PROFILE_TRACY)
+    target_link_libraries(corei_libraries_include INTERFACE Tracy::TracyClient)
+endif()


if(RTS_BUILD_OPTION_PROFILE) if(RTS_BUILD_OPTION_PROFILE_TRACY) target_link_libraries(corei_libraries_include INTERFACE Tracy::TracyClient) endif() endif()

Makes it easier to plugin new ones later.

xezon · 2026-02-23T20:47:16Z

cmake/config-build.cmake

@@ -8,6 +8,7 @@ option(RTS_BUILD_OPTION_DEBUG "Build code with the \"Debug\" configuration." OFF
 option(RTS_BUILD_OPTION_ASAN "Build code with Address Sanitizer." OFF)
 option(RTS_BUILD_OPTION_VC6_FULL_DEBUG "Build VC6 with full debug info." OFF)
 option(RTS_BUILD_OPTION_FFMPEG "Enable FFmpeg support" OFF)
+option(RTS_BUILD_OPTION_PROFILE_TRACY "Enable Tracy profiling for profile builds." OFF)


When we add a another profiler here, then how would that compile option work?

E.g.

RTS_BUILD_OPTION_PROFILE_TRACY ON RTS_BUILD_OPTION_PROFILE_OPTICK ON

What is expected to happen?

xezon · 2026-02-23T21:09:02Z

GeneralsMD/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp

+		return false;
+
+	// allocate intermediate texture
+	SurfaceClass *backBuffer = DX8Wrapper::_Get_DX8_Back_Buffer();


backBuffer is never released.

xezon · 2026-02-23T21:10:31Z

GeneralsMD/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp

+	// swizzle shader
+	// TheSuperHackers @todo In DX9 with ps2.0 this shader will be much simpler
+	ID3DXBuffer *compiledShader = nullptr;
+	static const char *shader =


const char *const, no static

xezon · 2026-02-23T21:15:02Z

GeneralsMD/Code/GameEngineDevice/Include/W3DDevice/GameClient/W3DDisplay.h

+	void TracyCaptureImage();
+	TextureClass *m_tracyRenderTarget = nullptr;
+	SurfaceClass *m_tracySurfaceClass = nullptr;
+	IDirect3DTexture8 *m_tracyIntermediateTexture = nullptr;


Does it need all these members in the class? If possible use texture data in one go passing from one function another.

xezon · 2026-02-23T21:15:44Z

GeneralsMD/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp

+	IDirect3DSurface8 *tracyBackbufferTextureSurface;
+	m_tracyIntermediateTexture->GetSurfaceLevel(0, &tracyBackbufferTextureSurface);
+	DX8Wrapper::_Copy_DX8_Rects(backBufferSurface, nullptr, 0,
+	                            tracyBackbufferTextureSurface, nullptr);


Style: can be one line

xezon · 2026-02-23T21:20:38Z

GeneralsMD/Code/GameEngineDevice/Source/W3DDevice/GameClient/W3DDisplay.cpp

@@ -1935,6 +2156,7 @@ void W3DDisplay::draw( void )
 				TheGraphDraw->render();
 				TheGraphDraw->clear();
 #endif
+				TracyCaptureImage();


Is this meant to capture every single frame? Does that create very large captures? What is the recommended interval for this by Tracy? I looked at Tracy Docs and did not find any.

Can we get some numbers? Consider being more conservative with the Frame Grab frequency.

Capturing images on spikes would also be an option.

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Jan 27, 2026

feat(profiling): Include Tracy profiler library in the solution (TheS…

8d66cbd

…uperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Jan 27, 2026

feat(profiling): Add frame image capturing to Tracy profiling (TheSup…

579a8b1

…erHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Jan 27, 2026

feat(profiling): Add messages to Tracy profiling on game start and ga…

e0397e4

…me end (TheSuperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Jan 27, 2026

feat(profiling): Add trace zones and frame marks to Tracy profiling (T…

cb0eee3

…heSuperHackers#2202)

stephanmeesters force-pushed the tracy-profiler branch from 12b8fbf to 8ede749 Compare January 27, 2026 22:28

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Jan 27, 2026

feat(profiling): Add plots for logical frame number and pathfinding c…

bec7e86

…ells/paths to Tracy profiling (TheSuperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Jan 27, 2026

docs(readme): Add section about profiling (TheSuperHackers#2202)

8ede749

stephanmeesters marked this pull request as ready for review January 27, 2026 22:29

greptile-apps bot reviewed Jan 27, 2026

View reviewed changes

cmake/tracy.cmake Show resolved Hide resolved

Core/Libraries/Include/rts/profile.h Show resolved Hide resolved

stephanmeesters force-pushed the tracy-profiler branch from 8ede749 to 38cf6dd Compare February 4, 2026 13:24

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Feb 4, 2026

feat(profiling): Include Tracy profiler library in the solution (TheS…

f765794

…uperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Feb 4, 2026

feat(profiling): Add frame image capturing to Tracy profiling (TheSup…

f635a27

…erHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Feb 4, 2026

feat(profiling): Add messages to Tracy profiling on game start and ga…

c046bae

…me end (TheSuperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Feb 4, 2026

feat(profiling): Add trace zones and frame marks to Tracy profiling (T…

a505202

…heSuperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Feb 4, 2026

feat(profiling): Add plots for logical frame number and pathfinding c…

9c74f4b

…ells/paths to Tracy profiling (TheSuperHackers#2202)

stephanmeesters added a commit to stephanmeesters/GeneralsGameCode that referenced this pull request Feb 4, 2026

docs(readme): Add section about profiling (TheSuperHackers#2202)

38cf6dd

greptile-apps bot reviewed Feb 4, 2026

View reviewed changes

stephanmeesters added 6 commits February 4, 2026 21:03

feat(profiling): Include Tracy profiler library in the solution (TheS…

dcdeca1

…uperHackers#2202)

feat(profiling): Add frame image capturing to Tracy profiling (TheSup…

2d06e07

…erHackers#2202)

feat(profiling): Add messages to Tracy profiling on game start and ga…

8081dad

…me end (TheSuperHackers#2202)

feat(profiling): Add trace zones and frame marks to Tracy profiling (T…

393f850

…heSuperHackers#2202)

feat(profiling): Add plots for logical frame number and pathfinding c…

860c892

…ells/paths to Tracy profiling (TheSuperHackers#2202)

docs(readme): Add section about profiling (TheSuperHackers#2202)

a36e02c

stephanmeesters force-pushed the tracy-profiler branch from 38cf6dd to a36e02c Compare February 4, 2026 20:04

xezon added Enhancement Is new feature or request Major Severity: Minor < Major < Critical < Blocker Gen Relates to Generals labels Feb 23, 2026

xezon added ZH Relates to Zero Hour Debug Is mostly debug functionality labels Feb 23, 2026

xezon reviewed Feb 23, 2026

View reviewed changes

Comments

Conversation

stephanmeesters commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Library include

What are we tracing?

Performance impact

Future work

Todo

Uh oh!

greptile-apps bot commented Jan 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Overview

Greptile Summary

Key Changes

Issues Found

Confidence Score: 3/5

Important Files Changed

Sequence Diagram

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Caball009 commented Jan 28, 2026

Uh oh!

stephanmeesters commented Jan 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

xezon left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

stephanmeesters Feb 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

stephanmeesters commented Jan 27, 2026 •

edited

Loading

greptile-apps bot commented Jan 27, 2026 •

edited

Loading

stephanmeesters commented Jan 29, 2026 •

edited

Loading

stephanmeesters Feb 23, 2026 •

edited

Loading