Using resources on iOS and OS X

It is common for Windows applications to use external files either to load images, play audio or video, or to load or save settings on XML files.

Resources are external files to your application that are included in the applications bundle. Resource files are hidden from the user to avoid alterations.

Cinder allows writing code to use resources that is equal when writing Windows or Mac applications, but the way resources are handled is slightly different. To learn how to use resources on Windows, please read the Using resources on Windows recipe.

Getting ready

Resources should be stored in a folder named resources in your project folder. If this folder does not exist, create it.

How to do it…

We will use Xcode to add resources to our application on iOS and OS X. Perform the following steps to do so:

1. Place any resource file you wish to use in the resources folder.

2. Add these files to your project by right-clicking on the Resources filter in your Xcode project and selecting Add and then ExistingFiles, navigate to the resources folder, and select the resource files you wish to add.

3. To load a resource in your code, you use the loadResource method and pass the name of the resource file. For example, to load an image named image.png, you should first create the gl::Texture member in the class declaration:

   gl::Texture mImage;

4. In the setup method, we initialize the texture with the following resource:

   mImage = loadImage( loadResource( "image.png" ));

5. The texture is now ready to be drawn in the window. To draw it at position (20, 20), type in the following line of code inside the draw method:

   gl::draw( mImage, Vec2f( 20.0f, 20.0f ) );

How it works...

On iOS and OS X, applications are actually folders that contain all the necessary files to run the application, such as the Unix executable file, the frameworks used, and the resources. You can access the content of these folders by clicking on any Mac application and selecting Show Package Contents.

When you add resources to the resources folder in your Xcode project, these files are copied during the build stage to the resources folder of your application bundle.

There's more...

You can also load resources using the same loadResource method that is used in Windows applications. This is very useful when writing cross-platform applications so that no changes are necessary in your code.

You should create the resource macro in the Resources.h file, and add the unique resource ID and its type string. For example, to load the image image.png, you can type in the following code snippet:

#pragma once
#include "cinder/CinderResources.h"
#define RES_IMAGE CINDER_RESOURCE(../resources/, image.png, 128, IMAGE)

And this is what the Resources.rc file should look like:

#include "..\include\Resources.h"

RES_IMAGE

Using the preceding example to load an image, the only difference is that we would load the texture with the following line of code:

mImage = loadImage( loadResource( RES_IMAGE ) );

The resource unique ID and type string will be ignored in Mac applications, but adding them allows creating code that is cross-platform.