uFMOD - это компактная, шустрая, надёжная, мультиплатформенная библиотека для качественного воспроизведения аудио в формате XM, разработанная полностью на ассемблере. XM может храниться в отдельном файле, в ресурсах или предварительно загружен в память. Поддерживаются также битые и не совсем стандартные файлы. Библиотека распространяется с открытым исходным кодом и примерами для следующих компиляторов: Visual C++, C#, Visual Basic, PureBasic, FreeBASIC, BlitzMax, Emergence BASIC, Delphi, Borland C++ Builder, Dev-C++ (MingW), FreePascal, MASM32, FASM, NASM и TASM.

• WINMM, DirectSound или OpenAL?
• Утилиты
  • XMStrip
  • Eff
• Компиляция библиотеки
• Примеры
• Дополнительное уменьшение размера
• ЧаВо
• Благодарности

 
WINMM, DirectSound или OpenAL?

uFMOD для Win32 поддерживает WINMM, DirectX® DirectSound и OpenAL. Все 3 подсистемы имеют свои плюсы и минусы. DirectX предоставляет возможность использовать звуковые эффекты, позволяет проигрывать одновременно несколько звуковых сигналов, поддерживает трёхмерный звук, спроектирован более надёжно чем WINMM. Зато WINMM поддерживается даже в Windows 95. OpenAL кроссплатформенна (доступны версии для Windows, Linux, Macintosh и т.д.), поддерживает аппаратное ускорение эффектов 3D-окружения, что очень полезно для разработчиков игр. Тем не менее, OpenAL не поставляется предустановленной в Windows XP и более ранних версиях, за исключением OEM машин со звуковыми карточками Creative. Таким образом, Вам скорее всего придётся скачать и установить OpenAL самостоятельно. В зависимости от аппаратуры и драйверов, качество звука может быть лучше в DirectSound или WINMM, хотя среднестатистический пользователь вряд ли почувствует разницу. Если вы не уверены какую версию uFMOD выбрать для своего проекта, скорее всего вам больше подойдёт стандартная версия с WINMM, так как она проще в использовании: для воспроизведения звука достаточно добавить всего лишь пару строчек кода.

 
Утилиты

В комплект включена пара бесплатных утилит для использования совместно с uFMOD: XMStrip и Eff. Обе утилиты совмещают в себе консольный и графический (GUI) интерфейсы. Если присутствуют параметры командной строки, включается консольный режим. Режим GUI интуитивно понятен, так что дальнейшее описание касается только консольного.

XMStrip обрабатывает заданный XM файл с целью уменьшения размера, без потери качества звучания. В процессе обработки, XMStrip удаляет неиспользующиеся инструменты и партитуры, вырезает комментарии и перепаковывает внутренние структуры файла для уменьшения размера и повышения скорости загрузки. Для начала, откроем командный интерпретатор и введём xmstrip /h чтобы получить следующее сообщение:

 uFMOD XMSTRIP
 USAGE:  xmstrip [options] file [output]
         file   - input file name, which can
                  contain wildcards (* and ?)         
                  for batch processing.
         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 "".

Если имя сохраняемого файла не указано, XMStrip перезапишет заданный файл. Если имя файла содержит пробелы, его необходимо заключить в кавычки (""). XMStrip поддерживает пакетную обработку файлов (символы * и ?).

Имейте в виду, что другие проигрыватели XM файлов, возможно, откажутся воспроизводить файл, обработанный XMStrip. Опция /c предусмотрена для восстановления таких файлов или обработки обычных XM файлов, которые планируется проигрывать не только в uFMOD.

Eff предназначается для опытных кодеров, желающих сэкономить каждый байт в своих приложениях. Для этого нужно выделить только те функции uFMOD, которые действительно будут использованы в целевом приложении, перекомпилировать библиотеку и получить наименьший возможный размер. Вот, что выдаёт eff /h :

 uFMOD XM effects extractor
 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
          /Dr - disable loading XM from resource
          /Dl - disable XM_NOLOOP
          /M  - mark & clear unused chunks of
                data in a masm32/tasm compatible dump

Последний параметр - имя XM файла, на использование которого ориентируются следующие параметры оптимизации:

• /Dm создаёт текстовый дамп данного XM файла для использования в исходнике на MASM32 или TASM. Примеры для MASM32 и TASM, в текущем дистрибутиве uFMOD, используют эти дампы вместо обычных ресурсов для оптимизации размера экзешника.
• /Dd и /Dc создают подобные дампы, но для Pascal (Delphi, Kylix, FreePascal) или C/C++ соответственно.
• /Ds создаёт аналогичный дамп в формате RCDATA, который используется в скриптах описания ресурсов (*.rc). Не все компиляторы ресурсов поддерживают синтаксис Microsoft: id RCDATA "имя_файла". Поэтому приходится использовать дампы для совместимости, например, со старыми версиями компилятора ресурсов GNU, вроде того, что входит в состав Dev-C++.
• Ключ /Di отключает все информативные функции: uFMOD_GetStats, uFMOD_GetRowOrder, uFMOD_GetTitle и uFMOD_GetTime. Это даёт выигрыш не только в размере библиотеки, но и в скорости.
• /Dp отключает функции uFMOD_Pause и uFMOD_Resume и поддержку флага XM_SUSPENDED. Если Вы не собираетесь использовать pause/resume, включите этот ключ в параметры командной строки для экономии ещё нескольких байт.
• uFMOD_SetVolume увеличивает не только размер библиотеки, но ещё и загрузку CPU. Добавьте ключ /Dv, чтобы отключить эту функцию и сэкономить несколько байт и тактов ;)
• /Dj отключает функцию Jump2Pattern. Данная функция предназначена для очень специфичных задач и, поэтому, используется редко. В разделе "Дополнительное уменьшение размера" подробно описано использование Jump2Pattern.
• Вам не нужна поддержка загрузки файлов и/или ресурсов? - Всё равно эффективнее использовать дампы вместо ресурсов! Тогда, не задумываясь, включайте /Df и /Dr для дополнительного уменьшения размера.
• Ключ /Dl (маленькая L) отключает поддержку флага XM_NOLOOP (и, следовательно, благотворно влияет на размер и скорость).
• Совсем "экстремальный" вид оптимизации предусмотрен специально для кодеров MASM32/TASM. В каждом XM файле есть цепочки байт, которые зарезервированы на будущее, или просто содержат комментарии или любую другую, не имеющую отношения к проигрыванию, информацию. /M выделяет эти "дыры", предоставляя возможность заполнить их полезной информацией (разместить данные или даже код). Пример Masm32\winmm\ как раз использует эту опцию.

eff /Dmpvjfrl /M file.xm
eff /M /Dm /Dp /Dv /Dj /Df /Dr /Dl file.xm
eff -M -Dmpvjfrl file.xm

Любой из предыдущих примеров создаст дамп для MASM32/TASM, выделит "дыры" и предварительно заполнит их нулями. Файл EFF.INC содержит список эффектов XM, которые действительно используются в заданном файле, и некоторые дополнительные флаги для отключения pause/resume, регулятора громкости, Jump2Pattern, поддержки файлов и ресурсов и XM_NOLOOP. Поместите этот новый EFF.INC в ufmodlib\src\ и перекомпилируйте библиотеку (в следующем разделе освещены некоторые вопросы касающиеся компиляции исходников библиотеки). Теперь у Вас имеется свой собственный оптимизированный билд uFMOD, но имейте в виду, что в этом билде включены не все эффекты XM. Поэтому, не следует использовать его для проигрывания других XM файлов, отличных от обработанного утилитой Eff!

 
Компиляция библиотеки

Необходимость компиляции исходников библиотеки uFMOD возникает при использовании утилиты Eff, а также для включения особых режимов и опций, которые отключены в сборке по умолчанию (см. таблицу Опции ниже). Для тех, кто хочет попрактиковаться в ассемблере и/или разобраться в библиотеке на самом низком уровне (в хорошем смысле), и предназначен данный раздел.

Исходники uFMOD расположены в ufmodlib\src\:

• eff.inc - этот заголовочный файл создаётся утилитой Eff. Не рекомендуется редактировать данный файл вручную.
• equs.inc содержит определения структур и констант, используемых в исходниках библиотеки.
• В core.asm находится большая часть исходного кода uFMOD. Этот самый файл присутствует во всех дистрибутивах библиотеки: Win32, Linux, Unix/BSD и KolibriOS. Загрузка XM-файла, смешивание каналов, наложение XM-эффектов и многие другие общие для всех дистрибутивов алгоритмы реализованы в данном файле.
• ufmod.asm содержит платформозависимые процедуры: чтение файлов и ресурсов, создание потоков и т.д. Поэтому, содержимое данного файла различается в дистрибутивах для разных ОСей.
• fasm.asm хранит определения констант, структур и т.д. под синтаксис Flat Assembler (FASM). Этот файл позволяет собирать различные версии библиотеки с помощью FASM.
• masm.asm хранит определения констант, структур и т.д. под синтаксис MASM32/TASM. Этот файл позволяет собирать различные версии библиотеки с помощью MASM32 или TASM.
• nasm.asm хранит определения констант, структур и т.д. под синтаксис Netwide Assembler (NASM). Этот файл позволяет собирать различные версии библиотеки с помощью NASM.
• ufmod.desc, oalufmod.desc и dsufmod.desc содержат описания библиотек для PureBasic. PureBasic Library SDK использует эти файлы при компиляции библиотек uFMOD в формате PureLibrary.
• ufmod.def, oalufmod.def и dsufmod.def содержат определения экспорта для компиляции uFMOD в формате DLL.

ufmodlib\import\ содержит исходники библиотек импорта, которые используются совместно с uFMOD в различных примерах. Некоторые из них используются самой библиотекой в Visual Basic 6 и FreePascal. Уже собранные версии данных библиотек импорта хранятся в ufmodlib\lib\. Исходники полных библиотек импорта для DirectSound и OpenAL под разные компиляторы также находятся тут. Все эти библиотеки можно пересобрать с помощью ImpLib SDK. ufmodlib\import\buildall.bat - батник, который перекомпилирует все вышеописанные библиотеки импорта.

При создании библиотеки в формате OMF для совместимости с Delphi используется утилита, которая находится в ufmodlib\bin\. Хотя данная утилита и уступает по мощности OMF2D EliCZ'а, она вполне справляется с задачей создания библиотеки uFMOD совместимой с Delphi. При компиляции библиотеки в формате OMF при помощи NASM, используется o4delphi.

Следующим, после внесения изменений в исходники, шагом является компиляция. Выберите один из батников в ufmodlib\, в зависимости от целевого компилятора, для которого нужно собрать библиотеку. Следующая таблица поможет сделать выбор:

Теперь откройте выбранный батник в текстовом редакторе. Всё, что находится между следующих строк:

rem *** CONFIG START

rem *** CONFIG END

SET UF_MASM=C:\masm32

SET UF_MASM=D:\TOOLS\MASM32

SET UF_ARCH=ar

SET UF_ARCH=C:\Program files\BlitzMax\bin\ar.exe

Запустите батник, чтобы собрать все доступные версии библиотеки: WINMM, OpenAL и DirectX DirectSound. Вот и всё!

 
Примеры

В каждом из каталогов представлены примеры с использованием как WINMM, так и DirectX-версий uFMOD. Под большинство компиляторов доступны также примеры с использованием OpenAL-версии uFMOD. Некоторые примеры сопровождаются откомпилированными экзешниками, чтобы показать минимальный размер, характерный для данного компилятора. Заметьте, что экзешники представлены без сжатия.

 
Дополнительное уменьшение размера

Утилита Eff предназначена для оптимизации и уменьшения размера библиотеки uFMOD.

Если Вы собираетесь включить XM статически в экзешник или в качестве ресурса, можете попробовать оптимизировать сначала сам XM. Modplug Player умеет сжимать XM-композиции по схеме APDCM, но учтите, что этот тип сжатия пагубно влияет на качество звучания! Утилита XMStrip перепаковывает XM файлы без потери качества.

Если Вы уверены в корректности формата всех композиций, которые будут использованы в приложении, можете пересобрать библиотеку в режиме UNSAFE.

При компиляции исполнимого модуля в VC++ или MASM32 включите директиву /opt:nowin98 в аргументы командной строки линкера для уменьшения выравнивания секций до минимума. Секции .rdata (read-only data, где хранятся символы IAT и некоторые константы) и .text (код приложения) можно совместить для ещё большего уменьшения размера. Для этого достаточно добавить в опции MS LINK.EXE или POLINK.EXE следующую директиву: /MERGE:.rdata=.text

Ещё один казус связан с линкером MS: link.exe добавляет в имидж экзешника некоторую лишнюю информацию, где-то между заглушкой DOS и началом PE заголовка. Балласт легко обнаруживается в хекс-редакторе по магическому слову 'Rich', за которым следует закодированный compid вашей машины. Если Вы против того, чтобы экзешники носили подпись машины, на которой были собраны, или просто не желаете тратить пол килобайта на эту самую подпись, можете поменять линкер :) Или найдите на wasm.ru документ, в котором подробно описан процесс патчинга link.exe.

Delphi любит создавать таблицу Relocation Table (секция .reloc) в обычных экзешниках (не DLL), где эта таблица зачастую абсолютно не нужна. Эту секцию можно убрать вручную или с помощью утилит StripReloc Джордана Расселя, PE Optimizer Dr. Golova и т.п.

Visual Basic и Delphi создают секцию ресурсов (.rsrc), даже если им нечего действительно полезного в неё поместить. Если в этой секции нет форм, XM-ов или других нужных ресурсов, можете попробовать её удалить, только осторожно! Аналогично для секции .flat в экзешниках созданных в PureBasic.

Упаковщики, вроде FSG и UPX, умеют ужимать экзешники. Тем не менее, для наглядности, все примеры предоставлены без сжатия!

При использовании библиотек импорта в формате MS-COFF (вроде kernel32.lib, libkernel32.a и т.д.), тратится определённое количество байт в экзешнике на размещение таблиц с оригинальными санками (original thunks). Данные переходники нужны только при наложении "байндинга" (связывания импорта утилитой bind.exe из SDK Visual Studio). Если Вы не собираетесь "байндить" ваши экзешники, можете избавиться от санков и сэкономить до 512 байт, а то и пары килобайт при использовании большого количества импортируемых функций. Для этого необходимо заменить стандартные библиотеки импорта, которые поставляются вместе с SDK компилятора (Visual Studio, masm32, ...) на модифицированные и пересобрать нужные проекты. Модифицированные библиотеки импорта можно создать с помощью ImpLib SDK.

Вот, собственно, и всё, что нужно знать об оптимизации размера экзешника. Давайте вернёмся к теме сокращения размера XM-файлов:

Есть ещё один хитрый способ оптимизации размера XM-файлов, который заключается в совмещении сразу нескольких композиций в одном файле. При этом можно удалять лишние экземпляры повторяющихся инструментов, если таковые имеются, что очень заметно сказывается на размере конечного файла. Даже без оптимизации инструментов размер композитного файла должен получиться меньше суммы размеров отдельных файлов, так как заголовки всех файлов заменяются одним общим. Давайте рассмотрим пример с тремя файлами:

Файл 1 : XM1_HEADER P11 P12 P13     I11 I12
Файл 2 : XM2_HEADER P21 P22 P23 P24 I21 I22 I23 I24
Файл 3 : XM3_HEADER P31             I31

Для начала, совместим все 3 композиции без оптимизации инструментов:

Файл 4 : XM4_HEADER P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I23 I24 I31

Файл 4 : XM4_HEADER P11 P12 P13 P21 P22 P23 P24 P31 I11 I12 I21 I22 I24

В использовании Jump2Pattern есть ещё один плюс - переключение происходит гораздо быстрее (практически моментально) чем при остановке текущей композиции и последующей загрузке новой. Можете брать на вооружение эту фишку для реализации решений, требующих максимально быстрого переключения музыкального фона.

 
ЧаВо

В: Библиотека uFMOD действительно бесплатна для любого использования, включая коммерческое?
О: Да, текущая версия абсолютно бесплатна для использования в любых целях.

В: Где бы достать композиции в формате XM?
О: The Mod Archive содержит внушительных размеров архив с бесплатными трекерскими композициями в формате XM, IT, S3M и MOD. Open Modplug Tracker умеет конвертировать IT, S3M и MOD в XM без потери качества. В сети много талантливых композиторов, которые бесплатно выкладывают свои работы. Не забывайте указывать соответствующие пометки об авторстве!

В: Существует ли какая-либо связь между проектом uFMOD и разработками Firelight Technologies®: FMOD и miniFMOD?
О: На данный момент никакой связи уже нет. До 2004го года включительно проект uFMOD основывался на исходных кодах библиотеки miniFMOD. С тех пор, код uFMOD был полностью переписан, оснащён новыми функциями, оптимизирован и отлажен. Таким образом, uFMOD более не связан ни с FMOD, ни с miniFMOD.

В: Некоторые разработчики утверждают, что их библиотеки увеличивают экзешники на N-ное количество килобайт. На сколько килобайт увеличивается размер экзешника при использовании uFMOD?
О: Точного ответа на этот вопрос нет, так как этот размер зависит от многих факторов: используемые характеристики библиотеки (особенно при использовании утилиты Eff), основной код программы, размер XM-файла (если XM включается в EXE). Размер также зависит от опций линкера. Пример MASM32\minimal.exe занимает 5632 байт без сжатия, модификации экзешника и прочих "грязных" способов уменьшить размер.

В: Где можно раздобыть официальное описание формата XM?
О: Полного официального описания современного формата XM нет. Позвольте предложить взамен этот документ: "The Unofficial XM File Format Specification: FastTracker II, ADPCM and Stripped Module Subformats" (только на англ.). В данном документе описаны многие тонкости работы с форматом XM, включая все нестандартные расширения, которые на данный момент поддерживает uFMOD. К тому же, из исходников ModPlug (на C++) можно почерпнуть массу полезной информации по трекерским форматам файлов.

 
Благодарности

antarman, Barracuda, bogrus, chris_b, cresta, dododo, flaith, Four-F, GL#0M, norki, q_q, ReSampled, S_T_A_S_, ts-soft, voodooattack и yoxola за помощь в устранении ошибок, предложения по улучшению библиотеки, примеры использования под разные компиляторы и всё остальное, так или иначе помогающее нам в развитии проекта.

[WASM.RU], CelerSMS и SourceForge.net за поддержку и хостинг.

 
Автор©тво

Исходные коды uFMOD и сопровождающие утилитарные приложения © 2005 - 2022 Asterix и Quantum.
Все права защищены.

Композиции:

• «mini.xm» by ReSampled © 2006 - 2022.
• BlitzXMK.XM из примера Jump2Pat © 2007 - 2022 Kim (он же - norki).