Как реализовать эффекты огибающей с кусочно-линейной функцией

Эффекты кусочно-линейной огибающей (PWLE) представляют собой последовательности точек, определяющих частоту вибрации и ускорение с течением времени. PWLE обеспечивают более насыщенный и динамичный виброотклик.

В Android 16 и более поздних версиях есть два API для разработчиков приложений, которые помогают создавать эффекты PWLE:

• Базовый API PWLE – простой, но с ограничениями. Подходит для быстрого начала работы. Она доступна на сайте BasicEnvelopeBuilder.
• Расширенный API PWLE. Больше контроля и гибкости. Требуются знания в области тактильных ощущений и оборудования. Доступно на сайте WaveformEnvelopeBuilder.

Чтобы поддерживать эти API, на устройствах должны быть реализованы следующие API HAL:

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

Basic PWLE API

Чтобы быстро создать эффект PWLE, не погружаясь в особенности оборудования или восприятия человека, разработчики могут использовать базовый API PWLE, определенный с помощью следующих параметров:

• Значение Intensity в диапазоне [0, 1] представляет воспринимаемую силу вибрации. Например, значение 0,5 воспринимается как половина максимальной интенсивности, которую может обеспечить устройство.
• Значение резкости в диапазоне [0, 1] определяет четкость вибрации. Чем ниже значение, тем мягче вибрация, а чем выше – тем она резче.
• Продолжительность – время, за которое происходит переход от предыдущей точки PWLE (то есть пары интенсивности и резкости) к новой, в миллисекундах.

Вот пример формы сигнала, которая увеличивает интенсивность от низкого тона до высокочастотной вибрации максимальной силы в течение 500 мс, а затем снижает ее до 0 (выкл.) в течение 100 мс:

VibrationEffect effect = new VibrationEffect.BasicEnvelopeBuilder()
          .setInitialSharpness(0.0f)
          .addControlPoint(1.0f, 1.0f, 500)
          .addControlPoint(0.0f, 1.0f, 100)
          .build();

Ограничения

Чтобы тактильные ощущения были плавными и непрерывными, эффекты PWLE должны начинаться и заканчиваться с интенсивностью 0.0. API обеспечивает это, устанавливая начальную интенсивность на уровне 0 и вызывая исключение, если конечная интенсивность не равна 0. Это ограничение позволяет избежать нежелательных динамических эффектов в вибрации из-за прерывистости амплитуды, которые могут негативно повлиять на тактильное восприятие пользователя.

Чтобы обеспечить единообразное воспроизведение эффектов PWLE во всей экосистеме Android, платформа требует, чтобы устройства, поддерживающие эту функцию, могли обрабатывать минимальную длительность 20 мс между точками PWLE и не менее 16 точек для эффектов PWLE. Эти требования проверяются с помощью тестов VTS, что помогает обеспечить надежную работу эффектов PWLE на устройствах Android.

Advanced PWLE API

Разработчики с глубокими знаниями в области тактильных ощущений могут определять эффекты PWLE, используя следующие критерии:

• Значение Амплитуда в диапазоне [0, 1] представляет собой достижимую силу на заданной частоте, определяемую FOAM устройства. Например, значение 0,5 означает, что ускорение будет в два раза меньше максимального, которое можно достичь при заданной частоте.
• Частота указывается непосредственно в Гц.
• Продолжительность – это время перехода от последней точки PWLE к новой точке в миллисекундах.

Вот пример временной диаграммы сигнала, который за 100 мс увеличивает амплитуду вибрации от нуля до максимума на частоте 120 Гц, удерживает это состояние в течение 200 мс, а затем за 100 мс снижает амплитуду до нуля:

VibrationEffect effect = new VibrationEffect.WaveformEnvelopeBuilder()
          .addControlPoint(1.0f, 120f, 100)
          .addControlPoint(1.0f, 120f, 200)
          .addControlPoint(0.0f, 120f, 100)
          .build();

Ограничения

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

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

Сопоставление частоты с выходным ускорением (FOAM)

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

Как работает сопоставление

Устройства, поддерживающие эффекты PWLE, должны предоставлять частоту для вывода карты ускорения (FOAM). FOAM – это структура данных, создаваемая HAL, которая сопоставляет частоту вибрации (в герцах) с максимальным ускорением на выходе привода (в G peak) на этой частоте. Эта карта необходима, чтобы понять, как меняется вибрация в поддерживаемом диапазоне частот, и определить базовый API PWLE.

На графике ниже показан пример FOAM для типичного резонансного привода, где входное напряжение ограничено вблизи резонансной частоты для защиты двигателя:

Рисунок 1. Пример FOAM для типичного резонансного привода.

FOAM выполняет три основные функции:

• Определение полного диапазона частот. FOAM определяет полный диапазон частот устройства, указывая минимальную и максимальную поддерживаемые частоты вибрации.
• Определение значений интенсивности и четкости. Базовый API PWLE работает с человеческим восприятием интенсивности и четкости, которые затем сопоставляются с параметрами частоты и амплитуды оборудования с помощью значений ускорения вывода в FOAM. Это сопоставление позволяет воспроизводить тактильные эффекты в соответствии с возможностями оборудования. Диапазон резкости определяется минимальным порогом восприятия и соответствует частотам, на которых устройство может создавать тактильные эффекты, ощущаемые пользователями. Фреймворк сопоставляет значения интенсивности с амплитудой на основе целевого выходного ускорения на выбранной частоте. Это помогает обеспечить выбранный уровень интенсивности, не выходя за пределы возможностей устройства.
• Доступ к возможностям оборудования. FOAM предоставляется разработчикам в VibratorFrequencyProfile, предоставляя полную частоту для вывода набора данных об ускорении, в котором подробно описаны некоторые возможности тактильной обратной связи устройства. Эти данные позволяют разработчикам, использующим расширенный API PWLE, создавать собственные эффекты вибрации, выходящие за рамки базовой интенсивности и четкости, заданных фреймворком.

FOAM и базовый PWLE API

FOAM играет важную роль в формировании вибрационных эффектов. Оно используется для расчета диапазона резкости для базового API огибающей, чтобы вибрации были ощутимы для пользователя. Этот диапазон соответствует частотам, при которых выходное ускорение впервые достигает 10 дБ выше порога восприятия человеком (то есть минимального воспринимаемого уровня), и до тех пор, пока выходное ускорение не опустится ниже этого порога. Этот диапазон должен включать резонансную частоту привода.

Кроме того, на основе данных FOAM фреймворк сопоставляет значения интенсивности и резкости, используемые в базовом API PWLE, с соответствующими значениями амплитуды и частоты. Это сопоставление помогает создавать ощутимую тактильную обратную связь на разных устройствах.

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

FOAM и расширенный PWLE API

Разработчики получают доступ к FOAM через VibratorFrequencyProfile со следующей информацией:

• Диапазон частот. Разработчики могут получить минимальную и максимальную поддерживаемые частоты устройства в герцах, используя getMinFrequencyHz и getMaxFrequencyHz соответственно.
• Максимальное ускорение на выходе. Максимальное ускорение на выходе, которого может достичь устройство (в G), доступно через getMaxOutputAccelerationGs.
• Сопоставление частоты и выходного ускорения. getFrequenciesOutputAcceleration предоставляет сопоставление частоты и выходного ускорения, реализованное в HAL.

Разработчики могут использовать эту информацию при создании эффектов огибающей с помощью расширенного PWLE API. Например, если вы указываете выходное ускорение (в G), его нужно нормализовать до значения в диапазоне [0.0, 1.0] относительно максимального выходного ускорения устройства.

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

Порог распознавания жестов

Порог восприятия человеком – это минимальное ускорение вибрации, которое человек может надежно обнаружить. Уровень вибрации зависит от ее частоты.

На графике ниже показан порог обнаружения тактильного восприятия человека¹ в зависимости от временной частоты:

Рисунок 2. Порог обнаружения тактильного восприятия человека.

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

Воспринимаемая интенсивность вибрации в зависимости от амплитуды ускорения вибрации

Восприятие интенсивности вибрации человеком (показатель восприятия) не растет линейно с увеличением амплитуды вибрации (физический параметр). API PWLE предполагает, что при изменении силы вибрации дизайнер или разработчик ожидает, что воспринимаемая интенсивность будет следовать PWLE. Воспринимаемая интенсивность характеризуется уровнем ощущения (SL), который определяется как дБ выше порога обнаружения на той же частоте. Таким образом, амплитуда ускорения вибрации (в пиковых значениях G) может быть рассчитана следующим образом:

\(Amplitude(G) =10^\frac{Amplitude(db)}{20}\)

Амплитуда в дБ – это сумма уровня звукового давления и порога обнаружения (значение по оси ординат на графике ниже) на определенной частоте.

Таким образом, API PWLE обеспечивает линейное изменение воспринимаемой интенсивности между последовательными парами контрольных точек.

На графике ниже показаны уровни ускорения вибрации² при 10, 20, 30, 40 и 50 дБ SL, а также порог обнаружения тактильного восприятия человека (0 дБ SL) в зависимости от временной частоты.

Рисунок 3. Уровни ускорения вибрации.

Определять кривую зависимости частоты от максимального выходного ускорения

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

Получите кривую максимального напряжения (В)

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

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

Рассчитайте максимальное ускорение (M)

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

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

Для этого преобразования используется следующее основное уравнение:

\(\text{Accel}(w)= (\text{Vsys}\times\text{BLsys}\times\text{Loc_coeff}/\text{Rsys}/\text{MPhone})\times{w^2}/\text{Psys_abs}/{9.81}\)

Место:

Vsys – фактический уровень напряжения, приложенного к тактильному приводу.

BLsys – произведение напряженности магнитного поля (B) и длины проводника (L) вибропривода.

Loc_coeff: коэффициент местоположения для преобразования ускорения на уровне модуля в ускорение на уровне телефона.

Rsys – электрическое сопротивление катушки вибропривода.

MPhone – масса устройства (например, телефона).

w – угловая частота (в радианах в секунду) управляющего сигнала, рассчитываемая по следующей формуле:

\(w = 2 \pi f\)

Psys_abs – амплитудная характеристика системы второго порядка с массой, демпфером и пружиной, рассчитываемая по следующей формуле:

\(\text{Psys_abs} = (\text{Wnsys}^2-w^2)^2+({w}\times(\text{Wnsys}/\text{Qsys}))^2\)

Wnsys – собственная частота колебательной системы.

Qsys – коэффициент качества вибрирующей системы.

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

\(\text{Loc_coeff} = \text{phone_acceleration} / \text{module_acceleration}\)

Например, если ускорение модуля составляет 1 g, а ускорение телефона – 2,5 g, то Loc_coeff = 2,5. Это означает, что значение увеличилось в 2,5 раза.

Фреймворк Android принимает частоту в герцах, поэтому HAL должен преобразовать единицу частоты из радиан в секунду в герцы при генерации данных FOAM.

Как создать кривую FOAM

Объедините кривую максимального напряжения (V) и расчет ускорения (M), чтобы определить кривую FOAM:

• Для каждой частоты (f) в нужном диапазоне найдите соответствующее максимальное напряжение V(f) на кривой максимального напряжения.
• Рассчитайте максимальное ускорение на этой частоте, используя приведенное выше уравнение, подставив V(f) вместо Vsys и соответствующее значение f вместо w. Это дает вам M(V(f), f).
• Это и будет значением FOAM(f).

Как получить доступ к данным FOAM

После создания кривой FOAM HAL представляет ее в виде списка объектов FrequencyAccelerationMapEntry. Каждая запись определяет точку на карте, указывая частоту (в герцах) и соответствующее ей максимальное выходное ускорение (в пиках G).

Чтобы повысить точность линейной интерполяции при определении промежуточных значений ускорения, рекомендуем задать высокое разрешение частоты вблизи частоты с максимальным выходным ускорением. Например, используйте шаг в 1 Гц в диапазоне +/- 10 Гц от этой частоты.

Возможности и ограничения устройств

В Android 16 и более поздних версий есть API HAL, с помощью которых разработчики могут запрашивать информацию о возможностях устройства в отношении эффектов PWLE, чтобы оптимизировать их и обеспечить совместимость с разными устройствами. Эти методы предоставляют информацию об ограничениях устройства, например о минимальной или максимальной длительности примитива PWLE и количестве примитивов, допустимых в композиции PWLE.

API HAL включают:

• CAP_COMPOSE_PWLE_EFFECTS_V2: возвращается методом IVibrator.getCapabilities, если устройство поддерживает эту функцию.
• getFrequencyToOutputAccelerationMap: получение данных FOAM.
• getPwleV2PrimitiveDurationMinMillis: получает минимальную продолжительность, допустимую для любого примитивного объекта PWLE, в миллисекундах.
• getPwleV2PrimitiveDurationMaxMillis – получает максимальную продолжительность любого примитива PWLE в миллисекундах.
• getPwleV2CompositionSizeMax: получает максимальное количество примитивов PWLE, поддерживаемых IVibrator.composePwleV2.

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

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