Monday, April 27, 2009

Storing Resource (WAV, MP3, ...) into Delphi Executables

Games and other types of applications which use multimedia files like sounds and animations must either distribute the extra multimedia files along with the application or embed the files within the executable.
Rather than distribute separate files for your application's use, you can add the raw data to your application as a resource. You can then retrieve the data from your application when it is needed. This technique is generally more desirable because it can keep others from manipulating those add-in files.

This article will show you how to embed (and use) sound files, video clips, animations and more generally any kind of binary files in a Delphi executable. For the most general purpose you'll see how to put a MP3 file inside a Delphi exe.

Resource Files (.RES)

In the "Resource Files Made Easy" article you were presented with several examples of the use of bitmaps, icons and cursors from resources. As stated in that article we can use the Image Editor to create and edit resources that consist of such types of files. Now, when we are interested in storing various types of (binary) files inside a Delphi executable we'll have to deal with resource script files (.rc), the Borland Resource Compiler tool and other.

Including several binary files in your executable consists of 5 steps:


  1. Create and/or collect all the files you whish to put in an exe,
  2. Create a resource script file (.rc) that describes those resources used by your application,
  3. Compile the resource script file (.rc) file to create a resource file (.res),
  4. Link the compiled resource file into the application’s executable file,
  5. Use individual resource element.
The first step should be simple, simply decide what types of files you would like to store in you executable. For example, we will store two .wav songs, one .ani animations and one .mp3 song.

Before we move on, here are a few important statements concerning limitations when working with resources:

a) Loading and unloading resources is not a time consuming operation. Resources are part of the applications executable file and are loaded at the same time the application runs.

b) All the (free) memory can be used when loading/unloading resources. In other words there are no limits on number of resources loaded at the same time.

c)Of course, resource file do double the size of an executable. If you want smaller executable consider placing resources and parts of your project in DLLs and Packages.

Let's now see how to create a file that describes resources.

Creating a Resource Script File (.RC)

A resource script file is a just a simple text file with the extension .rc that lists resources. The script file is in this format:
ResName1 ResTYPE1 ResFileName1
ResName2 ResTYPE2 ResFileName2
...
ResNameX ResTYPEX ResFileNameX
...
RexName specifies either a unique name or an integer value (ID) that identifies the resource. ResType describes the type of resource and the ResFileName is the full path and file name to the individual resource file.

To create a new resource script file, simply do the following:


  1. Create a new text file in your projects directory.
  2. Rename it to AboutDelphi.rc.
In the AboutDelphi.rc file, have the following lines:
Clock WAVE "c:\mysounds\projects\clock.wav"
MailBeep WAVE "c:\windows\media\newmail.wav"
Cool AVI cool.avi
Intro RCDATA introsong.mp3
The script file simply defines resources. Following the given format the AboutDelphi.rc script lists two .wav files, one .avi animation, and one .mp3 song. All statements in a .rc file associate an identifying name, type and file name for a given resource. There are about a dozen predefined resource types. These include icons, bitmaps, cursors, animations, songs, etc. The RCDATA defines generic data resources. RCDATA let you include a raw data resource for an application. Raw data resources permit the inclusion of binary data directly in the executable file. For example, the RCDATA statement above names the application’s binary resource Intro and specifies the file introsong.mp3, which contains the song for that mp3 file.

Note: make sure you have all the resources you list in your .rc file available. If the files are inside your projects directory you don't have to include full file name. In my .rc file .wav songs are located *somewhere* on the disk and both the animation and mp3 song are located in the project's directory.

Creating a Resource File (.RES)

To use the resources defined in the resource script file, we must compile it to a .res file with the Borland's Resource Compiler. The resource compiler creates a new file based on the contents of the resource script file. This file usually has an .res extension. The Delphi linker will later reformat the .res file into a resource object file and then link it to the executable file of an application.

The Borland's Resource Compiler command line tool is located in the Delphi Bin directory. The name is BRCC32.exe. Simply go to the command prompt and type brcc32 then press Enter. Since the Delphi\Bin directory is in your Path the Brcc32 compiler is invoked and displays the usage help (since it was called with no parapeters).

To compile the AboutDelphi.rc file to a .res file execute this command at the command prompt (in the projects directory):

BRCC32 AboutDelphi.RC
By default, when compiling resources, BRCC32 names the compiled resource (.RES) file with the base name of the .RC file and places it in the same directory as the .RC file.

You can name the resource file anything you want, as long as it has the extension ".RES" and the filename without the extension is not the same as any unit or project filename. This is important, because by default, each Delphi project that compiles into an application has a resource file with the same name as the project file, but with the extension .RES. It's best to save the file to the same directory as your project file.

No comments: