Class: SDL2::GameController

Inherits:
Object
  • Object
show all
Defined in:
gamecontroller.c,
gamecontroller.c

Overview

This class represents a “Game Controller”.

In SDL2, there is a gamecontroller framework to hide the details of joystick types. This framework is built on the existing joystick API.

The framework consists of two parts:

  • Mapping joysticks to game controllers
  • Aquire input from game controllers

Mapping information is a string, and described as:

GUID,name,mapping

GUID is a unique ID of a type of joystick and given by Joystick#GUID. name is the human readable string for the device, and mappings are contorller mappings to joystick ones.

This mappings abstract the details of joysticks, for exmaple, the number of buttons, the number of axes, and the position of these buttons a on pad. You can use unified interface with this framework theoretically. Howerver, we need to prepare the database of many joysticks that users will use. A database is available at https://github.com/gabomdq/SDL_GameControllerDB, but perhaps this is not sufficient for your usage. In fact, Steam prepares its own database for Steam games, so if you will create a game for Steam, this framework is useful. Otherwise, it is a better way to use joystick API directly.

Defined Under Namespace

Modules: Axis, Button

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.add_mapping(string) ⇒ Integer

Add suuport for controolers that SDL is unaware of or to cause an existing controller to have a different binding.

“GUID,name,mapping”, where GUID is the string value from SDL_JoystickGetGUIDString(), name is the human readable string for the device and mappings are controller mappings to joystick ones. Under Windows there is a reserved GUID of “xinput” that covers all XInput devices. The mapping format for joystick is:

  • bX: a joystick button, index X
  • hX.Y: hat X with value Y
  • aX: axis X of the joystick

Buttons can be used as a controller axes and vice versa.

This string shows an example of a valid mapping for a controller: “341a3608000000000000504944564944,Afterglow PS3 Controller,a:b1,b:b2,y:b3,x:b0,start:b9,guide:b12,back:b8,dpup:h0.1,dpleft:h0.8,dpdown:h0.4,dpright:h0.2,leftshoulder:b4,,rightshoulder:b5,leftstick:b10,rightstick:b11,leftx:a0,lefty:a1,rightx:a2,righty:a3,lefttrigger:b6,righttrigger:b7”

Parameters:

  • string (String) —

    mapping string

Returns:

  • (Integer) —

    1 if a new mapping, 0 if an existing mapping is updated.



96
97
98
99
100
 
# File 'gamecontroller.c', line 96

static VALUE GameController_s_add_mapping(VALUE self, VALUE string)
{
    int ret = HANDLE_ERROR(SDL_GameControllerAddMapping(StringValueCStr(string)));
    return INT2NUM(ret);
}

.axis_from_name(name) ⇒ Integer

Get a integer representation of the axis whose string representation is name.

The return value is the value of one of the constants in Axis

Parameters:

  • name (String) —

    a string representing an axis

Returns:

  • (Integer) 


149
150
151
152
153
154
155
156
157
 
# File 'gamecontroller.c', line 149

static VALUE GameController_s_axis_from_name(VALUE self, VALUE name)
{
    int axis = SDL_GameControllerGetAxisFromString(StringValueCStr(name));
    if (axis < 0) {
        SDL_SetError("Unknown axis name \"%s\"", StringValueCStr(name));
        SDL_ERROR();
    } 
    return INT2FIX(axis);
}

.axis_name_of(axis) ⇒ String

Get a string representing axis.

Parameters:

  • axis (Integer) —

    axis constant in Axis

Returns:

  • (String) 


110
111
112
113
114
115
116
117
118
 
# File 'gamecontroller.c', line 110

static VALUE GameController_s_axis_name_of(VALUE self, VALUE axis)
{
    const char* name = SDL_GameControllerGetStringForAxis(NUM2INT(axis));
    if (!name) {
        SDL_SetError("Unknown axis %d", NUM2INT(axis));
        SDL_ERROR();
    }
    return utf8str_new_cstr(name);
}

.button_from_name(name) ⇒ Integer

Get a integer representation of the button whose string representation is name.

The return value is the value of one of the constants in Button

Parameters:

  • name (String) —

    a string representing a button

Returns:

  • (Integer) 


170
171
172
173
174
175
176
177
178
 
# File 'gamecontroller.c', line 170

static VALUE GameController_s_button_from_name(VALUE self, VALUE name)
{
    int button = SDL_GameControllerGetButtonFromString(StringValueCStr(name));
    if (button < 0) {
        SDL_SetError("Unknown button name \"%s\"", StringValueCStr(name));
        SDL_ERROR();
    }
    return INT2FIX(button);
}

.button_name_of(button) ⇒ String

Get a string representing button.

Parameters:

  • button (Integer) —

    button constant in Button

Returns:

  • (String) 


128
129
130
131
132
133
134
135
136
 
# File 'gamecontroller.c', line 128

static VALUE GameController_s_button_name_of(VALUE self, VALUE button)
{
    const char* name = SDL_GameControllerGetStringForButton(NUM2INT(button));
    if (!name) {
        SDL_SetError("Unknown axis %d", NUM2INT(button));
        SDL_ERROR();
    }
    return utf8str_new_cstr(name);
}

.device_names ⇒ Array<String,nil>

Get the implementation dependent name for the game controllers connected to the machine.

The number of elements of returning array is same as Joystick.num_connected_joysticks.

Returns:

  • (Array<String,nil>) 


189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'gamecontroller.c', line 189

static VALUE GameController_s_device_names(VALUE self)
{
    int num_joysticks = SDL_NumJoysticks();
    int i;
    VALUE device_names = rb_ary_new2(num_joysticks);
    for (i=0; i<num_joysticks; ++i) {
        const char* name = SDL_GameControllerNameForIndex(i);
        if (name)
            rb_ary_push(device_names, utf8str_new_cstr(name));
        else
            rb_ary_push(device_names, Qnil);
    }
    return device_names;
}

.mapping_for(guid_string) ⇒ String

Get the game controller mapping string for a given GUID.

Parameters:

  • guid_string (String) —

    GUID string

Returns:

  • (String) 


212
213
214
215
216
 
# File 'gamecontroller.c', line 212

static VALUE GameController_s_mapping_for(VALUE self, VALUE guid_string)
{
    SDL_JoystickGUID guid = SDL_JoystickGetGUIDFromString(StringValueCStr(guid_string));
    return utf8str_new_cstr(SDL_GameControllerMappingForGUID(guid));
}

.open(index) ⇒ SDL2::GameController

Open a game controller and return the opened GameController object.

Parameters:

Returns:

Raises:

  • (SDL2::Error) —

    raised when device open is failed. For exmaple, index is out of range.



228
229
230
231
232
233
234
 
# File 'gamecontroller.c', line 228

static VALUE GameController_s_open(VALUE self, VALUE index)
{
    SDL_GameController* controller = SDL_GameControllerOpen(NUM2INT(index));
    if (!controller)
        SDL_ERROR();
    return GameController_new(controller);
}

Instance Method Details

#attached? ⇒ Boolean

Return true if self is opened and attached.

Returns:

  • (Boolean) 


253
254
255
256
 
# File 'gamecontroller.c', line 253

static VALUE GameController_attached_p(VALUE self)
{
    return INT2BOOL(SDL_GameControllerGetAttached(Get_SDL_GameController(self)));
}

#axis(axis) ⇒ Integer

Get the state of an axis control.

The state is an integer from -32768 to 32767. The state of trigger never returns negative value (from 0 to 32767).

Parameters:

  • axis (Integer) —

    the index of an axis, one of the constants in Axis

Returns:

  • (Integer) 


294
295
296
297
298
 
# File 'gamecontroller.c', line 294

static VALUE GameController_axis(VALUE self, VALUE axis)
{
    return INT2FIX(SDL_GameControllerGetAxis(Get_SDL_GameController(self),
                                             NUM2INT(axis)));
}

#button_pressed?(button) ⇒ Boolean

Return true if a button is pressed.

Parameters:

  • button (Integer) —

    the index of a button, one of the constants in Button

Returns:

  • (Boolean) 


306
307
308
309
310
 
# File 'gamecontroller.c', line 306

static VALUE GameController_button_pressed_p(VALUE self, VALUE button)
{
    return INT2BOOL(SDL_GameControllerGetButton(Get_SDL_GameController(self),
                                                NUM2INT(button)));
}

#destroy ⇒ Object

Close the game controller.

Returns:

  • nil



263
264
265
266
267
268
269
270
 
# File 'gamecontroller.c', line 263

static VALUE GameController_destroy(VALUE self)
{
    GameController* g = Get_GameController(self);
    if (g->controller)
        SDL_GameControllerClose(g->controller);
    g->controller = NULL;
    return Qnil;
}

#destroy? ⇒ Boolean

Return true if the gamecontroller is already closed.

Returns:

  • (Boolean)

#mapping ⇒ String

Get the mapping string of self.

Returns:

  • (String)

See Also:



279
280
281
282
 
# File 'gamecontroller.c', line 279

static VALUE GameController_mapping(VALUE self)
{
    return utf8str_new_cstr(SDL_GameControllerMapping(Get_SDL_GameController(self)));
}

#name ⇒ String

Get the name of an opened game controller.

Returns:

  • (String) 


241
242
243
244
245
246
247
248
 
# File 'gamecontroller.c', line 241

static VALUE GameController_name(VALUE self)
{
    const char* name = SDL_GameControllerName(Get_SDL_GameController(self));
    if (!name)
        SDL_ERROR();

    return utf8str_new_cstr(name);
}