iOS

Michalis Kamburelis edited this page Dec 11, 2015 · 2 revisions

Supported iOS Devices

The engine should work with all devices running iOS 4.2 or newer. It was successfully tested with iOS 5.1 and iOS 7. The engine runs flawlessly on iPhone Simulator as well.

Overview and Examples

At the moment, the only possible way to use the engine is to work with it using the library interface (see castle_game_engine/src/library). The engine is compiled to static library (.a) and this file is added to the Xcode project.

So this implies you have two possibilities on iOS at the moment:

  1. Use the engine as VRML/X3D file viewer. Just compile the library, add it to your project and call generic functions to load the file, manipulate with viewpoints, navigation modes, etc.
  2. Create your own library. Same way as the library interface has been made, you can make your own. Of course this way is not very convenient, and will be replaced with [Planned: build tool] that will enable to use the same source code for all platforms.

We have one working example app built upon our standard library interface. It is simple VRML/X3D viewer, and is located at castle_game_engine/examples/library/ios_tester.

Building the App

Tools

You will need any Mac computer with Xcode installed (available in Mac App Store, free). To compile the engine, you need to download and install FPC (Free Pascal Compiler, http://freepascal.org/) version 2.6.2 for OSX or later. There is some info about it on Lazarus wiki page. Anyway, you don't need to install any special Xcode template or Objective-Pascal extension to work with the engine.

Compiling Pascal Code

There is a script provided for the library (see castle_game_engine/src/library/compile-iOS.sh). It assumes FPC has been installed to default location (/usr/local/lib/fpc). The sript automatically creates the static library with code both for armv7 and iPhoneSim.

Please note you need to manually uncomment debug or release compile flags inside.

Creating the App

Unlike Android version of your app, the engine relies on OpenGL ES context prepared by iOS SDK in Xcode. So for this, just create a new Xcode iOS project. The easiest way to work with OpenGL ES on iOS is to use GLKViewController and GLKView.

Once correctly prepared (either from Storyboard or entirely from code), add compiled library (cge_library.a) and the header file (castleengine.h) to the project. In source code, just initialize the engine calling the appropriate functions, and connect update function of GLKViewController with CGE_Update() and glkView:drawInRect: to CGE_Render().

Please refer to ios_tester project in castle_game_engine/examples/library.

All resources needed by your app have to be added to the Xcode project as in any other iOS app. Xcode will automatically copy them to the compiled bundle.

User Interaction

To enable user interaction to the engine, there is only one possibility at the moment: simulate mouse events. Add tap, pan and/or pinch gesture recognizers to the GLKView, and pass the events to the engine. Please refer to the example ios_tester project again. As a downside of this approach, there is no multi-touch support possible. We plan to support and process multi-touch gestures automatically in the engine in the future.

Recapitulation

To describe the process when using the library interface:

  1. Compile the library using castle_game_engine/src/library/compile-iOS.sh
  2. Add cge_library.a and castleengine.h to your Xcode project
  3. Prepare GLKViewController and init the OpenGL ES context
  4. Init the engine (CGE_Open, CGE_SetUserInterface, CGE_Resize, CGE_Close)
  5. Connect GLKViewController update and draw to CGE_Update and CGE_Render
  6. Process touch gestures

Debugging the Pascal Code without iOS

Same info as for [Android development] applies here too as the Pascal code is platform independent.

Some limitations of the library approach

The Pascal library can only react to some events of the main program, and cannot cause some actions.

The event loop is controlled only by the main program. This means that Application.ProcessMessages does not work. The library cannot force the main process to handle some events, and wait for something to happen. This means that you cannot use Application.ProcessMessages, or things depending on them:

  • CastleMessages (functions in this unit make modal windows, running a message loop inside and only returning when user exits --- similar to ShowMessage in LCL),
  • CastleWindowProgress (it wants to process messages and redraw the screen inside Progress.Step).

However, you can still use the UI of messages and progress bar, by using TCastleDialog and TCastleProgressBar controls. You just have to continuously watch/update them yourself, for example in your Window.OnUpdate event.

You also cannot use the Window.Open and Window.Close from the Pascal code to force recreating OpenGL context. The context creation/destruction is only caused by the main program.