Подсистема сжатия звука в Windows

Функции работы с драйверами

acmDriverAdd — добавление нового драйвера

Функция устанавливает новый драйвер ACM либо указывает окно уведомления, которому будут передаваться сообщения об изменении приоритета и состояния глобальных драйверов ACM.

MMRESULT acmDriverAdd (
    HACMDRIVERID  *ForId,
    HINSTANCE  ModuleInstance,
    LPARAM  Entry,
    DWORD  Message,
    DWORD  Flags
  );

• ForId — указатель переменной, в которую будет занесен идентификатор установленного драйвера.
• ModuleInstance — ключ загруженного в память модуля, содержащего точку входа устанавливаемого драйвера.
• Entry — адрес функции драйвера (DriverProc) или ключ окна уведомления, которое будет получать сообщения о смене приоритетов и режимов, в зависимости от флагов в параметре Flags.
• Message — код сообщения Windows, посылаемого окну уведомления. Имеет смысл только в режиме задания окна уведомления, иначе этот параметр должен быть нулевым.
• Flags — флаги режимов установки драйвера. Имена констант флагов имеют префикс ACM_DRIVERADDF_:

Код сообщения Windows определяется приложением. Параметры wParam и lParam в получаемом окном сообщении не используются.

Флаги GLOBAL и LOCAL задаются только при установке драйверов; при задании окна уведомления они недопустимы.

После успешной установки пользовательского драйвера его основная функция начинает получать сообщения ACM, адресованные этому драйверу.

acmDriverRemove — удаление установленного драйвера

Удаляет установленный драйвер из списка доступных для приложения драйверов.

MMRESULT acmDriverRemove (
    HACMDRIVERID  DrvId,
    DWORD  Reserved
  );

• DrvId — идентификатор установленного драйвера.
• Reserved — зарезервированный параметр, должен иметь нулевое значение.

acmDriverEnum — перебор установленных драйверов

Последовательно перебирает установленные драйверы в порядке убывания приоритета, вызывая для каждого найденного драйвера заданную функцию поддержки перебора, которой передается описание драйвера.

MMRESULT acmDriverEnum (
    ACMDRIVERENUMCB  Callback,
    DWORD  Instance,
    DWORD  Flags
  );

• Callback — указатель функции поддержки перебора драйверов, которая будет вызываться ACM для каждого найденного драйвера.
• Instance — произвольное значение, которое будет передаваться функции поддержки перебора при каждом вызове.
• Flags — флаги условий перебора. Имена констант флагов имеют префикс ACM_DRIVERENUMF_:

Перебор продолжается до тех пор, пока не будет исчерпан список драйверов, либо пока функция поддержки перебора не вернет значение FALSE. В любом случае, если при переборе не возникло явной ошибки, даже если список запрошенных драйверов пуст, функция перебора завершается успешно.

acmDriverID — запрос идентификатора драйвера

Запрашивает у ACM идентификатор драйвера по ключу открытого драйвера или потока.

MMRESULT acmDriverID (
    HACMOBJ  Obj,
    HACMDRIVERID  *ForId,
    DWORD  Reserved
  );

• Obj — ключ объекта, для которого запрашивается идентификатор драйвера. Может быть ключом открытого драйвера (тип HACMDRIVER) или ключом открытого потока (тип HACMSTREAM).
• ForId — указатель переменной, в которую будет занесен идентификатор драйвера, соответствующего заданному ключу.
• Reserved — зарезервированный параметр, должен иметь нулевое значение.

acmDriverOpen — открывание драйвера

Открывает требуемый драйвер для последующей работы с ним.

MMRESULT acmDriverOpen (
    HACMDRIVER  *ForHandle, 
    HACMDRIVERID  DrvId,
    DWORD  Reserved
  );

• ForHandle — указатель переменной, в которую заносится ключ открытого драйвера. Впоследствии этот ключ используется для ссылок к драйверу.
• DrvId — идентификатор открываемого драйвера.
• Reserved — зарезервированный параметр, должен иметь нулевое значение.

acmDriverClose — закрывание открытого драйвера

MMRESULT acmDriverClose (
    HACMDRIVER  Drv,
    DWORD  Reserved
  );

• Drv — ключ открытого драйвера.
• Reserved — зарезервированный параметр, должен иметь нулевое значение.

acmDriverMessage — передача сообщения драйверу

Передает драйверу заданное сообщение. Обычно используется для передачи специальных пользовательских сообщений, однако может применяться и для передачи некоторых стандартных сообщений.

LRESULT acmDriverMessage 
    HACMDRIVER  Drv,
    UINT  Msg, 
    LPARAM  Param1,
    LPARAM  Param2
  );

• Drv — ключ открытого драйвера.
• Msg — код сообщения. Должен принадлежать диапазону кодов, зарезервированных для пользовательских сообщений (больше или равен ACMDM_USER и меньше ACMDM_RESERVED_LOW). Допустимы также стандартные сообщения ACMDM_DRIVER_ABOUT, DRV_QUERYCONFIGURE, DRV_CONFIGURE.
• Param1, Param2 — параметры сообщения.

Стандартное сообщение ACMDM_DRIVER_ABOUT требует от драйвера вывести диалог с кратким описанием и версией. Параметр Param1 должен содержать ключ окна — владельца диалога или быть нулевым; параметр Param2 не используется и должен быть нулевым.

Для того чтобы узнать, поддерживает ли драйвер вывод диалога описания, параметр Param1 должен иметь значение -1L. Успешное завершение функции означает способность драйвера вывести диалог, в противном же случае возвращается код ошибки MMSYSERR_NOTSUPPORTED.

acmDriverPriority — изменение приоритета драйвера

Изменяет приоритет выбранного драйвера. Дополнительно позволяет разрешить или запретить драйвер, а также отложить посылку уведомлений о смене состояния и приоритета.

MMRESULT acmDriverPriority (
    HACMDRIVERID  DrvId,
    DWORD  Priority,
    DWORD  Command
  );

• DrvId — идентификатор драйвера, для которого меняется приоритет, либо NULL в случае запрета или разрешения уведомлений о смене состояния/приоритета.
• Priority — значение приоритета, присваиваемого драйверу: 0 (не изменяется), 1 (высший), -1 (низший). Изменение приоритета допустимо только для глобальных драйверов.
• Command — команда, выполняемая функцией. Имена констант для кодов команд имеют префикс ACM_DRIVERPRIORITYF_:

В случае команд BEGIN/END параметры DrvId и Priority должны иметь нулевые значения. Команда BEGIN должна сопровождаться командой END сразу же, как только будет завершено изменение приоритета/состояния всех требуемых драйверов.

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

acmDriverDetails — запрос описания драйвера

Заполняет заданную структуру параметрами указанного драйвера.

MMRESULT acmDriverDetails (
    HACMDRIVERID  DrvId,
    ACMDRIVERDETAILS  *Details,
    DWORD  Reserved
  );

• DrvId — идентификатор драйвера.
• Details — указатель структуры типа ACMDRIVERDETAILS, которая будет заполнена параметрами драйвера.
• Reserved — зарезервированный параметр, должен иметь нулевое значение.

Функции работы с фильтрами и форматами

acmFilterTagDetails / acmFormatTagDetails — запрос описания типа

Возвращают описание заданного типа фильтров/форматов.

MMRESULT acmFilterTagDetails (
    HACMDRIVER  Drv,
    ACMFILTERTAGDETAILS  *Details,
    DWORD  RequestType
  );
MRESULT acmFormatTagDetails (
    HACMDRIVER  Drv,
    ACMFORMATTAGDETAILS  *Details,
    DWORD  RequestType
  );

• Drv — ключ открытого драйвера, у которого запрашивается описание. Если параметр имеет нулевое значение, ACM ищет подходящий драйвер самостоятельно.
• Details — указатель структуры типа ACMFILTERTAGDETAILS / ACMFORMATTAGDETAILS, которая будет заполнена информацией о типе фильтров/форматов.
• RequestType — тип запроса. Имена констант для типов запроса имеют префиксы ACM_FILTERTAGDETAILSF_ / ACM_FORMATTAGDETAILSF_:

acmFilterDetails / acmFormatDetails — запрос параметров фильтра/формата

Возвращает описание заданного фильтра/формата.

MMRESULT acmFilterDetails (
    HACMDRIVER  Drv,
    ACMFILTERDETAILS  *Details,
    DWORD  RequestType
  );
MMRESULT acmFormatDetails (
    HACMDRIVER  Drv,
    ACMFORMATDETAILS  *Details,
    DWORD  RequestType
  );

• Drv — ключ открытого драйвера, у которого запрашивается описание. Если параметр имеет нулевое значение, ACM ищет подходящий драйвер самостоятельно.
• Details — указатель структуры типа ACMFILTERDETAILS / ACMFORMATDETAILS, которая будет заполнена информацией о фильтре/формате.
• RequestType — тип запроса. Имена констант для типов запроса имеют префиксы ACM_FILTERDETAILSF_ / ACM_FORMATDETAILSF_:

Функции перебора типов и стандартных фильтров/форматов

Набор функций перебора состоит из четырех практически одинаковых функций, которые различаются только типами параметров и значениями флагов перебора:

MMRESULT acmFilterTagEnum (  // Перебор типов фильтров
    HACMDRIVER  Drv,
    ACMFILTERTAGDETAILS  *Details,
    ACMFILTERTAGENUMCB  Callback,
    DWORD  Instance, 
    DWORD  Flags
  );
MMRESULT acmFilterEnum (  // Перебор стандартных фильтров
    HACMDRIVER  Drv,
    ACMFILTERDETAILS  *Details,
    ACMFILTERENUMCB  Callback,
    DWORD  Instance, 
    DWORD  Flags
  );
MMRESULT acmFormatTagEnum (  // Перебор типов форматов
    HACMDRIVER  Drv,
    ACMFORMATTAGDETAILS  *Details,
    ACMFORMATTAGENUMCB  Callback,
    DWORD  Instance, 
    DWORD  Flags
  );
MMRESULT acmFormatEnum (  // Перебор стандартных форматов
    HACMDRIVER  Drv,
    ACMFORMATDETAILS  *Details,
    ACMFORMATENUMCB  Callback,
    DWORD  Instance, 
    DWORD  Flags
  );

• Drv — ключ открытого драйвера, типы и стандартные фильтры/форматы которого будут участвовать в переборе. Если параметр имеет нулевое значение, ACM последовательно опрашивает все установленные драйверы в порядке убывания приоритета.
• Details — указатель структуры типа ACMFILTERTAGDETAILS / ACMFILTERDETAILS / ACMFORMATTAGDETAILS / ACMFORMATDETAILS, которая будет заполняться информацией о каждом найденном типе или стандартном фильтре/формате. Поле dwFilterTag / dwFormatTag должно иметь осмысленное либо нулевое значение.
• Callback — указатель соответствующей функции поддержки перебора, которая будет вызываться ACM для каждого найденного типа или стандартного фильтра/формата. Если функция возвращает FALSE — процесс перебора прекращается.
• Instance — произвольное значение, которое будет передаваться ACM в функции поддержки перебора.
• Flags — флаги ограничения области перебора. Задают условия, которым должны соответствовать перебираемые типы или стандартные фильтры/форматы.

Для функций перебора типов фильтров/форматов acmFilterTagEnum и acmFormatTagEnum флаги не определены; параметр Flags должен быть нулевым.

Для функции перебора стандартных фильтров acmFilterEnum определен один флаг, имя которого имеет префикс ACM_FILTERENUMF_:

ля функции перебора стандартных форматов acmFormatEnum определены следующие флаги, имена которых имеют префикс ACM_FORMATENUMF_:

Понятие «заданный формат» означает описатель формата типа WAVEFORMATEX, на который ссылается поле pwfx структуры Details. Соответствующие запросу поля описателя должны иметь осмысленные значения.

Для каждого подходящего объекта перебора вызывается функция поддержки перебора, которой передается описание объекта, а также заданное приложением произвольное значение Instance; например, это может быть описатель списка, в который функция поддержки будет заносить найденные объекты. Если функция поддержки возвращает TRUE, — процесс перебора продолжается, в противном случае — прекращается.

Если в исходных данных нет ошибок, — функция перебора завершается успешно, даже если не обнаружено ни одного подходящего объекта перебора.

acmFilterChoose/acmFormatChoose — вывод диалога выбора фильтра/формата

Эти две практически одинаковые функции выводят на экран диалог выбора фильтра/формата, содержащий списки отобранных по заданным условиям стандартных фильтров или форматов. Пользователь может выбрать желаемый фильтр или формат, в соответствии с которым ACM сформирует описатель в заданной области памяти.

MMRESULT acmFilterChoose (ACMFILTERCHOOSE  *Choose);
MMRESULT acmFormatChoose (ACMFORMATCHOOSE  *Choose);

• Choose — структура типа ACMFILTERCHOOSE / ACMFORMATCHOOSE, описывающая способ построения диалога, его внешний вид, поведение и условия отбора фильтров/форматов в предлагаемые пользователю списки.

Если в структуре Choose задана функция перехвата, она вызывается перед обработкой каждого сообщения, полученного оконной функцией диалога выбора.

При успешном завершении структура, на которую ссылается поле pwfltr / pwfx, заполняется параметрами выбранного фильтра/формата; одновременно ACM заполняет прочие информационные поля в структуре Choose. При отказе пользователя от выбора (кнопка Cancel/Отмена или закрытие диалога через системное меню) функция возвращает код ACMERR_CANCELED.

acmFormatSuggest — запрос рекомендуемого для преобразования формата

Возвращает описатель формата, который, по мнению ACM, наиболее подходит для преобразования из заданного исходного формата. Эта функция обычно используется для определения формата PCM, в который наиболее удачно восстанавливается исходный сжатый формат.

MMRESULT acmFormatSuggest (
    HACMDRIVER  Drv,
    WAVEFORMATEX  *SrcFmt,
    WAVEFORMATEX  *DstFmt,
    DWORD  DstFmtSize,
    DWORD  Flags
  );

• Drv — ключ открытого драйвера или NULL, если поиск выполняется среди всех драйверов.
• SrcFmt — указатель описателя (WAVEFORMATEX) исходного формата, для которого подбирается результирующий формат.
• DstFmt — указатель описателя (WAVEFORMATEX), в который ACM заносит параметры результирующего формата. Если флаги, заданные параметром Flags, не требуют ограничения области поиска, начальной инициализации области памяти описателя не требуется.
• DstFmtSize — размер области памяти, занимаемой описателем результирующего формата. Ограничивает объем информации, возвращаемой ACM.
• Flags — флаги ограничения области поиска формата назначения. Условия совпадения задаются соответствующими полями описателя формата назначения DstFmt. Имена констант флагов имеют префикс ACM_FORMATSUGGESTF_:

Функции работы с потоками преобразования

Все функции работы с потоками преобразования, кроме acmStreamOpen, получают в первом параметре Stream ключ открытого потока, над которым выполняется запрошенная операция.

acmStreamOpen — открывание потока преобразования

Открывает поток, в котором будет происходить обработка звука фильтром или преобразование формата.

MMRESULT acmStreamOpen (
    HACMSTREAM  *ForHandle,
    HACMDRIVER  Drv,
    WAVEFORMATEX  *SrcFmt,
    WAVEFORMATEX  *DstFmt,
    WAVEFILTER  *Filter,
    DWORD  Callback,
    DWORD  Instance,
    DWORD  Flags
  );

• ForHandle — указатель переменной, в которую при успешном завершении операции возвращается ключ открытого потока. Если производится не открывание, а только проверка возможности создания такого потока (указан флаг QUERY), то параметр должен быть нулевым.
• Drv — ключ открытого драйвера, который будет осуществлять обработку потока или NULL, если драйвер автоматически выбирается ACM.
• SrcFmt — описатель (WAVEFORMATEX) исходного формата звука, подвергаемого преобразованию.
• DstFmt — описатель (WAVEFORMATEX) результирующего формата, в который должен быть преобразован исходный.
• Filter — описатель (WAVEFILTER) фильтра, которым будет обрабатываться звуковой поток. В одном потоке допустимо либо преобразование, либо обработка фильтром; если этот параметр не является нулевым, — оба описателя формата должны полностью совпадать.
• Callback — объект, используемый для уведомления приложения о завершении запрошенных операций: адрес функции, ключ окна (window handle) либо ключ события (event handle). Задание объекта уведомления допустимо только для асинхронных потоков (флаг ASYNC); в противном случае параметр должен быть нулевым.
• Instance — произвольное значение, которое будет передаваться ACM в параметрах функции уведомления или сообщения заданному окну.
• Flags — флаги режимов открывания потока и способ уведомления. Имена констант флагов имеют префикс ACM_STREAMOPENF_:

Имена констант способов уведомления имеют префикс CALLBACK_:

Если поток открыт асинхронно, то при наступлении каждого из трех событий потока выполняется действие, заданное способом уведомления:

• посредством объекта события — событие активизируется (Set Event);
• посредством оконного сообщения — заданному окну посылаются сообщения с кодами MM_ACM_OPEN (поток успешно открыт), MM_ACM_CLOSE (поток успешно закрыт), MM_ACM_DONE (завершена операция преобразования). Параметр сообщения wParam передает ключ открытого потока. В сообщении MM_ACM_DONE параметр lParam передает указатель заголовка, над которым выполнялась операция преобразования;
• посредством функции приложения — заданная функция вызывается в контексте специально созданной задачи (thread). Функция должна быть оформлена в соответствии с требуемым прототипом.

acmStreamClose — закрытие потока

Закрывает открытый поток преобразования.

MMRESULT acmStreamClose (
    HACMSTREAM  Stream,
    DWORD  Reserved
  );

• Reserved — зарезервированный параметр; должен иметь нулевое значение.

acmStreamSize — запрос рекомендуемого размера порции преобразования

Запрашивает рекомендуемый размер буфера для порции данных исходного или результирующего звукового потока. Полученные размеры гарантируют их применимость в функции acmStreamConvert.

MMRESULT acmStreamSize (
    HACMSTREAM  Stream,
    DWORD  InSize,
    DWORD  *ForOutSize,
    DWORD  Type
  );

• InSize — размер буфера порции данных, известный для одного из звуковых потоков (исходного или результирующего);
• ForOutSize — указатель переменной, в которую возвращается рекомендуемый размер буфера порции данных противоположного звукового потока;
• Type — тип потока, размер буфера порции данных которого задан параметром InSize. Имена констант типов потока имеют префикс ACM_STREAMSIZEF_:

В случае ошибки в переменную по указателю ForOutSize заносится нулевое значение.

acmStreamPrepareHeader — подготовка заголовка к преобразованию

Подготавливает заголовок потока к преобразованию. Обычно задачей этой операции является проверка допустимости адресов и размеров буферов потока. Заголовок потока обязательно должен быть подготовлен перед применением функции преобразования acmStreamConvert.

MMRESULT acmStreamPrepareHeader (
    HACMSTREAM  Stream,
    ACMSTREAMHEADER  *Hdr,
    DWORD  Reserved
  );

• Hdr — указатель описателя заголовка потока.
• Reserved — зарезервированный параметр; должен иметь нулевое значение.

Нет необходимости выполнять подготовку заголовка каждый раз перед передачей заголовка ACM, как это рекомендовано делать для буферов основной звуковой подсистемы (Wave/MIDI). Заголовок может быть подготовлен только однажды, и затем использован сколько угодно в функции преобразования; единственное ограничение — размеры буферов потока не должны превышать тех значений, что были заданы перед подготовкой.

При успешном завершении операции подготовки в слове состояния заголовка (поле fdwStatus) устанавливается флаг PREPARED.

Операция подготовки может потребовать у ACM и драйвера выделения каких-либо ресурсов, закрепляемых за данным заголовком. Поэтому перед закрытием потока для каждого ранее подготовленного заголовка необходимо выполнить обратные действия при помощи функции acmStreamUnprepareHeader. Это гарантирует, что все выделенные ресурсы будут освобождены.

acmStreamUnprepareHeader — отмена действий по подготовке заголовка

Отменяет действия, ранее предпринятые ACM и драйвером при подготовке заголовка функцией acmStreamPrepareHeader.

MMRESULT acmStreamUnprepareHeader (
    HACMSTREAM  Stream,
    ACMSTREAMHEADER  *Hdr,
    DWORD  Reserved
  );

• Hdr — указатель описателя заголовка потока;
• Reserved — зарезервированный параметр, должен иметь нулевое значение.

Вызов этой функции указывает ACM, что данный заголовок больше не будет использоваться для преобразования и все связанные с ним временные ресурсы могут быть освобождены.

Если размеры буферов потока, указанные в заголовке, были изменены после вызова функции подготовки acmStreamPrepareHeader, их значения должны быть восстановлены до обращения к функции acmStreamUnprepareHeader.

При успешном завершении операции подготовки в слове состояния заголовка (поле fdwStatus) сбрасывается флаг PREPARED. Это может происходить и при некоторых ошибках, когда функция возвращает ненулевое значение. Если выполнение функции завершилось с ошибкой, состояние этого флага показывает, смогла ли служба ACM действительно освободить заголовок. Если флаг сброшен, то возвращенный код ошибки имеет чисто информационное значение и повторного вызова функции не требуется.

Документация по ACM оговаривает, что при попытке выполнить функцию для заголовка, который не был подготовлен, не выполняется никаких действий, однако настоятельно рекомендуется избегать ситуаций, в которых функция может быть вызвана для неподготовленного заголовка.

acmStreamConvert — запрос преобразования очередной порции звуковых данных

Запрашивает у ACM обработку очередной порции данных исходного звукового потока.

MMRESULT acmStreamConvert (
    HACMSTREAM  Stream, 
    ACMSTREAMHEADER  *Hdr,
    DWORD  Flags
  );

• Hdr — указатель описателя заголовка потока.
• Flags — флаги режимов преобразования. Имена констант флагов имеют префикс ACM_STREAMCONVERTF_:

Даже если исходный поток является однородным, состоящим из единственного участка, для корректной работы драйвера необходимо указание флага START при обработке первой порции данных, и флага END — при обработке последней. Для упрощения обработки в качестве последней порции можно передать драйверу один или несколько отсчетов тишины, специально сформированных в исходном буфере.

При успешном прохождении всех входных проверок указанный заголовок, содержащий информацию о порции исходных данных и буфере для порции выходных данных, передается соответствующему драйверу для обработки.

Если поток был открыт асинхронно (флаг ASYNC в слове режимов открывания потока), то заголовок вносится в очередь драйвера; при этом в его слове состояния сбрасывается флаг завершения DONE и устанавливается флаг присутствия в очереди INQUEUE. После завершения обработки драйвер изымает заголовок из очереди, сбрасывает флаг INQUEUE, устанавливает флаг DONE и уведомляет приложение о завершении операции одним из трех возможных способов, заданным при открывании потока.

Если поток был открыт синхронно, то драйвер не возвращает управления до тех пор, пока не будет завершена обработка заданной порции данных. В этом случае флаги INQUEUE и DONE смысла не имеют.

После завершения операции преобразования поля cbSrcLengthUsed и cbDstLengthUsed в заголовке потока отражают объем исходных данных, использованных при выполнении операции, и объем результирующих данных, занесенных в выходной буфер. В том случае, когда в операции была использована не вся исходная порция, оставшиеся звуковые данные должны быть переданы драйверу в следующей операции преобразования. Например, «хвост» исходного буфера может быть сдвинут в его начало и затем дополнен звуковыми данными из входной очереди до заполнения буфера.

Ситуация, когда драйвер возвращает нулевое значение в одном из указанных полей, в общем случае не является ошибочной. Нулевое значение поля cbSrcLengthUsed может означать, что драйвер не смог объединить исходные данные с накопленными внутри драйвера и вернул результирующие данные лишь на основе накопленных. Нулевое значение поля cbDstLengthUsed означает, что исходных данных оказалось недостаточно для преобразования и они были запомнены драйвером для последующих операций. Ошибочной является лишь ситуация, когда оба этих поля имеют нулевые значения, так как в этом случае невозможно дальнейшее продвижение по потоку. Рекомендуется отслеживать возникновение подобной ситуации, чтобы процесс преобразования не зацикливался.

acmStreamReset — прерывание обработки потока

Служит для аварийного прерывания обработки потока и возврата всех заголовков из очереди драйвера.

MMRESULT acmStreamReset (
    HACMSTREAM  Stream,
    DWORD  Reserved
  );

• Reserved — зарезервированный параметр; должен иметь нулевое значение.

Для асинхронного потока функция аварийно прерывает выполнение операций преобразования, запрошенных функциями acmStreamConvert. Для каждого заголовка, находящегося в очереди драйвера, выполняются те же действия, что и при успешном завершении операции преобразования. Узнать об аварийном завершении операции можно по нулевому значению полей cbSrcLengthUsed и cbDstLengthUsed в заголовке потока.

Для синхронного потока функция не выполняет никаких действий.

acmStreamMessage — посылка сообщения драйверу потока

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

MMRESULT acmStreamMessage (
    HACMSTREAM  Stream,
    UINT  Msg, 
    LPARAM  Param1,
    LPARAM  Param2
  );

• Msg — код сообщения, посылаемого драйверу;
• Param1, Param2 — параметры сообщения.

Результатом функция является значение, возвращенное драйвером в ответ на переданное сообщение.

Функции, определяемые приложением

Эта группа функций определяется самим приложением для получения различных уведомлений от ACM. Имена функций в прототипах — условные, имя каждой функции полностью определяется приложением, а ACM получает только указатели этих функций.

Основную часть группы составляют функции поддержки перебора драйверов, типов фильтров/форматов и стандартных фильтров/форматов, вызываемые для каждого подходящего элемента соответствующего списка. Функции перебора содержат в своих условных именах слово Enum.

Каждая функция перебора должна возвратить значение TRUE для продолжения процесса перебора, и FALSE — для его завершения.

Функции перебора и уведомления не должны вызывать интерфейсных функций acmDriverAdd, acmDriverRemove, acmDriverPriority.

DriverEnumCallback — функция поддержки перебора драйверов

Вызывается для каждого драйвера, найденного в процессе выполнения функции перебора драйверов acmDriverEnum.

BOOL CALLBACK DriverEnumCallback (
    HACMDRIVERID  DrvId,
    DWORD  Instance,
    DWORD  Support
  );

• DrvId — идентификатор найденного драйвера;
• Instance — вспомогательное значение, заданное приложением при вызове функции перебора драйверов acmDriverEnum;
• Support — флаги поддерживаемых возможностей и режимов найденного драйвера.

Функции поддержки перебора типов и стандартных фильтров/форматов

Это четыре практически одинаковые функции, каждая из которых вызывается в процессе перебора типов и стандартных фильтров/форматов для каждого найденного типа или каждого стандартного фильтра/формата. Процесс перебора запускается функциями:

• acmFilterTagEnum — перебор типов фильтров;
• acmFilterEnum — перебор стандартных фильтров;
• acmFormatTagEnum — перебор типов форматов;
• acmFormatEnum — перебор стандартных форматов.

BOOL CALLBACK FilterTagEnumCallback (  // Поддержка перебора типов фильтров
    HACMDRIVERID  DrvId,
    ACMFILTERTAGDETAILS  *Details,
    DWORD  Instance,
    DWORD  Support
  );
BOOL CALLBACK FilterEnumCallback (  // Поддержка перебора стандартных фильтров
    HACMDRIVERID  DrvId,
    ACMFILTERDETAILS  *Details,
    DWORD  Instance,
    DWORD  Support
  );
BOOL CALLBACK FormatTagEnumCallback (  // Поддержка перебора типов форматов
    HACMDRIVERID  DrvId,
    ACMFORMATTAGDETAILS  *Details,
    DWORD  Instance,
    DWORD  Support
  );
BOOL CALLBACK FormatEnumCallback (  // Поддержка перебора стандартных форматов
    HACMDRIVERID  DrvId,
    ACMFORMATDETAILS  *Details,
    DWORD  Instance,
    DWORD  Support
  );

• DrvId — идентификатор драйвера, поддерживающего найденный тип или стандартный фильтр/формат.
• Details — указатель информационной структуры типа или фильтра/формата, заполненной сведениями о найденном объекте. В зависимости от работающей функции перебора указатель ссылается на структуру типа ACMFILTERTAGDETAILS, ACMFILTERDETAILS, ACMFORMATTAGDETAILS или ACMFORMATDETAILS.
• Instance — вспомогательное значение, заданное приложением при вызове соответствующей функции перебора.
• Support — флаги поддерживаемых возможностей и режимов драйвера, отвечающего за найденный тип или фильтр/формат.

Функция перехвата сообщений диалога выбора фильтра/формата

Вызывается для каждого сообщения Windows, поступившего для обработки в оконную функцию диалога выбора фильтра/формата, сформированного функциями выбора acmFilterChoose / acmFormatChoose.

UINT CALLBACK acmChooseHookProc (
    HWND hwnd,
    UINT uMsg,
    WPARAM wParam,
    LPARAM lParam
  );

Параметры функции являются стандартными параметрами оконной функции Windows.

Если функция обрабатывает сообщение WM_CTLCOLOR, она должна возвратить ключ кисти, которая будет использоваться для отрисовки фона управляющих элементов (control background).

В дополнение к стандартным сообщениям Windows функции перехвата вызываются также со специальными сообщениями ACM в процессе формирования трех «ниспадающих» списков (drop-down lists) диалога — названий пресетов (custom), названий типов (tag) и названий стандартных фильтров/форматов (filter/format). Вначале для каждого элемента, вносимого ACM в соответствующий список, функция перехвата вызывается с сообщением «проверка» (verify) и может разрешить или запретить включение элемента в список. После завершения формирования списков типов и стандартных фильтров/форматов функция перехвата для них вызывается с сообщением «добавление» (add). В ответ на это сообщение функция может добавить к спискам дополнительные типы или фильтры/форматы.

В качестве специального сообщения выступает код MM_ACM_FILTERCHOOSE / MM_ACM_FORMATCHOOSE, параметр wParam в котором задает тип списка и требуемую операцию. Имена констант для этих значений имеют вид objCHOOSE_list_op, где obj — объект выбора (FILTER или FORMAT), list — тип списка (CUSTOM, FILTERTAG, FILTER, FORMATTAG, FORMAT), op — операция (VERIFY или ADD).

Например: FILTERCHOOSE_CUSTOM_VERIFY — проверка возможности включения элемента в список пресетов диалога выбора фильтра, FORMATCHOOSE_FORMATTAG_ADD — запрос добавления нового элемента в список типов диалога выбора формата.

Для списка пресетов допустима только операция проверки, добавление в этот список запрещено.

Параметр lParam специального сообщения имеет различный смысл в зависимости от выполняемой операции:

• для операций проверки элементов списка типов lParam содержит код типа, включаемого в список;
• для операций проверки списков пресетов и стандартных фильтров/форматов lParam содержит указатель описателя добавляемого фильтра/формата — структуры типа WAVEFILTER / WAVEFORMATEX;
• для операций добавления дополнительных элементов в списки lParam содержит указатель буфера, в котором функция может сформировать описатель добавляемого элемента. Для списков типов этот буфер является двойным словом (DWORD), в которое функция заносит код типа, а для списков стандартных фильтров/форматов — структурой типа WAVEFILTER / WAVEFORMATEX. Размер буфера в последнем случае может быть определен при помощи функции acmMetrics.

При получении специального сообщения ACM функция перехвата должна вернуть значение TRUE, если сообщение воспринято и обработано, или FALSE, если сообщение игнорировано. Перед возвратом сообщения TRUE функция должна сообщить ACM результат обработки специального сообщения. Это делается при помощи стандартной функции Windows SetWindowLong:

SetWindowLong (hwnd, DWL_MSGRESULT, Result);

Параметр hwnd является ключом окна диалога, полученным от ACM, а Result — логическим значением TRUE/FALSE. Для операции проверки значение TRUE разрешает включение элемента в список, значение FALSE — запрещает. Для операции добавления значение TRUE запрашивает повторение операции добавления, значение FALSE свидетельствует о завершении процесса добавления. Если нет необходимости добавлять в списки новые значения, функция перехвата должна игнорировать специальные сообщения с кодами операций добавления.

Функция уведомления приложения о завершении операции с потоком

Вызывается при наступлении одного из событий потока.

void CALLBACK acmStreamConvertCallback (
    HACMSTREAM Stream,
    UINT Msg,
    DWORD Instance,
    LPARAM Param1,
    LPARAM Param2
  );

• Stream — ключ потока преобразования, для которого выполняется уведомление;
• Msg — код сообщения, отражающий тип наступившего события. Константы сообщений имеют префикс MM_ACM_:

Параметр Param1 содержит указатель описателя заголовка потока.

• Instance — вспомогательное информационное значение, заданное приложением при вызове функции acmStreamOpen;
• Param1, Param2 — дополнительные параметры, значения которых зависят от вида события.

Для вызова функции уведомления создается специальная задача (thread) с повышенным (ABOVE_NORMAL) приоритетом. Созданная задача используется для уведомления во всех потоках и существует до завершения приложения.

Уведомления допустимы только для асинхронных потоков.

Формально функция не должна обращаться к другим функциям Windows, кроме PostMessage, timeGetSystemTime, timeGetTime, timeSetEvent, timeKillEvent, midiOutShortMsg, midiOutLongMsg, OutputDebugStr. Фактически же она работает в контексте собственной задачи, а не в контексте драйвера, так что на практике большинство функций Windows оказываются доступными.

DriverProc — функция пользовательского драйвера ACM

Вызывается ACM для обработки запросов, адресованных драйверу, после установки пользовательского драйвера функцией acmDriverAdd.

LRESULT CALLBACK DriverProc (
    DWORD dwID,
    HDRIVER hdrvr,
    UINT uMsg,
    LPARAM lParam1,
    LPARAM lParam2
  );

Параметры функции драйвера и ее поведение описываются в Windows DDK (Driver Development Kit — набор для разработки драйверов).

Существующие драйверы подсистемы сжатия

В состав стандартной поставки Windows 95 и NT 4 входят шесть драйверов ACM — Microsoft ADPCM, IMA ADPCM, Microsoft CCITT G.711 (форматы a-law/u-law), Microsoft GSM 6.10, Lernout & Hauspie CELP/SBC, DSP Group TrueSpeech. Форматы ADPCM, a-law, u-law ориентированы на произвольный звуковой сигнал, форматы GSM, CELP/SBC, TrueSpeech — на монофонический речевой сигнал.

Для оптимизации передачи звука в Интернет Microsoft разработала формат MSN Audio, драйвер которого поставляется в комплекте пакета NetShow.

В комплекте Internet Explorer 4 и Windows 98/2000 поставляются драйверы форматов G.723.1, VoxWare MetaSound, VivoActive/Siren, также ориентированные на передачу произвольного звука по сети, а кроме того, декодер Fraunhofer IIS для формата MPEG Layer 3.

В комплекте программного обеспечения звуковых карт SoundBlaster поставляются драйверы Creative ADPCM и Creative FastSpeech 10, ориентированные на речевой сигнал.

Институтом Fraunhofer IIS разработан профессиональный драйвер-кодек для формата MPEG Layer 3, работающий в реальном времени. Для сжатия стереофонического 16-разрядного сигнала PCM с частотой дискретизации 44,1 кГц в формат со скоростью потока 256 Кбит/с необходим процессор Celeron 300A или более мощный.

Единственным известным автору драйвером-фильтром является разработанный Microsoft стандартный драйвер MSFilter, поставляемый в качестве примера в комплекте DDK для Windows 95/98 и NT/2000. Этот драйвер содержит два фильтра: Volume, изменяющий амплитуду сигнала в потоке, и Echo, реализующий эхо-эффект. Установочные файлы драйвера находятся в каталоге MSFilter.

Установка и удаление постоянных драйверов ACM

Драйверы ACM, входящие в стандартный комплект поставки Windows, устанавливаются при выборе пункта Audio Compression (Сжатие аудиоданных) в группе средств мультимедиа. Это можно сделать при установке Windows, если выбран режим выборочной установки (Custom Setup), либо в любое время при уже установленной системе — при помощи мастера установки/удаления программ.

Выборочную установку стандартных драйверов можно выполнить при помощи мастера установки оборудования в панели управления. Для этого нужно выбрать режим ручной установки, отказавшись от автоматического поиска оборудования, выбрать раздел звуковых, видео- и игровых контроллеров, в списке производителей выбрать Microsoft Audio Codecs или DSP Group, а в списке продуктов — нужный драйвер.

Отдельно поставляемые драйверы имеют либо программу самоустановки (Setup.exe), либо INF–файл сценария установки. В последнем случае драйвер устанавливается подобно аппаратному адаптеру, тем же способом, что и выборочная установка стандартных драйверов, но после получения списка производителей и продуктов нужно выбрать установку с диска и ввести путь к каталогу установочных файлов.

Просмотреть список установленных драйверов ACM можно при помощи мастера мультимедиа в панели управления, открыв в закладке Advanced (Дополнительно) раздел Audio Compression codecs (Программы аудиосжатия). Открыв нужный драйвер, можно разрешить или запретить его, сменить приоритет поиска, изменить настройки, получить дополнительные сведения о драйвере либо удалить драйвер из системы.

Использование драйвера фильтров MSFilter

Драйвер MSFilter, поддерживающий фильтры типов Volume и Echo, был предусмотрен Microsoft при проектировании подсистемы сжатия, поэтому все необходимые для его использования структуры и константы определены в файле MMREG.H. Однако по непонятной причине этот драйвер не был включен в стандартную поставку Windows, поэтому для работы с этими фильтрами необходимо установить драйвер в системе, используя мастер установки оборудования и файл сценария MSFILTER.INF.

Каждый из типов фильтров описывается собственной расширенной структурой, в основе которой лежит базовый описатель WAVEFILTER. Этот описатель является первым членом расширенной структуры описания каждого типа фильтра; по соглашению это поле имеет имя wfltr. Следом за базовым описателем располагаются собственные параметры фильтра данного типа.

Фильтры Volume и Echo работают только со звуковыми данными формата PCM.

По непонятной причине драйвер MSFilter «считает», что он неспособен обрабатывать звук в реальном времени и в обязательном порядке требует наличия флага NONREALTIME при открывании потока преобразования.

Фильтр Volume

Предназначен для амплитудной обработки звукового сигнала — усиления или ослабления его амплитуды. Обработка производится путем умножения каждого отсчета сигнала на заданный коэффициент.

Уникальный код типа имеет значение WAVE_FILTER_VOLUME. Расширенная структура VOLUMEWAVEFILTER имеет вид:

WAVEFILTER  wfltr;
  DWORD  dwVolume;

• dwVolume — коэффициент изменения амплитуды. На этот коэффициент умножается амплитуда исходного сигнала для получения амплитуды результирующего сигнала. Старшее слово представляет целую часть коэффициента, младшее — дробную. Для коэффициента K типа double, формула преобразования имеет вид: dwVolume = (DWORD)(K * 0x10000);

Фильтр Echo

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

Уникальный код типа имеет значение WAVE_FILTER_ECHO. Расширенная структура ECHOWAVEFILTER имеет вид:

WAVEFILTER  wfltr;
  DWORD  dwVolume;
  DWORD  dwDelay;

• dwVolume — коэффициент изменения амплитуды задержанного сигнала.
• dwDelay — время задержки в миллисекундах.

Недостатки подсистемы сжатия

Поскольку большинство драйверов ACM являются программными, они поддерживают только синхронную обработку потоков преобразования. Это создает неудобство при разработке многозадачных приложений, ориентированных на параллельную обработку данных. Впрочем, это ограничение легко обойти путем выноса алгоритмов работы с потоком в независимую задачу, которую затем можно запускать отдельно для каждого нового потока. Несмотря на то что на однопроцессорной платформе такой параллелизм будет мнимым, и каждая задача все равно будет занимать центральный процессор такое же количество времени, обработка нескольких потоков будет «размазана» во времени, и те потоки, для обработки которых требуется меньше процессорного времени, будут продвигаться быстрее. На многопроцессорных платформах задачи могут выполняться на разных процессорах, обеспечивая реальный, а не мнимый параллелизм.

Несмотря на то что ACM поддерживает для модулей обработки собственные наборы данных (instances) для каждого открытого потока, некоторые кодеки (например, Fraunhofer IIS Audio MPEG Layer 3) не позволяют открыть два и более параллельных потока преобразования в рамках одного процесса, даже если потоки открываются в разных задачах. Такое поведение кодека делает невозможным одновременное многоканальное преобразование звука. Обойти ограничение можно только путем запуска независимых параллельных процессов, организовав для них достаточно сложный алгоритм обмена данными.

Пример программы, использующей ACM

В качестве примера приведена программа RTCompress, записывающая звук с указанного устройства Wave In в формате PCM, в реальном времени преобразующая его в выбранный формат и записывающая в стандартный файл RIFF Wave (.wav). Файлы программы находятся в каталоге RTCompress.

Фактически программа RTCompress переделана из программы Delay, представленной в качестве примера к статье «Низкоуровневое программирование звука в Windows».

Программа написана на языке C++, в среде Microsoft Visual C++ 4.2. Из возможностей C++ в основном использованы только «косметические» — более строгая проверка типов и возможность использовать имена структур в качестве имен типов. Единственное объектно-ориентированное средство языка, примененное в программе, — наследование стандартной структуры WAVEFORMATEX для формирования расширенной структуры WaveFormat. Метод формирования расширенных структур форматов/фильтров, примененный в MMREG.H, рассчитан на совместимость с обычным языком C и основан на включении базовой структуры первым элементом расширенной. Такой подход создает неудобства, заставляя выписывать лишние имена или преобразования типов, в то время как механизм наследования С++ совершенно естественным образом решает поставленную задачу: — расширенная структура просто выводится из базовой, поскольку структуры в C++ являются классами с общим доступом.

Для работы с выходным файлом в программе использован интерфейс MMIO (функции с префиксом mmio), специально ориентированный на работу со звуковыми и видеофайлами. Этот интерфейс будет описан в одном из следующих выпусков журнала КомпьютерПресс.

Параметры исходного формата PCM задаются непосредственно, для выбора результирующего формата использована функция acmFormatChoose. В списках диалога отображаются только те форматы, в которые может быть преобразован исходный формат PCM.

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

В качестве последней порции исходного сигнала, снабженной пометкой завершения участка, формируется один блок отсчетов тишины (значения 0x80 для восьмиразрядных отсчетов, и нулевые — для всех остальных).

Поскольку программа работает с элементами управления диалогов (Common Controls), базовой звуковой подсистемой MME/Wave и подсистемой сжатия ACM, при построении используются библиотеки comctl32, winmm и msacm32.

КомпьютерПресс 7'2000