/*! \page CinderResources Using Resources in Cinder
\section intro Introduction
Most applications need to reference information outside of their own code in order to do anything very interesting. This information might be in the form of images, sounds, video, XML or any other sort of data, and when these files are built-in to the application itself they are typically referred to as \e resources. In Cinder, resources are handled as transparently as possible. Adding them to your application is simple, and loading them is nearly identical to loading a normal file or URL. By using the platform-native techniques for storing resources (as opposed to say, an external \e data folder) you can ensure your application is self-contained, removing the need for installers or the possibility of users inadvertently deleting the files your app depends on.

\section layout Project File Structure
For both single-platform and cross-platform applications, we recommend keeping your resource files in their own directory. These files are as much a part of your app as its source code, and they'll generally be managed by your version control system (say, Subversion or git) just as your C++ code or anything else in your project is. Depicted below is how we usually structure the directories in the Cinder samples, and if you don't already have your own convention, this is probably a good one to adopt:\n\n
\image html resources_file_structure.png
\n
We'll get into the specifics of some of these files in later sections.
\n
\section mac Resources on Mac OS X & Cocoa Touch
Under Mac OS X as well as Cocoa Touch (which includes the iPhone and iPad) resources are just normal files which are contained inside the application bundle. If you haven't before, try opening up one of these bundles yourself. Simply context-click (right-click or control-click) an application in your \e Applications folder and choose <b>Show Package Contents</b>. Here's the results of doing this with iTunes:\n\n
\image html resources_itunes_mac_show_package.png
\n\n
\image html resources_itunes_mac.png
\n
Looking around inside of the application bundle, we see a \e Resources folder inside of \e Contents. In here we can find all the data files the application depends on. As an example, the first few visible files in the screenshot are audio files iTunes plays as part of its user interface.\n
\n
A similar structure is maintained for iPhone and iPad apps, and it's the one Cinder uses for these platforms as well.
\n\n
\subsection macAdd Adding a Resource
Adding a resource to your Mac or Cocoa Touch application couldn't be easier. Let's assume you've got an image you'd like to use in your app. The first step is to add this file as a resource in Xcode. First, pull up your project window in Xcode. Now, context-click the \e Resources folder and choose <b>Add | Existing Files...</b>.\n\n

\image html resources_mac_add_resource.png
\n
Now select the file you'd like to add to your app from the Open dialog box that follows. After choosing your file, you'll see it listed in the \e Resources group of your Xcode project. The real magic happens though when Xcode copies these files into your application bundle at build time. To confirm that this will happen, select the \e Targets tab of your project inspector and reveal your application target under the \e Targets section. You'll see a build phase called <em>Copy Bundle Resources</em> and inside that will be the resource you've just added.\n\n

\image html resources_mac_build_phase.png
\n

\subsection macUse Using a Resource
Now that we've got a resource in the application, how do we actually make use of it with Cinder code? For a Mac or Cocoa Touch-only application, we simply call the loadResource() function and pass it the name of the resource as a string. The result of this function (which is a \ref cinder::DataSource "DataSourceRef", a class you won't generally need to use directly) can be passed to most Cinder functions and constructors that know how to do I/O. In the case of our logo image example, we would call loadResource() on that file and then pass it to loadImage(). Then the result of loadImage() can be used to create a \ref cinder::gl::Texture "gl::Texture" or a \ref cinder::SurfaceT "Surface" like so:
\code
gl::Texture myTexture( loadImage( loadResource( "Logo.jpg" ) ) );
Surface mySurface( loadImage( loadResource( "Logo.jpg" ) ) );
\endcode
or perhaps we want to create a QuickTime movie out of a resource called \e FlyingLogo.mov:
\code
qtime::MovieGl myMovie( loadResource( "FlyingLogo.mov" ) );
\endcode
\n
Pretty easy stuff. On the Cocoa side, that's all there is to it. In general, you can make use of the results of loadResource() about like you'd expect. However a handy function if you ever need to load a resource using a function which only accepts file paths is App::getResourcePath(). For example, calling this:
\code
console() << getResourcePath( "Logo.jpg" ) << endl;
\endcode
Results in something about like this:
<tt>/Users/andrewfb/Code/cinder/samples/resizeTest/xcode/build/Debug/resizeTest.app/Contents/Resources/Logo.jpg</tt>

\section msw Resources on Windows
Now let's take a look now at how resources are handled on Microsoft Windows. The most noticeable difference from the Mac is that resources are not stored as individual files, since an EXE does not encapsulate a directory like a Mac OS X application bundle does. Instead, resources are baked into the EXE using a resource compiler, and are stored as binary data. However we can access this binary data in memory using the same loadResource() routine we do on Mac OS X. Furthermore, Cinder's internal code is able to handle loading from either the flat file or in-memory representations transparently and efficiently, so in general you will not need to change application code between the platforms.
\n\n
<b>Note: </b>The text which follows is helpful for understanding how Windows resources work under the hood, but we recommend you read and consider the alternative techniques under the \ref xplatform "Cross-Platform Resources" section as well, even if you are writing Windows-only code.\n
\n
\subsection mswAdd Adding a Resource
Resources under Windows are identified by a combination of integer ID numbers and a string declaring the type of resource. The integer IDs are generally numbered starting from \c 128 though there is some flexibility here. Developers also adopt different idioms for the type string. For example, in the Cinder samples you might see \c GLSL as the type string for any OpenGL GLSL code stored as resources. In general developers will use a series of preprocessor <tt>\#define</tt>'s to create a list of unique IDs, and these should be defined in a header file which we typically create as <em>include\\%Resources.h</em>:\n
<b>%Resources.h</b>
\code
#pragma once

#define	RES_LOGO_ID             128
#define	RES_SPLASHSCREEN_ID     129
#define RES_THEME_MUSIC         130

\endcode
\n\n
Next, we will create a <em>Resources.rc</em> file, which will tell the compiler which resources we'd like to be included in our app. The structure of this file is a series of lines beginning with the unique resource ID (which we defined in <em>%Resources.h</em>), then a string declaring the resource type (again, this can be anything, but it's good to adopt a convention like assigning \c IMAGE to all of your image files) and last, the file path relative to the .rc file itself. Note that these files are C-style double-quoted strings and consequently, any backslashes must be doubled to distinguish them from escaped characters. The resource compiler walks this file, baking the data of each cited resource into the final EXE. A normal <em>Resources.rc</em> file might look like this:\n
<b>%Resources.rc</b>
\code
#include "..\include\Resources.h"

RES_LOGO_ID             IMAGE           "..\\resources\\Logo.jpg"
RES_SPLASHSCREEN_ID     IMAGE           "..\\resources\\Splashscreen.png"
RES_THEME_MUSIC_ID      MP3             "..\\resources\\Theme.mp3"

\endcode
\n
If it's not already part of your project, you'll need to add <em>Resources.rc</em> to your Visual C++ project. You can do this by right-clicking the \e Resources filter, choosing <b>Add | Existing Item...</b> and navigating to <em>Resources.rc</em>. Per the screenshot at the top of this document, we generally recommend storing this file in the same directory as your Visual C++ project, though that is not strictly necessary.\n\n
\image html resources_msw_add.png
\n
\subsection mswUse Using a Resource
So now our app has its resources baked in, but how do we use them? For Windows-only applications, we call the variant of App::loadResource() which accepts our resource ID/type combination. Just like on the Mac, the result of loadResource() can be passed directly to a function like loadImage(). Then for example, the result of loadImage() can be used to create a \ref cinder::gl::Texture "gl::Texture" or a \ref cinder::SurfaceT "Surface" like so:
\code
gl::Texture myTexture( loadImage( loadResource( RES_LOGO_ID, "IMAGE" ) ) );
Surface mySurface( loadImage( loadResource( RES_SPLASHSCREEN_ID, "IMAGE" ) ) );
\endcode
\n
\section xplatform Cross-Platform Resources
As we've seen, Mac OS X and Windows handle resources slightly differently, but Cinder provides some tools which can simplify these differences. The most straightforward way to use the same code on both platforms is to call the variant of loadResource() which accepts both a Mac file path and a Windows ID/Type combination. Cinder will automatically pay attention to the relevant parameters for the platform you are compiling on. Calling this looks about like this:
\code
loadResource( "Logo.jpg", RES_LOGO_ID, "IMAGE" );
\endcode
\n
However, Cinder provides some convenient capabilities which not only simplify your application code, but can consolidate the definition of the resources themselves. Let's continue the \e Logo.jpg example. We'll start with the most changed portion, which is the structure of <em>%Resources.h</em> \n
<b>%Resources.h</b>:
\code
#pragma once
#include "cinder/CinderResources.h"

#define RES_LOGO	CINDER_RESOURCE( ../resources/, Logo.jpg, 128, IMAGE )

\endcode
\n
You'll notice a couple of changes. The first is the inclusion of the file \e "cinder/CinderResources.h". This file defines the <tt>CINDER_RESOURCE</tt> macro, which breaks down as follows:\n
<tt>CINDER_RESOURCE</tt>( <em>relative path to the parent of the resource</em>,  <em>file name of the resource</em>, <em>Windows integer ID</em>, <em>Windows type</em> )\n
\n
As you can see, we use this macro to define a resource named <tt>RES_LOGO</tt>. Its path (relative to the <em>Resources.rc</em> file) is <tt>../resources/Logo.jpg</tt>, which we split into the parent and the name of the file itself with the macro. And finally, we assign our Windows ID/type combination, \c 128 for the ID and \c IMAGE for the type string. Should you need to define several resources, make sure each one is defined on its own line, and the last ends with a carriage return.
\n \n
Next, we'll look at our redefined \e Resources.rc file designed to make use of this macro:\n
\b Resources.rc:
\code
#include "..\include\Resources.h"

RES_LOGO

\endcode
\n
This file has been simplified by our new <tt>CINDER_RESOURCE</tt> macro. We simply write the name of the resource we want included in our .exe. Make sure each resource has its own line when you have multiple resources, and don't forget the carriage return on the last line.\n
\n
On the Mac OS X side of things, you'll still include your resource in the \e Resources group of your Xcode project, and confirm its presence in the <em>Copy Bundle Resources</em> build phase to be safe.\n
\n
Finally, let's look at how our application code has changed:\n
\code
#include "Resources.h"
...
gl::Texture myTexture( loadImage( loadResource( RES_LOGO ) ) );
\endcode
\n
It's about the same, except now we simply pass the resource name to loadResource() and the right thing will happen on either platform.
\n \n
That's all there is to using cross-platform resources. It can be a bit of a pain to setup initially, but it's easy to maintain once you've got it going, and TinderBox should setup things appropriately automatically if you use it. And while you can use either style of resource definition, we prefer the <tt>CINDER_RESOURCE</tt> technique since it's less error-prone and makes for slightly more legible application code.

*/
