Getting Started

Android

The following instructions for building the examples in the Android PowerVR Graphics SDK assume that you have already installed the Android SDK from Google, the NDK and Apache Ant.

To build individual components go to the /Build/Android sub-directory of the component to build. To create local properties, on the first build you will need to run:

1. android update project -p . -t [Target], where the list of targets can be found with the following command ([Target] corresponds to the ID number): android list target

To use the Android tool you need to have the Android SDK's tool folder in your path. After this, the building of an application is done in two stages. The first stage involves compiling the C++ code into a library. This is achieved using ndk-build which is part of the Android NDK and needs to be present in your path. To compile for all supported platforms:

1. Type ndk-build

2. On an a specific platform you can compile by typing: ndk-build APP_ABI=[Platform]. [Platform] is an entry from one of the following supported ABIs:

   • armeabi
   • armeabi-v7a
   • x86
   • mips

3. The second stage compiles the remaining Java components and creates the APK file for installing on your device. The quickest way of achieving this is to type: ant debug. This will create an APK file in ./bin and will handle the signing of your application for you. For creating a release build of your app please visit the relevant page at http://developer.android.com/guide/index.html.

Using Android SDK Manager

The following instructions for building the examples in the PowerVR Graphics SDK assume that you have an Eclipse environment with the Android SDK and NDK installed, as well as the NDK Eclipse plug-in. For more details about using the NDK, please visit Android Tools Project Site.

To download the Android PowerVR Graphics SDK through the Android SDK Manager, perform the following steps:

1. Open the Android SDK manager.

2. Open the Tools -> Manage Add-on Sites window and click the User Defined Sites tab.

3. Click New... and add the following URL: http://cdn.imgtec.com/sdk/androidsdk.xml

The PowerVR SDK should now appear on the Packages list, under API 10.

4. Once the SDK is installed you will then need to add the PVRSDKDIR environment variable for your NDK builds. To do so in Eclipse, click Window and open the Preferences menu. From there, navigate to C/C++ -> Build -> Environment and add the variable PVRSDKDIR, setting its value to where the add-on is installed (typically under the add-ons directory inside the Android SDK).

5. All the examples can be imported by selecting the PowerVR SDK during the creation of a new Android sample project in Eclipse.

Note: Please note that for Windows we recommend to point PVRSDKDIR to ../ and copy the shell/, tools/ and builds/ directories from the add-on folder to your workspace/. This is due to the dropping of support for Windows paths in GNU Make 3.81 onwards. Otherwise the use of paths containing : yields the error *** target pattern contains no '%'.

Note: For Windows, the Eclipse CDT "Scanner Configuration Builder" appears not to be working with the directory structure of our samples/tools/shell. For that reason is recommended to disable it from your project. To do this, right-click Project Name -> Properties -> Builders -> Disable the "Scanner Configuration Builder".

iOS

To proceed with the installation of the PowerVR Graphics SDK on iOS, complete the following steps:

1. Download a version of Apple's iOS SDK from http://developer.apple.com/ios/. You will need to become a member of Apple's developer programme in order to access this page. You can find details of how to join at http://developer.apple.com.

2. Install the Apple SDK on your Mac as specified by Apple's hardware and software requirements. This should also install Xcode and the other development tools required.

3. Expand the PowerVR Graphics SDK for iOS to a location for which you have both read and write access.

4. To build the examples and other projects from the SDK, find the various [API]***.xcode projects available within the SDKPackage_[API] directory and double click these to launch them in Xcode.

5. To build for an iOS device you will need a valid developer certificate in your machine's keychain. You may also have to change the Properties | Identifier property from Project | Edit Active Target... to match that which you have set up for yourself through Apple's Program Portal.

6. If you do not have a developer certificate from Apple then you can still build and launch applications in the iOS Simulator. Choose this configuration from the dropdown menu at the top left and then choose Build and Run from the dropdown menu.

Note: The Scheme that you are building under may need to be set up for the SDK's projects to run.

Windows

This SDK requires a PC equipped with Windows XP, Windows Vista or Windows 7. The required installation steps are:

1. Install the SDK on your machine as specified by Windows hardware and software requirements. The project and solution files provided do not require the SDK to be installed in a pre-defined location and are configured to use relative paths.

2. Copy the API-specific emulation "drivers" to a DLL-accessible directory prior to running the SDK applications. The API-specific emulation "drivers" are called libEGL.dll, libEGL.lib, lib[PVRVFrameShort].dll and lib[PVRVFrameShort].lib. The files are located by default in \Builds\Windows\x86_32\Lib and \Builds\Windows\x86_64\Lib.

Note: The examples can be launched directly from their project files.

OS X

The OS X SDK requires OS X (Snow Leopard) or higher for full operation.

1. Install the latest version of Xcode, available from http://developer.apple.com/ or from the Mac App store.

2. Expand the PowerVR Graphics SDK for OS X into a location for which you have full access.

3. To build the examples and other projects from the SDK, find the various [API]***.xcodeproj projects available within the SDKPackage_[API] directory and double click these to launch them in Xcode.

Note: The Scheme that you are building under may need to be set up for the SDK's projects to run.

Linux

Note: API libraries are not distributed with the PowerVR Graphics SDK for Linux. Please ask your platform provider for these libraries if you do not have them. You will also need to install the latest platform toolchain on your development machine for your target platform.

To build the code examples, follow the steps below:

1. Define the TOOLCHAIN environment variable to the toolchain directory, or add the path of the toolchain to the PATH environment variable (i.e., run export PATH="path to the toolchain:$PATH").

2. If you want an X11 build and it is available, define the environment variable X11ROOT to point to the freedesktop directory (i.e., export X11ROOT=/usr/X11R6_SGX).

3. To build individual components go to the directory Examples/[Level]/[ExampleName]/[API]/Build/LinuxGeneric and run the command: LinuxRaw: "make PLATFORM=[Platform]" or LinuxX11: "make PLATFORM=[Platform] X11BUILD=1". [Platform] is an entry from one of the following supported ABIs:

   • linux_armv7
   • linux_armv7hf
   • linux_x86_32
   • linux_x86_64

The executables for the examples will be under: Examples/[Level]/[ExampleName]/[API]/Build/[Platform]/[ReleaseDir] where [ReleaseDir] is one of ReleaseRaw or ReleaseX11. [ExampleName] is the name of the example that you are building and [Level] is either Beginner, Intermediate or Advanced.

To run an executable, follow the steps below:

1. Ensure that the PowerVR drivers are installed on the target device (please refer to the DDK/driver installation instructions).

2. If the standard C++ libraries are not present on your target device, copy libc++ from the toolchain into /usr/lib. libdl and libgcc may also be required.

   Note: libc++ lives at /usr/lib if you have installed the drivers, or can be found as part of a binary driver release package.

3. Ensure the drivers are running (e.g., type /etc/init.d/rc/pvr start, then run an X session if required).

   Under X11, window sizes can be specified for the executables using the command-line arguments -posx=n and -posy=n to define the top right hand corner, and -width=n and -height=n to define width and height, respectively.

   For example:

   ./[API]IntroducingPOD -posx=10 -posy=10 -width=100 -height=100

4. If you attempt to run an SDK example and it fails with the message: "Can't open display" produced by the X client, then make sure that the DISPLAY variable is set with the shell command: "set | grep -e DISPLAY". If this command does not yield any output then type (in shell): "DISPLAY=:0.0; export DISPLAY"

WebGL

The steps below highlight the procedure for setting up the WebGL SDK:

1. To host and run the WebGL SDK you will need a web server. Since the WebGL SDK only uses HTML5 and JavaScript (no dynamically generated content) any web server capable of serving HTML is suitable for hosting it. The WebGL SDK does not require building.

2. To use the WebGL SDK, copy across the contents of the WebGL package to an appropriate location in your web server tree (in some cases, also configure your web server to serve it), keeping the folder structure intact.

3. You can then navigate to and launch the required example from the SDK Browser.

Note: If you do not have a web server available, you will need to install and configure one, as appropriate. For example, on Windows, IIS is usually built in and may require to be enabled and configured. On OS X, Apache may require to be enabled and configured. Most Linux distributions will contain a web server such as Apache. Alternatively, you may want to download, install and configure another web server depending on what your specific needs are. A useful comparison of web server software is available in Wikipedia.

XCode Project Setup for OpenGL ES Using PVRVFrame

The following steps detail how to set up, from scratch, an XCode project for OpenGL ES using PVRVFrame:

1. Open the XCode application and then click File -> New -> Project from the menu. Select Cocoa Application from the template OS X or Application. Select Next and fill the product name, e.g., IntroducingPOD, and the company identifier. Other fields can be left as is. Then select the project destination directory.

2. To organise the project, right-click on it from the Project Navigator and select New Group. Following this, create the following groups (which will contain the mentioned application contents):

   • Source/Shell (Shell source files)
   • Content/Models (.pod files)
   • Content/Textures (.pvr textures)
   • Content/Shaders (shaders)
   • Libraries (dependencies)

3. Right click the Shell group and select Add Files to "project name" and add these following files:

   • PVRShell.h, PVRShell.cpp, PVRShellImpl.h (from [sdk-installation-directory]/Shell)
   • PVRShellAPI.h, PVRShellAPI.cpp, (from [sdk-installation-directory]/Shell/API/KEGL)
   • main.m, PVRShellOS.h, PVRShellOS.cpp, AppController.mm, AppController.h (from [sdk-installation-directory]/ /Shell/OS/OSX)

4. Under the Source group create a new .cpp file for your application code and include the following header files:

   • PVRShell.h
   • OGLES3Tools.h

5. Right-click the Libraries group and then select Add Files to "project name" and navigate to the [sdk-installation-directory] /Tools/[API]/Build/OSX/[API]Tools.xcodeproj and add this project.

6. Go to your project’s Targets Build Phases settings and add the following source files under the Compile Sources section:

   • Your application source file
   • PVRShell.cpp
   • PVRShellAPI.cpp
   • PVRShellOS.cpp
   • main.m
   • AppController.mm

   Add the library files under LinkBinary With Libraries section:

   • Lib[API]Tools.a
   • Quartzcore.framework
   • libEGL.dylib located at [sdk-installation-directory]/ /Builds/OSX/x86/Lib
   • libGLESv2.dylib located at [sdk-installation-directory]/ /Builds/OSX/x86/Lib

   Then add all content files (such as PVR files, POD files, shaders, icons, etc.) under Copy Bundle Resources.

   Following this, add a new build phase called Copy Files, and select Destination Frameworks and add these following library files:

   • libEGL.dylib
   • libGLESv2.dylib

7. Go to your project’s Targets Build Phases settings, and under the Preprocessing section add BUILD [API] preprocessor for Debug and release configuration. Then under the Search paths section select Yes for Always Search User Paths and add these header search paths to User Header Search Paths:

   • [sdk-installation-directory]/Builds/Include
   • [sdk-installation-directory]/Tools/[API]
   • [sdk-installation-directory]/Tools

   If your targeted API is OGLES3 then you also have to add:

   • [sdk-installation-directory]/Builds/Tools/OGLES2

   Add these following paths to the Library Search Paths:

   • [sdk-installation-directory]/Builds/OSX/x86/Lib