August 2012

Creating an OpenCL-enabled Android App with PGCL

by Sebastien Deldon, PGI Compiler Engineer

PGCL is an OpenCL compiler framework for ARM processor-based Systems-on-Chip (SoCs). It allows developers to create applications that run in parallel across multiple ARM CPU cores with NEON/SIMD extensions as an OpenCL compute device. PGCL is designed to be extensible, to allow for support of other types of OpenCL compute devices in the future. It gives ARM developers an avenue to create applications that are multi-core enabled, inherently scalable, and forward-portable to the coming accelerator-enabled mobile platforms.

PGCL can be used in combination with the Eclipse IDE and Dalvik (the Android Java environment) to create Android Apps in which compute-intensive portions of the App are accelerated on multiple ARM cores using OpenCL kernel functions. Most Android Apps are written in Java using the Android SDK (Software Development Kit), which allows some features to be written in the C language and made available within a Java App using the JNI (Java Native Interface). To accelerate portions of an App using PGCL, you simply write native C code that performs calls to OpenCL API routines and is dynamically linked with OpenCL device code compiled using the PGCL driver. The sections which follow describe how to create an App using this process.

Initializing your Android Development Environment for Use with PGCL

It is assumed here that you are already familiar with the use of Eclipse to create Android Apps, and that you have already set up an Android Java development environment on a Linux/x86 host as described on the Android Developer website. For this example, we will be using Android Platform 2.3.3 (Gingerbread). In addition, you must install the Android NDK as described on the Android Developer website.

Once you have the Java development kit and NDK installed, add the Android NDK directory to your PATH environment variable in a command-level shell. Make sure the correct connection via adb is established from Eclipse to your target Android device. Once this is accomplished, ensure that the installed location of PGCL is also included in your PATH environment variable, then launch the Eclipse IDE from your command shell.

Importing PGI's JavaLibOpenCL into your Eclipse Workspace

Most Android Apps are designed as Activities. Included with the PGCL distribution is the Android Java file OpenCLActivity.java that defines the OpenCLActivity class. This file can be found in the directory $PGI/androidarm/EXAMPLES/Dalvik/JavaLibOpenCL/src/com/pgroup/lib . The usage model is that an Android Activity can extend the OpenCLActivity class to use native functions that include OpenCL compute kernels. Follow these steps to import the OpenCLActivity class into your Eclipse workspace:

1. From the Eclipse menu, select File->Import

   

2. In the Import dialog, choose General->Existing Projects into Workspace, then click the Next > button.

   

3. In the Import Project dialog, choose “Select root directory”, browse to $PGI/androidarm/EXAMPLES/Dalvik/JavaLibOpenCL , and then click "OK."

   You should choose the "Copy projects into workspace" option to avoid working in the original PGCL install directory.

   The Projects list should now be populated with a project named JavaLibOpenCL.

   

4. Click "Finish". This should import into your Eclipse Workspace a new project named JavaLibOpenCL. This project includes Java sources for the OpenCLActivity class

   

   Now you can incorporate the OpenCLActivity class to build an Android Activity that uses OpenCL.

Creating an Android Activity that uses OpenCL

To create an Android Activity that uses the OpenCLActivity class, the following steps are required:

1. In Eclipse, create a new project using the menu: File->New-> Project.

   

2. Select Android Project in the New Project Wizard, then click Next >.

   

3. Choose the Name of your Project; for instance OclApp , and click Next>.

   

4. In the Select Build Target dialog, select Android 2.3.3, then click Next>.

   If Android 2.3.3 is missing then you have not set up Android with the 2.3.3 platform. You must do so to use PGCL 12.7. Future versions of PGCL will support Android 4.x (ICS) platforms.

   

5. Specify a package name like com.pgroup.samples and set Minimum SDK to the value 10 (Android 2.3.3). Then click Finish.

   

   A new project named OclApp should have been created in your Workspace. An OclAppActivity class should also have been created.

6. In the package explorer, right click on OclApp and select Properties from the menu.

   

7. In the Properties for OclApp dialog, select Android, and add library JavaLibOpenCL into the Library list.

   

   An OclAppActivity class should have been generated and its code should look as follows:

   package com.pgroup.samples;
   
   import android.app.Activity;
   import android.os.Bundle;
   
   public class OclAppActivity extends Activity {
       /** Called when the activity is first created. */
       @Override
       public void onCreate(Bundle savedInstanceState) {
           super.onCreate(savedInstanceState);
           setContentView(R.layout.main);
       }
   }
   

   To enable use of OpenCL in native code, this activity can be modified so that it extends OpenCLActivity instead of the Activity class. The modified code should look as follows:

   package com.pgroup.samples;
   
   import android.app.Activity;
   import android.os.Bundle;
   
   public class OclAppActivity extends OpenCLActivity {
       /** Called when the activity is first created. */
       @Override
       public void onCreate(Bundle savedInstanceState) {
           super.onCreate(savedInstanceState);
           setContentView(R.layout.main);
       }
   }

   You now have an Android Activity that can instantiate native C host code that uses OpenCL compute kernels compiled using PGCL.

Implementing SURF as an OpenCL-enabled Android App

The PGCL distribution includes an example Android App named NDKOclSurf. This example includes an OpenCL implementation of the Speed Up Robust Feature detector (SURF) algorithm. SURF is a robust image detector and descriptor, first presented by Herbert Bay et al. in 2006, that can be used in computer vision tasks like object recognition or 3D reconstruction. SURF is based on sums of 2D Haar wavelet responses and makes an efficient use of integral images. While the PGCL implementation is derived from AMD's open source implementation named CLSURF, there are several important differences:

• CLSURF relies on the OpenCV 2.1 Compute Vision library. This library provides numerous image processing algorithms used in computer graphics as well as in computer vision. PGCL SURF doesn't use OpenCV, thus avoiding the need to redistribute it and rely on Android native support for image reading and bitmap processing.

• CLSURF provides different types of algorithms, relying on access to a camera interface. PGCL SURF implements only a single image processing algorithm.

• CLSURF OpenCL kernel codes are optimized for mainstream GPU's. In this implementation, most of the kernels have been rewritten to take advantage of a dual-Cortex A9 CPU computing engine.

Importing PGCL NDKOclSurf into your Eclipse Workspace

Follow these steps to import the PGCL SURF example into your Eclipse workspace

1. From the Eclipse menu, select File->Import…

   

2. Expand the General Folder of the Import dialog, choose Existing Projects into Workspace, then click Next >.

   

3. In the Import Project dialog, click Select root directory, browse to $PGI/androidarm/EXAMPLES/Dalvik/NDKOclSurf, and then click OK.

   You should choose the Copy projects into workspace option to avoid working in the original PGCL install directory.

   The Projects list should now be populated with a project named NDKOclSurf.

   

4. Click Finish.

   This should import into your Eclipse Workspace a new project named NDKOclSurf. This project includes Java sources for the NDKOclSurfActivity class.

• ©2012 STMicroelectronics
• Terms of Use
• Privacy Policy