Gamut: Explore Colors in iOS Simulator

January 29, 2016

Quite a few years ago I put together a simple OCaml app that you can run in the iOS Simulator. Recently I revamped it to work with OCaml 4.02.3, and tested it under iOS 9.2.

As suggested in these screenshots, the app displays an animation that changes colors as you touch different locations on the screen. Each screen location is associated with a certain color, and (if you’re patient) you can touch every spot on the screen to try out all the possible colors of the display. Hence the app is called Gamut.

The most recent version of Gamut is 3.0.2. I built and tested it under OS X 10.11.2 (El Capitan) using Xcode 7.2. Previous versions of Gamut, for earlier versions of OS X and Xcode, can be found in the OCaml Programming Archives.

Overview

The main problems of running OCaml apps in the iOS Simulator are:

Compiling OCaml with iOS Simulator ABI
Linking to iOS Simulator libraries
Using Interface Builder

For the first problem, you can use the OCamliOS compiler that may one day be part of the official OCaml release. I’ve made some binary releases, described in Compile OCaml for iOS Simulator. The Gamut example shows how to solve the other two problems.

One problem that you don’t have with the iOS Simulator is packaging and code signing, as the simulator doesn’t require apps to be signed. This makes it easy to get an app working.

The iOS Simulator really does simulate an iOS device, so the other two problems are solved exactly as for code that runs on an iOS device. Linking to Objective C functions and classes is handled by having wrappers for them in OCaml. That is, you have small OCaml classes whose only purpose is to wrap up Objective C classes for use from OCaml. Similarly, you have inverse wrappers written in Objective C that allow access to OCaml classes. These inverse wrappers also provide Interface Builder with the information it needs to lay out the GUI and create an initial application state.

Keep in mind that the Gamut app doesn’t really do all that much, so the amount of OCaml code is quite a bit less than the amount of Objective C wrapper code. In more realistic apps (like our Cassino and Master Schnapsen/66 apps), almost all the code is in OCaml. Our library of Objective C wrapper code is relatively small and fixed.

Preliminaries

Before starting, make sure you have installed Apple’s Xcode, including the iOS Simulator SDK and the iOS Simulator itself. As I write this, the current version is Xcode 7.2. You can download Xcode (for free) from the Mac App Store. See Apple’s Xcode page for more details.

You also need an OCaml compiler that conforms to the iOS Simulator ABI. If you want to use OCamliOS as mentioned above, binaries and instructions for building from source are given in Compile OCaml for iOS Simulator.

Get Gamut Sources

Download the sources for Gamut 3.0.2 from this link:

Gamut 3.0.2

Unpack and Check Particulars

$ tar -xf gamut-3.0.2.tgz
$ cd gamut-3.0.2
$ ls
Gamut Gamut.xcodeproj

The work of building Gamut is done by Gamut/Makefile. You may need to change some of the specific settings near the beginning:

IOSMINREV = 7.0

HIDEOUT = /Applications/Xcode.app/Contents/Developer
TOOLDIR = $(HIDEOUT)/Toolchains/XcodeDefault.xctoolchain/usr/bin
PLT = $(HIDEOUT)/Platforms/iPhoneSimulator.platform
SDK = /Developer/SDKs/iPhoneSimulator.sdk
OCAMLDIR = /usr/local/ocamliossim64

IOSMINREV is the minimum version of (simulated) iOS that you want to run on. Gamut doesn’t depend on any recent features of iOS, so even a pretty old version is OK. If your Xcode is installed in a nonstandard location, change HIDEOUT to the Developer directory inside your Xcode application. OCAMLDIR is the location of your OCaml-to-iOS Simulator cross compiler.

Build and Run from Xcode

To open Xcode, you can use the following command:

$ open Gamut.xcodeproj

This starts Xcode and opens Gamut as an Xcode project. You can also open the project from Xcode’s File -> Open menu, or double click on Gamut.xcodeproj in the finder.

Make sure Xcode is building the Gamut target (not Gamutbin) and is building for the iOS simulator (not a device).

Click the left side of the scheme selector at the left end of the toolbar. From the menu select Gamut.
Then click a little bit to the right and select iPhone 6 (or any other desired iOS device) from the iOS Simulator section.

Note that the simulated device you choose must support the architecture (32-bit or 64-bit) of the cross compiler you’re using. These days 64-bit devices are the most common, so I’ve made it the default in the Makefile. However, some simulated devices only support 32-bit apps.

You can now build and run the app.

To build and run, click on the Product -> Run menu item.

If things go right, you’ll see the Gamut app running in the simulator.

Here are some hints for trying out the app:

Touch outside the circle to change the background to a different color. Touches near the top give red, then successively lower locations give orange, yellow, green, blue, and purple. At the bottom it wraps back around to red. This is the hue component of the color.
Touch toward the left to give less saturated colors (more grayish and world-weary looking). Touch toward the right to give more saturated ones (bright and cartoonish). This is the saturation component of the color.
The circle in the middle cycles through the different possible light and dark variants of the background color. Touch inside the circle to set the background color to the current level of lightness. This is the lightness component of the color.
Touch outside the circle and then move your (simulated) finger around to go through a series of colors.
Touch and hold inside the circle to go through a series of lightnesses.

Theory of Operation

Gamut is a very simple iOS app; just two classes do almost all the work.

GamutAppDelegate.t defines the application delegate. This class has a single instance that participates in the UIApplicationDelegate protocol to receive notifications of state changes. In particular, the application delegate notices when the app is activated and deactivated.

GamutViewControllerD.t also has a single instance that acts as a delegate for the single view controller of the app. This view controller delegate is the heart of the app; let’s call it Gvcd for short.

At startup, the application delegate establishes a timer that fires periodically, calling the timerTick method of Gvcd. Then Gvcd works by responding to outside events of three kinds:

Touches As Gvcd receives notifications of user touches, it tracks whether the touch began inside or outside the circle. If outside the circle, it tracks the most recently touched point; this is used to set the hue and saturation values when drawing content. If inside the circle, it tracks the finishing time of the touch. This is used to set the lightness values.
Timer ticks When Gvcd receives a timer tick, it updates its record of the current time, and tells the containing view that it’s time to redraw the content.
Redraw When graphics contents need to be redrawn, Gvcd uses Cocoa Touch methods to draw the content. The hue, saturation, and lightness values are determined based on the current time and on recent touches, as described above.

Interface Builder

If you enable the Project Navigator at the left and click on Main.storyboard in the leftmost pane, you’ll activate Interface Builder to show the storyboard for Gamut. There are only three interesting objects: the view controller, the main view, and the view controller delegate Gvcd. These are instances of classes PSViewConDelegator, PSViewDelegator, and GamutViewControllerD.

Both delegators are connected to Gvcd through their delegate outlets. You can see this by enabling the Connections Inspector at the far right. These connections allow Gvcd to control the behavior of Gamut as described above.

Since Interface Builder doesn’t know anything about OCaml, it gets its information from the header files for the wrapper classes. Note that you need wrappers only for OCaml classes that are accessed from Objective C, which should be just a few of them. In Gamut, the header files are PSViewConDelegatorM.h, PSViewDelegatorM.h, and wrap.h.

Discussion

Although I’ve packaged up Gamut to run in the iOS Simulator, it will naturally also run directly on an iOS device with no changes to the code. The only changes required are to the build environment. The code is written to be independent of screen size and resolution, so it ought to run reasonably on any iOS device.

Compiling OCaml to run directly on iOS devices is described in Compile OCaml for iOS. I’ve also packaged some example apps to run on iOS devices. There is a simple app named Portland that tracks the devices’s orientation (portrait or landscape), and a slightly more complicated app named Slide24 that plays (and solves) the classic 5x5 sliding tile puzzle. For a full list of OCaml-on-iOS programming resources, see our OCaml Programming page.

If you have questions, comments, or corrections please leave a comment below or email me at jeffsco@psellos.com.