Resource Compiler Reference

Published by Chris Hughes on March 10, 2010

This topic describes how resources (such as image, audio files, and binary files) are compiled by MoSync, and describes the format of the resource list files which contain the commands that are processed by the resource compiler.

Resources

MoSynC applications have three distinct sections: code, data, and resources. Resources are files external to your main code that are compiled during the build process into a form ready to be delivered to the target devices. Resources can include:

  • Images, and sprites cut from images
  • Media files in various formats
  • Binary files
  • Placeholders
  • Tilemaps and tilesets
  • Enums and script values

For more information about resources and how to create them, see the programming guide Compiling Resources. We also have a general tutorial, Adding Resources to a Project, which demonstrates how to make resources available to your applications and discusses many importants aspects of resource handling.

The Resource Compiler

The resource compiler is part of the MoSync Pipe-Tool. It is automatically invoked during the build process but can also be run from the command line using the command:

pipe-tool -R outfile infile1 [infile2 ...]

for example:

pipe-tool -R output/resources audio.lst images.lst other.lst

This command compiles all the resources referenced in the resource list files audio.lst, images.lst, and other.lst and concatenates them into a binary file called resources, ready for deployment to the device.

As well as the binary file, the resource compiler creates the header file MAheaders.h which should be included in your application program. This header file contains the #defines that symbolically link your application to its resources.

Resource List Files

To determine what resources it needs to compile, the resource compiler reads the resource list files (.lst) files in your project. A resource list file is a standard text file.

A resource listfile contains one or more resource definitions, and each resource definition in the file contains one or more commands for the compiler. Each resource definition begins with the .res command.

Example

/* Example of a resource list (.lst) file. A project can contain more than one .lst file */

/* Define an image resource */
.res image1
.dispose  // delete the image after loading has finished in run time
.image "testimage.png", 99, 99

/* Define a file resource */
.res afile
.bin
.include "testfile.dat"

/* Set a label for the beginning of mysprite */
.label mysprite_start

/* Define a sprite resource */
.res mysprite
.sprite image1, /* XY */ 0, 0, 10, 10, 5, 5

/* Define a binary resource */
.res                       // a resource with no name but which can be referenced as e.g. mysprite+1 
.bin
.string "The buck"         // string
.fill 8, '?'               // fill memory
.string "stops here!!!"    // string with esc codes
.byte 1,2,3,4              // bytes
.half 5,6,7,8              // shorts
.word 9,10,11,12           // ints
.include "randomdata.bin"  // include file

Resource IDs and numbering

Resources are numbered sequentially, starting at 1. The resource ID 0 is reserved.

Additionally, the .res command can include a symbolic identifier for the resource, which can be used to reference a previously loaded resource in a later command (see, for example .sprite in the example above).

The .label command can be used to identify the location of resources for the application in run time.

Comments

Both standard C and C++ comments can be used in the resource list file.

Command Reference

This section describe the various commands that can be included within the definitions in a resource list file.

.res [symbol]

Initializes a new resource, optionally with the symbolic name symbol:

.res myimage
.image "myimage.png"

.image "imagefile"

Declares a resource as an image and loads and stores an image file into the resource. The recommend image format is PNG which is supported by almost all devices. (Any type may be declared but whether or not the device supports it is another matter....) The filename can include a relative path, but always use forward slashes or escaped backslashes in the pathname. 

.res picture
.image "myfile\\myimage.png"    

.bin

Declares the resource as a binary. A binary resource is created and has 0 length.

.res myfile
.bin 

.ubin

Declares the resource as an unloaded binary. A binary resource is created and has 0 length. At runtime this resource will not be memory resident, but is accessed from the file system directly.

.media "MimeTypeString", "MediaFile"

Declares the resource as a media file with a particular MIME type. (Any type may be declared but whether or not the device supports it is another matter....) The filename can include a relative path, but always use forward slashes or escaped backslashes in the pathname.

.res tune1
.media "audio/mp3", "myfiles/mysound.mp3"

.umedia "MimeTypeString", "MediaFile"

Declares the resource as a unloaded media file with a particular MIME type. (Any type may be declared but whether or not the device supports it is another matter....) At runtime this resource will not be memory resident, but is accessed from the file system directly. The filename can include a relative path, but always use forward slashes or escaped backslashes in the pathname.

.res tune2
.umedia "audio/mp3", "mysound2.mp3"

.sprite imageRef, start_x, start_y, size_x, size_y[, ref_x, ref_y]

Declares the resource as a sprite object. It requires an image reference for a previously loaded image. The sprite is cut out from this image at start_x and start_y. The size of the sprite is defined by size_x and size_y. Optionally, the sprite's reference point is defined by ref_x and ref_y. If ref_x and ref_y are omitted, the reference point is set as top-left (0,0).

.res myimage    // set symbol for base image
.image "myimage.png"   // load base image, the top-left is always 0,0 

.res mysprite1
.sprite myimage,0,0,10,10    // cut sprite from myimage from 0,0 to 10,10, default reference point = 0,0

.res mysprite2
.sprite myimage,10,0,10,10,5,5    // cut sprite from myimage from 10,0 to 10,10, reference point =  5,5

.tileset "imageFile",tilesize_x,tilesize_y

Declares the resource as a tileset image. The image contains tiles of the specified tilesizes. The filename can include a relative path, but always use forward slashes or escaped backslashes in the pathname.

.res
.tileset "mytiles.png",16,16

.tilemap "tilemap.bin",mapsize_x,mapsize_y

Declares a tilemap. The tilemap binary file contains mapsize_x*mapsize_y 16-bit indices that refer to a tileset. The actual connection between tilemap and tileset is created at runtime. The filename can include a relative path, but always use forward slashes or escaped backslashes in the pathname.

.res
.tilemap "mytilemap.bin",64,64

.dispose

Marks a resource as disposable. When the resource loader has finished loading all resources, it deletes all those resources marked for disposal.

.res image1  
.dispose    // dispose of resource after loading
.image "myimage.png"

.placeholder

Creates an empty resource that can be filled with something at runtime.

.res myspace
.placeholder

.skip

Skips a resource when loading. This can be useful when you have duplicated resource list files and wish to skip some resources in some lists.

myreslist1.lst:

.res image1
.image "myfile/myimage1.png"

.res image2
.image "myfile/myimage2.png"

myreslist2.lst:

.res image1
.image "myfile/myimage1.png"   

.res image2
.image "myfile/myimage2.png" 
.skip

.label "name"

Creates a marker label resource entry, so the application can search for the resource symbolically at runtime. This allows libraries to find their resources. 

.label ui_resource_begin

.enum {variable[=expression][, variable[=expression] ...]}

Defines an enumerated set of variables that can be used in expressions.

.res myenum
.enum
{
a = 0,
b,         // assigns to b the value of the next enum (1)
days = 365,
d         // assigns to d the value of the next enum (366)
}

.string "string"

For binary resources only:  inserts an ASCII string. Note: This string has no null terminator.

.res welcome
.bin
.string "hello"    //  write non-null-terminated string to binary resource

.cstring "string"

For binary resources only: inserts an ASCII null-terminated string.

.res
.bin
.cstring "hello"    //  write null-terminated string to binary resource

.pstring "string"

For binary resources only: inserts a Pascal string.

.res
.bin
.pstring "hello"    // write Pascal string to binary resource

.fill size, filler

For binary resources only:  fills the resource with size bytes of the filler. The data will be inserted at the current data position.

.res
.bin
.fill 8, '?'    // insert '?' 8 times

.byte n1[,n2 ...]

For binary resources only: inserts bytes into the resource. The data is inserted at the current data position.

.res
.bin
.byte 1,2,3,4    //  write bytes 1,2,3,4 to binary resource

.half n1[,n2] ...

For binary resources only: inserts half words (16 bits) into the resource. The data is inserted at the current data position.

.res myfile
.bin
.half 1,2,3,4    // write shorts 1,2,3,4 to the binary resource

.word n1[,n2] ...

For binary resources only: inserts (32-bit) words into the resource. The data is inserted at the current data position.

.res myfile
.bin
.word 1,2,3,4    // write ints 1,2,3,4 to the binary resource

.include "file"

For binary resources only: inserts a binary file into the resource. The data is inserted at the current data position. The filename can include a relative path, but always use forward slashes or escaped backslashes in the pathname.

.res myfile
.bin
.include "bin/test.bin"   // write the contents of test.bin to the binary resource

.index symbol

For binary resources only: add an index so that a single resource can contain sub-indices. A resource with indices will contain an index table, which can be read by the user's program code with the resource index reading functions.

.res
.bin
.index "MySym"

.wideindex

For binary resources only: forces a indexed resource to use 32 bit indices's, so an index table may contain data pointers greater than 64K.

.res
.bin
.wideindex

.set variable[=expression]

Sets a script variable with the value of expression.

.res
.set hello = 1


Share on Facebook
MoSync AB | © 2004-2011 All Rights Reserved