Performance Tuning

Object Creation

• The Ray Handler is a heavyweight object. It contains many float arrays and couple FBO's when OpenGL es 2.0 is available. Ray Handler can be safely used throughout the lifetime of the application. Ray Handler must be disposed of when it is destroyed.
• Lights are moderate weight objects. Each light contains two mesh and if possible try to reuse these lights. Just set light to disabled if you know you will need another light of that type soon. Remove lights if you don't need them anymore or there is a large time window between them. Note that setActive(false) does not set the body reference to null.

Performance Tips

• Tips are marked with (CPU | GPU | MEMORY) depending on which part of the system the tip might help.
• Disabled lights have no performance overhead. Disabled lights are stored in a separate list. (CPU & GPU).
• Disable shadows if game is running on platform with GLES 1.0 and where render target do not have alpha channel. Usually this means Android with gles1.0. This may be done automatically in the library, but don't count on it! (GPU).
• Static flag makes light very cheap. You can even use static light for objects that move, but they rarely do. Static lights can be attached to bodies, but they do not follow body movement after the initial attach call. Every time you call a method that changes the state of a static light, it has to be updated. Static lights are a bad choice if the light is updated every frame. *(CPU)
• Xray flag prevents all raycasting for the light. This reduces the cpu load by about 80%. Xrays are optimal for small objects and usually dynamic light looks better/smoother when combined with xray pointlight. Use this flag whenever you don't need dynamic behavior. (CPU).
• Setting FBO size to small really makes a big difference with performance. First, it helps with light drawing because it uses less fillrate. Second, it helps with blur. A blur pass uses 5+5 dynamic texture fetch. With 800x480 screen: using original screen size as fbo size and three blur passes would need over 10 million texture lookups. But using box2dLights default settings of 200x120 (a quarter of the screen size) and one blur pass uses only 240 000 texture lookups but gives a smoother look. (GPU & MEMORY).
• Blur passes are heavy, try smaller fbo combined with more passes if really blurred lights are needed. Idea for blur algorithm can be found here https://www.rastergrid.com/blog/2010/09/efficient-gaussian-blur-with-linear-sampling/ (GPU).
• For dynamic lights, use only the amount of rays that are absolutely necessary. Usually the best result is somewhere between 5 and 128. For something really accurate and visible you might need more, but be careful. For each ray box2dLights have to use 1 raycast and 1 vertex + 2 for soft light.(CPU & GPU & MEMORY)* *.
• Light distance makes light a bit heavier. Raycast need to travel bigger distance and more pixels need to be drawn. For bigger light try to add color alpha channel first and maybe add some white color. If that does not help try using different fallof scheme(Still WIP).(CPU & GPU).
• Enable culling. Culling is a very light process, but safe for all raycast calculations and drawing. Lights are culled automatically if they are so much off screen that even light tips would never occur on screen. Culled light is still not free, so if you know something is behind camera really long time maybe that could be disabled.(CPU & GPU).
• Be reasonable with soft light distance and turn off softness that is not needed.(CPU & GPU).
• Only create rayHandlers with maxNumberRays that are needed (MEMORY).
• If physics are updated less often than game is rendered, ray handler update can be skipped if physic was not skipped between frames. If physics are updated more often than game is rendered then calling updateAndRender is best choice.(CPU).
• If not, individual lights are rendered blurry and light map blitting is skipped. So cull/disable lights that are not visible (GPU)