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 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.



99
100
101
102
103
 
# File 'gamecontroller.c', line 99

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) 


152
153
154
155
156
157
158
159
160
 
# File 'gamecontroller.c', line 152

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) 


113
114
115
116
117
118
119
120
121
 
# File 'gamecontroller.c', line 113

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) 


173
174
175
176
177
178
179
180
181
 
# File 'gamecontroller.c', line 173

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) 


131
132
133
134
135
136
137
138
139
 
# File 'gamecontroller.c', line 131

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>) 


192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'gamecontroller.c', line 192

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) 


215
216
217
218
219
 
# File 'gamecontroller.c', line 215

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.



231
232
233
234
235
236
237
 
# File 'gamecontroller.c', line 231

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) 


256
257
258
259
 
# File 'gamecontroller.c', line 256

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) 


297
298
299
300
301
 
# File 'gamecontroller.c', line 297

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) 


310
311
312
313
314
 
# File 'gamecontroller.c', line 310

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



266
267
268
269
270
271
272
273
 
# File 'gamecontroller.c', line 266

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:



282
283
284
285
 
# File 'gamecontroller.c', line 282

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) 


244
245
246
247
248
249
250
251
 
# File 'gamecontroller.c', line 244

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

    return utf8str_new_cstr(name);
}