Search Unity

Profiler.BeginSample needs some documentation love

Discussion in 'Documentation' started by Lost-in-the-Garden, Feb 23, 2017.

  1. Lost-in-the-Garden

    Lost-in-the-Garden

    Joined:
    Nov 18, 2015
    Posts:
    176
    We just dived into profiler samples and noticed that the docs for https://docs.unity3d.com/ScriptReference/Profiling.Profiler.BeginSample.html are a bit scarce.

    Questions I had (some of them already answered through trial/error)
    - Can I nest/stack multiple BeginSample calls?
    Code (CSharp):
    1. Profiler.BeginSample("scope A");
    2. foo();
    3. Profiler.BeginSample("sub scope B");
    4. bar();
    5. Profiler.EndSample();
    6. Profiler.EndSample();
    - It only mentions that it will be conditionally compiled out in release builds. Under what condition I ask? It would be cool to know the #define so that I can also run it in the editor without it. Since the intention is to leave the profiler calls in there, I don't want to loose too much performance when running in the editor.
     
    Lost-in-the-Garden, Feb 23, 2017
    #1
    TheSecretGordon likes this.

  2. MartinTilo

    MartinTilo

    Unity Technologies

    Joined:
    Aug 16, 2017
    Posts:
    2,456
    Yes

    #if DEVELOPMENT_BUILD
    But to be more precise, the call to Profiler.BeginSample itself won't be compiled out by the conditional. That's not possible since it sits in UnityEngine.dll. The call does however go to an empty method so there's a good chance that the compiler will optimize it out or that it at least carries a negligible overhead.

    However, calling Profiler.BeginSample is not as performant as e.g. CustomSampler.Begin or ProfilerMarker.Begin, since those two only send the name string on creation and after that only have an ID int that they send to the Profiler on any Begin and End call.

    Speaking of ProfilerMarker and Conditionals, we're preparing to make ProfilerMarker be an actual Conditionally compiled out call, by putting it into a package.


    If you use the CustomSampler or ProfilerMarker APIs the overhead should usually be not enough to matter, even in the editor. Sure, if you have a loop with 10000 iterations and begin end calls in each of them and only some math functions within, there is an overhead for measuring this that is relatively large compared to what you are profiling, but then you might want to reconsider what you are instrumenting. (And it still won't be large enough to be really noticable.)

    Thanks for the feedback on the documentation though. I'll look into clarifying it a bit.
     
    MartinTilo, Apr 25, 2020
    #2