bge.render.getStereoEye() and bge.types.LEFT_EYE/RIGHT_EYE

This function allows the user to run specific code for each of the
rendered stereoscopic eyes in the Game Engine.

The initial use case is to set the camera projection matrix in
a scene.pre_draw callback function for each eye, to be used in VR
(Virtual Reality) installations.

Reviewed by Mitchell Stokes and Campbell Barton, thank you guys.

Sample Test Python Script:
"""
import bge
import bgl
import blf

def init():
    """init function - runs once"""
    scene = bge.logic.getCurrentScene()
    scene.post_draw.append(write)

def write():
    """write on screen - depending on the eye"""
    width = bge.render.getWindowWidth()
    height = bge.render.getWindowHeight()

    # OpenGL setup
    bgl.glMatrixMode(bgl.GL_PROJECTION)
    bgl.glLoadIdentity()
    bgl.gluOrtho2D(0, width, 0, height)
    bgl.glMatrixMode(bgl.GL_MODELVIEW)
    bgl.glLoadIdentity()

    eye = bge.render.getStereoEye()

    if eye == bge.render.LEFT_EYE:
        blf.position(0, (width * 0.2), (height * 0.3), 0)
        blf.size(0, 40, 72)
        blf.draw(0, "Left")

    else: # bge.render.RIGHT_EYE:
        blf.position(0, (width * 0.7), (height * 0.3), 0)
        blf.size(0, 40, 72)
        blf.draw(0, "Right")
"""

source/gameengine/Ketsji/KX_PythonInit.cpp

@@ -1006,6 +1006,21 @@ static PyObject *gPyGetFocalLength(PyObject *, PyObject *, PyObject *)
 	Py_RETURN_NONE;
 }
 
+static PyObject *gPyGetStereoEye(PyObject *, PyObject *, PyObject *)
+{
+	int flag = RAS_IRasterizer::RAS_STEREO_LEFTEYE;
+
+	if (!gp_Rasterizer) {
+		PyErr_SetString(PyExc_RuntimeError, "Rasterizer.getStereoEye(), Rasterizer not available");
+		return NULL;
+	}
+
+	if (gp_Rasterizer->Stereo())
+		flag = gp_Rasterizer->GetEye();
+
+	return PyLong_FromLong(flag);
+}
+
 static PyObject *gPySetBackgroundColor(PyObject *, PyObject *value)
 {
 	
@@ -1496,6 +1511,7 @@ static struct PyMethodDef rasterizer_methods[] = {
 	{"getEyeSeparation", (PyCFunction) gPyGetEyeSeparation, METH_NOARGS, "get the eye separation for stereo mode"},
 	{"setFocalLength", (PyCFunction) gPySetFocalLength, METH_VARARGS, "set the focal length for stereo mode"},
 	{"getFocalLength", (PyCFunction) gPyGetFocalLength, METH_VARARGS, "get the focal length for stereo mode"},
+	{"getStereoEye", (PyCFunction) gPyGetStereoEye, METH_VARARGS, "get the current stereoscopy eye being rendered"},
 	{"setMaterialMode",(PyCFunction) gPySetMaterialType,
 	 METH_VARARGS, "set the material mode to use for OpenGL rendering"},
 	{"getMaterialMode",(PyCFunction) gPyGetMaterialType,
@@ -2320,6 +2336,10 @@ PyObject *initRasterizer(RAS_IRasterizer* rasty,RAS_ICanvas* canvas)
 	KX_MACRO_addTypesToDict(d, VSYNC_ON, VSYNC_ON);
 	KX_MACRO_addTypesToDict(d, VSYNC_ADAPTIVE, VSYNC_ADAPTIVE);
 
+	/* stereoscopy */
+	KX_MACRO_addTypesToDict(d, LEFT_EYE, RAS_IRasterizer::RAS_STEREO_LEFTEYE);
+	KX_MACRO_addTypesToDict(d, RIGHT_EYE, RAS_IRasterizer::RAS_STEREO_RIGHTEYE);
+
 	// XXXX Add constants here
 
 	// Check for errors