update docs & comments

project/thirdparty/tracy-0.11.1/README.md

@@ -1,38 +1,71 @@
-## Some notes about the integration
 
-At the moment there is support for Zonemarkers with Haxe's sourcemapping, Messages & Plots. What is missing is Memory tracking, though @Aidan63 has the large object heap + stacktraces working and is testing an idea on how to make all allocations visible.
+## How to use 
+
+To activate the tracy integration, compile your app with:
+
+```
+-D HXCPP_TRACY
+-D HXCPP_TELEMETRY
+-D HXCPP_STACK_TRACE
+-D HXCPP_STACK_LINE
+```
+
+and use the following call in your mainloop:
+
+```
+cpp.vm.tracy.TracyProfiler.frameMark();
+```
+
+Then start either Tracy's UI-App or cmdline server listening on localhost and start your hxcpp-made binary.
+
+
+## Some notes about the integration
 
 ### Haxe-Code
-We integrate Tracy into hxcpp as a Telemetry option and offer a set of global functions to set zones and other tracy functionality
+We integrate Tracy into hxcpp as a Telemetry option and offer a set of static functions to set zones and other tracy functionality.
 
-There are however native parts of hxcpp that wont be visible by default in Tracy (bc there are no ZoneScopes).
+There are however native parts of hxcpp that wont be visible by default in Tracy (bc there are no ZoneScopes). Note that these will be visible if you use the option to capture callstacks.
 > Note: There is a exception in the GC-Code, so it becomes visible for us.
 
 ### externs
-The same is true about externs you might be using in your project. If you want to make these visible, you need to add Tracy's C-Macros yourself in the extern's c/cpp-code. You should be able to include Tracy's client headers. 
+The same is true about externs you might be using in your project. If you want to make these visible, you need to `@:include('hx/TelemetryTracy.h')` and you gain access to Tracy's C-Macros that you can use in your extern's c/cpp-code. Please refer to the official Tracy documentation: https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf
 
 ### externs with static/dynamic libs
 Another special case are static or dynamic libs your externs might be using. For these you will have to make more changes that are beyond the scope of this doc here, please refer to Tracy's official documentation over here: https://github.com/wolfpld/tracy/releases/latest/download/tracy.pdf
 
+## Optional Features
 
-# How to use 
+### Memory Profiling
 
-To activate the tracy integration, compile your app with:
+The following define adds tracking (de-)allocations of hxcpp's small & large object heap.
 
 ```
--D HXCPP_TRACY
--D HXCPP_TELEMETRY
--D HXCPP_STACK_TRACE
--D HXCPP_STACK_LINE
+-D HXCPP_TRACY_MEMORY
 ```
 
-and use the following call in your mainloop:
+### Capture Callstacks
+
+By default we only track zones. If you wanna inspect the actual callstack per zone, you should use the following define:
 
 ```
-untyped __global__.__hxcpp_tracy_framemark();
+-D HXCPP_TRACY_INCLUDE_CALLSTACKS
 ```
 
-> Note: Alternatively you can use this simple class in your project: https://gist.github.com/dazKind/b36475c0846491aefdfb12c5f831daba
+> Note: This will inflate the telemetry data A LOT and cost more performance. Please be aware. 
 
 
-Then start Tracy listening on localhost and start your hxcpp-made exe.
+### On Demand Profiling
+
+By default this integration will start sampling & collecting telemetry with the start of your application. You can change this behavior by the following define and your app will only generate telemetry if the Tracy Profiler app is open and reachable. 
+
+```
+-D HXCPP_TRACY_ON_DEMAND
+```
+
+### Short-lived Application Support
+
+In cases where you dont have a mainloop or a very short-lived application you can use the following define to let your application stay around to complete sending telemetry data it has collected.  
+
+```
+-D HXCPP_TRACY_NO_EXIT
+```

toolchain/common-defines.xml

@@ -38,7 +38,7 @@
  <flag value='-DHXCPP_GC_DEBUG_LEVEL=${HXCPP_GC_DEBUG_LEVEL}' if="HXCPP_GC_DEBUG_LEVEL" tag="gc" />
  <flag value='-DHXCPP_WINXP_COMPAT' if="HXCPP_WINXP_COMPAT" tag="haxe"/>
 
- <!-- fwd these defines into haxe target so we check for it in telemetry -->
+ <!-- fwd these defines into haxe target so we can check for it in telemetry -->
  <flag value="-DHXCPP_GC_MOVING" if="HXCPP_GC_MOVING" tag="haxe" />
  <flag value="-DHXCPP_GC_GENERATIONAL" if="HXCPP_GC_GENERATIONAL" tag="haxe" />