RAII wrapper for SDL_Gamepad (standard layout mapping). More...

#include <mxvk/include/mxvk/mxvk_controller.hpp>

Public Member Functions
bool	active () const
	Check whether the controller is currently usable.
void	close ()
	Close the controller handle if open.
bool	connectEvent (SDL_Event &e)
	Handle a device-added/removed event to maintain connection state.
int	controllerIndex () const
	Return the device index this controller was opened with.
Sint16	getAxis (SDL_GamepadAxis axis) const
	Read the current axis value.
bool	getButton (SDL_GamepadButton button) const
	Test whether a mapped button is currently pressed.
Uint8	getHat (int hat) const
	Read the position of a POV hat.
std::optional< SDL_Gamepad * >	handle () const
	Return the underlying SDL_Gamepad handle as an optional.
std::string	name () const
	Return the controller's name as reported by SDL.
bool	open (int index)
	Open a gamepad by device index.
VK_Controller &	operator= (const VK_Controller &)=delete
VK_Controller &	operator= (VK_Controller &&)=delete
SDL_Gamepad *	unwrap () const
	Unwrap the SDL_Gamepad pointer, asserting it is open.
	VK_Controller ()
	Default constructor — device not yet opened.
	VK_Controller (const VK_Controller &)=delete
	VK_Controller (VK_Controller &&)=delete
	~VK_Controller () noexcept
	Destructor — closes the controller if open.

Static Public Member Functions
static int	joysticks ()
	Return the number of connected joysticks/controllers.

Protected Member Functions
bool	openByInstanceId (SDL_JoystickID instanceId, int index_hint=-1)

Protected Attributes
int	deviceIndex = -1
	Open index in the current gamepad list.
SDL_JoystickID	instanceId = 0
	Stable SDL gamepad instance identifier.
SDL_Gamepad *	stick = nullptr
	Underlying SDL gamepad handle.

Detailed Description

RAII wrapper for SDL_Gamepad (standard layout mapping).

Provides button, hat, and axis queries using SDL's gamepad API, which normalizes button layouts across different physical devices.

Definition at line 114 of file mxvk_controller.hpp.

Constructor & Destructor Documentation

◆ VK_Controller() [1/3]

mxvk::VK_Controller::VK_Controller ( )

default

Default constructor — device not yet opened.

◆ ~VK_Controller()

mxvk::VK_Controller::~VK_Controller ( )

noexcept

Destructor — closes the controller if open.

Definition at line 140 of file mxvk_controller.cpp.

                                           {
        close();
    }

◆ VK_Controller() [2/3]

mxvk::VK_Controller::VK_Controller ( const VK_Controller & )

delete

◆ VK_Controller() [3/3]

mxvk::VK_Controller::VK_Controller ( VK_Controller && )

delete

Member Function Documentation

◆ active()

bool mxvk::VK_Controller::active ( ) const

nodiscard

Check whether the controller is currently usable.

Returns: true if the controller is open and has a valid index.

Definition at line 246 of file mxvk_controller.cpp.

                                     {
        return stick != nullptr && SDL_GamepadConnected(stick);
    }

◆ close()

void mxvk::VK_Controller::close ( )

Close the controller handle if open.

Definition at line 192 of file mxvk_controller.cpp.

                              {
        if (stick != nullptr) {
            SDL_CloseGamepad(stick);
        }
 
        stick = nullptr;
        deviceIndex = -1;
        instanceId = 0;
    }

◆ connectEvent()

bool mxvk::VK_Controller::connectEvent ( SDL_Event & e )

Handle a device-added/removed event to maintain connection state.

Parameters

e	SDL event to inspect.

Returns: true if the event was a controller connect/disconnect.

Definition at line 250 of file mxvk_controller.cpp.

                                                 {
        if (e.type == SDL_EVENT_GAMEPAD_ADDED) {
            return openByInstanceId(e.gdevice.which);
        }
 
        if (e.type == SDL_EVENT_GAMEPAD_REMOVED) {
            if (stick != nullptr && instanceId == e.gdevice.which) {
                close();
            }
            return true;
        }
 
        return false;
    }

◆ controllerIndex()

int mxvk::VK_Controller::controllerIndex ( ) const

Return the device index this controller was opened with.

Returns: Device index.

Definition at line 216 of file mxvk_controller.cpp.

                                             {
        return deviceIndex;
    }

◆ getAxis()

Sint16 mxvk::VK_Controller::getAxis ( SDL_GamepadAxis axis ) const

nodiscard

Read the current axis value.

Parameters

axis	SDL_GamepadAxis constant.

Returns: Axis value in the range [-32768, 32767].

Definition at line 239 of file mxvk_controller.cpp.

                                                                  {
        if (stick == nullptr) {
            return 0;
        }
        return SDL_GetGamepadAxis(stick, axis);
    }

◆ getButton()

bool mxvk::VK_Controller::getButton ( SDL_GamepadButton button ) const

nodiscard

Test whether a mapped button is currently pressed.

Parameters

button SDL_GamepadButton constant.

Returns: true if pressed.

Definition at line 220 of file mxvk_controller.cpp.

                                                                      {
        if (stick == nullptr) {
            return false;
        }
        return SDL_GetGamepadButton(stick, button);
    }

◆ getHat()

Uint8 mxvk::VK_Controller::getHat ( int hat ) const

nodiscard

Read the position of a POV hat.

Parameters

hat	Hat index.

Returns: SDL hat position bitmask.

Definition at line 227 of file mxvk_controller.cpp.

                                                   {
        if (stick == nullptr) {
            return 0;
        }
 
        SDL_Joystick *joystick = SDL_GetGamepadJoystick(stick);
        if (joystick == nullptr) {
            return 0;
        }
        return SDL_GetJoystickHat(joystick, hat);
    }

◆ handle()

std::optional< SDL_Gamepad * > mxvk::VK_Controller::handle ( ) const

nodiscard

Return the underlying SDL_Gamepad handle as an optional.

Returns: std::optional containing the handle, or std::nullopt.

Definition at line 202 of file mxvk_controller.cpp.

                                                           {
        if (stick != nullptr) {
            return stick;
        }
        return std::nullopt;
    }

◆ joysticks()

int mxvk::VK_Controller::joysticks ( )

static

Return the number of connected joysticks/controllers.

Returns: SDL_NumJoysticks() result.

Definition at line 144 of file mxvk_controller.cpp.

                                 {
        int count = 0;
        SDL_JoystickID *ids = SDL_GetGamepads(&count);
        if (ids != nullptr) {
            SDL_free(ids);
        }
        return count;
    }

◆ name()

std::string mxvk::VK_Controller::name ( ) const

Return the controller's name as reported by SDL.

Returns: Device name string.

Definition at line 182 of file mxvk_controller.cpp.

                                        {
        if (stick != nullptr) {
            const char *device_name = SDL_GetGamepadName(stick);
            if (device_name != nullptr) {
                return device_name;
            }
        }
        return "Controller Not Opened.";
    }

◆ open()

bool mxvk::VK_Controller::open ( int index )

Open a gamepad by device index.

Parameters

index SDL gamepad index (0-based) within the current device list.

Returns: true on success.

Definition at line 167 of file mxvk_controller.cpp.

                                            {
        int count = 0;
        SDL_JoystickID *ids = SDL_GetGamepads(&count);
        if (ids == nullptr || index < 0 || index >= count) {
            if (ids != nullptr) {
                SDL_free(ids);
            }
            return false;
        }
 
        const SDL_JoystickID openedInstanceId = ids[index];
        SDL_free(ids);
        return openByInstanceId(openedInstanceId, index);
    }

◆ openByInstanceId()

bool mxvk::VK_Controller::openByInstanceId	(	SDL_JoystickID	instanceId,
		int	index_hint = -1 )

protected

Definition at line 153 of file mxvk_controller.cpp.

                                                                                                 {
        close();
 
        stick = SDL_OpenGamepad(newInstanceId);
        if (stick == nullptr) {
            return false;
        }
 
        deviceIndex = index_hint;
        instanceId = newInstanceId;
        SDL_SetGamepadEventsEnabled(true);
        return true;
    }

◆ operator=() [1/2]

VK_Controller & mxvk::VK_Controller::operator= ( const VK_Controller & )

delete

◆ operator=() [2/2]

VK_Controller & mxvk::VK_Controller::operator= ( VK_Controller && )

delete

◆ unwrap()

SDL_Gamepad * mxvk::VK_Controller::unwrap ( ) const

nodiscard

Unwrap the SDL_Gamepad pointer, asserting it is open.

Returns: Raw SDL_Gamepad pointer.

Definition at line 209 of file mxvk_controller.cpp.

                                             {
        if (stick != nullptr) {
            return stick;
        }
        throw mxvk::Exception("Invalid controller handle");
    }

Member Data Documentation

◆ deviceIndex

int mxvk::VK_Controller::deviceIndex = -1

protected

Open index in the current gamepad list.

Definition at line 204 of file mxvk_controller.hpp.

◆ instanceId

SDL_JoystickID mxvk::VK_Controller::instanceId = 0

protected

Stable SDL gamepad instance identifier.

Definition at line 205 of file mxvk_controller.hpp.

◆ stick

SDL_Gamepad* mxvk::VK_Controller::stick = nullptr

protected

Underlying SDL gamepad handle.

Definition at line 203 of file mxvk_controller.hpp.

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

mxvk/include/mxvk/mxvk_controller.hpp
mxvk/src/mxvk_controller.cpp

MXVK Vulkan Framework 0.24.0 C++20 Vulkan rendering framework for practical 2D and 3D application development with SDL3.

Public Member Functions

Static Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Constructor & Destructor Documentation

◆ VK_Controller() [1/3]

◆ ~VK_Controller()

◆ VK_Controller() [2/3]

◆ VK_Controller() [3/3]

Member Function Documentation

◆ active()

◆ close()

◆ connectEvent()

◆ controllerIndex()

◆ getAxis()

◆ getButton()

◆ getHat()

◆ handle()

◆ joysticks()

◆ name()

◆ open()

◆ openByInstanceId()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ unwrap()

Member Data Documentation

◆ deviceIndex

◆ instanceId

◆ stick