KSPROPSETID_Synth

Статья
06/15/2023

Набор KSPROPSETID_Synth свойств содержит свойства, которые являются глобальными для конфигурации узла синтезатора (KSNODETYPE_SYNTHESIZER).

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

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

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

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

Значение свойства (данные операции) — это структура типа SYNTHCAPS, задающая возможности синтезатора. К этим возможностям относятся следующие:

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

Дополнительные сведения см. в разделе SYNTHCAPS.

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

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

Дополнительные сведения о возможностях синтезатора см. в статье Метод IDirectMusicPort::GetCaps и структура DMUS_PORTCAPS в документации по Microsoft Windows SDK.

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

Свойство KSPROPERTY_SYNTH_CHANNELGROUPS используется системой для задания или получения количества активных групп каналов в экземпляре закреплений. Группы каналов нумеруются, начиная с нуля, на каждом экземпляре закреплений.

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

Значение свойства (данные операции) имеет тип ULONG и указывает, сколько групп каналов поддерживает закрепление. Если контакт поддерживает n групп каналов, группы каналов в контакте нумеруются от 0 до n-1.

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

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

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

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

Свойство KSPROPERTY_SYNTH_LATENCYCLOCK используется для запроса у драйвера мини-порта текущего времени задержки потока, которое всегда больше времени master часов.

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

Значение свойства (данные операции) имеет тип ULONGLONG и представляет текущее время задержки синтезатора. Это время задается относительно master часов и выражается в 100-наносекундных единицах.

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

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

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

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

Запрос KSPROPERTY_SYNTH_LATENCYCLOCK get-property должен возвращать время задержки, равное текущему времени master, а также минимальной гарантированной задержке звукового фильтра, через который проходит поток. Программа приложения, которая планирует воспроизведение звуковых данных раньше текущего времени задержки, рискует, что данные будут воспроизведены поздно.

Дополнительные сведения о часах задержки см. в следующих статьях:

Обсуждение свойства KSPROPERTY_SYNTH_LATENCYCLOCK в разделе Часы задержки.
Описание методов IDirectMusicPort::GetLatencyClock и IReferenceClock::GetTime в документации по Microsoft Windows SDK.

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

Свойство KSPROPERTY_SYNTH_PORTPARAMETERS используется для получения параметров конфигурации для порта DirectMusic, который является термином DirectMusic для устройства, которое отправляет или получает музыкальные данные. (В терминологии KS порт DirectMusic не соответствует драйверу порта DMus. Соответствует закреплению отрисовки или записи в фильтре DirectMusic.)

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

Дескриптор свойства (данные экземпляра) состоит из структуры KSNODEPROPERTY, за которой сразу же следует структура SYNTH_PORTPARAMS. Перед отправкой запроса на свойство клиент указывает запрошенные значения параметров, записывая их в структуру SYNTH_PORTPARAMS.

Значение свойства (данные операции) также имеет тип SYNTH_PORTPARAMS. Драйвер мини-порта загружает эту структуру со значениями параметров, которые фактически используются для настройки порта.

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

Если драйверу мини-порта удалось настроить порт DirectMusic точно так, как указано вызывающим объектом, он возвращает код STATUS_SUCCESS. В противном случае возвращается соответствующий код ошибки. В следующей таблице указаны некоторые из возможных кодов состояния ошибок.

Код состояния	Значение
STATUS_NOT_ALL_ASSIGNED	Операция выполнена успешно, но драйверу мини-порта пришлось изменить одно или несколько значений параметров, которые вызывающий объект помечает как допустимые в значении свойства .
STATUS_UNSUCCESSFUL	Операция не завершилась успешно.

Это самый сложный из элементов свойств DirectMusic для обработки. Хотя это свойство поддерживает только запрос get, запрос get также задает параметры порта. Порт передает структуру SYNTH_PORTPARAMS в качестве дескриптора свойства для запроса на свойство. Буфер значения свойства сопровождает запрос свойства, но так как это запрос на получение, буфер используется только для получения сведений из драйвера мини-порта.

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

Если драйвер мини-порта не вносит изменений в SYNTH_PORTPARAMS вызывающего объекта, вызывающий объект должен получить значение свойства, которое точно соответствует параметрам дескриптора свойств, которые вызывающий объект изначально отправил драйверу мини-порта.

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

Обработчик KSPROPERTY_SYNTH_PORTPARAMETERS драйвера мини-порта должен быть подготовлен к правильной обработке запросов на изменение частоты выборки.

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

Свойство KSPROPERTY_SYNTH_RUNNINGSTATS используется для запроса к драйверу мини-порта статистики производительности синтезатора.

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

Значение свойства (данные операции) — это структура типа SYNTH_STATS. Обработчик свойств драйвера мини-порта записывает в эту структуру следующую статистику:

Среднее количество воспроизводимых голосов
Загрузка ЦП
Число потерянных заметок
Объем свободной памяти
Пиковый уровень громкости

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

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

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

Статистика производительности синтезатора постоянно обновляется, пока устройство остается в состоянии KSSTATE_RUN. Каждый раз, когда устройство переходит в это состояние, оно сбрасывает статистику, которая обнуляет совокупные значения, такие как пиковый объем и количество потерянных заметок.

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

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

Свойство KSPROPERTY_SYNTH_VOICEPRIORITY указывает, какой приоритет должен иметь конкретный голос в синтезаторе MIDI, когда драйверу мини-порта необходимо выталкивать голоса из своего голосового кэша.

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

Дескриптор свойства (данные экземпляра) состоит из структуры KSNODEPROPERTY, за которой сразу же следует структура SYNTHVOICEPRIORITY_INSTANCE, которая задает группу каналов голоса (набор из 16 MIDI-каналов) и номер канала (в группе).

Значение свойства (данные операции) — это DWORD, задающий приоритет. Клиент использует запрос KSPROPERTY_SYNTH_VOICEPRIORITY set-property для отправки нового приоритета голоса драйверу мини-порта и использует запрос KSPROPERTY_SYNTH_VOICEPRIORITY get-property для получения текущего приоритета голоса от драйвера мини-порта.

Приоритеты голосовой связи

В файле заголовка Dmusprop.h определены следующие приоритеты групп каналов:

  DAUD_CRITICAL_VOICE_PRIORITY
  DAUD_HIGH_VOICE_PRIORITY
  DAUD_STANDARD_VOICE_PRIORITY
  DAUD_LOW_VOICE_PRIORITY
  DAUD_PERSIST_VOICE_PRIORITY

Предыдущий список упорядочен с наивысшим приоритетом в верхней части списка и самым низким в нижней части. Эти приоритеты являются ORed со смещениями приоритета канала для получения приоритета голоса для каждого канала в группе каналов. Полученные приоритеты передаются в запросах get и set-property.

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

Приоритеты по умолчанию

При создании драйвера мини-порта синтезатора он назначает приоритет по умолчанию каждому из своих голосов. Значения по умолчанию определяются следующим образом:

По умолчанию приоритеты равны в разных группах каналов. Это означает, например, что канал 5 в группе каналов 1 имеет тот же приоритет, что и канал 5 в группе каналов 2.
В соответствии со спецификациями уровня DLS 1 канал 10 (канал ударной передачи MIDI) имеет наивысший приоритет, за которым следуют 1–9 и 11–16.

Файл заголовка Dmusprop.h определяет следующие смещения приоритета:

  DAUD_CHAN10_VOICE_PRIORITY_OFFSET
  DAUD_CHAN1_VOICE_PRIORITY_OFFSET
  DAUD_CHAN2_VOICE_PRIORITY_OFFSET
  DAUD_CHAN3_VOICE_PRIORITY_OFFSET
  DAUD_CHAN4_VOICE_PRIORITY_OFFSET
  DAUD_CHAN5_VOICE_PRIORITY_OFFSET
  DAUD_CHAN6_VOICE_PRIORITY_OFFSET
  DAUD_CHAN7_VOICE_PRIORITY_OFFSET
  DAUD_CHAN8_VOICE_PRIORITY_OFFSET
  DAUD_CHAN9_VOICE_PRIORITY_OFFSET
  DAUD_CHAN11_VOICE_PRIORITY_OFFSET
  DAUD_CHAN12_VOICE_PRIORITY_OFFSET
  DAUD_CHAN13_VOICE_PRIORITY_OFFSET
  DAUD_CHAN14_VOICE_PRIORITY_OFFSET
  DAUD_CHAN15_VOICE_PRIORITY_OFFSET
  DAUD_CHAN16_VOICE_PRIORITY_OFFSET

Предыдущий список смещения упорядочивается с наивысшим приоритетом в верхней части списка. Файл заголовка Dmusprop.h также определяет приоритеты по умолчанию для каналов в каждой группе каналов путем побитового ORing каждого из этих смещений с DAUD_STANDARD_VOICE_PRIORITY. Например, следующее определение дает приоритет по умолчанию для канала 1 в каждой группе каналов:

  #define DAUD_CHAN1_DEF_VOICE_PRIORITY \
    (DAUD_STANDARD_VOICE_PRIORITY | DAUD_CHAN1_VOICE_PRIORITY_OFFSET)

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

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

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

Дополнительные сведения о приоритетах голосовой связи см. в описании методов IDirectMusicPort::GetChannelPriority и IDirectMusicPort::SetChannelPriority в документации по Microsoft Windows SDK.

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

Свойство KSPROPERTY_SYNTH_VOLUME получает или задает уровень громкости синтезатора.

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

Значение свойства (данные операции) имеет тип LONG и указывает уровень громкости синтезатора. Параметр тома указывается в единицах 1/100 единиц децибела. Драйвер мини-порта должен изменить свой том или сообщить о томе в зависимости от того, должен ли запрос получить или задать свойство .

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

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

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

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

Свойство KSPROPERTY_SYNTH_VOLUMEBOOST указывает объем, на который увеличивается объем устройства синтезатора.

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

Значение свойства (данные операции) имеет тип LONG и указывает, насколько следует увеличить звуковой сигнал после этапа микширования. Это объем, добавляемый к окончательному выходу синтезатора после завершения всех речевых операций и смешивания. Величина увеличения громкости указывается в 1/100ths от децибела. Это значение может быть положительным или отрицательным.

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

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

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

К выходным данным не следует добавлять другое повышение. Синтезатор должен следовать строгим соглашениям DLS уровня 1 для обозначения.

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

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

KSPROPSETID_Synth

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

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

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

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

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

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

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

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

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

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

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

Приоритеты по умолчанию

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

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

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

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

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

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

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