This section presents a step-by-step guide to building an application that leverages the Android NDK. Before jumping into the code, let’s walk through the high-level func- tionality of the application, which is named UA2EFindingEdges, including screen- shots showing the application in action. After the demo of the application, we examine each of the pieces of code to construct the application from the ground up.
Table 19.1 Build steps for an NDK library
Step Comment
Create Android project The starting point is to have an Android project to work with.
Create library source folder Use the name jni (short for Java Native Interface). This folder contains C source plus project-specific make files.
It should be at the same level as the src folder within a standard Android project folder structure.
Create C source file This file contains the implementation of the native library.
This code may be split among multiple C source files.
Create Android.mk This is the configuration (or make) file for the native library. An example is provided later in this chapter.
Change directory to library source folder The NDK must be run from within your jni folder.
Execute NDK Type ndk-build from the command line to execute the
build script. This processes a series of make files that perform all of the compilation and linking of the library.
The result is a file ready for inclusion in the APK file.
Optional step:
integrate NDK into project’s build
Ideally modifying and saving the C source file will result in the complete build of the application, including both SDK and NDK aspects. Taking the time to do this makes the development process much more appealing.
Look for any compilation or linking errors Any coding or configuration errors will become apparent as lines written to the standard output and standard error of the console where the script was executed. If run from within Eclipse, the output is shown in the console window.
19.2.1 Demonstrating the completed application
The sole function of this application is to convert a photograph into a grayscale image, showing the edges of the object within the photograph. The application is writ- ten in Java using the Android SDK with a minimalist interface, as shown in figure 19.2.
Selecting the Acquire Image button launches the built-in Camera application with default image settings. Take a photo. Figure 19.3 shows an image taken of a model race car body.
Clicking the OK button in the Camera application brings the photo back to our sam- ple application and displays the image. The Find Edges button is now available, as shown in figure 19.4.
Figure 19.2 Application waiting to take a photo
Figure 19.3 Take a photograph.
Figure 19.4 Captured image before image processing
It’s now time to exercise the primary function of this application: the edge-detection routine. See figure 19.5.
After the Find Edges button is selected, the application performs two consecutive image-processing routines, each of which is implemented in the C language JNI library. The first function converts the color image to grayscale, which is a common technique in image-processing algorithms. After the image has been converted, a transformation known as the Sobel Edge Detection algorithm is performed to highlight the edges in the photograph. Once the image processing is complete and the image updated, the application is ready to acquire a new image.
The image-processing prowess of this application is hardly groundbreaking, but the application is fun to play with and presents a sufficiently complex problem to solve with the NDK. You’re encouraged to follow along in the next section and build this application for yourself. If you’d like to just use the application, it’s available for down- load in the Android Market.
19.2.2 Examining the project structure
The application consists of two primary parts.
The first is the Android SDK-based Java code, which contains the application structure, the UI, the click handlers, code to display the images, and all of the usual AndroidManifest.xml goodies required to make the application run on an Android device. The second portion of the appli- cation is the image-processing library built with the NDK. The library contains the two image-pro- cessing functions, written in C and exported for use by the user interface code. Figure 19.6 shows the project as it looks in Eclipse.
This project looks like every other Android project you’ve worked with to date, with the addi- tion of the jni and libs folders.
Figure 19.5 Showing the edges of the car
Figure 19.6
A project in the Eclipse GUI
The jni folder contains three files of interest: the C language file and two make files. The output.txt file is created by the NDK build subsystem.
The libs folder contains output files from the NDK build process targeted for dif- ferent CPU architectures. The topic of which CPU target to use is beyond our objec- tives in this chapter—you can learn more about processor-specific settings in the readme files in the NDK’s docs folder.
Let’s start with a look at the JNI code.