BGE: scene.pre_draw_setup[] callback

This callback allows the user to change the camera data right before the
rendering calculations.

scene.pre_draw[] is not enough here, because if you want to change the
camera matrices (projection/modelview) the culling test is done before
that (after pre_draw_setup[] though).

Reviewers: moguri, campbellbarton

Differential Revision: https://developer.blender.org/D1251

Python sample code using this. The sample scene would need a default
camera (not used for rendering), a dummy camera ('Camera.VR'), and two
cameras ('Camera.Left', 'Camera.Right') that will be used for the actual
rendering.

```
import bge

def callback():
    scene = bge.logic.getCurrentScene()
    objects = scene.objects

    vr_camera = objects.get('Camera.VR')

    if bge.render.getStereoEye() ==  bge.render.LEFT_EYE:
        camera = objects.get('Camera.Left')
    else:
        camera = objects.get('Camera.Right')

    vr_camera.worldOrientation = camera.worldOrientation
    vr_camera.worldPosition =  camera.worldPosition

def init():
    scene = bge.logic.getCurrentScene()
    main_camera = scene.active_camera
    main_camera.useViewport = True

   scene.pre_draw_setup.append(callback)

    objects = scene.objects
    vr_camera = objects.get('Camera.VR')
    vr_camera.useViewport = True
    vr_camera.setViewport(
            0,
            0,
            bge.render.getWindowWidth(),
            bge.render.getWindowHeight() )
```

1 files changed, 6 insertions, 0 deletions

diff --git a/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst b/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst
index a6135054058..f4846cd9265 100644
--- a/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst
+++ b/doc/python_api/rst/bge_types/bge.types.KX_Scene.rst
@@ -125,6 +125,12 @@ base class --- :class:`PyObjectPlus`
 
       :type: list
 
+   .. attribute:: pre_draw_setup
+
+      A list of callables to be run before the drawing setup (i.e., before the model view and projection matrices are computed).
+
+      :type: list
+
    .. attribute:: gravity
 
       The scene gravity using the world x, y and z axis.