data in a masm32
/tasm compatible dump<
/font><
/table><
/center><
p>As you can see, the last parameter is expected to be a filename, specifying the XM file you plan to use in your application. Additional options:<
ul><
li><
b>
/Dm<
/b> produces a hex dump from the given XM file, suitable
for MASM32 and TASM. The syntax is also suitable
for FASM and NASM. However, both FASM and NASM support embedding binary
content from a file directly. This option should be enabled to use the <
b>
/M<
/b> key
(see below
).<
li><
b>
/Dd<
/b> and <
b>
/Dc<
/b> produce hex dumps in Pascal
(Delphi, Kylix, FreePascal
) or C
/C++ format respectively.<
li><
b>
/Ds<
/b> generates a hex dump in RCDATA format, used in resource scripts. No real use in KolibriOS.<
li>Specify <
b>
/Di<
/b> to disable all the information functions: uFMOD_GetStats, uFMOD_GetRowOrder, uFMOD_GetTitle and uFMOD_GetTime. Removing them reduces the library
size and makes it somewhat faster.<
li><
b>
/Dp<
/b> removes uFMOD_Pause and uFMOD_Resume functions and makes uFMOD ignore the XM_SUSPENDED flag. If you don
't plan to use pause/resume features, add this option to the command line and save some more bytes.<li>uFMOD_SetVolume not only makes the library bigger, but also consumes some additional CPU time. Just use <b>/Dv</b> to turn it off and recover some bytes and clock cycles ;)<li><b>/Dj</b> disables the Jump2Pattern feature. This is an advanced feature, not used in most applications. Check the <a href='#
5'>"Reducing the executable file size"</a> section for more information on using Jump2Pattern.<li>Not going to play files - only memory arrays? Then, you'd probably like to use <
b>
/Df<
/b> in order to make the library smaller.<
li><
b>
/Dl<
/b>
(lower-case letter L
) makes uFMOD ignore the XM_NOLOOP flag
(and makes the library smaller and faster, as expected
).<
li>Finally, a really insane optimization option is available only
for assembly coders. There are some byte chunks inside every XM file, which are reserved
for future use or just holding metadata
(comments, adds and so on
). <
b>
/M<
/b> marks all such
'holes' in the hex dump and makes them available
for something more useful, like storing
code and
/or
data right inside the XM track.
src/Masm32
/ example uses this feature.<
/ul>On success, Eff produces a file EFF.INC and a hex dump, if requested. Some examples
(all correct
):<
p><
b>eff
/Dmpvjfl
/M example.xm<
br>eff
/M
/Dm
/Dp
/Dv
/Dj
/Df
/Dl example.xm<
br>eff -M -Dmpvjfl example.xm<
/b><
p>The above commands produce an assembly dump with all the
'holes' properly outlined and cleared by default. The EFF.INC header contains the XM effects actually used in the given XM file and some additional flags to disable pause
/resume, volume control, Jump2Pattern, loading files and XM_NOLOOP. Copy EFF.INC to
src/ufmodlib
/src/ and recompile the library
(check the following section
for a quick guide
). Enjoy your own extremely optimized uFMOD build, but keep in mind that it contains a subset of XM effects. So, it will play normally only the given XM file!<
p> <
br><
a name='3'><
b>Compiling the library<
/b><
/a><
p>Recompiling the library sources is required after using <
a href='#22'>Eff<
/a> or to enable some special features in a regular build
(check the <
b>Options<
/b> table below
). Some people might consider modifying the source
code of the library just to practice assembly programming or
for any other reason. Well, the following information is intended only
for those interested in the subject.<
p>The complete source
code is included in
src/ufmodlib
/src/:<
ul><
li><
span style='color:#800080'><
b>eff.inc<
/b><
/span> is a header file. The <
a href='#22'>Eff<
/a> tool generates this file. Modifying it directly is not recommended, though an assembly coder never pays attention to this kind of recommendations anyway :
)<
li><
span style='color:#800080'><
b>ufmod.inc<
/b><
/span> contains a detailed uFMOD API description suitable
for ASM
/C
/C++ development.<
li><
span style='color:#800080'><
b>ufmod-codec.h<
/b><
/span> describes the special AC97SND mode API. This API is intended
for codec-oriented audio file players like Serge
's AC'97 player.<
li><
span style='color:#008080'><
b>core.asm<
/b><
/span> contains most of the uFMOD source
code. The exactly same file is used in KolibriOS, Unix
/BSD, Linux and Win32 packages. Loading an XM track, mixing sound channels, XM effects handling and other common algorithms are all implemented in this file.<
li><
span style='color:#008080'><
b>ufmod.asm<
/b><
/span> contains platform-specific implementation: file I
/O, driver I
/O, etc. The contents of this file vary in KolibriOS, Unix
/BSD, Linux and Win32.<
li><
span style='color:#008080'><
b>fasm.asm<
/b><
/span> contains Flat Assembler
(FASM
) specific definitions. This stub file makes it possible to compile uFMOD using FASM.<
li><
span style='color:#008080'><
b>masm.asm<
/b><
/span> contains MASM32 specific definitions. This stub file makes it possible to compile uFMOD using MASM32.<
li><
span style='color:#008080'><
b>nasm.asm<
/b><
/span> contains Netwide Assembler
(NASM
) specific definitions. This stub file makes it possible to compile uFMOD using NASM.<
/ul><
p>Once you are done modifying the uFMOD sources, if you want to rebuild ufmod.obj, open
src/ufmodlib
/makeobj.bat in a plain
text editor. Everything contained between the following lines:<
pre>rem *** CONFIG START<
/pre>and<
pre>rem *** CONFIG END<
/pre>is configurable. First, check the <
code>Pathes<
/code> section. There is an option saying:<
pre>SET UF_NASM
=\nasm<
/pre>If you do have NASM installed, make sure the above path points exactly to where nasmw.exe is located. Let
's say NASM has been installed to <code>D:\TOOLS\NASM</code>. Then, you'd have to modify the above entry as follows:<
pre>SET UF_NASM
=D:\TOOLS\NASM<
/pre>Not all of the pathes are used to recompile the library.
For example, if you prefer using FASM as your default assembler, you don
't need to setup the NASM path. Make sure all the pathes actually required to build the library have been set correctly. Then, procede modifying the available options, according to the following table:<p><table border=0 cellpadding=4 cellspacing=2 style='font-
size:10pt;font-family:Arial,Aerial
'><tr bgcolor=#708090 style='color:#E7E7E7;font-weight:bold
'><td>Option<td>Description<td width=200>Values<tr valign=top><td>UF_RAMP<td>This option controls the volume ramping (interpolation) mechanism. Ramping is intended to suppress audible clicks, but sometimes it may introduce distortion. STRONG is the default value recommended for most applications. It detects volume changes during sample playback and softens them using a 128-stage linear ramp. WEAK involves only 16 stages. It is less effective than STRONG, but distortion is also less likely to happen. NONE doesn't perform ramping at all. No ramping
= no distortion, but most XM samples will produce clicks, unless the samples are well balanced enough.<
td>NONE, WEAK, STRONG<
tr bgcolor=#E7E7E7
valign=top><
td>UF_FREQ<
td>Mixing rate
(in Hz
). 48KHz is the
value recommended
for most applications.<
td>
22050,
44100,
48000<
tr valign=top><
td>UF_ASM<
td>Assembler. Yes, the uFMOD library is compilable with various assemblers. Choose your favorite :
)<
td>MASM, NASM, FASM<
tr bgcolor=#E7E7E7
valign=top><
td>UF_MODE<
td>NORMAL is the default
value. Nothing special. UNSAFE disables checking an XM track
for validity at load time. When you are sure all XM tracks are valid
(you can use Eff or XMStrip to verify an XM file
), you can recompile uFMOD in UNSAFE mode to reduce the file
size and maximize the loading speed. Keep in mind that a damaged XM file can actually crash uFMOD while in UNSAFE mode! When AC97SND mode is on, ufmod.obj will contain a special codec-like uFMOD
version, used in Serge
's AC'97 player. It features a different API
(if interested, check the ufmod-plugin.h header file
for additional info
).<
td>NORMAL, UNSAFE, AC97SND<
/table><
p>Run the batch file to build the library. That
's all!<p> <br><a name='4'><b>Examples</b></a>