This page has been translated automatically.
Видеоуроки
Интерфейс
Основы
Продвинутый уровень
Подсказки и советы
Основы
Программирование на C#
Рендеринг
Профессиональный уровень (SIM)
Принципы работы
Свойства (properties)
Компонентная Система
Рендер
Физика
Редактор UnigineEditor
Обзор интерфейса
Работа с ассетами
Контроль версий
Настройки и предпочтения
Работа с проектами
Настройка параметров ноды
Setting Up Materials
Настройка свойств
Освещение
Sandworm
Использование инструментов редактора для конкретных задач
Расширение функционала редактора
Встроенные объекты
Ноды (Nodes)
Объекты (Objects)
Эффекты
Декали
Источники света
Geodetics
World-ноды
Звуковые объекты
Объекты поиска пути
Player-ноды
Программирование
Основы
Настройка среды разработки
Примеры использования
C++
C#
UnigineScript
UUSL (Unified UNIGINE Shader Language)
Плагины
Форматы файлов
Материалы и шейдеры
Rebuilding the Engine Tools
Интерфейс пользователя (GUI)
Двойная точность координат
API
Animations-Related Classes
Containers
Common Functionality
Controls-Related Classes
Engine-Related Classes
Filesystem Functionality
GUI-Related Classes
Math Functionality
Node-Related Classes
Objects-Related Classes
Networking Functionality
Pathfinding-Related Classes
Physics-Related Classes
Plugins-Related Classes
IG Plugin
CIGIConnector Plugin
Rendering-Related Classes
VR-Related Classes
Работа с контентом
Оптимизация контента
Материалы
Визуальный редактор материалов
Material Nodes Library
Miscellaneous
Input
Math
Matrix
Textures
Art Samples
Учебные материалы

Unigine::ControlsJoystick Class

Header: #include <UnigineControls.h>
Inherits from: Controls

This class handles joystick input. Generic joysticks can be hot-plugged. So, you can connect your joystick before or after create an instance of this class.

The ControlsJoystick class provides access to the following controller input:

  • Axes detect movement along X and Y axes (if a joystick is two-axis, which is the most typical case) and along Z axis (if it is three-axis one). Two-axis joysticks are configured in such a way that left-to-right movement of the stick is mapped to the movement along the X axis, while movement from backward to forward (down-up) indicates movement along the Y axis. In case of 3D joystick, twisting the stick to the left (counter-clockwise) or to the right (clockwise) corresponds to movement along the Z axis.
    Axes are quired for their states via getAxis(). To provide smooth interpolation between frames and avoid jerks, axis values can be filtered via setFilter().
  • Buttons correspond to the each button on the controller and can be either pressed or unpressed. Just in case with mouse/keyboard controls, they can be mapped to the specific controls states to bind input events and programmed actions.
    You can either bind buttons in the code via setStateButton() or let the user assign the button for a control state via getStateEvent().
  • POV (Point-Of-View) hat switches indicate the direction of view and support a number of positions such as left, right, up and down (similar to a D-pad).

A joystick should update the physical state of all its input controls (i.e. check whether the user has pressed the button, for example) each frame using updateEvents().

See also#

A UnigineScript API sample <UnigineSDK>/data/samples/controls/joystick_00

ControlsJoystick Class

Перечисления (Enums)

POV#

POV (Point-of-View) switch or DPad states.
ИмяОписание
POV_NOT_PRESSED = -1POV (Point-of-View) hat switch or D-Pad (directional pad) button is not pressed.
POV_UP = 0POV (Point-of-View) hat switch or D-Pad (directional pad) is in up position.
POV_UP_RIGHT = 4500POV (Point-of-View) hat switch or D-Pad (directional pad) is in right-up position.
POV_RIGHT = 9000POV (Point-of-View) hat switch or D-Pad (directional pad) is in right position.
POV_DOWN_RIGHT = 13500POV (Point-of-View) hat switch or D-Pad (directional pad) is in down-right position.
POV_DOWN = 18000POV (Point-of-View) hat switch or D-Pad (directional pad) is in down position.
POV_DOWN_LEFT = 22500POV (Point-of-View) hat switch or D-Pad (directional pad) is in down-left position.
POV_LEFT = 27000POV (Point-of-View) hat switch or D-Pad (directional pad) is in left position.
POV_UP_LEFT = 31500POV (Point-of-View) hat switch or D-Pad (directional pad) is in left-up position.

Members


static ControlsJoystickPtr create ( int num ) #

Constructor. Creates a new joystick.

Arguments

  • int num - Joystick number.

bool isAvailable ( ) const#

Checks if the joystick is available.

Return value

1 if the joystick is available; otherwise, 0.

float getAxis ( int axis ) const#

Returns a state value of a given axis. It includes position of the joystick along the following axes: X, Y (two-axis joystick) and Z (three-axis joystick). When a joystick is in the center position, X and Y axes values are zero. Negative values indicate left or down; positive values indicate right or up.

Arguments

  • int axis - Axis number.

Return value

Value in range [-1; 1].

const char * getAxisName ( int axis ) const#

Returns the name of a given axis.

Arguments

  • int axis - Axis number.

Return value

Axis name.

int getButton ( int button ) const#

Returns a button state (pressed or not pressed).

Arguments

  • int button - Button number.

Return value

1 if the button is pressed; otherwise, 0.

const char * getButtonName ( int button ) const#

Returns the name of a given button.

Arguments

  • int button - Button number.

Return value

Button name.

void setFilter ( float filter ) #

Sets a filter value used to correct the current state of the joystick axis relative to the previous one.

Arguments

  • float filter - Filter value for interpolation between axis states. The provided value is clamped to a range [0;1].
    • Filter value of 0 means there is no interpolation and the current value is not corrected.
    • Filter value of 1 means the previous state is used instead of the current one.

float getFilter ( ) const#

Returns a filter value used to correct the current state of the joystick axis relative to the previous one:
  • Filter value of 0 means there is no interpolation and the current value is not corrected.
  • Filter value of 1 means the previous state is used instead of the current one.

Return value

Filter value for interpolation between axis states.

const char * getName ( ) const#

Returns the name of the joystick.

Return value

Joystick name.

int getNumAxes ( ) const#

Returns the number of axes supported by the joystick.

Return value

The number of axes.

int getNumber ( ) const#

Returns the joystick number. There can be several joysticks connected, this number is used to identify a particular one.

Return value

Joystick number.

int getNumButtons ( ) const#

Returns the number of buttons supported by the joystick.

Return value

The number of buttons.

int getNumPovs ( ) const#

Returns the number of POV hat switches supported by the joystick.

Return value

The number of POV hats.

ControlsJoystick::POV getPov ( int pov ) const#

Returns a POV hat switch state. POV hats support the following positions: left, right, up and down.

Arguments

  • int pov - POV pad number.

Return value

One of the following:
  • -1  — not pressed
  • 0  — pressed "up"
  • 4500  — pressed "up" and "right"
  • 9000  — pressed "right"
  • 13500  — pressed "down" and "right"
  • 18000  — pressed "down"
  • 22500  — pressed "down" and "left"
  • 27000  — pressed "left"
  • 31500  — pressed "up" and "left"

const char * getPovName ( int pov ) const#

Returns the name of a given POV hat switch.

Arguments

  • int pov - POV hat number.

Return value

POV hat name.

void setStateButton ( int state, int button ) #

Sets a joystick button that switches a given state on or off.

Arguments

  • int state - State (one of the CONTROLS_STATE_* variables).
  • int button - Button number.

int getStateButton ( int state ) const#

Returns a game pad button that switches a given state on and off.

Arguments

Return value

Button that switches the given state.

void getStateEvent ( int state ) #

Lets the user assign a joystick button to a given state.

Arguments

  • int state - State (one of the CONTROLS_STATE_* variables), to which a button is going to be assigned.

int isStateEvent ( ) const#

Returns a value indicating if a joystick button is successfully assigned to a state.

Return value

1 if a button is already assigned; otherwise, 0.

String getStateName ( int state ) const#

Returns the name of a given state, that was assigned to one of controls.

Arguments

Return value

State name.

int clearButton ( int button ) #

Returns a button state and clears it to 0 (not pressed).

Arguments

  • int button - Button number.

Return value

1 if the button is pressed, and this function was not called previously in the current frame; otherwise, 0.

bool saveState ( const Ptr<Stream> & stream ) const#

Saves ControlsJoystick settings into the stream.

Example using saveState() and restoreState() methods:

Source code (C++)
// initialize a node and set its state
ControlsJoystickPtr joystick = ControlsJoystick::create(1);
joystick->setStateButton(0,1);

// save state
BlobPtr blob_state = Blob::create();
joystick->saveState(blob_state);

// change state
joystick->setStateButton(2,1);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
joystick->restoreState(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the ControlsJoystick settings are saved successfully; otherwise, false.

bool restoreState ( const Ptr<Stream> & stream ) #

Restores ControlsJoystick settings from the stream.

Example using saveState() and restoreState() methods:

Source code (C++)
// initialize a node and set its state
ControlsJoystickPtr joystick = ControlsJoystick::create(1);
joystick->setStateButton(0,1);

// save state
BlobPtr blob_state = Blob::create();
joystick->saveState(blob_state);

// change state
joystick->setStateButton(2,1);

// restore state
blob_state->seekSet(0);				// returning the carriage to the start of the blob
joystick->restoreState(blob_state);

Arguments

  • const Ptr<Stream> & stream - Stream smart pointer.

Return value

true if the ControlsJoystick settings are restored successfully; otherwise, false.

int updateEvents ( ) #

Scans the joystick controls (synchronizes joystick button states with the controller itself). Should be called each frame.
Notice
On Windows, in case a joystick is not connected, this function can substantially increase per-frame update time. (This happens due to calling IDirectInput8::EnumDevices() method.)

Return value

0 if a joystick is not found or updateEvents() already has been called for the frame; otherwise 1.

int getPlayerIndex ( ) const#

Returns the index of player for the joystick. Some devices support connection of multiple players (e.g., XBox 360 supports up to four players connected through XBox 360 gamepads). This method enables you to get this index.

Return value

Player index for the joystick.

int getDeviceType ( ) const#

Returns a value indicating the type of the device (wheel, throttle, etc.).

Return value

Device type. One of the DEVICE_TYPE_* values of the Input class.

float getAxisInitialValue ( int axis ) const#

Returns an initial value for the specified axis.

Arguments

  • int axis - Axis number.

Return value

Current initial value used for the specified axis.

const char * getGuid ( ) const#

Returns the GUID created on the basis of vendor and product identifiers and product version number. It enables you to identify device model (Controller XBox One, etc.), however, it will be the same for two identical models.

Return value

Device model GUID.

int getVendor ( ) const#

Returns a unique identifier of the device manufacturer (vendor). This can be very useful in case your application uses non-standard custom input devices to ensure proper configuration (dead zones, inverse flags, correction curves, etc.).

Return value

Unique identifier of the device manufacturer (vendor).

int getProduct ( ) const#

Returns a unique identifier for the product (GUID). This identifier is established by the manufacturer of the device. This can be very useful in case your application uses non-standard custom input devices to ensure proper configuration (dead zones, inverse flags, correction curves, etc.).

Return value

Unique identifier for the product (GUID).

int getProductVersion ( ) const#

Returns the version of the product established by the manufacturer of the device. This can be very useful in case your application uses non-standard custom input devices to ensure proper configuration (dead zones, inverse flags, correction curves, etc.).

Return value

Version of the product established by the manufacturer of the device.
Last update: 03.09.2022
Build: ()