• Create an instance of the input object.
  • It is generally a good idea to encapsulate the TVInputEngine object instance in its own “input handler” class, where all of your input handling happens.
• Call the Initialize method of the TVInputEngine object.
  • Arguments are both boolean, first = capture keyboard input, second = capture mouse input.
    • The arguments are generally both going to be set to true.
  • Examples:
    • VB: MyInput.Initialize(True, True)
    • C#: myInputEngine.Initialize(true,true);
  • Note: This step was not required with Truevision3D 6.2 !!!

Keyboard input is handled through two different methods. One method is to get the current state of any of the individual keys on the keyboard using “IsKeyPressed” and such.

VB Example:

If MyInput.IsKeyPressed(CONST_TV_KEY.TV_KEY_D) Then
   Console.WriteLine("The D Key is currently being pressed")
End If

This method is pretty straight-forward, however it does not account for changes in the state of the keyboard from one check to the next. To do this, you would have to implement a sophisticated and bulky state machine to keep track of all key states, and check each state for changes each frame. This is simply not feasible for most people, as it’s sloppy and cumbersome. So, the TVInputEngine also provides you with keyboard changes since its last check in the form of an array of key data.

To grab this array, you will need to declare a few variables to hold the data: A buffer array to hold the key data, and an integer to get the count of actual elements in the array. In the below examples, we’ll just call these vars “buffer” and “numkeys” respectively.

To get the array of keydata changes since the last check, call TVInputEngine.GetKeyBuffer

MyInput.GetKeyBuffer(buffer, numkeys)

IMPORTANT NOTE: ONCE YOU GET THE BUFFER, IT IS CLEARED FROM THE INTERNAL INPUT ENGINE, AND STARTS FILLING AGAIN! If you need this key buffer in multiple places, don’t try to grab it twice. Instead, grab it once, then pass the buffer (or individual keydata objects) to the other object that needs it.

FOR THIS REASON, ADD-ON CREATORS THAT PROCESS KEYBOARD INPUT SHOULD NOT GRAB THE INPUT KEY BUFFER! Doing so takes control of that buffer out of the programmer’s hands. Instead, implement a key injection system, where the programmer can inject keydata in to your addon. This is especially true of GUI systems!

To use the key buffer, you should loop through the array of keydata, and process it in some way.

VB Example:

      For I As Integer = 0 To numkeys - 1
          GUIRoot.InjectKey(buffer(I))
          If buffer(I).Pressed Then
              KeyPressed(buffer(I))
          End If
      Next

Note the GUI Injection. This way both the GUI system and the main app can be made aware of the keystroke.

Generally, a hybrid of using the keybuffer and straight-up checking “IsKeyPressed” are used.

The mouse is, of course, a very important and widely versatile input device. Its data, however, is actually very simple. Mouse data that the TVInputEngine grabs consists of:

• Absolute screen position (X,Y)
• Relative screen position (X,Y)
• Button States (Buttons0 thru Button3)
• Wheel State (Unsigned Integer, Negative = down, Positive = up)

There are two methods that are an absolute must for getting the above data: GetMouseState and GetMousePosition

GetMouseState takes up to 7 arguments:

• Relative X (The relative horizontal motion of the mouse since last check)
• Relative Y (The relative vertical motion of the mouse since last check)
• Button0 state
• Button1 state
• Button2 state
• Button3 state
• Wheel roll (+/-)

GetMousePosition gets the absolute position of the mouse on the screen, and only takes the two arguments of X and Y coordinates of the mouse on the screen.

A good idea is to keep a struct of your own persistent mouse data, such as this from EEGUI (Feel free to use it; EagleEye) :

Public Class MouseStates
  Public ButtonStates(4) As Boolean
  Public Wheel As Integer
  Public Location As Point
  Public AButtonIsDown As Boolean
  Public LastButtonDown As Byte
  Public LastButtonUp As Byte
  Public LastMouseDownPoint As New Point

  Public Sub CheckButtons()
      If GUI_MouseState.ButtonStates(0) = True Or GUI_MouseState.ButtonStates(1) = True Or GUI_MouseState.ButtonStates(2) = True Or GUI_MouseState.ButtonStates(3) = True Then
          AButtonIsDown = True
          If GUI_MouseState.ButtonStates(3) Then GUI_MouseState.LastButtonDown = 3
          If GUI_MouseState.ButtonStates(2) Then GUI_MouseState.LastButtonDown = 2
          If GUI_MouseState.ButtonStates(1) Then GUI_MouseState.LastButtonDown = 1
          If GUI_MouseState.ButtonStates(0) Then GUI_MouseState.LastButtonDown = 0
          LastMouseDownPoint = Location
      Else
          AButtonIsDown = False
          LastButtonUp = LastButtonDown
      End If
  End Sub
End Class

Public MyMouseState As New MouseStates

You can then get, and store, your mouse states using the following:

      With MyMouseState
          GUI_Input.GetMouseState(.Location.X, .Location.Y, .ButtonStates(0), .ButtonStates(1), .ButtonStates(2), .ButtonStates(3), .Wheel)
          GUI_Input.GetMousePosition(.Location.X, .Location.Y)
      End With

(Note: Location.X and Location.Y from the first call are overwritten in the second one, because I didn’t need to store relative mouse movement. Keep that in mind when using this.)

Remember, GetMousePosition gets the ABSOLUTE MOUSE POSITION ON THE SCREEN. GetMouseState gets the RELATIVE mouse position.

The absolute position is good for when you’re showing a cursor, and the relative movement is good for when using the mouse to pan/tilt the camera.

(Written by EagleEye)