Ссылка IOForceFeedbackLib.h
Открытые интерфейсы и константы раньше разрабатывали плагины Обратной связи Силы.
Производитель устройств обратной связи силы, возможно, должен был бы реализовать плагин, чтобы позволить Библиотеке Обратной связи Силы управлять устройством. Этот заголовочный файл описывает функции, которые должны быть реализованы. Это интерфейсное определение следует определению Microsoft Windows IDirectInputEffectDriver везде, где это целесообразно делать так. Эта сменная архитектура использует модель CFPlugIn (COM). Платформа Обратной связи Силы найдет доступные плагины и будет использовать этот интерфейс для передачи с аппаратными средствами.
Определенные функции могут содержать больше или меньше параметров, чем соответствующая версия Windows IDirectInputEffectDriver.
Включенные заголовки
<sys/cdefs.h>
<CoreFoundation/CoreFoundation.h>
<CoreFoundation/CFPlugInCOM.h>
<MacTypes.h>
<IOKit/IOTypes.h>
<ForceFeedback/ForceFeedback.h>
-
Этот функциональные команды устройство для «уничтожения» в настоящее время загружаемого эффекта. Эффект ID и любые данные, связанные с эффектом, освобожден и доступен для перераспределения.
Объявление
Objective C
HRESULT ( *DestroyEffect)( void *self, FFEffectDownloadID downloadID );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
downloadID
Указывает эффект ID, полученный из устройства, когда был загружен эффект.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_INVALIDDOWNLOADID
FFERR_GENERIC
FFERR_INTERNAL
-
Эта функция отправляет эффект в устройство.
Объявление
Objective C
HRESULT ( *DownloadEffect)( void *self, CFUUIDRef effectType, FFEffectDownloadID *pDownloadID, FFEFFECT *pEffect, FFEffectParameterFlag flags );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
effectType
Указывает тип создаваемого эффекта. Допустимые UUIDs перечислены как kFFEffectType_* константы в файле ForceFeedbackConstants.h. (Поддерживаемые типы эффекта включают Синус, Квадрат, Треугольник, SawtoothUp, SawtoothDown, Постоянный, Spring, Увлажнитель, и т.д.).
pDownloadID
На записи этот параметр указывает на дескриптор загружаемого эффекта. Если параметр указывает на нуль, то новый эффект загружается. На выходе FFEffectDownloadID, на который указывает этот параметр, содержит новый дескриптор эффекта. При отказе обнуляется FFEffectDownloadID, на который указывает этот параметр, если эффект потерян или оставлен в покое, если эффект все еще допустим со своими старыми параметрами. Обратите внимание на то, что нуль никогда не является допустимым дескриптором эффекта.
pEffect
Новые параметры для эффекта.
IMPORTANT ПРИМЕЧАНИЕ: В отличие от спецификации IDirectInputEffectDriver, оси и значений кнопки НЕ преобразовывается в идентификаторы объектов, прежде чем они будут переданы к драйверу. В этом случае единственный поддерживаемый метод, используемый, чтобы присвоить триггеры и вывести оси, посредством объектных смещений, определенных константами FFJOFS_*. Поэтому, если кнопка будет присвоена инициировать эффект, то FFEFFECT.dwTriggerButton будет содержать константу формы FFJOFS_BUTTONn. Точно так же выходные оси будут идентифицированы в FFEFFECT.rgdwAxes[n] как FFJOFS_X, FFJOFS_Y, и т.д.
flags
Указывает, какие части информации об эффекте уже изменились от эффекта на устройство. Эта информация передается драйверам для обеспечения оптимизации модификации эффекта. Если эффект изменяется, драйвер может быть в состоянии обновить эффект в своей исходной позиции и передать к устройству только изменившуюся информацию. Драйверы, однако, не требуются реализовать эту оптимизацию. Все элементы структуры FFEFFECT, на которые указывает pEffect параметр, допустимы, и драйвер может принять решение просто обновить все параметры эффекта при каждой загрузке. Может быть нуль, один, или больше следующего:
FFEP_DURATION
Указывает, что dwDuration элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки.
FFEP_SAMPLEPERIOD
Указывает, что dwSamplePeriod элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки.
FFEP_GAIN
Указывает, что dwGain элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки.
FFEP_TRIGGERBUTTON
Указывает, что dwTriggerButton элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки.
FFEP_TRIGGERREPEATINTERVAL
Указывает, что dwTriggerRepeatInterval элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки.
FFEP_AXES
Указывает cAxes, и rgdwAxes элементы структуры FFEFFECT загружаются впервые или изменились начиная с их последней загрузки.
FFEP_DIRECTION
Указывает cAxes, и rglDirection элементы структуры FFEFFECT загружаются впервые или изменились начиная с их последней загрузки. (dwFlags элемент структуры FFEFFECT указывает через FFEFF_CARTESIAN или FFEFF_POLAR, систему координат, в которой должны быть интерпретированы значения.)
FFEP_ENVELOPE
Указывает, что lpEnvelope элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки. Если этот флаг установлен, и lpEnvelope элемент является Указателем Нулевого, то эффект создается без конверта, или существующий конверт удаляется.
FFEP_TYPESPECIFICPARAMS
Указывает cbTypeSpecificParams, и lpTypeSpecificParams элементы структуры FFEFFECT загружаются впервые или изменились начиная с их последней загрузки.
FFEP_STARTDELAY
Указывает, что dwStartDelay элемент структуры FFEFFECT загружается впервые или изменился начиная с ее последней загрузки.
FFEP_START
Указывает, что эффект состоит в том, чтобы быть перезапущен с начала после того, как были обновлены параметры эффекта. Обратите внимание на то, что флаг FFEP_NODOWNLOAD переопределяет флаг FFEP_START.
FFEP_NORESTART
Если этот флаг не указан, драйверу устройства эффекта разрешают перезапустить эффект, если выполнение так необходимо для изменения указанных параметров. Обратите внимание на то, что FFEP_NODOWNLOAD и флаги FFEP_START переопределяют этот флаг.
FFEP_NODOWNLOAD
Подавляет автоматическую загрузку, обычно выполняющуюся после того, как параметры обновляются. Если этот флаг установлен, драйвер должен проверить параметры, не выполняя фактическую загрузку.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_DEVICEPAUSED
FFERR_DEVICEFULL
FFERR_INVALIDDOWNLOADID
FFERR_INTERNAL
FFERR_EFFECTTYPEMISMATCH
-
Эта функция выходит к драйверу. Этот метод вызывают в ответ на приложение, вызов методы FFDeviceEscape или FFEffectEscape.
Объявление
Objective C
HRESULT ( *Escape)( void *self, FFEffectDownloadID downloadID, FFEFFESCAPE *pEscape );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
downloadID
Указывает эффект, на который команда направлена, или нуль, если команда направлена на само устройство и не какой-либо определенный эффект.
pEscape
Указатель на структуру FFEFFESCAPE, описывающую команду, которая будет отправлена. На успехе cbOutBuffer элемент содержит число байтов буфера вывода, фактически используемых.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_UNSUPPORTED
-
Эта функция используется для определения информации о версии API и драйвера.
Объявление
Objective C
HRESULT ( *ForceFeedbackGetVersion) ( void *self, ForceFeedbackVersion *version);
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
version
Указатель на структуру ForceFeedbackVersion, которая должна получить требуемую информацию. См. описание структуры для подробных данных.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе.
-
Эта функция возвращает состояние эффекта устройства.
Объявление
Objective C
HRESULT ( *GetEffectStatus)( void *self, FFEffectDownloadID downloadID, FFEffectStatusFlag *pStatusCode );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
downloadID
Указывает эффект, который будет запрошен.
pStatusCode
Получает состояние эффекта. FFEffectStatusFlag, на который указывает этот параметр, должен быть переполнен в одним из следующих значений:
FFEGES_PLAYING
Эффект все еще играет.
FFEGES_NOTPLAYING
Эффект не играет.
Возвращаемое значение
Возвраты FF_OK.
-
Эта функция выходит к драйверу. Этот метод вызывают в ответ на приложение, вызов методы FFDevicEscape или FFEffectEscape.
Объявление
Objective C
HRESULT ( *GetForceFeedbackCapabilities)( void *self, FFCAPABILITIES *pCapabilities );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
pCapabilities
Указатель на структуру FFCAPABILITIES, которая должна быть заполнена в информацией о версии, описывающей аппаратные средства, встроенное микропрограммное обеспечение и драйвер.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_INTERNAL
FFERR_NOINTERFACE
-
Эта функция возвращает состояние устройства.
Объявление
Objective C
HRESULT ( *GetForceFeedbackState)( void *self, ForceFeedbackDeviceState *pDeviceState );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
pDeviceState
Указатель на структуру ForceFeedbackDeviceState, получающую состояние устройства. FF API устанавливает dwSize элемент структуры ForceFeedbackDeviceState к sizeof (ForceFeedbackDeviceState) прежде, чем вызвать этот метод.
Возвращаемое значение
Возвраты FF_OK.
-
Эта функция используется, чтобы «создать и уничтожить» определенные экземпляры устройства. Это предоставляет драйверу плагина FF все необходимые параметры запуска.
Объявление
Objective C
HRESULT ( *InitializeTerminate)( void *self, NumVersion forceFeedbackAPIVersion, io_object_t hidDevice, boolean_t begin );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
forceFeedbackAPIVersion
Номер версии FF API, загрузивший драйвер эффекта. Плагин должен проверить, что основная версия forceFeedbackAPI версии совпадает с основной версией API в то время, когда был скомпилирован плагин. Если основные версии отличаются, то сменный API изменился, и плагин НЕ будет совместим с ним.
Если начинаются, ложь, этот параметр проигнорирован.
hidDevice
Объект устройства, который может использоваться плагином FF, чтобы установить соединение с и связаться с устройством. Вызывающая сторона выпустит hidDevice объект устройства с вызовом к IOObjectRelease (), как только плагин FF завершает свою обработку InitializeTerminate, таким образом, реализация плагина FF не должна делать копию io_object_t переменной с намерением использовать его вне контекста этого вызова.
Если начинаются, ложь, этот параметр проигнорирован. (Можно передать NULL.)
begin
Ненулевой, если начинается доступ к устройству. Нуль, если заканчивается доступ к устройству. API FF вызовет InitializeTerminate (begin=TRUE), когда устройство FF будет сначала выбрано для использования и InitializeTerminate (begin=false), когда больше не необходимо устройство FF.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_INVALIDPARAM
FFERR_NOINTERFACE
FFERR_OUTOFMEMORY
-
Эта функция отправляет команду в устройство.
Объявление
Objective C
HRESULT ( *SendForceFeedbackCommand)( void *self, FFCommandFlag state );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
state
Указывает отправляемую команду. Та команда может быть одним из следующего:
FFSFFC_RESET
Указывает, что воспроизведение любых активных эффектов должно быть, остановился и что все эффекты должны быть удалены из устройства. Как только устройство было сброшено, все эффекты больше не действительны и должны быть воссозданы.
FFSFFC_STOPALL
Указывает, что должно быть остановлено воспроизведение всех эффектов. Отправка команды FFSFFC_STOPALL эквивалентна вызову метода FFEffect_Stop на всех играющих эффектах. Если устройство находится в приостановленном состоянии, драйверу устройства разрешают потерять приостановленное состояние.
FFSFFC_PAUSE
Указывает, что должно быть приостановлено воспроизведение всех эффектов. Когда эффекты приостанавливаются, время «остановки», пока не отправляется команда FFSFFC_CONTINUE. Например, предположите, что запускается эффект продолжительности пяти секунд. После одной секунды приостанавливаются все эффекты. После еще двух секунд продолжаются все эффекты. Эффект должен тогда играть в течение четырех дополнительных секунд. В то время как устройство обратной связи силы приостанавливается, начинание нового эффекта или изменение существующих могут заставить приостановленное состояние быть потерянным.
FFSFFC_CONTINUE
Указывает, что воспроизведение должно быть возобновлено в точке, в которой оно было прервано для тех эффектов, приостановленных предыдущей командой FFSCFFC_PAUSE.
ФФСФФК_СЕТЭКТУЭТОРСОН
Указывает, что должны быть включены приводы обратной связи силы устройства.
ФФСФФК_СЕТЭКТУЭТОРСОФФ
Указывает, что должны быть отключены приводы обратной связи силы устройства. Если успешный, эффекты обратной связи силы «отключены звук». В то время как приводы выключены, Обратите внимание на то, что время продолжает протекать. Например, предположите, что запускается эффект продолжительности пяти секунд. После одной секунды выключены приводы. После еще двух секунд приводы возвращены на. Эффект должен тогда играть в течение двух дополнительных секунд.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_INTERNAL
FFERR_INVALIDPARAM
-
Эта функция устанавливает свойства, определяющие поведение устройства.
Объявление
Objective C
HRESULT ( *SetProperty)( void *self, FFProperty property, void *pValue );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
property
Следующие значения свойств определяются для устройства FF:
FFPROP_AUTOCENTER
Указывает, самоцентрируются ли приводимые в действие оси FF. Это свойство управляет device\xD5s \xD2default, центрируясь spring\xD3.
pValue элемент указывает на UInt32 и может быть одним из следующих значений.
0 - OFF: устройство не должно автоматически центрироваться когда разъединения абонентом устройство. Приложение, применяющее силу обратная связь, должно отключить автоцентрирование перед игрением эффектов.
1 - ON: устройство должно автоматически центрироваться когда разъединения абонентом устройство.
Не все устройства поддерживают автоцентральное свойство.
FFPROP_FFGAIN
Устанавливает усиление для устройства.
pValue элемент указывает на UInt32, содержащий значение усиления, применяющееся ко всем эффектам, создаваемым на устройстве. Значение является целым числом в диапазоне от 0 до 10,000, указывая сумму, которой величины эффекта должны масштабироваться для устройства. Например, значение 10 000 указывает, что все величины эффекта должны быть взяты по номиналу. Значение 9 000 указывает, что все величины эффекта должны быть сокращены до 90% их номинальных величин.
Когда приложение хочет уменьшить масштаб силы всех эффектов обратной связи силы унифицированно, на основе пользовательских настроек, установка значения усиления полезна.
pValue
Адрес расположения, где должно быть считано значение свойства. Эта функция предположит, что данные допустимы, и корректного типа.
Возвращаемое значение
Если метод успешно выполняется, возвращаемое значение является FF_OK или FFERR_UNSUPPORTED. Если метод перестал работать, возвращаемое значение может быть одним из следующих ошибочных значений:
FFERR_INVALIDPARAM
-
Этот функциональные команды устройство для воспроизведения ранее загруженного эффекта.
Объявление
Objective C
HRESULT ( *StartEffect)( void *self, FFEffectDownloadID downloadID, FFEffectStartFlag mode, UInt32 iterations );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
downloadID
Указывает эффект, который будет играться.
mode
Указывает, как эффект состоит в том, чтобы влиять на другие эффекты. Только упомянутый ниже режим может использоваться; все другие режимы резервируются. Например, драйвер никогда не получает флаг FFES_NODOWNLOAD, потому что этим управляет FF API а не драйвер PlugIn. Этот параметр может быть нулем, один, или больше следующих флагов:
FFES_SOLO
Указывает, что все другие эффекты на устройство должны быть остановлены, прежде чем указанный эффект играется. Если этот флаг опущен, эффект смешан с существующими эффектами, уже запустившимися на устройстве.
iterations
Указывает число раз для выполнения эффекта. Если значение является FF_INFINITE, то эффект должен быть повторен, пока явно не остановлено или приостановлено.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_INTERNAL
FFERR_DEVICEPAUSED
FFERR_DEVICEFULL
FFERR_GENERIC
FFERR_INVALIDDOWNLOADID
-
Этот функциональные команды устройство для остановки ранее запущенного эффекта.
Объявление
Objective C
HRESULT ( *StopEffect)( void *self, UInt32 downloadID );
Параметры
self
Указатель на экземпляр реализации FFPlugInDriver.
downloadID
Указывает эффект, который будет остановлен.
Возвращаемое значение
Возвраты FF_OK в случае успеха или ошибка оценивают иначе:
FFERR_INTERNAL
FFERR_GENERIC
FFERR_INVALIDDOWNLOADID
См. Обзор для документации уровня заголовка.
-
Уникальная идентификация для эффекта.
Объявление
Objective C
typedef UInt32 FFEffectDownloadID;
Оператор импорта
Objective C
@import ForceFeedback;
Доступность
Доступный в OS X v10.2 и позже.
-
Информация о возвратах о состоянии устройства обратной связи силы.
Объявление
Objective C
typedef struct ForceFeedbackDeviceState ForceFeedbackDeviceState;
Оператор импорта
Objective C
@import ForceFeedback;
Доступность
Доступный в OS X v10.2 и позже.
-
Используемый для возврата информации о версии модуля.
Объявление
Objective C
typedef struct ForceFeedbackVersion ForceFeedbackVersion;
Оператор импорта
Objective C
@import ForceFeedback;
Доступность
Доступный в OS X v10.2 и позже.
-
Информация о возвратах о состоянии устройства обратной связи силы.
Объявление
Objective C
struct ForceFeedbackDeviceState { UInt32 dwSize; UInt32 dwState; UInt32 dwLoad; };
Поля
dwSize
Указывает размер структуры в байтах. Этот элемент должен быть инициализирован, прежде чем структура используется.
dwState
Указывает различные аспекты состояния устройства. Может указать нуль, один, или больше следующего:
FFGFFS_EMPTY
Указывает, что устройство обратной связи силы лишено любых загруженных эффектов.
FFGFFS_STOPPED
Указывает, что никакие эффекты в настоящее время не играют, и устройство не приостанавливается.
FFGFFS_PAUSED
Указывает, что воспроизведение эффектов было приостановлено предыдущей командой FFSFFC_PAUSE.
ФФГФФС_ЭКТУЭТОРСОН
Указывает, что включены приводы обратной связи силы устройства.
ФФГФФС_ЭКТУЭТОРСОФФ
Указывает, что отключены приводы обратной связи силы устройства.
FFGFFS_POWERON
Указывает, что питание к системе с обратной связью силы в настоящее время доступно. Если устройство не может сообщить о состоянии электропитания, то ни FFGFFS_POWERON, ни ФФГФФС_ПАУЭРОФФ не должны быть возвращены.
ФФГФФС_ПАУЭРОФФ Указывает, что питание к системе с обратной связью силы не в настоящее время доступно. Если устройство не может сообщить о состоянии электропитания, то ни FFGFFS_POWERON, ни ФФГФФС_ПАУЭРОФФ не должны быть возвращены.
FFGFFS_SAFETYSWITCHON
Указывает, что предохранительный выключатель (переключатель мертвеца) в настоящее время включен, означая, что может работать устройство. Если устройство не может сообщить о состоянии предохранительного выключателя, то ни FFGFFS_SAFETYSWITCHON, ни ФФГФФС_СЭФЕТИСВИЧОФФ не должны быть возвращены.
ФФГФФС_СЭФЕТИСВИЧОФФ
Указывает, что предохранительный выключатель (переключатель мертвеца) в настоящее время выключен, означая, что не может работать устройство. Если устройство не может сообщить о состоянии предохранительного выключателя, то ни FFGFFS_SAFETYSWITCHON, ни ФФГФФС_СЭФЕТИСВИЧОФФ не должны быть возвращены.
FFGFFS_USERFFSWITCHON
Указывает, что пользовательский переключатель обратной связи силы в настоящее время включен, означая, что может работать устройство. Если устройство не может сообщить о состоянии пользовательского переключателя обратной связи силы, то ни FFGFFS_USERFFSWITCHON, ни ФФГФФС_ЮЗРФФСВИЧОФФ не должны быть возвращены.
ФФГФФС_ЮЗРФФСВИЧОФФ
Указывает, что пользовательский переключатель обратной связи силы в настоящее время выключен, означая, что не может работать устройство. Если устройство не может сообщить о состоянии пользовательского переключателя обратной связи силы, то ни FFGFFS_USERFFSWITCHON, ни ФФГФФС_ЮЗРФФСВИЧОФФ не должны быть возвращены.
FFGFFS_DEVICELOST
Указывает, что устройство перенесло неожиданный отказ и находится в неопределенном состоянии. Это должно быть сброшено или путем неполучения и переполучения устройства, или путем явной отправки команды FFSFFC_RESET. Например, если пользователь приостанавливает компьютер, заставляя встроенную память на устройстве быть потерянным, устройство может быть потеряно.
dwLoad
Значение, указывающее процент памяти устройства в использовании. Значение нуля указывает, что память устройства абсолютно доступна. Значение 100 указывает, что устройство полно
-
Используемый для возврата информации о версии модуля.
Объявление
Objective C
struct ForceFeedbackVersion { NumVersion apiVersion; NumVersion plugInVersion; };
Поля
apiVersion
Версия сменного API, реализованного этим драйвером
plugInVersion
Определенная поставщиками версия плагина.
См. Обзор для документации уровня заголовка.
-
Объявление
Objective C
enum { kFFPlugInAPIMajorRev = 1, kFFPlugInAPIMinorAndBugRev = 0, kFFPlugInAPIStage = finalStage, kFFPlugInAPINonRelRev = 0 };
Обсуждение
Это отсылает обратную связь PlugIn API Силы (а не Платформа API).