Add compile-time selectable profiling backend with Tracy integration (#3239)

unfiv · web-flow · commit 765fb7fd3b29 · 2026-07-19T20:25:55.000+08:00
* Profiling: add Tracy 0.13.1 sources

* Profiling: integrate Tracy to build system, default to noop

* Profiling: add Tracy to 3dparty README.md

* Profiling: Tracy compilation flags

* Profiling: add Tracy to 3rd-party build flow

* Profiling: update cmake template with Tracy

* Profiling: track basic Frame

* Profiling: move AX_PROFILER_BACKEND cmake variable to the main module

* Profiling: remove unnecessary AX_WITH_TRACY logging

* Profiling: rename AX_PROFILER_ macroses to be consistent

* Profiling: setup basic AX_PROFILER_ macroses across the engine

* Profiling: separate AX_PROFILER_ZONE_SCOPED for AudionEngine update

* Profiling: apply clang-format fixes

* Profiling: fix backend includes

* Profiling: fix AX_PROFILER_BACKEND define missing in prebuilt workflow

* Profiling: move 3d-party Tracy dependency out of the repo, fetch on build when opt-in
diff --git a/1k/build.profiles b/1k/build.profiles
@@ -100,4 +100,5 @@ lz4=v1.10.0
 sample-assets=v3.0.0-alpha22
 live2d-core=5.5
 openxr=release-1.1.61
+tracy=v0.13.1
 # --- endregion
diff --git a/1k/sources.json b/1k/sources.json
@@ -40,6 +40,9 @@
     },
     "live2d-core": {
       "sources": { "origin": "https://github.com/axmolengine/live2d-axmol/releases/download/prebuilt/live2d-core-${ver}.zip" }
+    },
+	"tracy": {
+      "sources": { "origin": "https://github.com/wolfpld/tracy.git" }
     }
   },
   "devtools": {
diff --git a/3rdparty/CMakeLists.txt b/3rdparty/CMakeLists.txt
@@ -6,6 +6,7 @@ option(AX_WITH_WEBP "Build with internal webp support" ON)
 option(AX_WITH_CLIPPER2 "Build with internal Clipper2 support" ON)
 option(AX_WITH_POLY2TRI "Build with internal poly2tri support" ON)
 option(AX_WITH_FASTLZ "Build with internal fastlz support" ON)
+option(AX_WITH_TRACY "Build with internal Tracy support" ON)
 
 option(AX_WITH_CURL "Build with internal curl support" ON)
 option(AX_WITH_UNZIP "Build with internal unzip support" ON)
@@ -424,6 +425,20 @@ if(WIN32 AND AX_GLES_PROFILE)
   endif()
 endif()
 
+# tracy
+if(AX_PROFILER_BACKEND STREQUAL "TRACY")
+  set(AX_WITH_TRACY ON CACHE BOOL "" FORCE)
+else()
+  set(AX_WITH_TRACY OFF CACHE BOOL "" FORCE)
+endif()
+
+if(AX_WITH_TRACY)
+  _1kfetch(tracy)
+  set(TRACY_ENABLE ON CACHE BOOL "" FORCE)
+  set(TRACY_ON_DEMAND ON CACHE BOOL "" FORCE)
+  ax_add_3rd(${tracy_SOURCE_DIR} TARGETS TracyClient)
+endif()
+
 # yasio
 ax_add_3rd(yasio)
 
diff --git a/3rdparty/README.md b/3rdparty/README.md
@@ -249,6 +249,11 @@
 - Version: 2.30
 - License: MIT
 
+## tracy
+- [![Upstream](https://img.shields.io/github/v/release/wolfpld/tracy?label=Upstream)](https://github.com/wolfpld/tracy)
+- Version: 0.13.1
+- License: BSD-3-Clause
+
 ## unzip (minizip-1.2)
 - Upstream: https://github.com/simdsoft/mz12
 - Version: 1.2, with bugfixs & improvements
diff --git a/axmol/2d/ActionManager.cpp b/axmol/2d/ActionManager.cpp
@@ -392,6 +392,8 @@ ssize_t ActionManager::getNumberOfRunningActions() const
 // main loop
 void ActionManager::update(float dt)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     for (auto actionIt = _targets.begin(); actionIt != _targets.end();)
     {
         auto elt               = &actionIt->second;
diff --git a/axmol/2d/Sprite.cpp b/axmol/2d/Sprite.cpp
@@ -44,6 +44,7 @@ THE SOFTWARE.
 #include "axmol/renderer/Shaders.h"
 #include "axmol/rhi/ProgramState.h"
 #include "axmol/rhi/GraphicsCore.h"
+#include "axmol/base/Profiling.h"
 
 namespace ax
 {
@@ -1069,6 +1070,8 @@ void Sprite::updateTransform()
 // draw
 void Sprite::draw(Renderer* renderer, const Mat4& transform, uint32_t flags)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     if (_texture == nullptr || _texture->getRHITexture() == nullptr)
         return;
 
diff --git a/axmol/CMakeLists.txt b/axmol/CMakeLists.txt
@@ -191,6 +191,9 @@ option(AX_UPDATE_BUILD_VERSION "Update build version" ON)
 option(AX_DISABLE_GLES2 "Whether disable GLES2 support" OFF)
 option(AX_CORE_PROFILE "Whether strip deprecated features" ON)
 
+set(AX_PROFILER_BACKEND "NONE" CACHE STRING "Profiling backend")
+set_property(CACHE AX_PROFILER_BACKEND PROPERTY STRINGS NONE TRACY)
+
 # default value for axmol extensions modules to Build
 # total supported extensions count: 13
 # extensions dependicies: COCOSTUDIO may depend on spine & dragonBones if they are present in buildset
@@ -570,6 +573,10 @@ if(_simdc_defines)
   endif()
 endif()
 
+# profiling configuration
+ax_apply_profiler_backend(${_AX_CORE_LIB} PUBLIC)
+message(STATUS "AX_PROFILER_BACKEND=${AX_PROFILER_BACKEND}")
+
 # 3rd libs
 add_subdirectory(${_AX_ROOT}/3rdparty ${ENGINE_BINARY_PATH}/3rdparty)
 target_link_libraries(${_AX_CORE_LIB} 3rdparty)
diff --git a/axmol/audio/AudioEngineImpl.cpp b/axmol/audio/AudioEngineImpl.cpp
@@ -32,6 +32,7 @@
 #include "axmol/base/Scheduler.h"
 #include "axmol/base/Utils.h"
 #include "axmol/base/WeakPtr.h"
+#include "axmol/base/Profiling.h"
 
 #if AX_TARGET_PLATFORM == AX_PLATFORM_IOS || AX_TARGET_PLATFORM == AX_PLATFORM_MAC
 #    import <AVFoundation/AVFoundation.h>
@@ -1005,6 +1006,8 @@ void AudioEngineImpl::setFinishCallback(AudioId audioID, const std::function<voi
 
 void AudioEngineImpl::update(float /*dt*/)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     std::lock_guard<std::recursive_mutex> lck(_threadMutex);
     _updatePlayers(false);
 }
diff --git a/axmol/base/Director.cpp b/axmol/base/Director.cpp
@@ -55,6 +55,7 @@ THE SOFTWARE.
 #include "axmol/base/FPSImages.h"
 #include "axmol/base/Scheduler.h"
 #include "axmol/base/Macros.h"
+#include "axmol/base/Profiling.h"
 #include "axmol/base/EventDispatcher.h"
 #include "axmol/base/CustomEvent.h"
 #include "axmol/base/Logging.h"
@@ -1372,6 +1373,8 @@ void Director::activate(SetIntervalReason reason)
 
     _axmol_thread_id = std::this_thread::get_id();
 
+    AX_PROFILER_THREAD_NAME("MainThread");
+
     Application::getInstance()->setAnimationInterval(_animationInterval);
 
     // fix issue #3509, skip one fps to avoid incorrect time calculation.
@@ -1443,6 +1446,8 @@ void Director::renderFrame()
     if (!_active) [[unlikely]]
         return;
 
+    AX_PROFILER_ZONE_SCOPED;
+
     const auto canRender = _renderer->beginFrame();
 
     // calculate "global" dt
@@ -1534,6 +1539,8 @@ void Director::renderFrame()
     }
 
     _poolManager->getCurrentPool()->clear();
+
+    AX_PROFILER_FRAME_MARK;
 }
 
 void Director::renderFrame(float dt)
diff --git a/axmol/base/EventDispatcher.cpp b/axmol/base/EventDispatcher.cpp
@@ -47,6 +47,7 @@
 #include "axmol/scene/Camera.h"
 #include "axmol/scene/Node.h"
 #include "axmol/2d/ProtectedNode.h"
+#include "axmol/base/Profiling.h"
 
 #define DUMP_LISTENER_ITEM_PRIORITY_INFO 0
 
@@ -946,6 +947,8 @@ void EventDispatcher::dispatchEventToListeners(EventListenerVector* listeners,
 
 void EventDispatcher::dispatchEvent(Event* event, bool forced)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     if (!_isEnabled && !forced)
         return;
 
diff --git a/axmol/base/JobSystem.cpp b/axmol/base/JobSystem.cpp
@@ -25,6 +25,7 @@
 
 #include "axmol/base/JobSystem.h"
 #include "axmol/base/Logging.h"
+#include "axmol/base/Profiling.h"
 #include "yasio/thread_name.hpp"
 
 #include <queue>
@@ -149,6 +150,7 @@ class JobExecutor
             workers.emplace_back([this, thread_data] {
                 thread_data->init();
                 yasio::set_thread_name(thread_data->name());
+                AX_PROFILER_THREAD_NAME(thread_data->name());
                 for (;;)
                 {
                     std::function<void(JobThreadData*)> task;
diff --git a/axmol/base/Profiling.h b/axmol/base/Profiling.h
@@ -146,3 +146,11 @@ extern bool kProfilerCategoryParticles;
 /// @}
 
 }  // namespace ax
+
+#if defined(AX_PROFILER_BACKEND_TRACY)
+#    include "axmol/base/ProfilingBackendTracy.h"
+#elif defined(AX_PROFILER_BACKEND_NONE)
+#    include "axmol/base/ProfilingBackendNoop.h"
+#else
+#    error "No valid profiling backend selected"
+#endif
diff --git a/axmol/base/ProfilingBackendNoop.h b/axmol/base/ProfilingBackendNoop.h
@@ -0,0 +1,36 @@
+/****************************************************************************
+Copyright (c) 2019-present Axmol Engine contributors (see AUTHORS.md).
+
+https://axmol.dev/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+****************************************************************************/
+
+#pragma once
+
+/**
+ * No-op profiling backend.
+ *
+ * Maps Axmol profiling macros to no-op implementations.
+ */
+
+#define AX_PROFILER_ZONE_SCOPED
+#define AX_PROFILER_ZONE_SCOPED_N(...)
+#define AX_PROFILER_FRAME_MARK
+#define AX_PROFILER_THREAD_NAME(...)
diff --git a/axmol/base/ProfilingBackendTracy.h b/axmol/base/ProfilingBackendTracy.h
@@ -0,0 +1,38 @@
+/****************************************************************************
+Copyright (c) 2019-present Axmol Engine contributors (see AUTHORS.md).
+
+https://axmol.dev/
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+****************************************************************************/
+
+#pragma once
+
+/**
+ * Tracy profiling backend.
+ *
+ * Maps Axmol profiling macros to the native Tracy API.
+ */
+
+#include <tracy/Tracy.hpp>
+
+#define AX_PROFILER_ZONE_SCOPED         ZoneScoped
+#define AX_PROFILER_ZONE_SCOPED_N(name) ZoneScopedN(name)
+#define AX_PROFILER_FRAME_MARK          FrameMark
+#define AX_PROFILER_THREAD_NAME(name)   tracy::SetThreadName(name)
diff --git a/axmol/base/Scheduler.cpp b/axmol/base/Scheduler.cpp
@@ -723,6 +723,8 @@ void Scheduler::resumeTargets(const std::set<void*>& targetsToResume)
 // main loop
 void Scheduler::update(float dt)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     // active waitlist
     if (!_waitList.empty())
         activeWaitList();
diff --git a/axmol/physics/2d/PhysicsWorld2D.cpp b/axmol/physics/2d/PhysicsWorld2D.cpp
@@ -43,6 +43,7 @@
 #    include "axmol/base/EventDispatcher.h"
 #    include "axmol/base/CustomEvent.h"
 #    include "axmol/base/JobSystem.h"
+#    include "axmol/base/Profiling.h"
 #    include "box2d/constants.h"
 
 namespace ax
@@ -502,6 +503,8 @@ void PhysicsWorld2D::setSubsteps(int steps)
 
 void PhysicsWorld2D::stepSimulation(float delta)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     // Skip simulation if step is too small
     if (delta < FLT_EPSILON)
         return;
diff --git a/axmol/physics/3d/PhysicsWorld3D.cpp b/axmol/physics/3d/PhysicsWorld3D.cpp
@@ -35,6 +35,7 @@
 #    include "axmol/physics/3d/Rigidbody3D.h"
 #    include "axmol/renderer/Renderer.h"
 #    include "axmol/scene/Scene.h"
+#    include "axmol/base/Profiling.h"
 
 #    include <Jolt/Core/Factory.h>
 #    include <Jolt/Core/IssueReporting.h>
@@ -354,6 +355,7 @@ void PhysicsWorld3D::debugDraw(Renderer* renderer)
 
 void PhysicsWorld3D::stepSimulation(float dt)
 {
+    AX_PROFILER_ZONE_SCOPED;
 
     for (auto* actor : _physicsActors)
         actor->preSimulate();
diff --git a/axmol/renderer/Renderer.cpp b/axmol/renderer/Renderer.cpp
@@ -49,6 +49,7 @@
 #include "axmol/rhi/axmol-rhi.h"
 #include "axmol/rhi/RenderTarget.h"
 #include "axmol/rhi/GraphicsCore.h"
+#include "axmol/base/Profiling.h"
 
 namespace ax
 {
@@ -406,6 +407,8 @@ void Renderer::doVisitRenderQueue(const std::vector<RenderCommand*>& renderComma
 
 void Renderer::render()
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     // TODO: setup camera or MVP
     _isRendering = true;
 
diff --git a/axmol/renderer/TextureCache.cpp b/axmol/renderer/TextureCache.cpp
@@ -42,6 +42,7 @@ THE SOFTWARE.
 #include "axmol/base/Utils.h"
 #include "axmol/base/NinePatchImageParser.h"
 #include "axmol/rhi/GraphicsCore.h"
+#include "axmol/base/Profiling.h"
 
 using namespace std;
 
@@ -463,6 +464,8 @@ Texture2D* TextureCache::addImage(std::string_view path, bool autoGenMipmaps)
 
 Texture2D* TextureCache::addImage(std::string_view path, PixelFormat renderFormat, bool autoGenMipmaps)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     Texture2D* texture = nullptr;
     Image* image       = nullptr;
     // Split up directory and filename
diff --git a/axmol/scene/Scene.cpp b/axmol/scene/Scene.cpp
@@ -37,6 +37,7 @@ THE SOFTWARE.
 #include "axmol/base/text_utils.h"
 #include "axmol/renderer/Renderer.h"
 #include "axmol/scene/SceneCompositor.h"
+#include "axmol/base/Profiling.h"
 
 #if defined(AX_ENABLE_PHYSICS_2D)
 #    include "axmol/physics/2d/PhysicsWorld2D.h"
@@ -211,6 +212,7 @@ void Scene::setDebugCamera(Camera* camera)
 
 void Scene::visit(Renderer* renderer, const Mat4& parentTransform, uint32_t parentFlags)
 {
+    AX_PROFILER_ZONE_SCOPED;
     Node::visit(renderer, parentTransform, parentFlags);
 }
 
@@ -287,6 +289,8 @@ void Scene::setFixedDeltaTime(float fixedStep)
 
 void Scene::tick(float deltaTime)
 {
+    AX_PROFILER_ZONE_SCOPED;
+
     if (_fixedUpdateEnabled)
     {
         // apply time scale and clamp to avoid huge dt spikes
diff --git a/cmake/Modules/AXBuildHelpers.cmake b/cmake/Modules/AXBuildHelpers.cmake
diff --git a/cmake/Modules/AXLinkHelpers.cmake b/cmake/Modules/AXLinkHelpers.cmake
diff --git a/templates/common/cmake/modules/AXGameEngineOptions.cmake b/templates/common/cmake/modules/AXGameEngineOptions.cmake

Original file line number	Diff line number	Diff line change
`@@ -392,6 +392,8 @@ ssize_t ActionManager::getNumberOfRunningActions() const`
`392`	`392`	`// main loop`
`393`	`393`	`void ActionManager::update(float dt)`
`394`	`394`	`{`
	`395`	`+ AX_PROFILER_ZONE_SCOPED;`
	`396`	`+`
`395`	`397`	`for (auto actionIt = _targets.begin(); actionIt != _targets.end();)`
`396`	`398`	`{`
`397`	`399`	`auto elt = &actionIt->second;`
Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,7 @@ THE SOFTWARE.`
`44`	`44`	`#include "axmol/renderer/Shaders.h"`
`45`	`45`	`#include "axmol/rhi/ProgramState.h"`
`46`	`46`	`#include "axmol/rhi/GraphicsCore.h"`
	`47`	`+#include "axmol/base/Profiling.h"`
`47`	`48`
`48`	`49`	`namespace ax`
`49`	`50`	`{`
`@@ -1069,6 +1070,8 @@ void Sprite::updateTransform()`
`1069`	`1070`	`// draw`
`1070`	`1071`	`void Sprite::draw(Renderer* renderer, const Mat4& transform, uint32_t flags)`
`1071`	`1072`	`{`
	`1073`	`+ AX_PROFILER_ZONE_SCOPED;`
	`1074`	`+`
`1072`	`1075`	`if (_texture == nullptr \|\| _texture->getRHITexture() == nullptr)`
`1073`	`1076`	`return;`
`1074`	`1077`
Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,7 @@`
`32`	`32`	`#include "axmol/base/Scheduler.h"`
`33`	`33`	`#include "axmol/base/Utils.h"`
`34`	`34`	`#include "axmol/base/WeakPtr.h"`
	`35`	`+#include "axmol/base/Profiling.h"`
`35`	`36`
`36`	`37`	`#if AX_TARGET_PLATFORM == AX_PLATFORM_IOS \|\| AX_TARGET_PLATFORM == AX_PLATFORM_MAC`
`37`	`38`	`# import <AVFoundation/AVFoundation.h>`
`@@ -1005,6 +1006,8 @@ void AudioEngineImpl::setFinishCallback(AudioId audioID, const std::function<voi`
`1005`	`1006`
`1006`	`1007`	`void AudioEngineImpl::update(float /dt/)`
`1007`	`1008`	`{`
	`1009`	`+ AX_PROFILER_ZONE_SCOPED;`
	`1010`	`+`
`1008`	`1011`	`std::lock_guard<std::recursive_mutex> lck(_threadMutex);`
`1009`	`1012`	`_updatePlayers(false);`
`1010`	`1013`	`}`