Getting Started

Android

The PowerVR Graphics SDK examples have been redesigned with the aim of making it as easy as possible to use with the new Android tools, including moving from Apache Ant to Gradle, and from Eclipse to Android Studio.

Using Gradle scripts, the native (NDK) component has been integrated with the Android Java component, so as to allow easier building from the Command Line (using the Gradle wrapper), or from Android Studio.

The following instructions for building the examples in the Android PowerVR Graphics SDK assume that you have:

• Installed the Android SDK from Google
• Installed the Android NDK
• Added the Android NDK to the system path

Adding the Android NDK to the system path for Windows has changed to Control Panel/System/Advanced System Settings/Advanced/Environment Variables. On Linux it is dependent on the specific system. It is also recommended to add the [Android SDK]/platform-tools sub-directory to the path to facilitate adb and similar tools.

It is recommended to build through Android Studio, but it is also possible to build through a Command Line.

To build through the Android Studio:

1. On the Startup screen or in the main Android Studio screen, select Import Project
2. Navigate to the /Build/Android sub-directory of the component to build
3. Select the build.gradle file (will normally have a green icon) and press OK

From that point onwards, the project can be debugged and/or built using Android Studio as normal.

To build through the Command Line:

1. A file named local.properties must be present in the /Build/Android sub-directory. This file must contain a line pointing to the Android SDK. On Windows, bear in mind that backslashes (\) must be escaped (\\), and semicolons (:) must be escaped (\:) as well. For example:
   
   
   • Windows: sdk.dir=C\:\\Android\\AndroidSdk
   • Linux: sdk.dir=/usr/local/android_sdk

   In order to create this file you can open a new file in any suitable text editor, like Notepad on Windows or Vim, Sublime etc. on Linux.

   If you have imported the example in Android Studio, the local.properties file will have already been created for you.

2. Run Gradle. We are bundling the Gradle wrapper so the required Gradle version will automatically be downloaded and used. On Windows, run gradlew [target]; on Linux, run ./gradlew [target], where [target] is usually:
   
   
   • clean to remove old build and temporary files
   • assembleDebug to create a debug version of the application
   • assembleRelease to create the basis for a release version of the application. In order to create a release version of your application, visit the page http://developer.android.com/guide/index.html

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. If you have installed our SDK with the installer, the PVRVFrame libraries will already be in your PATH environment variable.

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

Note: If the installer has not added the PVRVFrame directory to your PATH environment variable, you must copy the PVRVFrame emulation "drivers" to a DLL-accessible directory prior to running the SDK applications. The driver files names are; EGL, GLES_CM (OpenGL ES 1.x) and GLESv2 (OpenGL ES 2.0 & 3.x). The PVRVFrame libraries are provided as static libraries (lib*.lib) and dynamic libraries (lib*.dll).

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/[ExampleLevel]/[ExampleName]/[API]/Build/LinuxGeneric and run the command: LinuxNullWS: "make PLATFORM=[Platform]" or LinuxX11: "make PLATFORM=[Platform] X11BUILD=1". [Platform] is an entry from one of the following supported ABIs:

   • armv7
   • armv7hf
   • armv8
   • mips_32
   • mips_64
   • x86_32
   • x86_64

The executables for the examples will be under: Examples/[ExampleLevel]/[ExampleName]/[API]/Build/[Platform]/[ReleaseDir] where [ReleaseDir] is one of ReleaseNullWS or ReleaseX11

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):

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

3. Add the following frameworks to the project:

   • PVRCore (from [sdk-installation-directory]/PVRCore/Builds/OSX/PVRCore.xcodeproj)
   • PVRShell (from [sdk-installation-directory]/PVRShell/Builds/OSX/PVRShell.xcodeproj)
   • PVR[GlueAPI] (from [sdk-installation-directory]/PVRPlatformGlue/[GlueAPI]/Builds/OSX/PVR[GlueAPI].xcodeproj)
   • PVR[API] (from [sdk-installation-directory]/PVRApi/[API]/Builds/OSX/PVR[API].xcodeproj)
   • (Optional)PVRUIRenderer (from [sdk-installation-directory]/PVRUIRenderer/Builds/OSX/PVRUIRenderer.xcodeproj)
   • (Optional)PVRCamera (from [sdk-installation-directory]/PVRCamera/Builds/OSX/PVRUIRenderer.xcodeproj)

4. Under the Sources group create a new .cpp file for your application code.

5. Go to your project’s Targets Build Phases settings and add Your application source file under the Compile Sources section:

   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

6. Go to your project’s 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]/Framework
   • [sdk-installation-directory]/Tools

   Add these following paths to the Library Search Paths:

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