glSnoop.guide

@database glsnoop.guide
@width 72

@node Main "glSnoop"

    @{B}glSnoop User Guide v1.0@{UB}

    @{" What is glSnoop for and what it does             " link WhatisThat}
    @{" How to use                                       " link Usage}
    @{" Command-line parameters                          " link CommandLineParameters}
    @{" GUI mode                                         " link GUImode}
    @{" Tracing                                          " link Tracing}
    @{" Profiling                                        " link Profiling}
    @{" Filtering                                        " link Filtering}
    @{" Questions & Answers                              " link QuestionsAndAnswers}
    @{" Tips & Tricks                                    " link TipsAndTricks}
    @{" Author & Thanks                                  " link Authorthanks}

    Website:  https://github.com/capehill/glsnoop

@endnode

@node Whatisthat "What is glSnoop for and what it does"

   @{B}What is glSnoop for and what it does@{UB}

   glSnoop is an experimental graphics API tracing and profiling tool for AmigaOS4.
   It was born as an attempt to bring something like @{B}apitrace@{UB}, but written from scratch
   and AmigaOS4 specific.

   At the moment only ogles2.library and Warp3DNova.library are supported.

   glSnoop works by patching libraries via SetMethod() and wrapping the original functions
   with tracing and profiling mechanisms:

      OGLES2:

      glSnoop patches IExec GetInterface and DropInterface using SetMethod, in order to
      detect applications who ask for IOGLES2 interface. Then the interface-specific
      OGLES2 functions get also patched using SetMethod:
      https://github.com/capehill/glsnoop/blob/master/ogles2_module.c#L3064

      NOVA:

      W3DN_CreateContext is patched using SetMethod, then the function pointers in Nova
      context are simply replaced with wrapper functions:
      https://github.com/capehill/glsnoop/blob/master/warp3dnova_module.c#L3000

@endnode

@node Usage "How to use"

@{B}   How to use@{UB}

   glSnoop operates in two modes: Command-line one and GUI one.
   Command-line mode is the default mode, and GUI can be started with @{B}GUI@{UB} argument.
   The difference between command-line and GUI mode is that in GUI mode you can pause/stop tracing & profiling
   Both modes are described in their respective sections.

@endnode

@node CommandLineParameters "Command-line parameters"

@{B}   Command-line parameters@{UB}

      OGLES2/S,NOVA/S,GUI/S,PROFILE/S,STARTTIME/N,DURATION/N,FILTER/K

@{B}   OGLES2@{UB}

      Enable ogles2.library tracing and profiling

@{B}   NOVA@{UB}

      Enable Warp3DNova.library tracing and profiling

@{B}   GUI@{UB}

      Launch the graphical user interface

@{B}   PROFILE@{UB}

      Disable function tracing in serial logs.

      Profiling is also enabled by default when tracing is enabled, but for speed reasons one may want to disable tracing
      and keep only profiling to avoid massive output to serial (which usually slow things down, even with Sashimi).

      When tracing is disabled, performance is better and the slowest parts of application can be profiled.

      Profiling tables have the following columns:

         function: name of used function
         call count: how many times given function was called
         error: how many times function was flagging errors
         duration (ms): accumulated time in milliseconds taken by all the functions calls
         avg. call dur. (us): average call duration in microseconds. In other words "accumulated time / call count"
         % of xxxx ms: percentage of context usage, "100% * (this function duration / total duration of all functions)"
         % of CPU time: percentage of CPU time context was used. Example: if context is alive for 10 seconds, and
                                                  and this function consumed 2 seconds, then result would be 20%.

@{B}   STARTTIME@{UB}

     Delay profiling for X seconds after process start (context creation). It may help to avoid the recording of
     eventually uninteresting initialization stuff or library internal "warm-up" phases.

@{B}   DURATION@{UB}

     Limit tracing/profiling to Y seconds. This could help to produce better comparable logs.

@{B}   FILTER@{UB}

      FILTER filename: define a subset of patched functions


   By default glSnoop is running with OpenGL ES 2.0 and Warp3D Nova tracing enabled, while GUI and function filtering are disabled.

@endnode

@node GUImode "GUI mode"

@{B}   GUI mode@{UB}

   N/A

@endnode

@node Tracing "Tracing"

   @{B}Tracing@{UB}

   glSnoop supports logging of:

   ogles2.library 3.3: all (a)gl* functions
   Warp3DNova.library 54.16: all context-related functions

@endnode

@node Profiling "Profiling"

   @{B}Profiling@{UB}

   glSnoop records the call count and duration of all known OpenGL ES 2.0 and Warp3D Nova functions.
   Profiling summaries are logged when contexts are being destroyed.

   Time spent inside OpenGL ES 2.0 functions includes also time spent inside Warp3D Nova functions.

@endnode


@node Filtering "Filtering"

   @{B}Filtering@{UB}

   Filtering can be used to patch only a subset of OGLES2/NOVA functions.
   This produces less logs and is faster. Filtering impacts also profiling, because non-patched functions cannot be profiled either.

@endnode



@node QuestionsAndAnswers "Questions & Answers"

   @{B}Questions & Answers@{UB}

   N/A

@endnode


@node TipsAndTricks "Tips & Tricks"

   @{B}Tips & Tricks@{UB}

   @{B}---@{UB}

   glSnoop uses serial port for logging. To redirect logs to a file (for speed), one may use the Sashimi tool:

   run >NIL: Sashimi > RAM:MyLogFile.txt

   Download Sashimi: @{B}http://os4depot.net/index.php?function=showfile&file=development/debug/sashimi.lha@{UB}

   @{B}---@{UB}

   To create more comparable and cleaner logs (free of initialisation and warm-up calls), one may use STARTTIME
   and DURATION command-line parameters. For example:

   work:> glSnoop PROFILE STARTTIME 5 DURATION 10

   Meaning, profile only, initialize counters 5 seconds after context creation and profile for 10 seconds.

   @{B}---@{UB}

   Disable tracing always when profiling to get the best results. In other words, use PROFILE switch when
   function call parameters are not under investigation.

@endnode

@node AuthorThanks "Author & Thanks"

@{B}   Author:@{UB}

     Juha "Capehill" Niemimaki

@{B}   Thanks to:@{UB}

     kas1e for ideas, testing and AmigaGuide document
     Mason for icons
     samo79 for ideas
     Hans for ideas
     Jabirulo for ideas
     Daniel for ideas

@endnode