BGE: new bge.logic.setRender() to enable/disable render.

The render pass is enabled by default but it can be disabled with
bge.logic.setRender(False).
Once disabled, the render pass is skipped and a new logic frame starts
immediately. Note that VSync no longer limits the fps when render is off
but the 'Use Frame Rate' option in the Render Properties still limits it.

4 files changed, 62 insertions, 4 deletions

diff --git a/doc/python_api/rst/bge.logic.rst b/doc/python_api/rst/bge.logic.rst
index b119bdd1ba1..c197b77ff5f 100644
--- a/doc/python_api/rst/bge.logic.rst
+++ b/doc/python_api/rst/bge.logic.rst
@@ -378,6 +378,27 @@ General functions
 
    Render next frame (if Python has control)
 
+.. function:: setRender(render)
+
+   Sets the global flag that controls the render of the scene. 
+   If True, the render is done after the logic frame.
+   If False, the render is skipped and another logic frame starts immediately.
+
+   .. note::
+      GPU VSync no longer limits the number of frame per second when render is off, 
+      but the 'Use Frame Rate' option still regulates the fps. To run as many frames
+      as possible, untick this option (Render Properties, System panel)
+
+   :arg render: the render flag
+   :type render: bool
+
+.. function:: getRender()
+
+   Get the current value of the global render flag
+
+   :return: The flag value
+   :rtype: bool
+
 *****************
 Utility functions
 *****************
diff --git a/source/gameengine/Ketsji/KX_KetsjiEngine.cpp b/source/gameengine/Ketsji/KX_KetsjiEngine.cpp
index f714a1558e3..c9b868d4ff6 100644
--- a/source/gameengine/Ketsji/KX_KetsjiEngine.cpp
+++ b/source/gameengine/Ketsji/KX_KetsjiEngine.cpp
@@ -106,7 +106,7 @@ double KX_KetsjiEngine::m_suspendeddelta = 0.0;
 double KX_KetsjiEngine::m_average_framerate = 0.0;
 bool   KX_KetsjiEngine::m_restrict_anim_fps = false;
 short  KX_KetsjiEngine::m_exitkey = 130; //ESC Key
-
+bool   KX_KetsjiEngine::m_doRender = true;
 
 /**
  *	Constructor of the Ketsji Engine
@@ -733,7 +733,7 @@ bool KX_KetsjiEngine::NextFrame()
 	// Start logging time spend outside main loop
 	m_logger->StartLog(tc_outside, m_kxsystem->GetTimeInSeconds(), true);
 	
-	return doRender;
+	return doRender && m_doRender;
 }
 
 
@@ -1851,6 +1851,16 @@ short KX_KetsjiEngine::GetExitKey()
 	return m_exitkey;
 }
 
+void KX_KetsjiEngine::SetRender(bool render)
+{
+	m_doRender = render;
+}
+
+bool KX_KetsjiEngine::GetRender()
+{
+	return m_doRender;
+}
+
 void KX_KetsjiEngine::SetShowFramerate(bool frameRate)
 {
 	m_show_framerate = frameRate;
diff --git a/source/gameengine/Ketsji/KX_KetsjiEngine.h b/source/gameengine/Ketsji/KX_KetsjiEngine.h
index d02359a727e..081b6734cf2 100644
--- a/source/gameengine/Ketsji/KX_KetsjiEngine.h
+++ b/source/gameengine/Ketsji/KX_KetsjiEngine.h
@@ -104,7 +104,6 @@ private:
 	int					m_activecam;
 	bool				m_bFixedTime;
 	
-	
 	bool				m_firstframe;
 	int					m_currentFrame;
 
@@ -126,6 +125,8 @@ private:
 
 	static short			m_exitkey; /* Key used to exit the BGE */
 
+	static bool				m_doRender;  /* whether or not the scene should be rendered after the logic frame */
+
 	int					m_exitcode;
 	STR_String			m_exitstring;
 
@@ -363,6 +364,16 @@ public:
 	static short GetExitKey();
 
 	/**
+	 * Activate or deactivates the render of the scene after the logic frame
+	 * \param render	true (render) or false (do not render)
+	 */
+	static void SetRender(bool render);
+	/**
+	 * Get the current render flag value
+	 */
+	static bool GetRender();
+
+	/**
 	 * \Sets the display for frame rate on or off.
 	 */
 	void SetShowFramerate(bool frameRate);
diff --git a/source/gameengine/Ketsji/KX_PythonInit.cpp b/source/gameengine/Ketsji/KX_PythonInit.cpp
index b1824f68eb2..04910a78182 100644
--- a/source/gameengine/Ketsji/KX_PythonInit.cpp
+++ b/source/gameengine/Ketsji/KX_PythonInit.cpp
@@ -470,6 +470,21 @@ static PyObject *gPyGetExitKey(PyObject *)
 	return PyLong_FromLong(KX_KetsjiEngine::GetExitKey());
 }
 
+static PyObject *gPySetRender(PyObject *, PyObject *args)
+{
+	int render;
+	if (!PyArg_ParseTuple(args, "i:setRender", &render))
+		return NULL;
+	KX_KetsjiEngine::SetRender(render);
+	Py_RETURN_NONE;
+}
+
+static PyObject *gPyGetRender(PyObject *)
+{
+	return PyBool_FromLong(KX_KetsjiEngine::GetRender());
+}
+
+
 static PyObject *gPySetMaxLogicFrame(PyObject *, PyObject *args)
 {
 	int frame;
@@ -913,6 +928,8 @@ static struct PyMethodDef game_methods[] = {
 	{"setAnimRecordFrame", (PyCFunction) gPySetAnimRecordFrame, METH_VARARGS, (const char *)"Sets the current frame number used for animation recording"},
 	{"getExitKey", (PyCFunction) gPyGetExitKey, METH_NOARGS, (const char *)"Gets the key used to exit the game engine"},
 	{"setExitKey", (PyCFunction) gPySetExitKey, METH_VARARGS, (const char *)"Sets the key used to exit the game engine"},
+	{"setRender", (PyCFunction) gPySetRender, METH_VARARGS, (const char *)"Set the global render flag"},
+	{"getRender", (PyCFunction) gPyGetRender, METH_NOARGS, (const char *)"get the global render flag value"},
 	{"getAverageFrameRate", (PyCFunction) gPyGetAverageFrameRate, METH_NOARGS, (const char *)"Gets the estimated average frame rate"},
 	{"getBlendFileList", (PyCFunction)gPyGetBlendFileList, METH_VARARGS, (const char *)"Gets a list of blend files in the same directory as the current blend file"},
 	{"PrintGLInfo", (PyCFunction)pyPrintExt, METH_NOARGS, (const char *)"Prints GL Extension Info"},
@@ -1579,7 +1596,6 @@ static PyObject *gPyOffScreenCreate(PyObject *UNUSED(self), PyObject *args)
 	return PyObject_CallObject((PyObject *) &PyRASOffScreen_Type, args);
 }
 
-
 PyDoc_STRVAR(Rasterizer_module_documentation,
 "This is the Python API for the game engine of Rasterizer"
 );