BGE: Fix for T42341 Sensor.frequency is badly named

"Frequency" parameter is renamed to "Skip" in the LogicBricks sensors as it represents skipped frames between pulses.

Naming something (frequency) the exact opposite of what it represents (period) was the worst choice.

Also, a new BGE python attribute 'skippedTicks' was introduced. 'frequency' attribute is maintained but deprecated.

Internally, freq variable is used yet at DNA_Sensor to maintain compability and to avoid do_versions.

Thanks to Sybren for the investigation.

{F162440}

Reviewers: campbellbarton, sybren, moguri, hg1

Reviewed By: sybren, hg1

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

8 files changed, 52 insertions, 20 deletions

diff --git a/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst b/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst
index 9efd2e2d63a..af444fb9e65 100644
--- a/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst
+++ b/doc/python_api/rst/bge_types/bge.types.SCA_ISensor.rst
@@ -23,8 +23,14 @@ base class --- :class:`SCA_ILogicBrick`
 
    .. attribute:: frequency
 
-      The frequency for pulse mode sensors.
-      
+      The frequency for pulse mode sensors. (Deprecated: use SCA_ISensor.skippedTicks)
+
+      :type: integer
+
+   .. attribute:: skippedTicks
+
+      Number of logic ticks skipped between 2 active pulses
+
       :type: integer
 
    .. attribute:: level
diff --git a/source/blender/editors/space_logic/logic_window.c b/source/blender/editors/space_logic/logic_window.c
index 7204144ce85..d4fa911f025 100644
--- a/source/blender/editors/space_logic/logic_window.c
+++ b/source/blender/editors/space_logic/logic_window.c
@@ -903,7 +903,7 @@ static void draw_sensor_internal_header(uiLayout *layout, PointerRNA *ptr)
 	sub = uiLayoutRow(row, false);
 	uiLayoutSetActive(sub, (RNA_boolean_get(ptr, "use_pulse_true_level") ||
 	                        RNA_boolean_get(ptr, "use_pulse_false_level")));
-	uiItemR(sub, ptr, "frequency", 0, IFACE_("Freq"), ICON_NONE);
+	uiItemR(sub, ptr, "skipped_ticks", 0, IFACE_("Skip"), ICON_NONE);
 	
 	row = uiLayoutRow(split, true);
 	uiItemR(row, ptr, "use_level", UI_ITEM_R_TOGGLE, NULL, ICON_NONE);
diff --git a/source/blender/makesdna/DNA_sensor_types.h b/source/blender/makesdna/DNA_sensor_types.h
index 8d59a13768b..d886dcf2807 100644
--- a/source/blender/makesdna/DNA_sensor_types.h
+++ b/source/blender/makesdna/DNA_sensor_types.h
@@ -164,7 +164,7 @@ typedef struct bSensor {
 	struct bSensor *next, *prev;
 	/* pulse and freq are the bool toggle and frame count for pulse mode */
 	short type, otype, flag, pulse;
-	short freq, totlinks, pad1, pad2;
+	short freq, totlinks, pad1, pad2; /* freq makes reference to skipped ticks between 2 active pulses */
 	char name[64];	/* MAX_NAME */
 	void *data;
 	
diff --git a/source/blender/makesrna/intern/rna_sensor.c b/source/blender/makesrna/intern/rna_sensor.c
index 69dd0925a42..3cc94039d59 100644
--- a/source/blender/makesrna/intern/rna_sensor.c
+++ b/source/blender/makesrna/intern/rna_sensor.c
@@ -325,9 +325,11 @@ static void rna_def_sensor(BlenderRNA *brna)
 	RNA_def_property_ui_text(prop, "Pulse False Level", "Activate FALSE level triggering (pulse mode)");
 	RNA_def_property_update(prop, NC_LOGIC, NULL);
 	
-	prop = RNA_def_property(srna, "frequency", PROP_INT, PROP_NONE);
+	prop = RNA_def_property(srna, "skipped_ticks", PROP_INT, PROP_NONE);
 	RNA_def_property_int_sdna(prop, NULL, "freq");
-	RNA_def_property_ui_text(prop, "Frequency", "Delay between repeated pulses(in logic tics, 0=no delay)");
+	RNA_def_property_ui_text(prop, "Skip",
+	                         "Number of logic ticks skipped between 2 active pulses "
+	                         "(0 = pulse every logic tick, 1 = skip 1 logic tick between pulses, etc.)");
 	RNA_def_property_range(prop, 0, 10000);
 	RNA_def_property_update(prop, NC_LOGIC, NULL);
 
diff --git a/source/gameengine/Converter/KX_ConvertSensors.cpp b/source/gameengine/Converter/KX_ConvertSensors.cpp
index 0d706fcd924..b781e4d1cc8 100644
--- a/source/gameengine/Converter/KX_ConvertSensors.cpp
+++ b/source/gameengine/Converter/KX_ConvertSensors.cpp
@@ -105,7 +105,7 @@ void BL_ConvertSensors(struct Object* blenderobject,
 	bSensor* sens = (bSensor*)blenderobject->sensors.first;
 	bool pos_pulsemode = false;
 	bool neg_pulsemode = false;
-	int frequency = 0;
+	int skipped_ticks = 0;
 	bool invert = false;
 	bool level = false;
 	bool tap = false;
@@ -120,13 +120,13 @@ void BL_ConvertSensors(struct Object* blenderobject,
 
 	while (sens) {
 		SCA_ISensor* gamesensor=NULL;
-		/* All sensors have a pulse toggle, frequency, and invert field.     */
+		/* All sensors have a pulse toggle, skipped ticks parameter, and invert field.     */
 		/* These are extracted here, and set when the sensor is added to the */
 		/* list.                                                             */
 		pos_pulsemode = (sens->pulse & SENS_PULSE_REPEAT)!=0;
 		neg_pulsemode = (sens->pulse & SENS_NEG_PULSE_MODE)!=0;
 		
-		frequency = sens->freq;
+		skipped_ticks = sens->freq;
 		invert    = !(sens->invert == 0);
 		level     = !(sens->level == 0);
 		tap       = !(sens->tap == 0);
@@ -602,7 +602,7 @@ void BL_ConvertSensors(struct Object* blenderobject,
 			/* Conversion succeeded, so we can set the generic props here.   */
 			gamesensor->SetPulseMode(pos_pulsemode,
 			                         neg_pulsemode,
-			                         frequency);
+			                         skipped_ticks);
 			gamesensor->SetInvert(invert);
 			gamesensor->SetLevel(level);
 			gamesensor->SetTap(tap);
diff --git a/source/gameengine/GameLogic/SCA_ISensor.cpp b/source/gameengine/GameLogic/SCA_ISensor.cpp
index 1cb17af8325..66dd69f93c4 100644
--- a/source/gameengine/GameLogic/SCA_ISensor.cpp
+++ b/source/gameengine/GameLogic/SCA_ISensor.cpp
@@ -67,7 +67,7 @@ SCA_ISensor::SCA_ISensor(SCA_IObject* gameobj,
 	m_neg_ticks = 0;
 	m_pos_pulsemode = false;
 	m_neg_pulsemode = false;
-	m_pulse_frequency = 0;
+	m_skipped_ticks = 0;
 	m_state = false;
 	m_prev_state = false;
 	
@@ -102,11 +102,11 @@ bool SCA_ISensor::IsPositiveTrigger()
 
 void SCA_ISensor::SetPulseMode(bool posmode, 
                                bool negmode,
-                               int freq)
+                               int skippedticks)
 {
 	m_pos_pulsemode = posmode;
 	m_neg_pulsemode = negmode;
-	m_pulse_frequency = freq;
+	m_skipped_ticks = skippedticks;
 }
 
 void SCA_ISensor::SetInvert(bool inv)
@@ -263,7 +263,7 @@ void SCA_ISensor::Activate(class SCA_LogicManager* logicmgr)
 			 * not set :( */
 			if (m_pos_pulsemode) {
 				m_pos_ticks++;
-				if (m_pos_ticks > m_pulse_frequency) {
+				if (m_pos_ticks > m_skipped_ticks) {
 					if ( m_state )
 					{
 						ActivateControllers(logicmgr);
@@ -276,7 +276,7 @@ void SCA_ISensor::Activate(class SCA_LogicManager* logicmgr)
 			if (m_neg_pulsemode && !m_tap)
 			{
 				m_neg_ticks++;
-				if (m_neg_ticks > m_pulse_frequency) {
+				if (m_neg_ticks > m_skipped_ticks) {
 					if (!m_state )
 					{
 						ActivateControllers(logicmgr);
@@ -367,7 +367,7 @@ PyMethodDef SCA_ISensor::Methods[] = {
 PyAttributeDef SCA_ISensor::Attributes[] = {
 	KX_PYATTRIBUTE_BOOL_RW("usePosPulseMode",SCA_ISensor,m_pos_pulsemode),
 	KX_PYATTRIBUTE_BOOL_RW("useNegPulseMode",SCA_ISensor,m_neg_pulsemode),
-	KX_PYATTRIBUTE_INT_RW("frequency",0,100000,true,SCA_ISensor,m_pulse_frequency),
+	KX_PYATTRIBUTE_INT_RW("skippedTicks",0,100000,true,SCA_ISensor,m_skipped_ticks),
 	KX_PYATTRIBUTE_BOOL_RW("invert",SCA_ISensor,m_invert),
 	KX_PYATTRIBUTE_BOOL_RW_CHECK("level",SCA_ISensor,m_level,pyattr_check_level),
 	KX_PYATTRIBUTE_BOOL_RW_CHECK("tap",SCA_ISensor,m_tap,pyattr_check_tap),
@@ -376,6 +376,7 @@ PyAttributeDef SCA_ISensor::Attributes[] = {
 	KX_PYATTRIBUTE_RO_FUNCTION("status", SCA_ISensor, pyattr_get_status),
 	KX_PYATTRIBUTE_RO_FUNCTION("pos_ticks", SCA_ISensor, pyattr_get_posTicks),
 	KX_PYATTRIBUTE_RO_FUNCTION("neg_ticks", SCA_ISensor, pyattr_get_negTicks),
+	KX_PYATTRIBUTE_RW_FUNCTION("frequency", SCA_ISensor, pyattr_get_frequency, pyattr_set_frequency),
 	{ NULL }	//Sentinel
 };
 
@@ -444,6 +445,27 @@ int SCA_ISensor::pyattr_check_tap(void *self_v, const KX_PYATTRIBUTE_DEF *attrde
 		self->m_level = false;
 	return 0;
 }
+
+PyObject *SCA_ISensor::pyattr_get_frequency(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef)
+{
+	SCA_ISensor *self = static_cast<SCA_ISensor*>(self_v);
+	ShowDeprecationWarning("SCA_ISensor.frequency", "SCA_ISensor.skippedTicks");
+	return PyLong_FromLong(self->m_skipped_ticks);
+}
+
+int SCA_ISensor::pyattr_set_frequency(void *self_v, const struct KX_PYATTRIBUTE_DEF *attrdef, PyObject *value)
+{
+	SCA_ISensor *self = static_cast<SCA_ISensor*>(self_v);
+	ShowDeprecationWarning("SCA_ISensor.frequency", "SCA_ISensor.skippedTicks");
+	if (PyLong_Check(value)) {
+		self->m_skipped_ticks = PyLong_AsLong(value);
+		return PY_SET_ATTR_SUCCESS;
+	}
+	else {
+		PyErr_SetString(PyExc_TypeError, "sensor.frequency = int: Sensor, expected an integer");
+		return PY_SET_ATTR_FAIL;
+	}
+}
 #endif // WITH_PYTHON
 
 /* eof */
diff --git a/source/gameengine/GameLogic/SCA_ISensor.h b/source/gameengine/GameLogic/SCA_ISensor.h
index 7bbba7aaafe..1e82f3ab11f 100644
--- a/source/gameengine/GameLogic/SCA_ISensor.h
+++ b/source/gameengine/GameLogic/SCA_ISensor.h
@@ -57,8 +57,8 @@ protected:
 	/** Pulse negative pulses? */
 	bool m_neg_pulsemode;
 
-	/** Repeat frequency in pulse mode. */
-	int m_pulse_frequency;
+	/** Number of skipped ticks between two active pulses. */
+	int m_skipped_ticks;
 
 	/** Number of ticks since the last positive pulse. */
 	int m_pos_ticks;
@@ -125,7 +125,7 @@ public:
 	 */
 	void SetPulseMode(bool posmode,
 					  bool negmode,
-					  int freq);
+					  int skippedticks);
 	
 	/** Set inversion of pulses on or off. */
 	void SetInvert(bool inv);
@@ -201,6 +201,8 @@ public:
 	static PyObject*	pyattr_get_status(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
 	static PyObject*	pyattr_get_posTicks(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
 	static PyObject*	pyattr_get_negTicks(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
+	static PyObject*	pyattr_get_frequency(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
+	static int			pyattr_set_frequency(void *self_v, const struct KX_PYATTRIBUTE_DEF *attrdef, PyObject *value);
 
 	static int          pyattr_check_level(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
 	static int          pyattr_check_tap(void *self_v, const KX_PYATTRIBUTE_DEF *attrdef);
diff --git a/source/gameengine/GameLogic/SCA_RandomSensor.cpp b/source/gameengine/GameLogic/SCA_RandomSensor.cpp
index 4e93556453a..2fe4d18a7fc 100644
--- a/source/gameengine/GameLogic/SCA_RandomSensor.cpp
+++ b/source/gameengine/GameLogic/SCA_RandomSensor.cpp
@@ -107,7 +107,7 @@ bool SCA_RandomSensor::Evaluate()
 
 	bool evaluateResult = false;
 
-	if (++m_interval > m_pulse_frequency) {
+	if (++m_interval > m_skipped_ticks) {
 		bool drawResult = false;
 		m_interval = 0;
 		if (m_iteration > 31) {