BGE Patch: [#27425] Allow to change the damping of the camera actuator

##########
original name: "Allow to change the strenght of the "go behind" constraint of the camera actuator"

The camera actuator is an actuator that drive the camera to follow an object, with a set of constraint.
Currently, when the object followed rotate on himself (like a person, or an helicopter), the camera is really slow to go behind (at least 10 seconds).

This patch gives the UI to tweak the strenght of the 'go behind'[named damping] constraint.
###########

epydocs (rst) updated too

doc/python_api/rst/bge.types.rst

@@ -710,6 +710,12 @@ Game Engine  bge.types Module
 
    Applies changes to a camera.
 
+   .. attribute:: damping
+
+      strength of of the camera following movement.
+
+      :type: float
+   
    .. attribute:: min
 
       minimum distance to the target object maintained by the actuator.

source/blender/blenkernel/intern/sca.c

@@ -430,6 +430,7 @@ void init_actuator(bActuator *act)
 		act->data= MEM_callocN(sizeof(bCameraActuator), "camact");
 		ca = act->data;
 		ca->axis = ACT_CAMERA_X;
+		ca->damping = 1.0/32.0;
 		break;
 	case ACT_EDIT_OBJECT:
 		act->data= MEM_callocN(sizeof(bEditObjectActuator), "editobact");

source/blender/blenloader/intern/readfile.c

@@ -11647,6 +11647,21 @@ static void do_versions(FileData *fd, Library *lib, Main *main)
 				}
 			}
 		}
+
+		{
+			/* add default value for behind strength of camera actuator */
+			Object *ob;
+			bActuator *act;
+			for(ob = main->object.first; ob; ob= ob->id.next) {
+				for(act= ob->actuators.first; act; act= act->next) {
+					if (act->type == ACT_CAMERA) {
+						bCameraActuator *ba= act->data;
+
+						ba->damping = 1.0/32.0;
+					}
+				}
+			}
+		}
 	}
 	
 	/* WATCH IT!!!: pointers from libdata have not been converted yet here! */

source/blender/editors/space_logic/logic_window.c

@@ -3786,6 +3786,8 @@ static void draw_actuator_camera(uiLayout *layout, PointerRNA *ptr)
 	row = uiLayoutRow(layout, 1);
 	uiItemR(row, ptr, "min", 0, NULL, ICON_NONE);
 	uiItemR(row, ptr, "max", 0, NULL, ICON_NONE);
+
+	uiItemR(layout, ptr, "damping", 0, NULL, ICON_NONE);
 }
 
 static void draw_actuator_constraint(uiLayout *layout, PointerRNA *ptr, bContext *C)

source/blender/makesdna/DNA_actuator_types.h

@@ -133,7 +133,7 @@ typedef struct bIpoActuator {
 typedef struct bCameraActuator {
 	struct Object *ob;
 	float height, min, max;
-	float pad;
+	float damping;
 	short pad1, axis;
 	float pad2;
 } bCameraActuator ;

source/blender/makesrna/intern/rna_actuator.c

@@ -922,6 +922,13 @@ static void rna_def_camera_actuator(BlenderRNA *brna)
 	RNA_def_property_ui_text(prop, "Max", "");
 	RNA_def_property_update(prop, NC_LOGIC, NULL);
 
+	prop= RNA_def_property(srna, "damping", PROP_FLOAT, PROP_NONE);
+	RNA_def_property_float_sdna(prop, NULL, "damping");
+	RNA_def_property_range(prop, 0, 10.0);
+	RNA_def_property_ui_range(prop, 0, 5.0, 1, 2);
+	RNA_def_property_ui_text(prop, "Damping", "Specify the strength of the constraint that drive the camera behind the target");
+	RNA_def_property_update(prop, NC_LOGIC, NULL);
+
 	/* x/y */
 	prop= RNA_def_property(srna, "axis", PROP_ENUM, PROP_NONE);
 	RNA_def_property_enum_sdna(prop, NULL, "axis");

source/gameengine/Converter/KX_ConvertActuators.cpp

@@ -287,7 +287,8 @@ void BL_ConvertActuators(char* maggiename,
 						camact->height,
 						camact->min,
 						camact->max,
-						camact->axis=='x');
+						camact->axis=='x',
+						camact->damping);
 					baseact = tmpcamact;
 				}
 				break;

source/gameengine/Ketsji/KX_CameraActuator.cpp

@@ -54,14 +54,16 @@ KX_CameraActuator::KX_CameraActuator(
 	float hght,
 	float minhght,
 	float maxhght,
-	bool  xytog
+	bool  xytog,
+	float damping
 ): 
 	SCA_IActuator(gameobj, KX_ACT_CAMERA),
 	m_ob (obj),
 	m_height (hght),
 	m_minHeight (minhght),
 	m_maxHeight (maxhght),
-	m_x (xytog)
+	m_x (xytog),
+	m_damping (damping)
 {
 	if (m_ob)
 		m_ob->RegisterActuator(this);
@@ -283,7 +285,7 @@ bool KX_CameraActuator::Update(double curtime, bool frame)
 	}
 	
 	inp= fp1[0]*fp2[0] + fp1[1]*fp2[1] + fp1[2]*fp2[2];
-	fac= (-1.0 + inp)/32.0;
+	fac= (-1.0 + inp) * m_damping;
 
 	from[0]+= fac*fp1[0];
 	from[1]+= fac*fp1[1];
@@ -390,6 +392,7 @@ PyAttributeDef KX_CameraActuator::Attributes[] = {
 	KX_PYATTRIBUTE_FLOAT_RW("height",-FLT_MAX,FLT_MAX,KX_CameraActuator,m_height),
 	KX_PYATTRIBUTE_BOOL_RW("useXY",KX_CameraActuator,m_x),
 	KX_PYATTRIBUTE_RW_FUNCTION("object", KX_CameraActuator, pyattr_get_object,	pyattr_set_object),
+	KX_PYATTRIBUTE_FLOAT_RW("damping",0.f,10.f,KX_CameraActuator,m_damping),
 	{NULL}
 };
 

source/gameengine/Ketsji/KX_CameraActuator.h

@@ -73,6 +73,9 @@ private :
 	
 	/** xy toggle (pick one): true == x, false == y */
 	bool m_x;
+	
+	/** damping (float), */
+	float m_damping;
 
 	/* get the KX_IGameObject with this name */
 	CValue *findObject(char *obName);
@@ -95,7 +98,8 @@ private :
 		float hght,
 		float minhght,
 		float maxhght,
-		bool xytog
+		bool xytog,
+		float damping
 	);