Gamut: Explore Colors in iOS Simulator
Posted by Jeffrey
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.
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.
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:
Unpack and Check Particulars
$ tar -xf gamut-3.0.2.tgz
$ cd gamut-3.0.2
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
HIDEOUT to the Developer directory inside your Xcode
OCAMLDIR is the location of your OCaml-to-iOS Simulator
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.tdefines the application delegate. This class has a single instance that participates in the
UIApplicationDelegateprotocol to receive notifications of state changes. In particular, the application delegate notices when the app is activated and deactivated.
GamutViewControllerD.talso 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 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.
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
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
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 email@example.com.