forked from KolibriOS/kolibrios
33 lines
20 KiB
HTML
33 lines
20 KiB
HTML
|
<html><head><meta http-equiv=Content-Type content="text/html; charset=windows-1251"><title>uFMOD</title></head><body style='margin:0'><table border=0 cellpadding=0 cellspacing=0 width=100%><tr bgcolor=#E7E7E7 align=center><td height=20 style='color:#708090;font-size:9pt;font-family:Arial,Aerial'>[ English | <a href='es.htm'>Español</a> | <a href='ru.htm'>Pyccκuú</a> ]<tr bgcolor=#708090><td height=1></table><center><h2 style='font-size:14pt;font-family:Arial,Aerial'>μFMOD v1.25 for KolibriOS</h2></center><div style='font-size:10pt;font-family:Arial,Aerial;text-align:justify;margin:8'><p>uFMOD is an XM player library written in assembly language. It's perfect for size- and speed-critical applications, click free, highly reliable, easy to use, open source, multiplatform. File and direct memory playback supported. It is able to play even damaged and non-standard XM tracks. Usage examples available for the following compilers: FASM, MASM32 and NASM.<p>KolibriOS port should run correctly on any PC meeting the following requirements:<ol><li>KolibriOS SVN revision 574 or later. You can download the latest official distro and the SVN binaries from <a href='http://www.kolibrios.org/?&lang=en'>www.kolibrios.org</a>.<li>A sound card supported by the <a href='http://infinity-sound.narod.ru/'>Infinity Sound audio library</a>. It is the default KolibriOS sound driver. Currently it supports many AC'97 compatible sound cards.</ol>If your machine meets the above requirements but uFMOD doesn't run properly, let us know (check the <a href='#ci'>contact information</a> near the bottom of this page).<ul><li><a href='#1'>Getting started</a><li><a href='#2'>Tools</a><ul><li><a href='#21'>XMStrip</a><li><a href='#22'>Eff</a></ul><li><a href='#3'>Compiling the library</a><li><a href='#4'>Examples</a><li><a href='#5'>Reducing the executable file size</a><li><a href='#6'>FAQ</a><li><a href='#7'>Thanks</a></ul><p> <br><a name='1'><b>Getting started</b></a><p>KolibriOS is an operating system written is assembly language. That's why it is so small and extremely fast. It is very powerful as well, as you've probably found out already. That's also uFMOD's spirit ;)<p>Most of the tasks described below can be accomplished directly in Kolibri. However, since many novice Kolibri coders prefer compiling their programs in Windows and then moving them to Kolibri for testing, we'll use crosscompilation here for the sake of universality.<p> <br><a name='2'><b>Tools</b></a><p>There are 2 freeware tools currently available to use along with uFMOD: XMStrip and Eff. None of them has been ported to KolibriOS yet. So, you should pick one of the other platform-specific distros (Win32, Linux or Unix/BSD) and use XMStrip and Eff crossplatformly. No matter which platform-specific version you choose, both utilities have dual interface: terminal and GUI. GUI is rather self-explanatory. Next, we'll explain the terminal interface.<p><table border=0 cellpadding=0 cellspacing=0 bgcolor=#708090 style='font-size:9pt;font-family:Arial,Aerial'><tr><td colspan=3 height=1><tr height=18><td style='color:#E7E7E7'><b> SVN </b><td bgcolor=#E7E7E7> <a href='http://ufmod.svn.sourceforge.net/viewvc/ufmod'>Complete source code available</a> <td width=1><tr><td colspan=3 height=1></table><p><a name='21'><b><i>XMStrip</i></b></a> expects an XM filename on input, repacks the file contents to make it smaller, without losing sound quality. What it does exactly is removing overhead data (dummy instruments, patterns and junk metadata), stripping reserved and currently unused bytes, repacking pattern data. Running <code>xmstrip /h</code> produces the following output:<p><center><table border=0 cellpadding=8><tr bgcolor=#000000><td><pre><font color=#FFFFFF> USAGE: xmstrip [options] file [output]
|
||
|
|
file - input file name.
|
||
|
|
output - optional output file name.
|
||
|
|
options:
|
||
|
|
/c - clean only (don't strip)
|
||
|
|
When [output] is not specified, XMSTRIP
|
||
|
|
attempts to overwrite the input. If file
|
||
|
|
name contains spaces, enclose it in "".</font></table></center><p>Keep in mind, that other XM players whould probably reject a 'stripped' XM file. The <b>/c</b> option is useful for 'recovering' such a stripped file or just cleaning a regular file intended to be played with any other XM player.<p><a name='22'><b><i>Eff</i></b></a> is useful for advanced users, willing to squeeze every single byte out of their applications. The general idea is to extract only those features you do mean to use in your application, recompile the uFMOD library from source and obtain the smallest possible footprint. Running <code>eff /h</code> requests the following prompt:<p><center><table border=0 cellpadding=8><tr bgcolor=#000000><td><pre><font color=#FFFFFF> USAGE: eff [options] file
|
||
|
|
file - input file name
|
||
|
|
options:
|
||
|
|
/Dm - generate a masm32/tasm dump
|
||
|
|
/Dd - generate a Pascal (Delphi) dump
|
||
|
|
/Dc - generate a C/C++ dump
|
||
|
|
/Ds - generate an RCDATA resource dump
|
||
|
|
/Di - disable infoAPI:
|
||
|
|
uFMOD_GetStats, uFMOD_GetRowOrder,
|
||
|
|
uFMOD_GetTitle and uFMOD_GetTime
|
||
|
|
/Dp - disable uFMOD_Pause, uFMOD_Resume
|
||
|
|
and XM_SUSPENDED
|
||
|
|
/Dv - disable volume control
|
||
|
|
/Dj - disable Jump2Pattern
|
||
|
|
/Df - disable loading XM from file
|
||
|
|
/Dl - disable XM_NOLOOP
|
||
|
|
/M - mark & clear unused chunks of
|
||
|
|
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.
|
||
|
|
<b>File 1 :</b> XM1_HEADER P11 P12 P13 I11 I12
|
||
|
|
<b>File 2 :</b> XM2_HEADER P21 P22 P23 P24 I21 I22 I23 I24
|
||
|
|
<b>File 3 :</b> XM3_HEADER P31 I31
|
||
|
|
</pre><i><b>Legend:</b> XMn_HEADER is the header of the n-th XM file. Pni is the i-th pattern of the n-th XM file. Ini is the i-th instrument of the n-th XM file.</i><p>First, let's merge them in a single file without sharing the instruments:<pre>
|
||
|
|
<b>File 4 :</b> XM4_HEADER P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I23 I24 I31
|
||
|
|
</pre>Now, let's say I12 is very similar or even equal to I23 and I24 is the same as I31. So, we can modify P2n to make them use I12 instead of I23 and P31 to use I24, so that we can remove I23 and I31:<pre>
|
||
|
|
<b>File 4 :</b> XM4_HEADER P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I24
|
||
|
|
</pre>You'll have to modify the looping and pattern jumping commands and the references to instruments in "files" 2 and 3. Obviously, you can merge just 2 files or more than 3. XM file format limits the amount of patterns and instruments in a single file. That's the general idea. You'd have to learn how to use a tracker in order to perform this kind of optimization. Once you've got all your files merged, you can issue a single uFMOD_PlaySong function call and trigger all the "files" with uFMOD_Jump2Pattern. For example, uFMOD_Jump2Pattern(3) will start playing the 2nd "file", uFMOD_Jump2Pattern(7) will launch the 3rd and uFMOD_Jump2Pattern(0) will reset to the first "file". The exact indexes depend on your pattern layout. The <b>jmp2pat</b> example uses this feature.<p>Using Jump2Pattern has another advantage: switching is done much faster (practically in no time), as opposed to stopping and reloading a track. So, you can use this feature when quickly switching the background music is required.<p> <br><a name='6'><b>FAQ</b></a><p><span style='color:#008080'><b>Q:</b> Is uFMOD free for any type of use? Even commercial?</span><br><b>A:</b> Yes, currently it is.<p><span style='color:#008080'><b>Q:</b> Where can I get XM files from?</span><br><b>A:</b> Try visiting <a href='http://modarchive.org/'>The Mod Archive</a>. They have a huge archive of free tracker music in XM, IT, S3M and MOD format. You can use <a href='http://www.modplug.com/'>Open Modplug Tracker</a> to convert IT, S3M and MOD tracks to XM format without apparent degradation. There are many talented composers out there in the web sharing their music at no cost. Just don't forget the copyright!<p><span style='color:#008080'><b>Q:</b> Is uFMOD related in some way to Firelight Technologies® FMOD and miniFMOD sound libraries?</span><br><b>A:</b> Not any more. Up until 2004 uFMOD was based on the latest miniFMOD public source code release. Since then, library sources had been completely rewritten, introducing many new features. So, uFMOD is in no way representative of FMOD and miniFMOD sources.<p><span style='color:#008080'><b>Q:</b> Some XM player libraries claim to add only N kilobytes to the executable file. How many Kb does uFMOD add exactly to the executable's size?</span><br><b>A:</b> It is impossible to tell an exact value, because it depends on library features used (especially, when using the Eff utility), test program code layout, XM file size (when embedding the XM into the executable file). It also depends on the linker options. For example, bin/mini is 4.768 bytes without compression.<p><span style='color:#008080'><b>Q:</b> Where can I get the official XM file format specification from?</span><br><b>A:</b> No official and up to date specification exists. However, you can take a look at <a href='http://sourceforge.net/project/showfiles.php?group_id=158498&package_id=234625'>"The Unofficial XM File Format Specification: FastTracker II, ADPCM and Stripped Module Subformats"</a>. This document covers most aspects of the original XM file format and all the non-standard extensions currently supported by uFMOD. ModePlug's public source code (it's C++) also serves as reference material on module file formats.<p> <br><a name='7'><b>Thanks go out to</b></a><p>antarman, Barracuda, bogrus, chris_b, cresta, dododo, flaith, Four-F, GL#0M, norki, q_q, SofT MANiAC, S_T_A_S_, voodooattack and yoxola for reporting bugs, requesting interesting features, submitting usage examples and otherwise helping us improve uFMOD.<p><a href='http://wasm.ru'>[WASM.RU]</a> and <a href='http://sf.net'>SourceForge.net</a> for support and hosting.<p> <br><b>Copyright</b><p>uFMOD sources, binaries and utility programs © 2005 - 2007 Asterix and Quantum.<br>All rights reserved.<p>Sample tunes:<ul><li>Minimal III © 2006 - 2007 SofT MANiAC (CoolPHat).<li>BlitzXMK.XM from Jump2Pat example © 2007 Kim (aka norki).</ul></div><table border=0 cellpadding=0 cellspacing=0 width=100%><tr bgcolor=#708090><td height=1><tr bgcolor=#E7E7E7><td height=52 style='color:#7080
|