SDK Tools Guides


Resource Compilation

Various different types of resources (such as image, audio, and binary files) can be included in your application. Here we discuss how you make MoSync aware of them and ensure type safety. We also give 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.

A note on HTML5 resources

The MoSync Resource Compiler provides a way to manage applications resources for C/C++ applications. If you are working in HTML5/JavaScript, those resources should be handled in the normal HTML way: store them in the /LocalFiles folder, load them using e.g. <img> tags, use conditions to call the appropriate resource file, and so on. See Developing Apps in HTML5 and JavaScript.

Resources handling alternatives

MoSync handles resources at three levels:

  • Standard folders. This is the simplest way to organise resources using predefined folder names.
  • Custom folders and LSTX lists. Create your own folder structure and specify it with arbitrarily complex conditions. (Note: you must use this format to include resources that are not stored in files (for example, placeholders and tilemaps.)
  • Custom folders and LST lists. The old way of doing it in MoSync 2.7 still works.

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

Handling 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. MoSync 3.0 and above solves this by making it possible to customize what resources to bundle with a specific device or a group of devices in a project.


<image id="R_PRETTY_IMAGE" resource="pretty_image.png"/>

Example, MoSync versions prior to 3.0:

.image "pretty_image.png"

Handling 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:

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


<media id="R_MUSIC" resource="songs/song.mp3"/>  


<audio id="R_MUSIC" resource="songs/song.mp3"/>

Example, MoSync versions prior to 3.0:

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

Handling 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.


<binary id="R_MY_DATA" resource="my_data.bin"/>

Example, MoSync versions prior to 3.0:

.res R_MY_DATA
.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.

Defining 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.


MoSync SDK 3.3
Copyright © 2013 MoSync AB