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

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

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);

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;
 	

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);
 

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);

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 */

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);

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) {