Before you begin
You should have the following things ready:
- The BlackBerry 10 Native SDK
- Your BlackBerry 10 device
- A basic understanding of the C language and some experience running applications with the Native SDK
- A Bluetooth Human Interface Device (HID) game controller such as:
Create your project
This tutorial walks through the Gamepad sample application available from the NDK-Samples repository on GitHub. This sample contains all the code used to set up, initialize, and process gamepad events and render graphics to the screen. The project includes the bbutil.c and bbutil.h files which provide convenience functions for graphics such as initializing and terminating EGL, rendering textures, and changing the screen orientation. Understanding the bbutil API isn't necessary for this tutorial but if you want more information, take a look at Functions in the bbutil API.
To import the complete project:
- From the NDK-Samples repository on GitHub, download and extract the sample application.
- Launch the Native SDK.
- On the File menu, click Import.
- Expand General, then select Existing Projects into Workspace. Click Next.
- Browse to the location where you extracted the sample app and click OK.
- Click Finish to import the project into your workspace
Using the application
If this application runs with a Bluetooth HID game controller connected to the BlackBerry 10 device, a collection of buttons and analog sticks representing the controller is drawn by the application. This virtual gamepad reacts to input events from the controller. You can assign buttons on the virtual gamepad to physical buttons on the real controller by first tapping a virtual button and then pressing a physical button on the controller. This is similar to how a game allows players to change its controls.
Tapping the Polling button at the bottom of the Gamepad application causes device events to be polled rather than triggered by the Screen and Windowing Library.
If this application runs without a gamepad or joystick connected to the BlackBerry 10 device, the message No device detected appears.
To add support for game controllers to your application, you must first ensure the controller pairs with your BlackBerry 10 device. The SteelSeries Free Mobile Wireless Controller is recommended but any gamepad or joystick compatible with the Bluetooth HID profile should work. The advantage to using a recommended controller, beyond the fact that it's been tested on BlackBerry 10, is that its buttons are mapped to an enumeration in the Screen and Windowing Library. The use of this enumeration is discussed later.
To pair the controller with your BlackBerry 10 device:
- On your BlackBerry 10 device, swipe down from the top of the screen.
- Tap Settings > Network Connections > Bluetooth.
- Ensure Bluetooth is turned on by setting the toggle switch to On.
- Put your controller into pairing mode. This is usually done by holding one or more buttons on the controller for several seconds but it varies by device, so you may need to consult your controller's manual. The table below shows pairing instructions for known devices.
- In the Settings application, select the controller from the list. If the controller doesn't appear right away, you can tap Refresh and try again.
|SteelSeries Free Mobile Wireless Controller||
If this is the first time using the controller, hold down the A button for three seconds to turn on the controller and make it discoverable.
If the controller was previously set to "Arcade Mode" for use with another device, switch it to "Gamepad Mode":
|Nintendo Wii Remote||On the controller, hold down the 1 and
You must wait until the name of the controller resolves on the Bluetooth settings screen (it will start with "Nintendo") before you attempt to pair.
Once the pairing completes, the messages Successfully paired and Successfully connected appear on the BlackBerry 10 device. The first message indicates that the Bluetooth connection is established and the second indicates the controller is recognized as providing a Bluetooth HID service. This service is required for the Gamepad sample app to receive Bluetooth HID events from the controller.
You can test that the controller works by running the completed Gamepad sample app. With your controller connected, you should see a collection of buttons and analog sticks on the screen of the BlackBerry 10 device that light up when you play around with the controller. Now let's move on to the code that makes it happen.