BGE: Improve clock management

This patch improves clock management in BGE, to be able to accelerate /
slow the time, and also to finely synchronize clock with external
engines. Several new python functions have been added and existence ones
have been improved for that purpose. Now we have:

- getClockTime(): Get the current BGE render time, in seconds. The BGE
render time is the simulation time corresponding to the next scene that
will be rendered.

- getFrameTime(): Get the current BGE frame time, in seconds. The BGE
frame time is the simulation time corresponding to the current call of
the logic system. Generally speaking, it is what the user is interested
in.

- getRealTime(): Get the number of real (system-clock) seconds elapsed
since the beginning of the simulation.

- getTimeScale(): Get the time multiplier between real-time and
simulation time. The default value is 1.0. A value greater than 1.0
means that the simulation is going faster than real-time, a value lower
than 1.0 means that the simulation is going slower than real-time.

- setTimeScale(time_scale): Set the time multiplier between real-time
and simulation time. A value greater than 1.0 means that the simulation
is going faster than real-time, a value lower than 1.0 means that the
simulation is going slower than real-time. Note that a too large value
may lead to some physics instabilities.

- getUseExternalClock(): Get if the BGE use the inner BGE clock, or rely
or on an external clock. The default is to use the inner BGE clock.

- setUseExternalClock(use_external_clock): Set if the BGE use the inner
BGE clock, or rely or on an external clock. If the user selects the use
of an external clock, he should call regularly the setClockTime method.

- setClockTime(new_time): Set the next value of the simulation clock. It
is preferable to use this method from a custom main function in python,
as calling it in the logic block can easily lead to a blocked system (if
the time does not advance enough to run at least the next logic step).

Rationale are described more precisely in the thread
http://lists.blender.org/pipermail/bf-gamedev/2013-November/000165.html.

See also T37640

Reviewers: sybren, panzergame, #game_engine, lordloki, moguri

Reviewed By: sybren, panzergame, #game_engine, lordloki, moguri

Subscribers: moguri, hg1, sybren, panzergame, dfelinto, lordloki

Projects: #game_engine

Maniphest Tasks: T37640

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

1 files changed, 70 insertions, 0 deletions

diff --git a/source/gameengine/Ketsji/KX_PythonInit.cpp b/source/gameengine/Ketsji/KX_PythonInit.cpp
index d35f09dd820..8a010726bba 100644
--- a/source/gameengine/Ketsji/KX_PythonInit.cpp
+++ b/source/gameengine/Ketsji/KX_PythonInit.cpp
@@ -548,6 +548,64 @@ static PyObject *gPyGetAverageFrameRate(PyObject *)
 	return PyFloat_FromDouble(KX_KetsjiEngine::GetAverageFrameRate());
 }
 
+static PyObject *gPyGetUseExternalClock(PyObject *)
+{
+	return PyBool_FromLong(gp_KetsjiEngine->GetUseExternalClock());
+}
+
+static PyObject *gPySetUseExternalClock(PyObject *, PyObject *args)
+{
+	bool bUseExternalClock;
+
+	if (!PyArg_ParseTuple(args, "p:setUseExternalClock", &bUseExternalClock))
+		return NULL;
+
+	gp_KetsjiEngine->SetUseExternalClock(bUseExternalClock);
+	Py_RETURN_NONE;
+}
+
+static PyObject *gPyGetClockTime(PyObject *)
+{
+	return PyFloat_FromDouble(gp_KetsjiEngine->GetClockTime());
+}
+
+static PyObject *gPySetClockTime(PyObject *, PyObject *args)
+{
+	double externalClockTime;
+
+	if (!PyArg_ParseTuple(args, "d:setClockTime", &externalClockTime))
+		return NULL;
+
+	gp_KetsjiEngine->SetClockTime(externalClockTime);
+	Py_RETURN_NONE;
+}
+
+static PyObject *gPyGetFrameTime(PyObject *)
+{
+	return PyFloat_FromDouble(gp_KetsjiEngine->GetFrameTime());
+}
+
+static PyObject *gPyGetRealTime(PyObject *)
+{
+	return PyFloat_FromDouble(gp_KetsjiEngine->GetRealTime());
+}
+
+static PyObject *gPyGetTimeScale(PyObject *)
+{
+	return PyFloat_FromDouble(gp_KetsjiEngine->GetTimeScale());
+}
+
+static PyObject *gPySetTimeScale(PyObject *, PyObject *args)
+{
+	double time_scale;
+
+	if (!PyArg_ParseTuple(args, "d:setTimeScale", &time_scale))
+			return NULL;
+
+	gp_KetsjiEngine->SetTimeScale(time_scale);
+	Py_RETURN_NONE;
+}
+
 static PyObject *gPyGetBlendFileList(PyObject *, PyObject *args)
 {
 	char cpath[sizeof(gp_GamePythonPath)];
@@ -847,7 +905,19 @@ 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"},
+	{"getUseExternalClock", (PyCFunction) gPyGetUseExternalClock, METH_NOARGS, (const char *)"Get if we use the time provided by an external clock"},
+	{"setUseExternalClock", (PyCFunction) gPySetUseExternalClock, METH_VARARGS, (const char *)"Set if we use the time provided by an external clock"},
+	{"getClockTime", (PyCFunction) gPyGetClockTime, METH_NOARGS, (const char *)"Get the last BGE render time. "
+	"The BGE render time is the simulated time corresponding to the next scene that will be renderered"},
+	{"setClockTime", (PyCFunction) gPySetClockTime, METH_VARARGS, (const char *)"Set the BGE render time. "
+	"The BGE render time is the simulated time corresponding to the next scene that will be rendered"},
+	{"getFrameTime", (PyCFunction) gPyGetFrameTime, METH_NOARGS, (const char *)"Get the BGE last frametime. "
+	"The BGE frame time is the simulated time corresponding to the last call of the logic system"},
+	{"getRealTime", (PyCFunction) gPyGetRealTime, METH_NOARGS, (const char *)"Get the real system time. "
+	"The real-time corresponds to the system time" },
 	{"getAverageFrameRate", (PyCFunction) gPyGetAverageFrameRate, METH_NOARGS, (const char *)"Gets the estimated average frame rate"},
+	{"getTimeScale", (PyCFunction) gPyGetTimeScale, METH_NOARGS, (const char *)"Get the time multiplier"},
+	{"setTimeScale", (PyCFunction) gPySetTimeScale, METH_VARARGS, (const char *)"Set the time multiplier"},
 	{"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"},
 	{"PrintMemInfo", (PyCFunction)pyPrintStats, METH_NOARGS, (const char *)"Print engine statistics"},