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.
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.
We will use Visual C++ 2010 to add resources to our applications on Windows. Perform the following steps to do so:
- Open the Visual C++ solution and open the
resources.hfile inside the Header Files filter. - Add the
#pragma oncemacro to your file to prevent it from being included more than once in your project and include theCinderResources.hfile.#pragma once #include "cinder/CinderResources.h"
- 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
IMAGEmay be used when declaring image resources,VIDEOfor declaring video resources, and so on. - 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_RESOURCEmacro is the relative path to the folder where the resource file is, in this case the defaultresourcesfolder.The second parameter is the name of the file, and after that comes the unique ID of this resource, and finally its type string.
- Now we need to add our
resourcesmacro to theresources.rsfile, as follows:#include "..includeResources.h" RES_IMAGE
- This resource is now ready to be used in our application. To load this image into
ci::gl::Texturewe simply include theTexture.hfile in our application's source code:#include "cinder/gl/Texture.h"
- We can now declare the texture:
gl::Texture mImage;
- In the setup, we create the texture by loading the resource:
mImage = gl::Texture( loadImage( loadResource( RES_IMAGE ) );
- 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
drawmethod:gl::draw( mImage, Vec2f( 20.0f, 20.0f ) );
The resources.rc file is used by a resource compiler to embed resources into the executable file as binary data.