IDirectSoundBuffer::GetVolume

HRESULT GetVolume( LPLONG lplVolume );

Возвращаемое значение

В случае успешного завершения возвращает значение DS_OK. В противном случае возвращаемое значение может принимать одно из следующих значений:

• DSERR_CONTROLUNAVAIL — требуемый элемент управления (уровень воспроизведения, стерео баланс и т.д.) отсутствует.

• DSERR_INVALIDPARAM — один или несколько аргументов метода имеют недопустимые значения.

• DSERR_PRIOLEVELNEEDED — вызывающее приложение имеет недостаточно высокий уровень приоритета для вызова данной функции.

Аргументы

0. lplVolume — указатель на переменную, в которую будет записан уровень воспроизведения, установленный для данного объекта DirectSoundBuffer.

Примечание

Метод IDirectSoundBuffer::GetVolume позволяет получить значение уровня воспроизведения, установленное для данного объекта DirectSoundBuffer.

Уровень воспроизведения задаётся в сотых долях децибела (дБ). Уровень воспроизведения должен находиться в пределах между DSBVOLUME_MIN (тишина) и DSBVOLUME_MAX (отсутствие ослабления). В настоящее время значения этих величин определены в файле заголовка Dsound.h как -10 000 и 0 соответственно. Уровню DSBVOLUME_MAX соответствует исходный уровень воспроизводимого звукового сигнала. Значению DSBVOLUME_MIN соответствует ослабление сигнала на 100 дБ. Теоретический динамический диапазон 16-разрядных звуковых карт, реализуемый при выводе через них меандра, составляет 90 дБ, поэтому значению DSBVOLUME_MIN в большинстве случаев соответствует вывод нулевого сигнала. Собственные шумы аналоговой части звуковых карт дополнительно снижают их динамический диапазон. Для исключения искажений, возникающих при ограничении сигнала, DirectSound не поддерживает его усиление.

IDirectSoundBuffer::Lock

HRESULT Lock( DWORD dwWriteCursor, DWORD dwWriteBytes, LPVOID lplpvAudioPtr1, LPDWORD lpdwAudioBytes1, LPVOID lplpvAudioPtr2, LPDWORD lpdwAudioBytes2, DWORD dwFlags );

Возвращаемое значение

В случае успешного завершения возвращает значение DS_OK. В противном случае возвращаемое значение может принимать одно из следующих значений:

• DSERR_BUFFERLOST — память, выделенная под буфер, освобождена и должна быть выделена заново.

• DSERR_INVALIDCALL — вызов данной функции недопустим при текущем состоянии объекта.

• DSERR_INVALIDPARAM — один или несколько аргументов метода имеют недопустимые значения.

• DSERR_PRIOLEVELNEEDED — вызывающее приложение имеет недостаточно высокий уровень приоритета для вызова данной функции.

Аргументы

0. dwWriteCursor — смещение начала заблокированной области от начала буфера, выраженное в байтах. Значение данного аргумента игнорируется, если в аргументе dwFlags установлен флаг DSBLOCK_FROMWRITECURSOR.

1. dwWriteBytes — размер заблокированной области, выраженный в байтах. Следует помнить, что аудио буфер является циклическим.

2. lplpvAudioPtr1 — адрес указателя на первый заблокированный блок аудио буфера.

3. lpdwAudioBytes1 — указатель на переменную, в которую будет записан размер первого заблокированного блока аудио буфера. Если значение данного аргумента меньше значения аргумента dwWriteBytes, то аргумент lplpvAudioPtr2 содержит указатель на второй блок аудио информации.

4. lplpvAudioPtr2 — адрес указателя на второй заблокированный блок аудио буфера. Если данный аргумент имеет нулевое значение, аргумент lplpvAudioPtr1 содержит указатель на весь заблокированный блок аудио буфера.

5. lpdwAudioBytes2 — указатель на переменную, в которую будет записан размер второго заблокированного блока аудио буфера. Если аргумент lplpvAudioPtr2 имеет нулевое значение, то данный аргумент тоже должен иметь нулевое значение.

6. dwFlags — флаги, определяющие режим блокировки. Является комбинацией следующих значений:

• DSBLOCK_FROMWRITECURSOR — производит блокировку, начиная с текущей позиции записи, исключая необходимость вызова метода IDirectSoundBuffer::GetCurrentPosition. При установке данного флага значение аргумента dwWriteCursor игнорируется.

• DSBLOCK_ENTIREBUFFER — блокирует весь буфер. При установке данного флага значение аргумента dwWriteBytes игнорируется

Примечание

Метод IDirectSoundBuffer::Lock позволяет получит корректный указатель на данные, расположенные в аудио буфере. Входной информацией данного метода является смещение и размер блокируемой области, а выходной информацией — два указателя, используемые для записи и размеры соответствующих им буферов. Использование двух указателей связано с тем, что аудио буфер является циклическим. Если выделяемый блок памяти не фрагментирован, то аргумент lplpvAudioBytes2 имеет нулевое значение. В противном случае в этот аргумент записывается указатель на начало аудио буфера. Если приложение записывает нулевые значения в аргументы lplpvAudioPtr2 и lpdwAudioBytes2, DirectSound не блокирует вторую часть буфера.

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

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