---

GAUGE3D::GInputMap Class Reference

Maps user-configured input to game-specific controls. More...

#include <gauge3d/input/inputmap.h>

Inherits GAUGE3D::GMessageQueue::Handler.

List of all members.

Public Methods
	GInputMap (pGMessageQueue outputQueue)
	Constructs an input map. More...
virtual	~GInputMap ()
	Destructor.
virtual bool	HandleMessage (pGMessage message)
	Translates and dispatches a message (called by the input message queue).
void	NewControl (GString name,int type)
	Add a new control to the list of game-specific controls. More...
void	MapInput (GString input,GString control,float sensitivity=1.0)
	Maps an input source to a control with a given sensitivity. More...
void	ControlList (pGDirectory config)
	Loads a list of controls from a config file. More...
void	ControlMap (pGDirectory config)
	Loads the input to control map from a config file. More...
void	ClearControlList ()
	Empties the list of controls.
void	ClearControlMap ()
	Erases all input-to-control mappings.
virtual void	DoFrame (tTime time,tTime frameTime)
	This will be called every frame by the scheduler. More...

---

Detailed Description

Maps user-configured input to game-specific controls.

GInputMap makes it easy to allow users to configure their controls rather than use forced key bindings. It also translates the input type to the control type (analog vs. digital, absolute vs. relative) and applies sensitivity settings to the controls.

To make the input map translate messages, you must register it as a message handler in the input message queue. Also, make sure to call GInputMap::DoFrame() every frame.

---

Constructor & Destructor Documentation

GAUGE3D::GInputMap::GInputMap ( pGMessageQueue outputQueue )

Constructs an input map. Parameters: outputQueue   A message queue to which the translated messages should be sent. This must not be the same as the input queue for obvious reasons.

---

Member Function Documentation

void GAUGE3D::GInputMap::NewControl ( GString name, int type )

Add a new control to the list of game-specific controls. Parameters: name   The name that the translated messages will have. type   The type of the control. This is a bitwise OR of either GInputMessage::DIGITAL or GInputMessage::ANALOG with either GInputMessage::ABSOLUTE or GInputMessage::RELATIVE. This function adds a new game-specific control to the list of controls which the user can configure, but it does not actually bind an input source to it. Use MapInput to bind one or more input sources to the control. When an input source is mapped to a control, the message is translated from the input's type to the control's type, so you don't have to worry about handling any type of input other than what you expect, yet the user is free to bind any sort of input to any control (almost). Choosing the right type for the control is tricky, especially if it is an analog control. Here are what the four types represent: Absolute Digital: Any sort of simple button-pressing control, like fire, use, jump, etc. You will recieve messages when the user presses or releases the button. Relative Digital: Something that cycles in two directions by discreet amounts. For example, a control that cycles though your inventory would be relative digital. You will receive messages when the user cycles forward or back. Think mouse wheel. Absolute Analog: Something which has defined limits. The only really way I can describe the difference between this and relative analog is by explaining how the translation is done. When mapping any sort of absolute input to an absolute analog control, the output value is simply the same as the input (after sensitivity is applied). When mapping a relative input to an absolute analog output, a running total of the input is kept and clamped to the range [-1.0, 1.0], and that total is output. An example of an absolute analog control would be a glance left/right function, where you can only turn your head so far to the left or right and the view should snap back to center afterwards. Relative Analog: A control with no limits. Again, I can't think of a good way to explain this without explaining exactly how the mapping is done. When mapping any sort of relative input to a relative analog control, the output value is simply the same as the input (after sensitivity is applied). When mapping absolute input, messages are sent every frame as long as the input value is not zero. So, the input becomes sort of a rate of change, as if the input were a mouse and were moving at exactly that speed. Unfortunately, the explanation I just gave you sucked, so you will have to experiment a little or I will have to get a better documentation writer. Examples of relative analog controls include movement, turning, looking, etc.

void GAUGE3D::GInputMap::MapInput ( GString input, GString control, float sensitivity = 1.0 )

Maps an input source to a control with a given sensitivity. Parameters: input   The name of the input source to map. control   The name of the control to which the input should be mapped. sensitivity   The sensitivity of the input. How exactly this is used depends on the types of both the input and the control. Usually, the input value is multiplied by the sensitivity, but in some cases (usually when converting from analog input to a digital control) the sensitivity is actually a threshold value. Note: You can not map an input to a control before you create the control by calling NewControl (or ControlList()).

void GAUGE3D::GInputMap::ControlList ( pGDirectory config )

Loads a list of controls from a config file. Parameters: config   The directory representing the config file. See GConfigFile for more info on how this works. The format of the config file is as follows: config is one section of the config file. Each line in that section should have the form "control name = [absolute|relative] [digital|analog]". Here's an example: [controls] cycle weapon = relative digital fire = absolute digital look Y = absolute analog move X = analog relative move Y = analog relative [/controls]

void GAUGE3D::GInputMap::ControlMap ( pGDirectory config )

Loads the input to control map from a config file. Parameters: config   The directory representing the config file. See GConfigFile for more info on how this works. Note: You must load the control list before loading the input map. The format of the config file is as follows: config is one section of the config file. Each line in that section should have the form: 'control name = "input name"[*sensitivity] ["input2 name"[*sensitivity] [...]] Here's an example: [control map] cycle weapon = "mouse wheel" fire = "space" "mouse 1" look Y = "mouse y"*2.0 move X = "left"*-1.0 "s"*-1.0 "right"*1.0 "d"*1.0 "joystick x"*0.83 move Y = "up"*1.0 "w"*1.0 "down"*-1.0 "a"*-1.0 "joystick y"*0.83 [/control map]

void GAUGE3D::GInputMap::DoFrame ( tTime time, tTime frameTime ) [virtual]

This will be called every frame by the scheduler. Remarks: You can safely pretend this function does not exist. Everything will be handled for you. :) Reimplemented from GAUGE3D::GObject.

---

The documentation for this class was generated from the following file:

• gauge3d/input/inputmap.h

---