Using resources on Windows

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 embedded in the application's executable file. Resource files are hidden from the user to avoid alterations.

Getting ready

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

Resources on Windows must be referenced in a file called Resources.rc. This file should be placed next to the Visual C++ solution in the vc10 folder. If this file does not exist, you must create it as an empty file. If the resources.rs file is not included already in your project solution, you must add it by right-clicking on the Resources filter and choosing Add and then ExistingItem. Navigate to the file and select it. As a convention, this file should be kept in the same folder as the project solution.

How to do it…

We will use Visual C++ 2010 to add resources to our applications on Windows. Perform the following steps to do so:

1. Open the Visual C++ solution and open the resources.h file inside the Header Files filter.

2. Add the #pragma once macro to your file to prevent it from being included more than once in your project and include the CinderResources.h file.

   #pragma once
   #include "cinder/CinderResources.h"

3. On Windows, each resource must have a unique ID number. As a convention, the IDs are defined as sequential numbers starting from 128, but you can use other IDs if it suits you better. Make sure to never use the same ID twice. You must also define a type string. The type string is used to identify resources of the same type, for example, the string IMAGE may be used when declaring image resources, VIDEO for declaring video resources, and so on.

4. To simplify writing multiplatform code, Cinder has a macro for declaring resources that can be used on both Windows and Mac.

   For example, to declare the resource of an image file named image.png, we would type in the following line of code:

   #define RES_IMAGE CINDER_RESOURCE(../resources/, image.png, 128, IMAGE)

   The first parameter of the CINDER_RESOURCE macro is the relative path to the folder where the resource file is, in this case the default resources folder.

   The second parameter is the name of the file, and after that comes the unique ID of this resource, and finally its type string.

5. Now we need to add our resources macro to the resources.rs file, as follows:

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

6. This resource is now ready to be used in our application. To load this image into ci::gl::Texture we simply include the Texture.h file in our application's source code:

   #include "cinder/gl/Texture.h"

7. We can now declare the texture:

   gl::Texture mImage;

8. In the setup, we create the texture by loading the resource:

   mImage = gl::Texture( loadImage( loadResource( RES_IMAGE ) );

9. The texture is now ready to be drawn on screen. To draw the image at position (20, 20), we will type in the following line of code inside the draw method:

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

How it works...

The resources.rc file is used by a resource compiler to embed resources into the executable file as binary data.

There's more...

Cinder allows writing code to use resources that is coherent across all supported platforms, but the way resources are handled on Windows and OS X/iOS is slightly different. To learn how to use resources on a Mac, please read the Using resources on iOS and OS X recipe.