Shady/rst/Timing.rst

[Former user]

(Brief introductory blah about the nature of the problem—Shady animations tend to be somewhat robust because they're all func(t), but frame skips can still cause trouble)

System settings

    - Making the stimulus screen your "Main display" in Windows (unfortunately that puts the task bar on it, but we've found
      it necessary on multiple-screens-on-multiple-graphics-cards setup, to ensure that the correct display's frame rate is respected)

    - configuring the desired frame rate on your stimulus display (in Windows: advanced properties -> "Monitor" tab)

    - Graphics card-specific setting ("vertical sync" / "vertical blanking" / VBL)

Assessing timing performance fairly/veridically

    - no custom sizing or frame
    - FOREGROUND THE WINDOW (easy to forget in interactive mode)

Vertical sync issues

    the graphics-card-specific setting, as above

    `Shady.World.SetSwapInterval()` method (see caveats in its docstring: only works with accelerator backend, and only on some platforms/graphics cards)

    tearing test
        from outside python:  `python -m Shady tearing`  (reproduce some of the didactic material in the comments there, esp. what to look for)
        from inside python:    `Shady.TearingTest( world )`  # or something like that---verify prototype of `Shady.Utilities.TearingTest`


Then it's the programmer's own responsibility to ensure frame-to-frame computation isn't excesssive
    - on CPU (dynamics etc)
    - on GPU (too many stimuli, especially if they overlap heavily --> more than one screenful of pixels)

    Diagnostic tools:

        `Shady.FrameIntervalGauge <Shady.Utilities.FrameIntervalGauge>`
            requires numpy
            causes *some* frame-to-frame overhead itself, but much less than a text fps meter would in Shady
            what to look for

        `Shady.PlotTimings <Shady.Utilities.PlotTimings>`
            requires numpy, matplotlib
            maybe show screenshot with and without `world.debugTiming=True`

            from outside python:  `python -m Shady timings LOGFILENAME`

    Gotchas within Shady - significant image-generation work done on CPU, and data transferred CPU->GPU, both in violation of Shady's own usual principles:
        1. Shady.Text re-rendering (but only if there's an actual de-facto change in any .text.* properties)
        2. Shady.Video decoding (whenever there's a new frame)

        (you can reproduce/summarize some of the didactic material from `python -m Shady demo showcase`, where both of these gotchas are mentioned)

    ...and any other failures to ruthlessly optimize your own computations---refer the reader to `python -m Shady demo dots2` to
    see what a difference different strategies can make (and maybe summarize some of that material)

    Also note the impact of concurrent NON-Shady operations. See the note at the end of the :doc:`Concurrency` document
    about multi-threading in Python.

Anything else you can think of.

Note the way that python/Shady/rst/*.rst are numbered. Somewhere from 056 to 079 would seem to be the appropriate logical place in the sequence.