--------------------
Performance in PyGfx
--------------------

PyGfx has numerous options to balance performance with quality. We try to select
defaults that are sensible for the majority of use-cases, probably leaning a bit towards quality.
But each use-case is different.

In this document we give an overview of what knobs you can turn to increase performance (or quality).


Pixel-scale, pixel-ratio, and upsampling
----------------------------------------

The value of ``render.pixel_scale`` is 1 for hiDPI screens and 2 otherwise. A value larger than one means that SSAA (super-sample anti-aliasing) is used, which
costs affects memory usage and performance. You can set ``renderer.pixel_scale=1`` to disable SSAA.

You can also set ``renderer.pixel_scale`` or ``renderer.pixel_ratio`` to values smaller than one, so the image is rendered to
a smaller internal texture, which is then upsampled to the screen resolution.

When you're setting ``pixel_scale`` to values ``>1``, keep in mind that the pixel filter (see ``renderer.pixel_filter``) is optimized for ``pixel_scale==2``.


Other anti-aliasing
-------------------

The ``rendere.ppaa`` controls the PPAA (post-procesing anti-aliasing). It defaults to "ddaa" to improve the visual result of the rendered image.
You can set ``renderer.ppaa='none'`` to disable it.

The ``material.aa`` available on text, lines, and points should not significantly affect performance. This means that, if your scene
does not contain intersecting objects, you can turn it on, turn off the PPAA or SSAA, and still have comparable quality.


Opaque objects
--------------

The default ``alpha_mode='auto'`` handles both opaque and transpareny objects. If you know that your object is opaque (i.e. solid), set ``material.alpha_mode='solid'``.
The renderer sorts opaque objects front-to-back to avoid overdraw, which improves performance.


Picking and clipping
--------------------

To enable picking on an object, you must set ``material.pick_write=True``.
Although it should not affect performance a lot, it may become significant if
applied to a lot of objects. So keep in mind to only turn it on when needed.

Same for ``material.clipping_planes``.


Shadows and lights
------------------

The shader iterates over each light to do lighting calculations. A handfull of lights should be fine, but don't go crazy.
The renderer must create a shadow map for every light in the scene. Take that in mind when adding lights and setting ``material.cast_shadow``.


Canvas update-mode
------------------

The canvas ``update_mode`` that can be provided whan a canvas is created, and set with ``canvas.set_update_mode()`` can be set to "manual", "ondemand", "continuous", and "fastest".
The ondemand mode is intended to only draw when there is a change, saving your laptop battery. The continuous mode keeps drawing, at a preset maximum FPS. If you wanna go as fast
as your system can, use "fastest". It may then still stick to your system's vsync, which can be turned off when creating a canvas (``RenderCanvas(..., vsync=False)``).


Data updates
------------

Whenever the data of a texture or buffer is changed, it needs to be uploaded to the GPU before the next draw.
If this is a lot of data (large data, or many small buffers/textures) this can affect performance.


Object transforms
-----------------

The logic behind object transform has been optimied *a lot*, but it's all Python
and Numpy. So in use-cases with many changes to object transformations in deep
nested scene graphs can affect performance.


Events
------

Doing a lot of work on certain events can affect performance. Especially events like "pointer_move".
Some seemingly hamless things, like using ``print()`` on every draw, are more expensive than you might think.


Probably more
-------------

This document is a work in progress. Let us know if we forgot something!