Adding haptic effects to your Android application

Transcription

1 Adding haptic effects to your Android application Version 1, June 24th, 2011 Immersion Corporation

2 Table of contents 2011 Immersion Corporation. All rights reserved. Adding haptic effects to your Android application Table of contents Why Immersion? What you will learn in this course Who should be taking this course What you should have installed before starting the class What will be provided to you in class The science of haptics The benefits of haptics Examples of haptic effects and implementations Immersion s haptic technologies Exploring prebuilt effects using the Haptic Effect Preview application Exercise 1: Exploring prebuilt effects in an Android application Understanding the Universal Haptic Layer (UHL) Exercise 2: Adding the UHL package to the Bouncing Ball application Set up an Eclipse project Add the Universal Haptic Layer (UHL) package Add the jar file Right-click on the BouncingBall project in the Eclipse Package Explorer and choose Build Path > Configure Build Path. Add the Javadocs for the UHL Expand the UHL.jar directory and select Javadoc location. Add the native library file Adjusting an application s manifest file Exercise 3: Adjust the Bouncing Ball application s manifest file Disabling automatic haptic feedback Adding prebuilt haptic effects to an application Playing a haptic effect Stopping a haptic effect Exercise 4: Adding prebuilt haptic effects to the Bouncing Ball application Importing the Launcher class Playing the haptic effect Stopping the haptic effect Running an application to test haptic effects Exercise 5: Test the haptic effect applied to the Bouncing Ball application Haptic power modes

3 Exercise 6: Add different power variants of the Bounce effect to the Bouncing Ball application Appendix A: Configure ProGuard Appendix B: Android NDK Additional Resources

4 Who is Immersion? About Immersion Corporation: Immersion has been a leader in the research, development and delivery of haptics since our formation in Immersion technology has shipped in hundreds of millions of devices worldwide, including gaming peripherals, mobile phones, tablets, medical devices, touchscreen kiosks, casino games, digital cameras, and automotive applications. Our extensive technology and expertise allows us to offer the most comprehensive series of solutions available. Problem Statement: Research has shown that consumers find a mobile experience with haptics more intuitive, engaging and informative than simple touch interfaces. The key to delivering on the promise of a superior haptics mobile experience is twofold: 1) Integrating highresolution haptics technology to communicate meaningful & nuanced information 2) Ensuring that the technology is well implemented at both the OS and the application level to create a consistent but context-sensitive experience. Hundreds of millions of phones and tablets have shipped with haptics, and advancements in haptics technology have improved resolution and enabled advanced effects, but the haptics mobile experience has been hampered by underutilization in the user interface (UI) and applications. This is primarily due to the complexity of integrating haptics in the UI and the lack of API access for mobile application developers. The Immersion Solution: With the continued success of Android as the dominant OS in the smart phone marketplace, Immersion now has access to a development platform that is capable of addressing the complexities of haptics for the mobile ecosystem. Immersion is announcing a revolutionary new tool for the Android platform, the Immersion MOTIV Development Platform. MOTIV provides a set of software development tools that allows Mobile OEMs, Carriers and Application Developers to easily deliver a HD haptics experience through automated integration tools and effects libraries that simplify customization at the UI and the application levels. The Immersion MOTIV Development Platform for Android is an innovative software solution for OEMs, Carriers and Application Developers that enables a HD haptics experience through tighter integration of haptics into the Android UI and applications. The MOTIV Development Platform is comprised of two key elements, the MOTIV Integrator for OEMs and the MOTIV SDK for application developers. For this course, we will only address MOTIV SDK for application developers. MOTIV SDK: Our SDK makes it simple for application developers to implement haptics by providing simple code samples that developers can use to insert haptics into their applications. The MOTIV SDK enables haptic effects on ALL Android handsets in the market, allowing the developers to have a single code base and avoid fragmentation. The SDK comes with a number of valuable features, including:

5 developer.immersion.com: Our new developer site filled with resources to provide developers with the latest releases of our SDK, as well as helpful tools like: sample code, best practices, handset compatibility, the latest applications using MOTIV and a forum developer s can access to help get their questions answered. Also included on the developer s site: Universal Haptic Layer (UHL): Automatically optimizes haptics effects based on the handset the consumer is using and includes effects libraries: Immersion has developed over 100 individual effects that developers can select to incorporate into their applications. Categories of effects include: textures, explosions, engines, weapons, alerts, clicks, bounces, and even impacts made on different materials, like wood, rubber and metal. MOTIV Studio: For more advanced developers, the MOTIV Studio program offers the ability to edit existing haptic effects or create entirely new effects from scratch. UHL Effect Preview: An Android Application that is used by developers to preview effects on their handset. Effect Preview doesn t require any PC tethering, making it easy for Android developers to quickly test how effects will feel on different handsets. Developer Values: The MOTIV Development Platform delivers a superior user experience Customizing applications to include haptics creates a more fun and exciting user experience Differentiation: Games with haptics are a way to differentiate your application in a crowded marketplace, as users look for applications that take advantage of their haptics technology Realism: Haptics brings an element of realism to applications that are not available through normal vibrations or non-haptics environments Stickiness: A superior user experience makes for a sticky application, users are more engaged. Control: The MOTIV Development Platform provides an opportunity for application developers to have greater control over the user experience With Immersion s MOTIV Development Platform, you will be the first to market with next-gen technology Hundreds of millions of users have haptics technology in them, but users have never been able to download applications with this level of customization before Differentiate your application in the market Bringing an arcade experience to a handset/high performance console gaming. Bring rumble to the handset. Attract the early adopters and garner attention as a technology leader

6 Immersion s MOTIV Development Platform is straightforward and easy to use Immersion s tools are comprised of pre-designed haptic effects, customization tools, and simple code samples that can be inserted into your application, making it simple to add a custom haptic experience Tools are easily accessible through the MOTIV Development Platform developer s portal Today, mobile developers have simple turn on/turn off features for haptics. With the MOTIV Development Platform, they will have many more colors in the palette to paint from Immersion as already done the hard work and prebuilt hundreds of effects, from a simple button press to explosions to textures Immersion provides sample code, reference effects, reference games and more to mobile developers

7 What you will learn in this course In this course, you will learn about haptic effects and how to include them in your Android applications. Topics include: The science of haptics Why use haptics? Examples of haptic effects and implementations Immersion s haptic technologies Adding haptics to an application Understanding the Universal Haptic Layer (UHL) Exploring prebuilt effects using the Haptic Effect Preview application Adjusting an application s manifest file Disabling automatic haptic feedback Adding prebuilt haptic effects to an application Running an application to test haptic effects Who should be taking this course This course targets experienced Android developers who have practical experience with: Android architecture The life cycle of components Event handling Debugging an application Deploying an application to a device

8 What you should have installed before starting the class As an experienced Android developer, you should attend class with these items installed on your computer: Java SE Eclipse Android SDK Android Developer Tools From within Eclipse s Install new Software option, point to UHL Package tegory&layout=blog&id=119&itemid=592 For detailed instructions on installing the Android SDK and Android developer tools, see: What will be provided to you in class This course focuses on integrating haptics into an existing Android application: Bouncing Ball ( Itemid=659). The following files will be provided to you in class: BouncingBall_Starter.zip (Eclipse project file) BouncingBall_Starter.apk BouncingBall_Solution.zip (Eclipse project file) BouncingBall_Solution.apk

9 The science of haptics In this context, haptics is the science concerned with how people explore the environment through touch, or tactile feedback. The role of touch, as a sense, is often underestimated. We rely extensively on touch input to control the movement of our bodies and to perceive the world around us have you ever tried to walk when your foot was asleep? Haptic interaction with the physical environment relies on mechanical signals such as contact forces, torques, movement of objects and limbs, mass, geometry and weight of objects, stiffness and texture of materials, etc. Haptic perception in virtual environments relies on sensory signals simulated by haptic interfaces. Haptic interfaces use actuators to create haptic sensations. For example, by delivering a perfectly timed and tuned set of vibrations, a user is able to perceive the edges of a button while running their finger across a screen what is actually a two-dimensional display. Haptic interfaces use the sense of touch to provide environmental cues. Figure 1: A carefully timed and tuned vibration can simulate the pressure felt when running a finger over a change in surface.

10 You ve probably experienced haptics in many of the consumer devices that you use every day. The rumble effect in your console game controller and the reassuring touch vibration you receive on your smart-phone dial-pad are both examples of haptic effects. In the world of mobile devices, computers, consumer electronics, and digital devices and controls, meaningful haptic information is frequently limited or missing. For example, when dialing a number or entering text on a conventional touchscreen without haptics, users have no sense of whether they ve successfully completed a task. With haptic technology, users feel the vibrating force or resistance as they push a virtual button, scroll through a list or encounter the end of a menu. In a video or mobile game with haptics, users can feel the gun recoil, the engine rev, or the crack of the bat meeting the ball. When simulating the placement of cardiac pacing leads, a user can feel the forces that would be encountered when navigating the leads through a beating heart, providing a more realistic experience of performing this procedure. Haptics can enhance the user experience through: Improved Usability: By restoring the sense of touch to otherwise flat, cold surfaces, haptics creates fulfilling multi-modal experiences that improve usability by engaging touch, sight and sound. From the confidence a user receives through touch confirmation when selecting a virtual button to the contextual awareness they receive through haptics in a first person shooter game, haptics improves usability by more fully engaging the user s senses. Enhanced Realism: Haptics inject a sense of realism into user experiences by exciting the senses and allowing the user to feel the action and nuance of the application. This is particularly relevant in applications like games or simulations that rely on only visual and audio inputs. The inclusion of tactile feedback provides additional context that translates into a sense of realism for the user. Restoration of Mechanical Feel: Today s touchscreen-driven devices lack the physical feedback that humans frequently need to fully understand the context of their interactions. By providing users with intuitive and unmistakable tactile confirmation, haptics can create a more confident user experience and can also improve safety by overcoming distractions. This is especially important when audio or visual confirmation is insufficient, such as industrial applications, or applications that involve distractions, such as automotive navigation. The potential for haptics in computer interface design goes beyond using touch to simulate forces found in nature. Haptics can be used to develop a tactile language that consistently delivers touch cues to reinforce typical interactions. A simple example of this, in wide use today, is the delivery of different vibrations to signal incoming calls, incoming text messages, etc., on a mobile device. In this course we will explore a sample application, Bouncing Ball, that uses tactile feedback to provide dimension to a library of visual objects.

11 Learn more about haptics: International Society for Haptics Haptics-e Haptics Laboratory

12 The benefits of haptics Here are some ways that haptics can improve your applications: Haptics-enabled content, such as navigational cues, ringers, or games enhance the user's experience, making it more engaging, intuitive, and personal. Touch sensations make navigating software user interfaces easier by assisting with hand-eye coordination and confirming completed tasks. Sensations, such as unique vibrating effects, assist in identifying callers without the use of sound. Touch sensations can replace or complement graphical cues to diminish problems with screen glare or when looking at the screen is inconvenient, such as receiving an alert during a call. Surveys show a clear and measurable preference for haptic-enabled applications: 90% of respondents indicated a preference for haptics in their next phone. 95% of users surveyed perceived next-generation, haptic-enabled applications to be of high value.

13 Examples of haptic effects and implementations Immersion provides developers with a library of more than 100 prebuilt haptic effects each available in three different amplitudes (strengths). You can view a complete list in the Immersion Developer Center ( Itemid=814). You can also sample these effects on your Android device by downloading and installing the Immersion Developer Effects Preview from the Android Marketplace. If you own a modern touch-screen device, you have likely experienced haptic effects. The Android OS for example, uses haptics (when enabled) to provide a sense of touch to the action of unlocking your phone or dialing using the keypad. Figure 2 shows other examples of hapticsenabled experiences (Figure 2). Figure 2: These are three examples of applications that use haptics to enhance the user experience.

14 Immersion s haptic technologies Immersion makes haptic player technology (TouchSense) for device manufacturers as well as resources and tools for application developers. When you combine Immersion-based player and development technologies, you can create unique, high fidelity haptic experiences. While Immersion player technology is being adopted by an increasing number of manufacturers, your application will need to talk to devices that don t have it. Immersion provides developers with a software emulator that controls the existing vibrator on an Android device (Figure 3). Figure 3: Haptic effects can be delivered to devices with or without Immersion TouchSense technology on board.

15 While the Android SDK allows access to device vibrators, the fine control necessary to deliver a meaningful, consistent haptic-experience requires either a haptic player or emulation software. It is Immersion s emulator that facilitates realistic haptic experiences on devices that do not incorporate Immersion TouchSense or other player technology.

16 Adding haptics to an application Immersion provides Android developers with a Universal Haptic Layer (UHL) that includes a library of more than 100 prebuilt haptic effects. You can also use Immersion s MOTIV Studio to easily create your own custom haptic effects. MOTIV Studio works in tandem with MOTIV Bridge to allow you to test effects on an Android device (Figure 4). Figure 4: The Universal Haptic Layer, MOTIV Studio, and MOTIV Bridge are the three core components of the Immersion developer technologies. In the first half of this course you will learn how to add haptic effects to an existing application using the UHL. In the second half of this course you will learn how to develop custom effects using MOTIV Studio and MOTIV Bridge.

17 Exploring prebuilt effects using the Haptic Effect Preview application You will select prebuilt haptics from a list maintained here: emid=814 You can experience these prebuilt effects using Immersion s UHL Effect Preview application available in the Android Marketplace (Figure 8). Figure 5: These are screen captures from Immersion s UHL Effect Preview application.

18 In the preview application, effects are organized by type (Table 1). Many effects are available in different powers and each variant is identified by a unique ID number. Power is typically expressed as High (100%), Mid (66%) or Low (33%). ID range Effect Type 0-11 Single Double Triple Buzz Ramp up Ramp down Pulse Buzz-Bump Alert Explosion Weapon Collision Texture Engine Table 1: UHL Effect categories representing 123 total prebuilt effects as of this writing. Note: In Exercise 4 you will be using the prebuilt haptic effect: ID 9, Bounce-High. In Exercise 6, you will adjust the power of the Bounce-High effect based on input. You will do this by implementing ID 10, Bounce-Mid and ID 11, Bounce-Low.

19 Exercise 1: Exploring prebuilt effects in an Android application In this exercise, you will use your Android device to: Install and explore a version of the sample application (Bouncing Ball) that does not include haptic effects. Download and explore Immersion s UHL Effect Preview application. Install and explore a version of the sample application that does employ haptic effects. Install the Bouncing Ball starter file 1. Install BouncingBall_Starter.apk (provided in class) using the command line tool adb (Android Debug Bridge). Note: The Android Debug Bridge is installed on your computer as part of the Android SDK. Use the command: adb install <path_to_apk> 2. Launch the Bouncing Ball application on your device. 3. Manipulate the device to move the ball and notice that it bounces off of the display edges. Explore the UHL Effect Preview application 4. Download and install Immersion UHL Effect Preview from the Android Marketplace. 5. Launch the application. 6. Navigate through the various categories to try out different effects.

20 Install the Bouncing Ball solution file 7. Install BouncingBall_Solution.apk using the command line tool adb. Note: When switching between the starter and solution applications on your device, you must delete one before installing the other. 8. Launch the application on your device. 9. Manipulate the device and notice the haptic effects that are delivered when the ball contacts an edge.

21 Understanding the Universal Haptic Layer (UHL) You can download the Universal Haptic Layer (UHL) package in the Immersion developer center ( =blog&id=119&itemid=592). The UHL package consists of three files: UHL.jar: Java library containing the UHL implementation. Java applications using the UHL must link with this library. libemmulatorj.so: Native library for ARM, containing the emulator (TouchSense 3000) implementation. Applications using the UHL must link with this library. UHLdoc.zip: Documentation in javadoc format. This provides context-sensitive help for UHL classes in Eclipse. You will need these three files in the following exercise and will use them throughout the course.

22 Exercise 2: Adding the UHL package to the Bouncing Ball application In this exercise you will set up an Eclipse project using the starter file provided to you and then add the UHL package to the project. Set up an Eclipse project The first step is to create a new Eclipse project and then import the Bouncing Ball source code (See: What will be provided to you in class). 1. In Eclipse, select File > Import > General > Existing Projects into Workspace. 2. Select Next and choose the radio button for Select archive file. 3. Enter the path to the file BouncingBall_Starter.zip that you downloaded earlier. 4. Click Finish. You now have the Bouncing Ball source code in the Eclipse environment. Add the Universal Haptic Layer (UHL) package 5. Unzip the UHL package that you downloaded earlier. You will see three files: UHL.jar libemmulatorj.so UHLdoc.zip Add the jar file 6. Right-click on the BouncingBall_Starter project in the Eclipse Package Explorer and choose Build Path > Configure Build Path. 7. Select the Libraries tab and click on Add External JARs. 8. Browse to where you unzipped the UHL package and select the UHL.jar file. Notice the UHL.jar file added to the project.

23 Figure 6. Add the UHL.jar file to the BouncingBall project in the project s build path. Add the Javadocs for the UHL 9. Expand the UHL.jar directory and select Javadoc location. 10. Click Edit.

24 Figure 7. Click to edit the Javadoc location. 11. In the Javadoc For UHL.jar window, click Javadoc in archive. 12. To set the Archive path, browse to your unzipped UHL package and select UHLdoc.zip.

25 Figure 8. Browse to select the UHLdoc.zip for the Archive path. 13. Click OK. Add the native library file 14. Create a new folder armeabi, inside the libs folder in your project directory. 15. Copy the libimmemulatorj.so file from the UHL package and paste it into the new armeabi folder. Note: If you are using NDK, reference Appendix B for details on how to configure your environment for the UHL native library.

26 Adjusting an application s manifest file All of the prebuilt haptic effects require Android SDK version 7 (Eclair) and above. You must make this declaration in the application s manifest file. You must also set the VIBRATE permission.

27 Exercise 3: Adjust the Bouncing Ball application s manifest file In this exercise, you will make changes in the manifest file for the BouncingBall project to add the VIBRATE permission and to specify the Android SDK version. 1. In Eclipse, within the BouncingBall_Starter project, open AndroidManifest.xml in the root directory. 2. Locate the tag <uses-sdk android:minsdkversion= 3 /> and change the value of the minsdkversion to 7. Your code should look like this: <uses-sdk android:minsdkversion= 7 /> 3. After the application tag block, add the following code for the VIBRATE permission: <uses-permission android:name="android.permission.vibrate" /> 4. Save the file.

28 Disabling automatic haptic feedback The Android user interface automatically applies haptic feedback (when enabled) to certain interface components depending on configuration. Since you will be providing haptic feedback through the UHL, and since you don t know how the device has been configured, you must disable automatic feedback on a per-instance basis. You can do this in two ways: In the layout s XML file, add the property for the specific component: <Button android:layout_weight="0" android:layout_width="fill_parent" android:layout_height="wrap_content" android:layout_margintop="10px" android:text="@string/btnplaymag" android:hapticfeedbackenabled="false" android:onclick="btnplaymagsweepclicked" /> In Java code, you can set a boolean value for the property sethapticfeedbackenabled on a UI component: mbtnper.sethapticfeedbackenabled(false);

29 Adding prebuilt haptic effects to an application When adding a prebuilt haptic to your application, you must import the Launcher class in the UHL API. You must then instantiate the Launcher object in order to play the chosen effect. Importing the Launcher class The Launcher class is used to start and stop playing built-in effects. You must import this class for use. import com.immersion.uhl.launcher; The UHL provides many classes to aid you in adding haptics to your application. Refer to this documentation for more information: =765 Note: You will deal with other classes when adding custom effects (covered later). Instantiating a Launcher object You must instantiate the Launcher object before you can use it in the code. This is typically done in the oncreate() method of your Android Activity. You create a Launcher object by calling the Launcher constructor and passing in the context of the Activity: /** Called when the Activity is first created. public void oncreate(bundle savedinstancestate) super.oncreate(savedinstancestate); setcontentview(r.layout.main); try mlauncher = new Launcher(this); } catch (Exception e) Log.e("My App", "Exception!: " + e.getmessage());

30 } } You can learn more about the Launcher object here: =783 Playing a haptic effect After you have created and instantiated a Launcher object, you can use it at any point in your application to provide haptic feedback. For example, you might play a short double click effect on a button click: public void btnplayeffectclicked(view view) try mlauncher.play(launcher.double_strong_click_100); } catch (Exception e) Log.e("My App", "Exception!: " + e.getmessage()); } }

31 Stopping a haptic effect If a haptic effect is playing, you must stop it once you exit from the activity. This is typically done in the onpause() event of the Android lifecycle. protected void onpause() super.onpause(); } // stop vibration effect on application pause try m_launcher.stop(); } catch (RuntimeException re) Log.e("My App", "Exception!: " + re.getmessage()); }

32 Exercise 4: Adding prebuilt haptic effects to the Bouncing Ball application In this exercise, you will add code to the Bouncing Ball application to: Import the Launcher class Create an instance of Launcher class for an Activity Play a haptic effect when the ball bounces off the edge of the screen The effect that you are adding is Bounce - High Power, with an ID of 9. Importing the Launcher class 1. In Eclipse, within the BouncingBall_Starter project, open BouncingBallActivity.java. 2. Add an import statement for the Launcher class to the list of imports: import com.immersion.uhl.launcher; Instantiating a Launcher object for an Activity 3. Create a private variable for the Launcher object in the BouncingBallActivity class: private Launcher m_launcher; 4. Within the oncreate() method, add code to create an instance of the Launcher object as shown here: protected void oncreate(bundle savedinstancestate) super.oncreate(savedinstancestate); setcontentview(r.layout.main); m_view = (BouncingBallView)findViewById(R.id.bouncingballview);

33 PowerManager pm = (PowerManager) getsystemservice(context.power_service); m_wakelock = pm.newwakelock(powermanager.full_wake_lock, "DoNotDimScreen"); // initialize UHL vibration object try m_launcher = new Launcher(this); } catch (RuntimeException re) } } m_nextcollision = 0; m_view.getphysicsworld().setcontactlistener(m_contactlistener); Playing the haptic effect 5. Within the same class, locate the ContactListener event handler for the moving ball. Note: The ContactListener class is a gaming class that lets you control how an object will react to a collision. This class is available as part of the org.jbox2d.dynamics package and is open source. Please refer to this link to learn more about this class /org/jbox2d/dynamics/ContactListener.java.htm 6. Add code for playing the haptic as shown here: private ContactListener m_contactlistener = new ContactListener() public void add(contactpoint contactpoint) } public void persist(contactpoint contactpoint)} public void remove(contactpoint contactpoint) } public void result(contactresult contactresult) if (contactresult.normalimpulse >= MIN_COLLISION_IMPULSE) long time = System.currentTimeMillis(); // effects played too fast blur together if (time >= m_nextcollision)

34 }; } } } // choose a suitably strong collision effect try m_launcher.play(launcher.bounce_100); } catch (RuntimeException re) } m_nextcollision = time + MIN_COLLISION_TIME; Stopping the haptic effect 7. Within the same class, locate the onpause() method. 8. Add code for stopping the haptic effect as shown here: protected void onpause() super.onpause(); m_wakelock.release(); m_view.pause(); } // stop vibration effect on application pause try m_launcher.stop(); } catch (RuntimeException re) } 9. Save this file.

35 Running an application to test haptic effects You will test the haptic effects in your application by installing it on your device and running it. Connect your android device to your machine using a USB cable and simply Run the application within Eclipse. This automatically downloads and launches the application.

36 Exercise 5: Test the haptic effect applied to the Bouncing Ball application In this exercise, you will run the application on an Android device to test the haptic effect that is launched when the ball strikes and edge. 1. Connect your device to your desktop using a USB cable. 2. In Eclipse, select the BouncingBall_Starter project and click Run > Run from the main menu. Note: When switching between the starter and solution applications on your device, you must delete one before installing the other. 3. On the device, notice the Bouncing Ball application being installed and launched. 4. Manipulate the device to move the ball and test the haptic effect.

37 Haptic power modes As discussed previously, many effects are available in different power modes. You can use different versions of the same effect to control the intensity of a haptic effect. You might want a subtle haptic reaction in some instances and a more pronounced effect in others. Here is an example of a haptic effect available in three different powers: ID Name Description 0 Sharp Single Click - High Power Click Effect, Narrow Pulse, 100% Power 1 Sharp Single Click - Mid Power Click Effect, Narrow Pulse, 66% Power 2 Sharp Single Click - Low Power Click Effect, Narrow Pulse, 33% Power Table 2: Example of an effect available in three different power settings. Note: The Launcher Class has all of the constants defined for all of the effects but the names vary slightly for example, Sharp Single Click -High Power is SHARP_CLICK_100 Based on design requirements, you can add code to your application to make it play different power variants of a haptic effect for different events.

38 Exercise 6: Add different power variants of the Bounce effect to the Bouncing Ball application In this exercise, you will add code to play a different haptic effect based on the intensity of the collision. If the ball collides with the edge at a high intensity, you will play ID 9: Bounce-High (Bounce_100)). If the ball collides at a medium intensity, you will play ID 10: Bounce-Mid (Bounce_66). If the ball collides at low intensity, you will play ID 11: Bounce-Low (Bounce_33). 1. In Eclipse, within the BouncingBall_Starter project, open BouncingBallActivity.java. 2. Within the same class, locate the ContactListener event handler for the moving ball. 3. Within the try loop, add code to determine collision strength: private ContactListener m_contactlistener = new ContactListener() public void add(contactpoint contactpoint) } public void persist(contactpoint contactpoint)} public void remove(contactpoint contactpoint) } public void result(contactresult contactresult) if (contactresult.normalimpulse >= MIN_COLLISION_IMPULSE) long time = System.currentTimeMillis(); // effects played too fast blur together if (time >= m_nextcollision) // choose a suitably strong collision effect try float strength = (contactresult.normalimpulse - MIN_COLLISION_IMPULSE) / (MAX_COLLISION_IMPULSE - MIN_COLLISION_IMPULSE); if (strength < 0.34f) m_launcher.play(launcher.bounce_33); else if (strength < 0.67f) m_launcher.play(launcher.bounce_66); else m_launcher.play(launcher.bounce_100); }

39 catch (RuntimeException re) } }; } } } m_nextcollision = time + MIN_COLLISION_TIME; 4. Save this file. 5. Run the application and notice the different haptic effects based on collision intensity.

40 Appendix A: Configure ProGuard ProGuard is a tool built in to the Android build that optimizes and obfuscates application code. When using ProGuard, developers must configure it to work with the Universal Haptic Layer. To configure ProGuard, open the proguard.cfg file and add these lines to the end of the file: -dontwarn com.immersion.** -dontnote com.immersion.**

41 Appendix B: Android NDK If your application is using NDK and needs to include haptics, you may add the UHL native library as a prebuilt library (requires NDK r5b or later). Since build systems vary, please refer to the Android NDK Dev Guide for complete details on using prebuilt libraries with the NDK. Using the UHL native library instead of the complete UHL java interface has some tradeoffs. Several features of the UHL will be bypassed if you choose to use the native library directly. These include: Built-in effect support (Launcher class) TouchSense Emulator (the application will only play effects on devices containing the TouchSense Player) Version compatibility (the application will only play effects on devices containing the TouchSense Player that matches the version number of the UHL native library being used. For example, you app will run on devices that have TouchSense 3.4.*, but not on devices with TouchSense 3.3 or 2.0) Note: NDK users will have to implement a C-to-Java interface for accessing UHL since UHL is a Java library. The instructions below represent a typical build configuration. You must follow these to add the UHL native library to your project. 1. In most cases, your native source will be located in the jni subdirectory of your project folder. In the jni directory, create a new subdirectory called libimmemulatorj. 2. Place libimmemulatorj.so in the newly created jni/libimmemulatorj directory. 3. Add a new Android.mk file to this folder that contains this code: LOCAL_PATH := $(call my-dir) include $(CLEAR_VARS) LOCAL_MODULE := ImmEmulatorJ-prebuilt LOCAL_SRC_FILES := libimmemulatorj.so include $(PREBUILT_SHARED_LIBRARY) 4. Now you must explicitly call this new Android.mk file located in the libimmemulatorj folder from the Android.mk located in the jni folder. To do this, add the following to the end of your Android.mk file:

42 include $(call all-makefiles-under,$(local_path)) 5. Launch your NDK build. In addition to compiling your own native libraries, the NDK will copy libimmemulatorj.so into your project s libs/armeabi directory. 6. In Eclipse, right-click on the application project and choose Refresh. You should see libimmemulatorj.so under armeabi.

43 Additional Resources Android Developer website:

44 LEGAL DISCLAIMERS General Disclaimer. Although Immersion has attempted to provide accurate information in this document, Immersion assumes no responsibility for the accuracy of the information. Mention of non-immersion products or services is for information purposes only and constitutes neither an endorsement nor a recommendation. THIS DOCUMENT, INCLUDING ALL CONTENT AND INFORMATION CONTAINED HEREIN ARE PROVIDED ON AN "AS IS" BASIS. IMMERSION EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND, WHETHER EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND WARRANTIES ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE. Intellectual Property. The trademarks, logos and service marks ("Marks") displayed in this document are the property of Immersion or other third parties. You are not permitted to use these Marks without the prior written consent of Immersion or such appropriate third party. All information in this document is (and shall continue to be) owned exclusively by Immersion or other third parties, and is protected under applicable copyrights, patents, trademarks, trade dress, and/or other proprietary rights, and the copying, redistribution, use or publication by you of any such information or any part of this document is prohibited. Under no circumstances will you acquire any ownership rights or other interest in any information contained herein by or through your use of this document Immersion Corporation. All rights reserved. Complying with all applicable copyright laws is the responsibility of the reader. Without limiting the rights under copyright, no part of this document may be reproduced without the express written permission of Immersion Corporation. Immersion, the Immersion logo, MOTIV and TouchSense are trademarks of Immersion Corporation in the United States and other countries. All other trademarks are the property of their respective owners. immersion.com Fox Lane San Jose, California 95131