DirectSound вводит понятие набора свойств (property set) - параметров, описывающих виды обработки звука. При помощи набора свойств можно описать параметры зала, голоса исполнителя, манеры пения, звучания инструментов и т.п. При наличии необходимых средств обработки одну и ту же звуковую картину можно представлять в разных ракурсах, активизируя нужные наборы свойств.

В данное время эти виды обработки почти не поддерживаются; наборы свойств введены в основном на будущее.

Именование интерфейсных функций

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

Поскольку ряд интерфейсов имеет схожую структуру (IDirectSound/IDirectSoundCapture, IDirectSoundBuffer/IDirectSound3DBuffer), многие методы являются общими для нескольких интерфейсов сразу. В таких случаях я буду упоминать имя интерфейса, только если в использовании одного и того же метода в разных интерфейсах существует принципиальная разница.

Совместимость

Интерфейсы DirecSound доступны для платформ Windows 98 или 2000 и выше. В Windows 95 интерфейсы становятся доступными после установки пакета DirectX. В Windows NT 4/SP3 доступен только базовый уровень функциональности - интерфейсы IDirectSound и IDirectSoundBuffer.

Общая схема взаимодействия программы и DirectSound

Приложение начинает работу с DirectSound, создавая объект устройства с интерфейсом IDirectSound - для воспроизведения звука или IDirectSoundCapture - для захвата (записи) звука. Объект устройства воспроизведения создается функцией DirectSoundCreate, объект устройства захвата - DirectSoundCaptureCreate.

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

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

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

Перед началом работы с устройством необходимо установить уровень взаимодействия методом SetCooperativeLevel.

Работа со звуком начинается с создания объектов звуковых буферов. Если приложение работает на обычном уровне взаимодействия, первичный буфер не создается. На остальных уровнях необходимо создать первичный буфер методом CreateSoundBuffer и задать его формат методом SetFormat. На обычном уровне взаимодействия формат первичного буфера фиксирован - 22 050 Гц, стерео, восемь разрядов.

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

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

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

Для запуска воспроизведения буфера вызывается метод Play, для остановки - Stop. Чтобы определить, какой фрагмент звучит в данный момент, используется метод GetCurrentPosition, для запуска звучания с определенного места - SetCurrentPosition.

При необходимости приложение может изменить параметры звучания в буфере: частоту дискретизации (SetFrequency), громкость (SetVolume), положение на панораме (SetPan). Для пространственных источников возможно изменение координат, ориентации, скорости движения и т.п.

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

Захват (запись) звука производится с помощью объектов устройств IDirectSoundCapture. Здесь нет разделения на первичный и вторичные буферы, поэтому методом CreateCaptureBuffer создается единственный буфер захвата, которому этим же методом приписывается нужный формат. Затем методом Start запускается захват звука, который может быть остановлен методом Stop. Для извлечения звуковых данных из буфера служат методы Lock и Unlock. Процесс захвата во многом симметричен процессу воспроизведения, поэтому в описании интерфейсов захвата упомянуты лишь их отличия от основных интерфейсов.

При желании приложение может воспользоваться интерфейсом уведомления IDirectSoundNotify, запрашивая его у объектов тех буферов, для которых требуются уведомления, и заказывая установку заданных объектов программных событий (event objects) по достижении определенных позиций в буфере.

Завершая работу, приложение уничтожает методом Release объекты буферов, а затем - объекты устройств.

Программирование в DirectSound

Средства разработки, включаемые файлы и библиотеки

Описывается программирование на языке C++ в среде Microsoft Visual C++. DirectSound поддерживает программирование и из обычного C, однако использование C++ позволяет более естественно оформлять работу с интерфейсами и не ведет к какому бы то ни было увеличению объектного кода по сравнению с C, поскольку модель DirectSound изначально ориентирована на объекты и методы обращения к ним из C++.

Полный комплект DirectX 7.0a SDK занимает 128 Мбайт, однако наиболее важные его части доступны отдельно. Набор документации включаемых заголовочных файлов и библиотек занимает 1,3 Мбайт и доступен по ссылке http://download.microsoft.com/download/win98SE/DXSDK/7.0/W9X/EN-US/dx7libhdr.exe.

Вместе с демонстрационной программой к статье прилагаются файлы dsound.h и dsound.lib из комплекта DirectX SDK 7.0a. Тем не менее одних этих файлов недостаточно для построения примера; среда разработки должна поддерживать хотя бы одну из версий DirectX.

Структуры, используемые при работе с подсистемой

Все структуры имеют поле dwSize, в которое при инициализации структуры необходимо занести ее размер в байтах. Размер используется для определения версии интерфейса. Это единственное поле, которое требует обязательной инициализации во всех структурах; остальные поля заполняются, только если они являются входными.

DSCAPS - параметры устройства воспроизведения

Данная структура описывает возможности и параметры устройства воспроизведения. Для удобства определен тип LPCDSCAPS - константный указатель на тип DSCAPS.

DWORD   dwSize;
 DWORD   dwFlags;
 DWORD   dwMinSecondarySampleRate;
 DWORD   dwMaxSecondarySampleRate;
 DWORD   dwPrimaryBuffers;
 DWORD   dwMaxHwMixingAllBuffers;
 DWORD   dwMaxHwMixingStaticBuffers;
 DWORD   dwMaxHwMixingStreamingBuffers;
 DWORD   dwFreeHwMixingAllBuffers;
 DWORD   dwFreeHwMixingStaticBuffers;
 DWORD   dwFreeHwMixingStreamingBuffers;
 DWORD   dwMaxHw3DAllBuffers;
 DWORD   dwMaxHw3DStaticBuffers;
 DWORD   dwMaxHw3DStreamingBuffers;
 DWORD   dwFreeHw3DAllBuffers;
 DWORD   dwFreeHw3DStaticBuffers;
 DWORD   dwFreeHw3DStreamingBuffers;
 DWORD   dwTotalHwMemBytes;
 DWORD   dwFreeHwMemBytes;
 DWORD   dwMaxContigFreeHwMemBytes;
 DWORD   dwUnlockTransferRateHwBuffers;
 DWORD   dwPlayCpuOverheadSwBuffers;
 DWORD   dwReserved1;
 DWORD   dwReserved2;

• dwSize - размер структуры в байтах;
• dwFlags - флаги характеристик устройства. Имена флагов имеют префикс DSCAPS_:

• dwMinSecondarySampleRate, dwMaxSecondarySampleRate - минимальная и максимальная частота дискретизации, поддерживаемая для аппаратных вторичных буферов;
• dwPrimaryBuffers - количество поддерживаемых первичных буферов. В текущей модели всегда равно единице;
• dwMaxHwMixingAllBuffers - максимальное общее количество поддерживаемых буферов с аппаратным смешиванием. Может быть меньше суммы числа статических и потоковых буферов из-за различия способов их организации в аппаратуре;
• dwMaxHwMixingStaticBuffers - максимальное количество статических звуковых буферов с аппаратным смешиванием;
• dwMaxHwMixingStreamingBuffers - максимальное количество потоковых звуковых буферов с аппаратным смешиванием;
• dwFreeHwMixingAllBuffers, dwFreeHwMixingStaticBuffers, dwFreeHwMixingStreamingBuffers - количество свободных буферов с аппаратным смешиванием - всех, статических и потоковых;
• dwMaxHw3DAllBuffers, dwMaxHw3DStaticBuffers, dwMaxHw3DStreamingBuffers - максимальное количество аппаратных буферов для источников объемного звука - всех, статических и потоковых;
• dwFreeHw3DAllBuffers, dwFreeHw3DStaticBuffers, dwFreeHw3DStreamingBuffers - количество свободных аппаратных буферов для источников объемного звука - всех, статических и потоковых.
• dwTotalHwMemBytes - общий объем внутренней памяти адаптера, доступной для размещения статических буферов;
• dwFreeHwMemBytes - объем свободной внутренней памяти адаптера;
• dwMaxContigFreeHwMemBytes - объем наибольшего непрерывного участка внутренней памяти адаптера;
• dwUnlockTransferRateHwBuffers - скорость пересылки данных из основной памяти в память адаптера (Кбайт/с). Пересылка выполняется при вызове метода Unlock, время отработки метода может быть определено из значения этого поля и объема занесенных в буфер звуковых данных;
• dwPlayCpuOverheadSwBuffers - приблизительная доля времени центрального процессора (в %), необходимая для смешивания звука из буферов, расположенных в основной памяти;
• dwReserved1, dwReserved2 - служебные поля.

DSBCAPS - параметры звукового буфера

Структура описывает возможности и параметры существующего звукового буфера. Для удобства определен тип LPCDSBCAPS - константный указатель на тип DSBCAPS.

DWORD   dwSize;
 DWORD   dwFlags;
 DWORD   dwBufferBytes;
 DWORD   dwUnlockTransferRate;
 DWORD   dwPlayCpuOverhead;

• dwSize - размер структуры в байтах;
• dwFlags - флаги возможностей, параметров и режимов буфера. Имена констант флагов имеют префикс DSBCAPS_:/

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

• dwBufferBytes - размер буфера в байтах;
• dwUnlockTransferRate - скорость загрузки данных в буфер (килобайт в секунду). Для буферов, расположенных в основной памяти, скорость обычно значительно выше, чем для расположенных в памяти адаптера. Это значение позволяет оценить время выполнения метода Unlock, осуществляющего пересылку данных в буфер;
• dwPlayCpuOverhead - доля процессорного времени (в %), необходимая для добавления (смешивания) звучания данного буфера в общий звук. Для буферов с аппаратным смешиванием это значение равно нулю, для программно смешиваемых оно зависит от скорости процессора, формата этого и первичного буферов.

DSBUFFERDESC - описатель создаваемого буфера

Структура описывает конфигурацию и свойства создаваемого звукового буфера. Для удобства определен тип LPDSBUFFERDESC - указатель на тип DSBUFFERDESC.

DWORD dwSize;
 DWORD dwFlags;
 DWORD dwBufferBytes;
 DWORD dwReserved;
 LPWAVEFORMATEX lpwfxFormat;
 GUID guid3DAlgorithm;

• dwSize - размер структуры в байтах;
• dwFlags - флаги параметров и режимов работы буфера. Определены в описании слова флагов структуры DSBCAPS;
• dwBufferBytes - размер буфера в байтах. При создании первичного буфера должно быть задано нулевое значение, так как размеры первичных буферов определяются подсистемой. Фактический размер созданного первичного буфера можно узнать посредством его метода GetCaps. Для вторичных буферов размер должен лежать в диапазоне от DSBSIZE_MIN до DSBSIZE_MAX;
• dwReserved - служебное поле;
• lpwfxFormat - адрес структуры WAVEFORMATEX, описывающей формат буфера. Для первичного буфера поле должно иметь нулевое значение - формат первичного буфера всегда устанавливается методом SetFormat;
• guid3DAlgorithm - алгоритм моделирования объемного звука системой из двух звукоизлучателей (громкоговорителей или наушников). Относится только к буферам пространственных источников, используемых в DirectSound3D. Для обычных моно- и стереоисточников значение поля игнорируется.

Флаги LOCHARDWARE и LOCSOFTWARE являются взаимоисключающими. Они запрашивают размещение буфера в памяти адаптера или компьютера, однако не гарантируют, что это будет соблюдено. О фактическом размещении буфера можно узнать при помощи его метода GetCaps.

Описанный формат структуры используется начиная с DirectX 7.0. До этого использовалась структура, не содержавшая поля guid3DAlgorithm; для совместимости старый формат сохранен под именем DSBUFFERDESC1. Подсистема определяет версию структуры, используя значение поля dwSize, и корректно обрабатывает наличие или отсутствие дополнительного поля.

DSCCAPS - параметры устройства захвата

Описывает возможности и параметры устройства записи (захвата). Для удобства определен тип LPCDSCCAPS - константный указатель на тип DSCCAPS.

DWORD   dwSize;
 DWORD   dwFlags;
 DWORD   dwFormats;
 DWORD   dwChannels;

• dwSize - размер структуры в байтах;
• dwFlags - флаги параметров устройства. Имена констант имеют префикс DSCCAPS_:

• dwFormats - стандартные форматы, поддерживаемые устройством. Флаги форматов эквивалентны используемым в структуре MME WAVEINCAPS. Имена констант флагов имеют вид WAVE_FORMAT_fcnn, где f - символ частоты дискретизации (1 - 11025 Гц, 2 - 22050 Гц, 4 - 44100 Гц), c - символ количества каналов (M - моно, S - стерео), а nn - разрядность отсчета (08 или 16). Таким образом, всего определено 12 стандартных форматов;
• dwChannels - количество каналов устройства (1 - моно, 2 - стерео, и т.п.).

DSCBCAPS - параметры буфера захвата

Описывает параметры существующего буфера захвата. Для удобства определен тип LPCDSCBCAPS - константный указатель на тип DSCBCAPS.

DWORD   dwSize;
 DWORD   dwFlags;
 DWORD   dwBufferBytes;
 DWORD   dwReserved;

• dwSize - размер структуры в байтах;
• dwFlags - флаги параметров. Пока определен только один флаг - DSCBCAPS_WAVEMAPPED, разрешающий использование Wave Mapper для форматов, не поддерживаемых устройством непосредственно и для которых в работу неявно может быть включена подсистема сжатия ACM;
• dwBufferBytes - размер буфера в байтах;
• dwReserved - служебное поле.

DSCBUFFERDESC - описатель создаваемого буфера захвата

Описывает конфигурацию и свойства создаваемого буфера захвата. Для удобства определен тип LPDSCBUFFERDESC - указатель на тип DSCBUFFERDESC.

DWORD dwSize;
 DWORD dwFlags;
 DWORD dwBufferBytes;
 DWORD dwReserved;
 LPWAVEFORMATEX   lpwfxFormat.

Как видно, структура аналогична DSBUFFERDESC, за исключением поля guid3DAlgorithm. В версиях DirectX до 7.0, где в структуре DSBUFFERDESC этого поля не было, форматы описателей создаваемых буферов для устройств воспроизведения и записи были тождественны.

Различия касаются также поля dwFlags, содержащего управляющие флаги. В описываемой структуре оно может содержать только флаг DSCBCAPS_WAVEMAPPED.

DSBPOSITIONNOTIFY - описатель позиции для уведомления

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

DWORD   dwOffset;
 HANDLE   hEventNotify;

• dwOffset - смещение от начала буфера, при достижении которого должно быть выполнено уведомление. Специальное значение DSBPN_OFFSETSTOP запрашивает уведомление в момент остановки звучания - либо методом Stop, либо при достижении конца буфера;
• hEventNotify - ключ объекта события (event object handle), который устанавливается (set) для выполнения уведомления.

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

Уведомление приложения о наступлении событий

В подсистеме DirectSound существует только одно асинхронное событие - это достижение заданной позиции внутри звукового буфера. Как частный случай событие может возникать при остановке звучания буфера - методом Stop, или при естественном достижении конца буфера.

Подсистема использует для уведомления только объекты программных событий (event objects). Это не так удобно, как в подсистеме MME, предоставляющей несколько видов уведомлений, однако вполне в духе многозадачной модели Win32, когда для управления буферами и перезагрузки их содержимого создается отдельная задача (thread). Эта задача не занимается ничем посторонним, ожидая установки одного из заданных объектов событий, после которой выполняет обновление отработанной части буфера.

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

Набор интерфейсных функций подсистемы

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

Перечень базовых интерфейсов DirectSound

Перечень внеинтерфейсных функций высшего уровня

Значения, возвращаемые функциями и методами

Все функции и методы интерфейсов возвращают результат типа HRESULT, эквивалентный типу LONG. Значение DS_OK равное нулю означает успешное выполнение функции, любое другое значение указывает на ошибку. Константы для кодов ошибок имеют префиксы DSERR_:

Внеинтерфейсные функции высшего уровня

Enumerate - перебор устройств воспроизведения или захвата

HRESULT DirectSoundEnumerate (
    LPDSENUMCALLBACK EnumCallback,
    LPVOID Context
 );

HRESULT DirectSoundCaptureEnumerate (
    DSENUMCALLBACK EnumCallback,
    VOID *Context
 );

• EnumCallback - указатель перебирающей функции, которая будет вызываться для каждого обнаруженного устройства;
• Context - произвольное 32-разрядное значение, которое будет передаваться перебирающей функции при каждом вызове. Например, это может быть описатель параметров искомого устройства, указатель области памяти для найденного идентификатора и т.п.

EnumCallback - перебирающая функция

BOOL CALLBACK EnumCallback (
    LPGUID GUID,
    LPCSTR Description,
    LPCSTR Module,
    VOID *Context
 );

• GUID - указатель идентификатора очередного найденного устройства;
• Description - строка названия устройства;
• Module - строка имени модуля драйвера устройства;
• Context - 32-разрядное значение, заданное в функции Enumerate.

Функция вызывается для каждого найденного устройства заданного класса. Если возвращается значение TRUE - перебор продолжается, если FALSE - прекращается.

Create - создание объекта устройства воспроизведения или захвата

HRESULT WINAPI DirectSoundCreate (
    LPCGUID GUID,
    LPDIRECTSOUND *Dev,
    LPUNKNOWN   Outer
 );

HRESULT WINAPI DirectSoundCaptureCreate (
    LPCGUID GUID,
    LPDIRECTSOUNDCAPTURE *Dev,
    LPUNKNOWN Outer
 );

• GUID - указатель идентификатора устройства либо нулевое значение для использования стандартного устройства;
• Dev - указатель переменной, в которую будет занесен указатель созданного объекта;
• Outer - указатель наружного интерфейса COM. Не используется, должен иметь нулевое значение.

После успешного создания устройства воспроизведения, до начала проигрывания звуковых источников приложение должно установить уровень взаимодействия методом SetCooperativeLevel.

Интерфейс IUnknown

Является базовым для всех интерфейсов COM и содержит средства фиксации объекта, его освобождения и запроса нужного интерфейса из набора (агрегата).

QueryInterface - запрос интерфейса из набора

HRESULT IUnknown::QueryInterface (
      REFIID IID,
      LPVOID *Obj
   );

• IID - идентификатор (GUID) требуемого интерфейса;
• Obj - указатель переменной, в которую будет занесен указатель объекта, имеющего требуемый интерфейс.

Если объект, для которого интерфейс IUnknown является базовым, имеет указанный интерфейс, то в заданную переменную заносится указатель объекта, через который доступен запрашиваемый интерфейс.

Обычно в качестве переменной выступает указатель объекта того типа, который имеет запрашиваемый интерфейс в своем составе. Например, при получении интерфейса IDirectSound3DBuffer из объекта с указателем Buf типа IDirectSoundBuffer вызывается метод

Buf->QueryInterface (IID_IDirectSound3DBuffer, (LPVOID *)&Buf3D),

где Buf3D - указатель объекта типа IDirectSound3DBuffer. Указатели Buf и Buf3D обычно ссылаются на один и тот же объект, однако рассчитывать на это не стоит.

При успешном завершении функция возвращает код S_OK (нуль). Возможными кодами ошибки могут быть E_NOINTERFACE (исходный объект не имеет требуемого интерфейса) и E_POINTER (передан недопустимый указатель переменной).

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

AddRef - фиксация объекта

ULONG IUnknown::AddRef ();

Увеличивает счетчик ссылок объекта на единицу. При создании объекта счетчик устанавливается в единицу, при получении нового интерфейса счетчик автоматически увеличивается на единицу.

При завершении работы с объектом должен быть вызван метод Release, уменьшающий счетчик ссылок на единицу. Когда количество ссылок становится нулевым, объект уничтожается.

Функция возвращает значение обновленного счетчика ссылок.

Release - освобождение объекта

ULONG IUnknown::Release ();

Уменьшает счетчик ссылок объекта на единицу. При обнулении счетчика объект уничтожается. Метод должен вызываться для всех объектов, полученных приложением, при завершении работы с ними.

Интерфейс IDirectSound

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

Initialize - инициализация устройства

HRESULT IDirectSound::Initialize (
    LPCGUID GUID
 );

• GUID - идентификатор устройства либо нулевое значение для выбора стандартного устройства.

Метод используется для объектов, созданных не специальной функциями Create, а стандартным для COM методом CoCreateInstance. Функции Create возвращают инициализированный объект, в то время как CoCreateInstance - объект-заготовку, который не связан с конкретным устройством.

SetCooperativeLevel - установка уровня взаимодействия

HRESULT IDirectSound::SetCooperativeLevel (
    HWND Win,
    DWORD Level
 );

• Win - ключ окна (window handle), по положению которого определяется состояние приложения. Когда окно становится текущим (foreground), приложение также считается текущим, и наоборот. Если приложение использует DirectDraw, то в методах установки уровня DirectDraw и DirectSound должно использоваться одно и то же окно.
• Level - запрашиваемый уровень взаимодействия. Имена констант кодов уровней имеют префикс DSSCL_:;

CreateSoundBuffer - создание звукового буфера

HRESULT IDirectSound::CreateSoundBuffer (
    LPCDSBUFFERDESC BufferDesc,
    LPDIRECTSOUNDBUFFER *Buffer,
    IUnknown *Outer
 );

• BufferDesc - указатель заполненного описателя создаваемого буфера (структура DSBUFFERDESC);
• Buffer - указатель переменной, в которую будет занесен указатель созданного объекта буфера;
• Outer - указатель объекта <наружного> интерфейса IUnknown. Не используется, должен иметь нулевое значение.

Метод создает звуковой - первичный или вторичный буфер, в зависимости от состояния флага DSBCAPS_PRIMARYBUFFER. При создании буфера должны быть указаны способы управления (флаги DSBCAPS_CTRLxxx), которые будут использоваться при проигрывании буфера.

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

DuplicateSoundBuffer - создание копии объекта буфера

HRESULT IDirectSound::DuplicateSoundBuffer (
    LPDIRECTSOUNDBUFFER Original,
    LPLPDIRECTSOUNDBUFFER Duplicate
 );

• Original - указатель копируемого объекта;
• Duplicate - указатель переменной, в которую заносится указатель объекта-копии.

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

GetCaps - запрос параметров и состояния устройства

HRESULT IDirectSound::GetCaps (
    DSCAPS *Caps
 );

• Caps - указатель структуры DSCAPS, которая будет заполнена параметрами устройства. Перед обращением к методу должно быть установлено поле dwSize, определяющее версию интерфейса.

GetSpeakerConfig - запрос конфигурации звукоизлучателей

HRESULT IDirectSound::GetSpeakerConfig (
    DWORD *Config
 );

• Config - адрес переменной, в которую будет занесен код текущей конфигурации звукоизлучателей для данного устройства. Имена констант значений кодов имеют префикс DSSPEAKER_:;

В конфигурации STEREO добавляется код расположения громкоговорителей. Имена значений кодов имеют префикс DSSPEAKER_GEOMETRY_:

Для выделения из двойного слова кодов конфигурации и расположения используются макросы DSSPEAKER_CONFIG и DSSPEAKER_GEOMETRY.

SetSpeakerConfig - установка конфигурации звукоизлучателей

HRESULT IDirectSound::SetSpeakerConfig (
    DWORD Config
 );

• Config - набор флагов, описывающих конфигурацию.

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

Для объединения кодов конфигурации и расположения используется макрос DSSPEAKER_COMBINED (Config, Geometry).

Compact - уплотнение внутренней памяти адаптера

HRESULT IDirectSound::Compact ();

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

Для использования метода приложение должно иметь уровень взаимодействия не ниже приоритетного.

Интерфейс IDirectSoundBuffer

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

Initialize - инициализация объекта буфера

HRESULT IDirectSoundBuffer::Initialize (
    DIRECTSOUND *DevObj,
    LPCDSBUFFERDESC BufferDesc
 );

• DevObj - указатель объекта устройства DirectSound;
• BufferDesc - указатель описателя буфера (структура DSBUFFERDESC).

Метод инициализирует объект звукового буфера в соответствии с заданным описателем. При создании буфера методом IDirectSound::CreateSoundBuffer возвращается уже инициализированный объект буфера. Метод IDirectSoundBuffer::Initialize предназначен для унификации и будущих расширений интерфейса.

Restore - восстановление памяти потерянного буфера

HRESULT IDirectSoundBuffer::Restore ();

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

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

GetCaps - запрос параметров буфера

HRESULT IDirectSoundBuffer::GetCaps (
    DSBCAPS *Caps
 );

• Caps - указатель описателя параметров буфера (структура DSBCAPS), который будет заполнен подсистемой. Поле dwSize должно быть установлено до обращения к методу.

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

GetFormat - запрос текущего формата буфера

HRESULT IDirectSoundBuffer::GetFormat (
    WAVEFORMATEX *Format,
    DWORD SizeAllocated,
    DWORD *SizeWritten
 );

• Format - указатель области памяти для описателя формата (структура WAVEFORMATEX), который будет заполнен параметрами формата буфера, или нуль;
• SizeAllocated - размер в байтах области памяти описателя;
• SizeWritten - указатель переменной, в которую будет занесен реальный размер заполненного описателя, или нуль, если размер не требуется.

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

Если указатель области имеет нулевое значение, в переменную по указателю SizeWritten заносится размер области памяти, необходимый для размещения полного описателя.

SetFormat - установка формата буфера

HRESULT IDirectSoundBuffer::SetFormat (
    LPCWAVEFORMATEX Format
 );

• Format - указатель описателя формата (структура WAVEFORMATEX).

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

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

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

Если первичный буфер не поддерживает устанавливаемый формат, ошибки не возникает. В этом случае подсистема устанавливает наиболее близкий формат и прозрачно преобразует звуковые данные при их занесении в буфер. Определить реально установленный формат можно при помощи метода GetFormat.

Lock - запрос обновления данных в буфере

HRESULT IDirectSoundBuffer::Lock (
    DWORD WriteCursor,
    DWORD WriteBytes,
    LPVOID *Ptr1,
    DWORD *Bytes1,
    LPVOID *Ptr2,
    DWORD *Bytes2,
    DWORD Flags
 );

• Cursor - смещение (относительно начала буфера) участка, к которому запрашивается прямой доступ;
• Bytes - размер участка в байтах;
• Ptr1, Ptr2 - указатели переменных, в которых будут возвращены указатели частей полученного участка памяти. Поскольку буферы фактически являются кольцевыми, полученный участок может пересекать границу буфера и <заворачиваться> на его начало. Если получен непрерывный участок, в переменной Ptr2 возвращается нулевое значение, иначе этот указатель всегда ссылается на начало буфера;
• Bytes1, Bytes2 - указатели переменных, в которых будут возвращены размеры частей полученного участка памяти. Если получен непрерывный участок, в переменной Bytes2 возвращается нулевое значение;
• Flags - флаги, уточняющие операцию. Имена констант флагов имеют префикс DSBLOCK_:

При задании нулевых значений в параметрах Ptr1 и Bytes1 подсистема предоставляет доступ только к непрерывной части буфера, не выполняя <заворачивание> через границу.

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

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

Unlock - завершение обновления данных в буфере

HRESULT IDirectSoundBuffer::Unlock (
    VOID *Ptr1,
    DWORD Bytes1,
    VOID *Ptr2,
    DWORD Bytes2
 );

• Ptr1, Ptr2 - указатели обновленных участков буфера, возвращенные ранее методом Lock;
• Bytes1, Bytes2 - количества байтов, реально записанных в обновленные участки.

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

Play - запуск звучания буфера

HRESULT IDirectSoundBuffer::Play (
    DWORD Reserved,
    DWORD Priority,
    DWORD Flags
 );

• Reserved - зарезервированный параметр, должен иметь нулевое значение;
• Priority - приоритет данного источника звука, если при создании буфера был указан флаг отложенного размещения DSBCAPS_LOCDEFER. В этом случае подсистема стремится обеспечить аппаратное смешивание для источников с наибольшими значениями приоритета. Если флаг отложенного размещения не был указан, этот параметр должен иметь нулевое значение;
• Flags - флаги, уточняющие операцию. Имена констант флагов имеют префикс DSBPLAY_:

Флаги условий досрочного завершения звучания гарантируют, что источник будет смешиваться аппаратно, однако при нехватке ресурсов его звучание может быть досрочно прекращено. Имена констант имеют префикс DSBPLAY_TERMINATEBY_:

Флаги LOCHARDWARE и LOCSOFTWARE являются взаимоисключающими. Эти два флага, а также флаги TERMINATEBY допускаются только для буферов с отложенным размещением (флаг DSBCAPS_LOCDEFER).

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

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

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

Перед первым с момента создания объекта устройства обращением к методу Play должен быть установлен уровень взаимодействия методом IDirectSound::SetCooperativeLevel. В противном случае метод Play завершается успешно, но звук появляется только после установки уровня взаимодействия.

Stop - прекращение проигрывания буфера

HRESULT IDirectSoundBuffer::Stop ();

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

GetStatus - запрос состояния буфера

HRESULT IDirectSoundBuffer::GetStatus (
    DWORD *Status
 );

• Status - указатель переменной, в которую будут возвращены флаги состояния буфера. Имена констант флагов имеют префикс DSBSTATUS_:

Флаги LOCHARDWARE и LOCSOFTWARE являются взаимоисключающими. Они, а также флаг TERMINATED могут быть установлены только для буферов с отложенным размещением (флаг DSBCAPS_LOCDEFER).

GetCurrentPosition - запрос текущих позиций буфера

HRESULT IDirectSoundBuffer::GetCurrentPosition (
    DWORD *PlayCursor,
    DWORD *WriteCursor
 );

• PlayCursor - указатель переменной, в которой будет возвращено смещение позиции воспроизведения буфера;
• WriteCursor - указатель переменной, в которой будет возвращено смещение позиции записи (обновления данных) буфера.

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

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

SetCurrentPosition - установка позиции воспроизведения буфера

HRESULT IDirectSoundBuffer::SetCurrentPosition (
    DWORD PlayPosition
 );

• PlayPosition - новая позиция воспроизведения в виде байтового смещения от начала буфера.

Метод допустим только для вторичных буферов. Проигрывание первичного буфера всегда начинается с его начала.

GetFrequency - запрос частоты дискретизации

HRESULT IDirectSoundBuffer::GetFrequency (
    DWORD *Frequency
 );

• Frequency - указатель переменной, в которой будет возвращено текущее значение частоты дискретизации буфера (в Гц, или отсчетах в секунду).

SetFrequency - установка частоты дискретизации

HRESULT IDirectSoundBuffer::SetFrequency (
    DWORD Frequency
 );

• Frequency - новое значение частоты дискретизации буфера (в Гц, или отсчетов в секунду). Должно быть в диапазоне между DSBFREQUENCY_MIN (обычно 100) и DSBFREQUENCY_MAX (обычно 100000). Значение DSBFREQUENCY_ORIGINAL возвращает частоту, заданную исходным форматом при создании буфера.

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

GetPan - запрос текущего положения источника на панораме

HRESULT IDirectSoundBuffer::GetPan (
    LONG *Pan
 );

• Pan - указатель переменной, в которой возвращается текущее положение источника звука на стереопанораме. Смысл значения раскрыт в описании метода SetPan.

SetPan - установка текущего положения источника на панораме

HRESULT IDirectSoundBuffer::SetPan (
    LONG Pan
 );

• Pan - новое положение источника на стереопанораме. Знак значения задает ослабляемый канал (минус - правый, плюс - левый), абсолютная величина - степень ослабления громкости канала в сотых долях децибела. Значение DSBPAN_CENTER (нуль) означает центральное положение (оба канала имеют полную громкость). Значения DSBPAN_LEFT (минус 10000) и DSBPAN_RIGHT (10000) дают ослабление правого/левого канала на 100 дБ.

GetVolume - запрос уровня громкости источника

HRESULT IDirectSoundBuffer::GetVolume (
    LONG *Volume
 );

• Volume - указатель переменной, в которой возвращается текущее значение уровня громкости источника. Смысл значения раскрыт в описании метода SetVolume.

SetVolume - установка уровня громкости источника

HRESULT IDirectSoundBuffer::SetVolume (
    LONG Volume
 );

• Volume - новое значение уровня громкости источника в сотых долях децибела. Уровень 0 дБ (DSBVOLUME_MAX) соответствует исходному уровню цифрового сигнала в буфере. Определена также константа DSBVOLUME_MIN (минус 10000), задающая уровень -100 дБ. Усиление сигнала относительно исходного уровня в данной реализации не поддерживается.

Интерфейс IDirectSoundCapture

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

Интерфейс содержит следующие методы:

Initialize - инициализация объекта устройства

HRESULT IDirectSoundCapture::Initialize (
    LPCGUID GUID
 );

Подобен методу IDirectSound::Initialize.

GetCaps - запрос параметров устройства

HRESULT IDirectSoundCapture::GetCaps (
    DSCCAPS *Caps
 );

• Caps - указатель описателя параметров устройства захвата (структура DSCCAPS).

Подобен методу IDirectSound::GetCaps.

CreateCaptureBuffer - создание буфера захвата

HRESULT IDirectSoundCapture::CreateCaptureBuffer (
    DSCBUFFERDESC *BufferDesc,
    LPDIRECTSOUNDCAPTUREBUFFER *Buffer,
    UNKNOWN *Outer
 );

• BufferDesc - указатель описателя создаваемого буфера (структура DSCBUFFERDESC);
• Buffer - указатель переменной, в которой будет возвращен указатель созданного объекта буфера;
• Outer - указатель объекта <наружного> интерфейса IUnknown. Не используется, должен иметь нулевое значение.

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

Интерфейс IDirectSoundCaptureBuffer

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

Интерфейс содержит следующие методы:

Initialize - инициализация объекта буфера

HRESULT IDirectSoundCaptureBuffer::Initialize (
    DIRECTSOUNDCAPTURE *CaptureDev,
    LPCDSCBUFFERDESC BufferDesc
 );

• CaptureDev - указатель объекта устройства захвата;
• BufferDesc - указатель описателя буфера (структура DSCBUFFERDESC).

Метод подобен IDirectSoundBuffer::Initialize.

GetCaps - запрос параметров буфера

HRESULT IDirectSoundCaptureBuffer::GetCaps (
    DSCBCAPS *Caps
 );

• Caps - указатель описателя параметров буфера захвата (структура DSCBCAPS).

Метод подобен IDirectSoundBuffer::GetCaps.

GetFormat - запрос формата буфера

HRESULT IDirectSoundCaptureBuffer::GetFormat (
    WAVEFORMATEX *Format,
    DWORD SizeAllocated,
    DWORD *SizeWritten
 );