KSPROPSETID_Synth_Dls

Статья
06/15/2023

Набор KSPROPSETID_Synth_Dls свойств содержит свойства, которые используются для скачивания примеров и инструментов DLS в синтезатор MIDI. Это свойства узла синтезатора (KSNODETYPE_SYNTHESIZER) в контакте DirectMusic фильтра DirectMusic (см. статью Фильтры MIDI и DirectMusic).

В этом разделе описывается поведение этих свойств в отношении того, как они скачивают и выгружают "блоки" памяти, содержащие данные DLS. Фактический формат загруженных блоков инструментов и волновых данных указывается в низкоуровневом обсуждении DLS в документации по Microsoft Windows SDK.

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

В этом разделе термин ресурс DLS или просто ресурс относится к блоку инструментов DLS или блоку волн DLS. Система правильно поддерживает количество ссылок для всех ресурсов DLS:

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

Элементы свойств в этом наборе задаются KSPROPERTY_SYNTH_DLS значениями перечисления, как определено в файле заголовка Dmusprop.h.

Сводная таблица использования

Свойство KSPROPERTY_SYNTH_DLS_APPEND указывает объем зарезервированного дискового пространства, который клиент добавляет к данным DLS в каждом буфере, скачиваемом в синтезатор.

Получить	Присвойте параметру	Назначение	Тип дескриптора свойства	Тип значения свойства
Да	Нет	Pin	KSNODEPROPERTY	ULONG

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

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

Запрос свойства KSPROPERTY_SYNTH_DLS_APPEND возвращает STATUS_SUCCESS, указывающий на успешное выполнение. В противном случае запрос возвращает соответствующий код состояния ошибки. В следующей таблице показаны некоторые возможные коды ошибок.

Код состояния	Значение
STATUS_UNSUCCESSFUL	Операция не завершилась успешно.

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

Сводная таблица использования

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

Получить	Присвойте параметру	Назначение	Тип дескриптора свойства	Тип значения свойства
Нет	Да	Pin	KSNODEPROPERTY	Нет

С этим свойством не связано значение свойства (данные операции).

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

Запрос свойства KSPROPERTY_SYNTH_DLS_COMPACT возвращает STATUS_SUCCESS, указывающий на успешное выполнение. В противном случае запрос возвращает соответствующий код состояния ошибки. В следующей таблице показаны некоторые возможные коды ошибок.

Код состояния	Значение
STATUS_UNSUCCESSFUL	Операция не завершилась успешно.

Реализация обработчика для этого свойства не должна прерывать воспроизведение.

Дополнительные сведения см. в описании метода IDirectMusicPort::Compact в документации по Microsoft Windows SDK.

Сводная таблица использования

Свойство KSPROPERTY_SYNTH_DLS_DOWNLOAD используется для загрузки данных DLS в синтезатор.

Получить	Присвойте параметру	Назначение	Тип дескриптора свойства	Тип значения свойства
Да	Нет	Pin	KSNODEPROPERTY + SYNTH_BUFFER	SYNTHDOWNLOAD

Дескриптор свойства (данные экземпляра) состоит из структуры KSNODEPROPERTY, за которой сразу же следует структура SYNTH_BUFFER, указывающая расположение и размер загружаемого буфера данных DLS.

Значение свойства (данные операции) является структурой SYNTHDOWNLOAD. Драйвер минипорта передает следующие сведения в этой структуре:

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

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

Запрос свойства KSPROPERTY_SYNTH_DLS_DOWNLOAD возвращает STATUS_SUCCESS, указывающий на успешное выполнение. В противном случае запрос возвращает соответствующий код состояния ошибки. В следующей таблице показаны некоторые возможные коды ошибок.

Код состояния	Значение
STATUS_BUFFER_TOO_SMALL	Буфер был слишком мал для завершения операции.
STATUS_UNSUCCESSFUL	Операция не завершилась успешно.
STATUS_NO_MEMORY	Для выполнения этого запроса нет доступной памяти.

Дополнительные сведения см. в описании метода IDirectMusicPort::D ownloadInstrument в документации по Microsoft Windows SDK.

Пример

Запрос свойства KSPROPERTY_SYNTH_DLS_DOWNLOAD указывает расположение скачиваемых данных DLS с адресом памяти пользователя. Драйвер мини-порта должен проверять и блокировать память пользователя, содержащую данные DLS, перед попыткой доступа к ней. В следующем примере кода показано, как это сделать:

  NTSTATUS Status = STATUS_UNSUCCESSFUL;
  PSYNTH_BUFFER pDlsBuffer = (PSYNTH_BUFFER)pRequest->Instance;
  PMDL pMdl = IoAllocateMdl(pDlsBuffer->BufferAddress, pDlsBuffer->BufferSize,
                            FALSE, FALSE, NULL);
  if (pMdl)
  {
      __try
      {
          MmProbeAndLockPages(pMdl, KernelMode, IoReadAccess);
          PVOID pvUserData = MmGetSystemAddressForMdlSafe(pMdl, NormalPagePriority);
 
         // do something with the data here
      }
      __except (EXCEPTION_EXECUTE_HANDLER)
      {
          Status = GetExceptionCode();
      }
 
      MmUnlockPages(pMdl);
      IoFreeMdl(pMdl);
  }
  else
  {
      Status = STATUS_NO_MEMORY;
  }

Сводная таблица использования

Свойство KSPROPERTY_SYNTH_DLS_UNLOAD выгружает ранее скачанный ресурс данных DLS.

Получить	Присвойте параметру	Назначение	Тип дескриптора свойства	Тип значения свойства
Нет	Да	Pin	KSNODEPROPERTY	HANDLE

Значение свойства (данные операции) имеет тип HANDLE и содержит дескриптор загруженного ресурса данных DLS, который должен быть освобожден. Это дескриптор, созданный драйвером мини-порта для идентификации данных DLS в предыдущем запросе KSPROPERTY_SYNTH_DLS_DOWNLOADget-property.

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

Запрос KSPROPERTY_SYNTH_DLS_UNLOAD свойства возвращает STATUS_SUCCESS, указывающий на успешное завершение. В противном случае запрос возвращает соответствующий код состояния ошибки. В следующей таблице показаны некоторые возможные коды ошибок.

Код состояния	Значение
STATUS_BUFFER_TOO_SMALL	Буфер был слишком мал для завершения операции.
STATUS_UNSUCCESSFUL	Операция не завершилась успешно.
STATUS_PENDING	Операция будет завершена позже.

Драйвер мини-порта должен выгрузить данные DLS, как только не будет воспроизведения заметок, использующих данные DLS. Если синтезатор не может освободить память, связанную с ресурсом данных DLS во время запроса KSPROPERTY_SYNTH_DLS_UNLOAD set-property, он может использовать асинхронное завершение свойства для последующего завершения запроса.

Если после выгрузки ресурса данных DLS синтезатор получает событие note-on, которое использует этот ресурс, драйвер мини-порта должен игнорировать событие, если пока не был скачан новый ресурс данных DLS.

Дополнительные сведения см. в описании метода IDirectMusicPort::UnloadInstrument в документации по Microsoft Windows SDK.

Сводная таблица использования

Свойство KSPROPERTY_SYNTH_DLS_WAVEFORMAT используется для запроса у синтезатора формата выходной волны.

Получить	Присвойте параметру	Назначение	Тип дескриптора свойства	Тип значения свойства
Да	Нет	Pin	KSNODEPROPERTY	WAVEFORMATEX

Значение свойства (данные операции) имеет тип WAVEFORMATEX и задает волновой формат выходного потока синтезатора.

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

Запрос свойства KSPROPERTY_SYNTH_DLS_WAVEFORMAT возвращает STATUS_SUCCESS, указывающий на успешное выполнение. В противном случае запрос возвращает соответствующий код состояния ошибки. В следующей таблице показаны некоторые возможные коды ошибок.

Код состояния	Значение
STATUS_BUFFER_TOO_SMALL	Буфер был слишком мал для завершения операции.

Буфер свойств-значений в байтах sizeof(WAVEFORMATEX) может быть недостаточно большим для всех волновых форматов. Например, для многоканального формата требуется буфер sizeof(WAVEFORMATEXTENSIBLE) байтов. Если запрос на свойство возвращает код состояния STATUS_BUFFER_TOO_SMALL, клиент может проверка размер значения свойства, который выводит драйвер мини-порта, выделить буфер большего размера, а затем отправить второй запрос.

Дополнительные сведения см. в описании метода IDirectMusicPort::GetFormat в документации по Microsoft Windows SDK.

Поделиться через

KSPROPSETID_Synth_Dls

Сводная таблица использования

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

Сводная таблица использования

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

Сводная таблица использования

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

Сводная таблица использования

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

Сводная таблица использования

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

Обратная связь

Дополнительные ресурсы