Scarfski/tracy
1
0
Fork 0
mirror of https://github.com/wolfpld/tracy.git synced 2026-10-23 01:00:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add user manual links to achievements.

Browse Source
This commit is contained in:
Bartosz Taudul
2026-10-11 19:54:57 +02:00
parent ef18ae1b7a
commit 70d00ab9f2
15 changed files with 27 additions and 27 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
profiler/src/achievements/100Million.md
View File

@@ -4,11 +4,11 @@ Tracy can handle a lot of data. How about 100 million zones in a single trace? A
Capturing a long-running profile trace is easy. Need to profile an hour of your program execution? You can do it.
Note that it doesn't make much sense to instrument every little function you might have. The cost of the instrumentation itself will be higher than the cost of the function in such a case.
Note that it doesn't make much sense to instrument every little function you might have. The cost of the instrumentation itself will be higher than the cost of the function in such a case (see [Performance impact](#perfimpact)).
> [!TIP]
> **Tip**
>
> Keep in mind that the more zones you have, the more memory and CPU time the profiler will use. Be careful not to run out of memory.
> Keep in mind that the more zones you have, the more memory and CPU time the profiler will use (see [Memory usage](#memoryusage)). Be careful not to run out of memory.
>
> To capture 100 million zones, you will need approximately 4 GB of RAM.

4
profiler/src/achievements/AnnotateZones.md
View File

@@ -1,6 +1,6 @@
# Annotate zones
Zones can carry more than just timing. Use the `ZoneText(txt, size)` macro to attach a contextual note to the current zone (the name of the file being opened, the id of the entity being processed) or `ZoneValue(value)` to report a number without paying the cost of converting it to a string. For printf-style formatting, use `ZoneTextF(fmt, ...)`.
Zones can carry more than just timing. Use the [`ZoneText(txt, size)`](#markingzones) macro to attach a contextual note to the current zone (the name of the file being opened, the id of the entity being processed) or `ZoneValue(value)` to report a number without paying the cost of converting it to a string. For printf-style formatting, use `ZoneTextF(fmt, ...)`.
```c++
void LoadTexture( const std::string& path )
@@ -11,7 +11,7 @@ void LoadTexture( const std::string& path )
}
```
The annotation shows up wherever the zone is displayed: in the tooltip when you hover over it on the timeline, and in the Zone info window. A `ZoneValue` is reported as a text note of the `1024 [0x400]` style. If you want to replace the zone's displayed name instead, use `ZoneName(txt, size)`, but note that such a per-call name is not used when zones are grouped for statistics.
The annotation shows up wherever the zone is displayed: in the tooltip when you hover over it on the timeline, and in the [Zone info window](#zoneinfo). A `ZoneValue` is reported as a text note of the `1024 [0x400]` style. If you want to replace the zone's displayed name instead, use `ZoneName(txt, size)`, but note that such a per-call name is not used when zones are grouped for statistics.
Zones can be colored, too: `ZoneScopedC(color)` sets a constant color at compile time, while `ZoneColor(color)` overrides it per call.

4
profiler/src/achievements/AppInfo.md
View File

@@ -1,6 +1,6 @@
# Describe your application
When traces pile up, it helps to know which build produced them. Use the `TracyAppInfo(txt, size)` macro to attach information about your application, for example, the source repository revision, the build configuration, or the environment (dev/prod) it is running in:
When traces pile up, it helps to know which build produced them. Use the [`TracyAppInfo(txt, size)`](#appinfo) macro to attach information about your application, for example, the source repository revision, the build configuration, or the environment (dev/prod) it is running in:
```c++
const char* info = "revision: a1b2c3d, config: Release";
@@ -9,4 +9,4 @@ TracyAppInfo( info, strlen( info ) );
Call it as your application starts up. You can report several facts by calling it multiple times. Each call adds its own line to the application info. The text becomes part of the trace, so it is available whenever you load it later.
Click the * Info* button on the top bar to open the Trace information window and find your description under the `Application info:` label. Try it out!
Click the * Info* button on the top bar to open the [Trace information window](#traceinfo) and find your description under the `Application info:` label. Try it out!

4
profiler/src/achievements/ConnectToClient.md
View File

@@ -2,8 +2,8 @@
Let's start our adventure by instrumenting your application and connecting it to the profiler. Here's what you need to do:
1. Integrate Tracy Profiler into your application. This can be done using CMake, Meson, or simply by adding the source files to your project.
1. Integrate Tracy Profiler into your application (see [Initial client setup](#initialsetup)). This can be done using CMake, Meson, or simply by adding the source files to your project.
2. Make sure that `TracyClient.cpp` is added to your build, or that the Tracy library is linked.
3. Define `TRACY_ENABLE` in your build configuration for the whole application. Do not define it in a single source file because it won't work.
4. Start your application, and * Connect* to it with the profiler.
4. Start your application, and * Connect* to it with the profiler (see [Interactive profiling](#interactiveprofiling)).

4
profiler/src/achievements/FindZone.md
View File

@@ -1,10 +1,10 @@
# Find some zones
To find a zone, open the Find zone window with the * Find* button on the top bar and type in the zone name — in most cases the function name in the code.
To find a zone, open the [Find zone window](#findzone) with the * Find* button on the top bar and type in the zone name — in most cases the function name in the code.
1. If several zones share the name, a list of matches is shown. Select the one you're looking for.
2. The window shows a histogram of execution times, along with statistics such as total time, mean, and median.
3. Drag a range on the histogram to filter the zone list below to just the entries within that range.
4. Pick one of the zone groupings to highlight that group's time on the histogram.
You can also jump straight to a zone from the Statistics window: clicking an entry there opens Find zone as if you had searched for it.
You can also jump straight to a zone from the [Statistics window](#statistics): clicking an entry there opens Find zone as if you had searched for it.

6
profiler/src/achievements/FrameImages.md
View File

@@ -1,11 +1,11 @@
# A picture is worth a thousand words
Tracy allows you to add context to each frame by attaching a screenshot. You can do this with the `FrameImage` macro.
Tracy allows you to add context to each frame by attaching a screenshot. You can do this with the [`FrameImage`](#frameimages) macro.
You will have to do the screen capture and resizing yourself, which can be a bit complicated. The manual provides sample code that shows how to do this in a performant way.
You will have to do the screen capture and resizing yourself, which can be a bit complicated. The manual provides [sample code](#screenshotcode) that shows how to do this in a performant way.
The frame images are displayed in the context of a frame, for example, when you hover over the frame in the timeline or in the frame graph at the top of the screen.
You can even view a recording of what your application was doing by clicking the * Tools* icon and then selecting the * Playback* option. Try it out!
You can even view a recording of what your application was doing by clicking the * Tools* icon and then selecting the * Playback* option ([Frame image playback window](#playback)). Try it out!
The `FrameImage` macro is a great way to see what happened in your application at a particular time. Maybe you have a performance problem that only occurs when a certain object is on the screen?

2
profiler/src/achievements/GhostZones.md
View File

@@ -1,6 +1,6 @@
# Ghost zones
Automated sampling gives Tracy a rough picture of what your application was doing, even in places where you placed no zones. That data can be displayed as ghost zones, approximate spans of execution reconstructed from the samples, marked with the * ghost* icon so they are never mistaken for real instrumentation.
[Automated sampling](#sampling) gives Tracy a rough picture of what your application was doing, even in places where you placed no zones. That data can be displayed as [ghost zones](#zoneslocksplots), approximate spans of execution reconstructed from the samples, marked with the * ghost* icon so they are never mistaken for real instrumentation.
On any thread track that has both instrumented zones and sampling data, a * ghost* icon appears next to the thread label. Click it to switch that track between instrumented and ghost display, the same time range, viewed two ways. Threads that contain no instrumented zones display ghost zones automatically.

2
profiler/src/achievements/GlobalSettings.md
View File

@@ -1,5 +1,5 @@
# Global settings
Tracy has a variety of settings that can be adjusted to suit your needs. These settings can be found by clicking on the * Wrench* icon on the welcome screen. This will open the About window, where you can expand the * Global settings* menu.
Tracy has a variety of settings that can be adjusted to suit your needs. These settings can be found by clicking on the * Wrench* icon on the welcome screen. This will open the [About window](#aboutwindow), where you can expand the * Global settings* menu.
The settings are saved between sessions, so you only need to set them once.

4
profiler/src/achievements/InstrumentFrames.md
View File

@@ -2,7 +2,7 @@
In addition to instrumenting functions, you can also instrument frames. This allows you to see how much time is spent in each frame of your application.
To instrument frames, you need to add the `FrameMark` macro at the end of each frame. This can be done in the main loop of your application, or in a separate function that is called at the end of each frame.
To instrument frames, you need to add the [`FrameMark`](#markingframes) macro at the end of each frame. This can be done in the main loop of your application, or in a separate function that is called at the end of each frame.
```c++
#include "Tracy.hpp"
@@ -17,6 +17,6 @@ void Render()
When you profile your application, you will see a new frame appear on the timeline each time the `FrameMark` macro is called. This allows you to see how much time is spent in each frame and how many frames are rendered per second.
The `FrameMark` macro is a great way to see at a glance how your application is performing over time. Maybe there are some performance problems that only appear after a few minutes of running the application? A frame graph is drawn at the top of the profiler window where you can see the timing of all frames.
The `FrameMark` macro is a great way to see at a glance how your application is performing over time. Maybe there are some performance problems that only appear after a few minutes of running the application? A [frame graph](#frametimegraph) is drawn at the top of the profiler window where you can see the timing of all frames.
Note that some applications do not have a frame-based structure, and in such cases, frame instrumentation may not be useful. That's OK.

6
profiler/src/achievements/InstrumentationIntro.md
View File

@@ -2,7 +2,7 @@
Instrumentation is a powerful feature that allows you to see the exact runtime of each call to the selected set of functions. The downside is that it takes a bit of manual work to get it set up.
To get started, open a source file and include the `Tracy.hpp` header. This will give you access to a variety of macros provided by Tracy. Next, add the `ZoneScoped` macro to the beginning of one of your functions, like this:
To get started, open a source file and include the `Tracy.hpp` header. This will give you access to a variety of macros provided by Tracy. Next, add the [`ZoneScoped`](#markingzones) macro to the beginning of one of your functions, like this:
```c++
#include "Tracy.hpp"
@@ -19,6 +19,6 @@ Now, when you profile your application, you will see a new zone appear on the ti
> [!NOTE]
> **Note**
>
> The `ZoneScoped` macro is just one of the many macros provided by Tracy. See the manual for more information.
> The `ZoneScoped` macro is just one of the many macros provided by Tracy. See the [Client markup](#client) chapter of the manual for more information.
The above description applies to C++ code, but things are done similarly in other programming languages. Refer to the documentation for your language for more information.
The above description applies to C++ code, but things are done similarly in other programming languages. Tracy ships out-of-the-box Lua bindings, and third-party bindings exist for many other languages. Refer to the [C API](#capi), [Python API](#pythonapi), or [Fortran API](#fortranapi) documentation, or the documentation for your language, for more information.

2
profiler/src/achievements/InstrumentationStatistics.md
View File

@@ -2,4 +2,4 @@
Once you have instrumented your application, you can view the statistics for each zone in the timeline. This allows you to see how much time is spent in each zone and how many times it is called.
To view the statistics, click on the * Statistics* button on the top bar. This opens the Statistics window, which lists every zone name in the trace.
To view the statistics, click on the * Statistics* button on the top bar. This opens the [Statistics window](#statistics), which lists every zone name in the trace.

2
profiler/src/achievements/LoadTrace.md
View File

@@ -1,5 +1,5 @@
# Load a trace
You can open a previously saved trace file (or one received from a friend) with the * Open saved trace* button on the welcome screen.
You can open a previously saved trace file (or one received from a friend) with the * Open saved trace* button on the welcome screen. After the trace is loaded, the [Analyzing captured data](#analyzingdata) chapter describes what you can do with it.
Trace files are version-specific: a trace from a newer Tracy version will fail to open, but traces from older versions load fine — only very old traces are rejected.

6
profiler/src/achievements/SamplingIntro.md
View File

@@ -1,12 +1,12 @@
# Sampling program execution
Sampling program execution is a great way to find out where the hot spots are in your program. It can be used to find out which functions take the most time, or which lines of code are executed the most often.
[Sampling program execution](#sampling) is a great way to find out where the hot spots are in your program. It can be used to find out which functions take the most time, or which lines of code are executed the most often.
While instrumentation requires changes to your code, sampling does not. However, because of the way it works, the results are coarser and it's not possible to know when functions are called or when they return.
Sampling is automatic on Linux. On Windows, you must run the profiled application as an administrator for it to work.
Sampling is automatic on Linux. On Windows, you must [run the profiled application as an administrator](#privilegeelevation) for it to work.
> [!WARNING]
> **Warning**
>
> Depending on your system configuration, some additional steps may be required. Please refer to the user manual for more information.
> Depending on your system configuration, some additional steps may be required. Please refer to the [Automated data collection](#automated) chapter for more information.

2
profiler/src/achievements/SaveTrace.md
View File

@@ -1,6 +1,6 @@
# Save a trace
Now that you have traced your application (or are in the process of doing so), you can save it to disk for future reference. You can do this by clicking on the * Connection* icon in the top left corner of the screen and then clicking on the * Save trace…* button.
Now that you have traced your application (or are in the process of doing so), you can save it to disk for future reference. You can do this by clicking on the * Connection* icon in the top left corner of the screen and then clicking on the * Save trace…* button (see [Connection information pop-up](#connectionpopup)).
Keeping old traces on hand can be beneficial, as you can compare the performance of your optimizations with what you had before.

2
profiler/src/achievements/Sections.md
View File

@@ -1,6 +1,6 @@
# Mark sections
Zones are bound to the scope of a function or a block, but your program's big-picture phases are not. For those, use sections: `TracySectionEnter( "Loading level %d", level )` marks the start and returns an identifier you store, and `TracySectionLeave( id )` marks the end, even when the two calls sit in completely different places. Every section is tracked independently, so sections may overlap, nest, or leave gaps: a main menu section, one section per level, and so on.
Zones are bound to the scope of a function or a block, but your program's big-picture phases are not. For those, use [sections](#markingsections): `TracySectionEnter( "Loading level %d", level )` marks the start and returns an identifier you store, and `TracySectionLeave( id )` marks the end, even when the two calls sit in completely different places. Every section is tracked independently, so sections may overlap, nest, or leave gaps: a main menu section, one section per level, and so on.
Sections can be organized into categories. `TracySectionSetup( category, "Game levels" )` gives a category a name, and `TracySectionEnterCategory( category, ... )` starts a section inside it. Sections started with plain `TracySectionEnter` end up in category 0. Categories let you filter out the noise later. For example, when you care about level progression, you can hide the inventory-screen sections instead of sifting through them.