Resource Compilation

This topic describes the different types of resources (such as image, audio files, and binary files) that can be included in your application, and how you make MoSync aware of them and ensure type safety. It also gives a brief overview of how MoSync compiles resources during the build process.

For detailed information about resource compilation, the resource compiler, and resource list files and commands, see the Resource Compiler Reference guide. We also have a general tutorial that looks at various aspects of resource handling and provides oodles of good advice: Adding Resources to a Project.

Resource List Files

MoSync uses resource list files (files with the extension .lst) to identify which external resources are to be included in an application. During the build process, the identified resource files are compiled to a single binary file called resources (both the program and resources are combined to a program.comb file also for easy downloading and execution of a program over the internet). This resource file is loaded on application startup and all resources are prepared for use in MoSync API syscalls.

Creating a Resource List File

Open MoSync, then select File > New > Other. The New Wizard window will open:

Expand the MoSync folder and select MoSync Resource File. The New Resource Wizard window opens.

Select a parent folder, then enter a filename for your resource file:

A resource list file contains declarations of resources and instructions. Each resource is identified by a .res declaration, followed by instructions for the resource compiler. Optionally you can add a symbolic name  for the resource which can be used anywhere in the code to identify the resource. These names will be used to generate a header file with preprocessor definitions, mapping the name to a numeric ID, i.e. a MoSync handle. To make use of the resource, it is convenient to include the MAHeaders.h file and use the symbolic names instead of the actual numbers.

Example:

.res R_MYFACE    // resource declaration, with the symbolic name R_MYFACE
.dispose       // instruction to delete the resource after loading
image "myimages/face.png"    // image to load - relative path may be included with forward slashes

Binary Resources

Using this resource type, any binary data can be stored in a resource for access in MoSync. There's two types of binary resources: standard binary resources (.bin) and unloaded binary resources (.ubin). Standard binary resources will be loaded into memory directly at startup while unloaded binary resources will be kept on permanent storage. Standard binary resources can be read from and written to while unloaded binary resources only can be read from. Note that all changes made to the binary resource will be discarded whenever the application is closed as the memory will be discarded. The use of unloaded binary resources saves memory while sacrificing speed, as it usually is slower to do reads from the permanent storage.
Example:

 .res R_MY_DATA
 .bin 
 .include "my_data.bin"

All paths in a resource file are relative to the MoSync project directory. The filename can include a relative path, but always use forward slashes (for example, files/myaudio/dylan.mp3) or escaped backslashes (\\) in the pathname.

Image Resources

Image resources should be used for loading images from standard image formats. At application start the resource loader will automatically decode images and make them ready to use with the image related syscalls. Different phones support different image formats and sizes. Future MoSync versions will solve this by making it possible to customize what resources to bundle with a specific device or a group of devices in a project. This isn't possible right now, so to be sure that the images can be loaded, you should use png images as we've made sure that png images always can be loaded.
Example:

 .res R_PRETTY_IMAGE
 .image "pretty_image.png" 

Media Resources

The media resource is the resource type used for audio. Similar to the binary resource, there's two types of media resources - standard media resources (.media) and unloaded media resources (.umedia). With standard media resources, the audio will be loaded, and sometimes decoded, to memory. With unloaded media resources the sound will be streamed from disk to the extent possible. Some devices cannot stream from disk and will load the whole sound to memory anyway due to limitations in the underlying platform. The media resource statement is followed by a string of the mime-type and then the path to the file that should be included.

Common supported mime-types are:

1. audio/mpeg - for mp3 audio
2. audio/x-wav - for Microsoft's wave audio format (note: this is the only format supported on windows mobile devices for now)
3. audio/basic - for Sun's au format

Example:

 .res R_MUSIC
 .umedia "audio/mpeg", "songs/song.mp3" 

Placeholders

The Placeholder is a type of resource that may be used to create new resources programatically. Several syscalls such as maCreateDrawableImage and maCreateData must be passed a placeholder. This placeholder can then be used to identify the dynamically created resource. Note that there is also support to dynamically create placeholders using the maCreatePlaceholder syscall. Also, any resource that is destroyed at runtime becomes a placeholder.