본문으로 건너뛰기

Class BhapticsLibrary

BhapticsLibrary 클래스는 bHaptics 햅틱 디바이스를 사용하기 위한 함수를 포함하고 있습니다.

레퍼런스​

  • 경로: Assets\Bhaptics\SDK2\Scripts\Core\Plugins\BhapticsLibrary.cs

정적 함수 — 이벤트 기반 햅틱 재생​

Designer/Portal에서 만든 특정 햅틱 이벤트에 바인딩된 햅틱 패턴을 재생합니다. 이 함수들의 사용을 강력히 권장합니다.

Play​

public static int Play(string eventId, int startMillis = 0, float intensity = 1f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f, int requestId = -1);

햅틱의 강도, Duration, 방향을 조절하면서 햅틱 이벤트를 재생합니다.

Parameters​

  • string eventId: 재생할 햅틱 이벤트의 이름입니다.
  • int startMillis: 이벤트 재생을 시작할 위치(ms)입니다. 앞쪽 startMillis ms는 건너뜁니다(재생 전 지연이 아니라 시작 오프셋입니다). 기본값은 0입니다. Windows/macOS/Android에서만 지원됩니다.
  • float intensity: 햅틱 Intensity에 이 값이 곱해집니다.
  • float duration: 햅틱 Duration에 이 값이 곱해집니다.
  • float angleX: 전역 Vector3.up을 중심으로 햅틱을 반시계 방향으로 회전합니다. 유효 범위: [0.0f - 360.0f]
  • float offsetY: 햅틱을 위 또는 아래로 이동합니다. 유효 범위: [-0.5f - 0.5f]
  • int requestId: 무작위 ID 대신 사용할 요청 ID를 지정합니다. 유효한 값은 0 이상입니다. 생략하거나 음수를 지정하면 무작위 ID가 할당됩니다.
    요청 ID 재사용

    일반적으로 다른 햅틱이 재생 중일 때 햅틱을 재생하면, 새 재생이 현재 재생 위에 겹쳐서 실행됩니다. 하지만 현재 햅틱과 같은 eventId와 requestId로 재생하면, 현재 재생이 중지되고 새 재생이 시작됩니다. 이를 통해 짧은 간격으로 반복 재생할 때 각 햅틱이 더 뚜렷하게 느껴지고 햅틱이 겹겹이 쌓이지 않습니다.

    eventId와 requestId에 따른 재생 타임라인

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

Example​

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
private void OnShoot()
{
// Assume the event name is "shootpistol"

// BASIC USAGE
BhapticsLibrary.Play(BhapticsEvent.SHOOTPISTOL);
// or
BhapticsLibrary.Play("shootpistol");

// ADVANCED USAGE
BhapticsLibrary.Play(
BhapticsEvent.SHOOTPISTOL, // Haptic name
0, // Playback start position (millisecond)
1.0f, // Haptic intensity
1.0f, // Haptic duration
20.0f, // Rotate haptic around global Vector3.up (0f - 360f)
0.3f // Move haptic up or down (-0.5f - 0.5f)
);

// CUSTOM REQUEST ID
BhapticsLibrary.Play(BhapticsEvent.SHOOTPISTOL, requestId: 1001);
}
}

PlayParam​

public static int PlayParam(string eventId, float intensity = 1.0f, float duration = 1.0f, float angleX = 0.0f, float offsetY = 0.0f, int requestId = -1);

햅틱의 강도, Duration, 방향을 조절하면서 햅틱 이벤트를 재생합니다.

Parameters​

  • string eventId: 재생할 햅틱 이벤트의 이름입니다.
  • float intensity: 햅틱 Intensity에 이 값이 곱해집니다.
  • float duration: 햅틱 Duration에 이 값이 곱해집니다.
  • float angleX: 전역 Vector3.up을 중심으로 햅틱을 반시계 방향으로 회전합니다. 유효 범위: [0.0f - 360.0f]
  • float offsetY: 햅틱을 위 또는 아래로 이동합니다. 유효 범위: [-0.5f - 0.5f]
  • int requestId: 무작위 ID 대신 사용할 요청 ID를 지정합니다. 유효한 값은 0 이상입니다. 생략하거나 음수를 지정하면 무작위 ID가 할당됩니다.
    요청 ID 재사용

    일반적으로 다른 햅틱이 재생 중일 때 햅틱을 재생하면, 새 재생이 현재 재생 위에 겹쳐서 실행됩니다. 하지만 현재 햅틱과 같은 eventId와 requestId로 재생하면, 현재 재생이 중지되고 새 재생이 시작됩니다. 이를 통해 짧은 간격으로 반복 재생할 때 각 햅틱이 더 뚜렷하게 느껴지고 햅틱이 겹겹이 쌓이지 않습니다.

    eventId와 requestId에 따른 재생 타임라인

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

Example​

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
private void OnShoot()
{
BhapticsLibrary.PlayParam(
BhapticsEvent.SHOOTPISTOL, // Haptic name
1.0f, // Haptic intensity
1.0f, // Haptic duration
20.0f, // Rotate haptic around global Vector3.up (0f - 360f)
0.3f // Move haptic up or down (-0.5f - 0.5f)
);
}
}

PlayAngle​

public static int PlayAngle(string eventId, float angleX, float offsetY);

햅틱의 방향을 조절하면서 햅틱 이벤트를 재생합니다. intensity와 duration을 1.0f로 고정한 PlayParam의 편의 래퍼입니다.

Parameters​

  • string eventId: 재생할 햅틱 이벤트의 이름입니다.
  • float angleX: 전역 Vector3.up을 중심으로 햅틱을 반시계 방향으로 회전합니다. 유효 범위: [0.0f - 360.0f]
  • float offsetY: 햅틱을 위 또는 아래로 이동합니다. 유효 범위: [-0.5f - 0.5f]

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

PlayLoop​

public static int PlayLoop(
string eventId,
float intensity = 1.0f,
float duration = 1.0f,
float angleX = 0.0f,
float offsetY = 0.0f,
int interval = 200,
int maxCount = 999999
);

햅틱을 반복해서 재생합니다. 또한 PlayHapticWithOption 함수처럼 햅틱의 강도, Duration, 방향을 조절할 수 있습니다.

Parameters​

  • string eventId: 재생할 햅틱 이벤트의 이름입니다.
  • float intensity: 햅틱 Intensity에 이 값이 곱해집니다.
  • float duration: 햅틱 Duration에 이 값이 곱해집니다.
  • float angleX: 전역 Vector3.up을 중심으로 햅틱을 반시계 방향으로 회전합니다. 유효 범위: [0.0f - 360.0f]
  • float offsetY: 햅틱을 위 또는 아래로 이동합니다. 유효 범위: [-0.5f - 0.5f]
  • int interval: 반복 사이의 시간 간격(밀리초)입니다.
  • int maxCount: 반복 횟수입니다.

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

Example​

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
private void OnShoot()
{
BhapticsLibrary.PlayLoop(
BhapticsEvent.SHOOTPISTOL, // Haptic name
1.0f, // Haptic intensity
1.0f, // Haptic duration
20.0f, // Rotate haptic around global Vector3.up (0f - 360f)
0.3f, // Move haptic up or down (-0.5f - 0.5f)
200, // Loop interval time (millisecond)
999999 // Loop count
);
}
}

PlayLoopOnly​

public static int PlayLoopOnly(string eventId, int interval = 200, int maxCount = 999999);

햅틱을 반복해서 재생합니다. intensity와 duration을 1.0f로 고정하고 방향 조절을 하지 않는 PlayLoop의 편의 래퍼입니다.

Parameters​

  • string eventId: 재생할 햅틱 이벤트의 이름입니다.
  • int interval: 반복 사이의 시간 간격(밀리초)입니다.
  • int maxCount: 반복 횟수입니다.

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

정적 함수 — 햅틱 직접 재생​

새 이벤트를 만들지 않고 햅틱을 재생하고 싶다면 이 함수들을 사용하세요.

PlayMotors​

public static int PlayMotors(int position, int[] motors, int durationMillis);

특정 햅틱 액추에이터에서 햅틱 피드백을 재생합니다. 이벤트를 만들지 않고도 이 함수를 사용할 수 있습니다.

Parameters​

  • int position: 햅틱 디바이스의 종류입니다. 자세한 내용은 여기를 참고하세요.
    값디바이스동일한 값...모터 개수
    0TactSuit ProPositionType.Vest32
    1TactSleeve(왼쪽)PositionType.ForearmL3
    2TactSleeve(오른쪽)PositionType.ForearmR3
    3TactVisorPositionType.Head4
    4Tactosy for Hands(왼쪽)PositionType.HandL3
    5Tactosy for Hands(오른쪽)PositionType.HandR3
    6Tactosy for Feet(왼쪽)PositionType.FootL3
    7Tactosy for Feet(오른쪽)PositionType.FootR3
    8TactGlove(왼쪽)PositionType.GloveL8
    9TactGlove(오른쪽)PositionType.GloveR8
  • int[] motors: 디바이스의 모터 개수만큼 배열의 길이를 지정합니다. 배열의 값은 모터의 Intensity를 의미합니다. 배열 내 각 값의 유효 범위: [0 - 100]
  • int durationMillis: 햅틱의 Duration(밀리초 단위)입니다. 100 이상을 권장합니다.

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

Example​

using Bhaptics.SDK2;

public class Example : MonoBehaviour
{
private void OnCall()
{
// TactSuit Pro has 32 motors, so length of array should be 32 too.
int[] MotorValueArray = new int[] {
50, 40, 30, 20, 10, 50, 40, 30,
50, 40, 30, 20, 10, 50, 40, 30,
50, 40, 30, 20, 10, 50, 40, 30,
50, 40, 30, 20, 10, 50, 40, 30,
};

BhapticsLibrary.PlayMotors(
(int)PositionType.Vest, // Device type
MotorValueArray, // Haptic intensities
500 // Haptic duration (millisecond)
);
}
}

PlayWaveform​

public static int PlayWaveform(
PositionType positionType,
int[] motorValues,
GlovePlayTime[] playTimeValues,
GloveShapeValue[] shapeValues,
int frequency = 80,
int repeatCount = 0
);

TactGlove 전용. TactGlove에서 햅틱을 재생합니다. PlayMotors를 사용할 때와 달리 햅틱 Duration과 진동 Intensity 변화를 세밀하게 조절할 수 있습니다. 이를 통해 햅틱 피드백을 더욱 섬세하게 표현할 수 있습니다.

각 배열(motorValues, playTimeValues, shapeValues)은 TactGlove DK2의 경우 여섯 개, TactGlove DK3의 경우 여덟 개의 요소를 가져야 하며, 세 배열의 길이는 모두 같아야 합니다. 그 외의 길이는 -1을 반환합니다.

Parameters​

  • PositionType positionType: 햅틱 디바이스의 종류입니다.

    값디바이스동일한 값…
    PositionType.GloveLTactGlove(왼쪽)8
    PositionType.GloveRTactGlove(오른쪽)9
  • int[] motorValues: 각 모터의 Intensity를 나타내는 배열입니다. 배열의 길이는 TactGlove의 모터 개수와 일치해야 합니다. 즉 여섯 개(TactGlove DK2) 또는 여덟 개(TactGlove DK3)입니다. 배열 인덱스 6과 7의 손바닥 모터(아래 표 참조)는 DK3에만 존재합니다. 배열 내 각 값의 유효 범위: [0 - 100]

    배열 인덱스모터 위치
    0엄지 끝
    1검지 끝
    2중지 끝
    3약지 끝
    4새끼손가락 끝
    5손목
    6손바닥 (엄지 쪽)
    7손바닥 (새끼손가락 쪽)
  • GlovePlayTime[] playTimeValues: motorValues와 같은 길이(DK2는 여섯 개, DK3는 여덟 개)의 배열로, 각 요소는 작동 시간 간격을 나타내며 시간은 GlovePlayTime 열거형으로 정의합니다.

    값Duration동일한 값…
    GlovePlayTime.None없음0
    GlovePlayTime.FiveMS5ms1
    GlovePlayTime.TenMS10ms2
    GlovePlayTime.TwentyMS20ms4
    GlovePlayTime.ThirtyMS30ms6
    GlovePlayTime.FortyMS40ms8
  • GloveShapeValue[] shapeValues: motorValues와 같은 길이(DK2는 여섯 개, DK3는 여덟 개)의 배열로, 각 요소는 시간에 따른 햅틱 Intensity 변화의 형태를 나타내며 GloveShapeValue 열거형으로 지정합니다.

    값웨이브폼동일한 값…
    GloveShapeValue.ConstantDuration 동안 일정한 Intensity0
    GloveShapeValue.Decreasing지정한 Intensity로 시작하여 절반까지 감소1
    GloveShapeValue.Increasing지정한 Intensity의 절반으로 시작하여 지정한 Intensity까지 증가2

    [TactGlove DK3] DK3 글러브에서는 손목 액추에이터(배열 인덱스 5)가 voice-coil motor(VCM)이므로 shapeValues를 반영하지 않습니다. 나머지 7개 모터는 DK2 글러브와 동일하게 웨이브폼 형태가 적용됩니다.

  • int frequency: [TactGlove DK3 전용] DK3 글러브 자체 액추에이터의 진동 주파수(Hz)입니다. 기본값은 80입니다. DK3 글러브 자체에만 영향을 주며, 연결된 다른 디바이스의 작동 주파수는 변경하지 않습니다. DK2 글러브나 범용(non-Windows/macOS) 경로에는 영향을 주지 않습니다. Windows/macOS에서만 지원됩니다.

  • int repeatCount: 웨이브폼을 반복할 횟수이며 1부터 셉니다. 0은 한 번만 재생합니다. Windows/macOS에서만 지원됩니다.

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

Example​

using Bhaptics.SDK2;

public class TestHaptic : MonoBehaviour
{
public void OnCall()
{
int[] motorValues = new int[8] { 50, 80, 100, 0, 0, 0, 0, 0 };

GlovePlayTime[] playTimeValues = new GlovePlayTime[8] {
GlovePlayTime.FiveMS, GlovePlayTime.TwentyMS,
GlovePlayTime.ThirtyMS, GlovePlayTime.None,
GlovePlayTime.None, GlovePlayTime.None,
GlovePlayTime.None, GlovePlayTime.None
};

GloveShapeValue[] shapeValues = new GloveShapeValue[8] {
GloveShapeValue.Constant, GloveShapeValue.Decreasing,
GloveShapeValue.Increasing, GloveShapeValue.Constant,
GloveShapeValue.Constant, GloveShapeValue.Constant,
GloveShapeValue.Constant, GloveShapeValue.Constant
};

BhapticsLibrary.PlayWaveform(
PositionType.GloveL, // Device Type
motorValues, // Intensities
playTimeValues, // Intervals
shapeValues // Intensity changing forms
);
}
}

PlayPath​

public static int PlayPath(
int position,
float[] xValues,
float[] yValues,
int[] intensityValues,
int duration
);

특정 좌표 주변에서 햅틱을 재생합니다. 각 햅틱 액추에이터별로 햅틱 Intensity를 개별 지정하는 PlayMotors 함수와 달리, 이 함수는 특정 좌표에 대한 햅틱 Intensity를 지정합니다.

햅틱 위치를 지정할 때 PlayMotors는 이산적인 제어를 제공하는 반면, PlayPath는 더 연속적입니다. PlayMotors는 개별 액추에이터에 Intensity를 할당하지만, PlayPath는 특정 좌표(X축과 Y축 모두 0과 1 사이)에 Intensity를 지정할 수 있으며, 그에 따라 근처의 액추에이터가 진동합니다.

여러 좌표를 여러 Intensity와 함께 지정할 수 있습니다. 배열 내 좌표 주변의 모든 액추에이터는 순차적으로 작동하는 것이 아니라 동시에(같은 시간에) 작동한다는 점에 유의하세요. 또한 모든 배열의 크기는 동일해야 합니다.

값을 점진적으로 변경하면서 이 함수를 계속 호출하면 햅틱 포인트가 이동하는 효과를 낼 수 있습니다.

[TactGlove DK3] PlayPath는 DK3 글러브의 손목 voice-coil motor(VCM)를 구동하지 않습니다.

Frame 82.png

Parameters​

  • int position: 햅틱 디바이스의 종류입니다.
    값디바이스동일한 값...
    0TactSuit ProPositionType.Vest
    1TactSleeve(왼쪽)PositionType.ForearmL
    2TactSleeve(오른쪽)PositionType.ForearmR
    3TactVisorPositionType.Head
    4Tactosy for Hands(왼쪽)PositionType.HandL
    5Tactosy for Hands(오른쪽)PositionType.HandR
    6Tactosy for Feet(왼쪽)PositionType.FootL
    7Tactosy for Feet(오른쪽)PositionType.FootR
    8TactGlove(왼쪽)PositionType.GloveL
    9TactGlove(오른쪽)PositionType.GloveR
  • float[] xValues: X 좌표를 지정합니다. 배열 내 각 값의 유효 범위: [0.0f - 1.0f]
  • float[] yValues: Y 좌표를 지정합니다. 배열 내 각 값의 유효 범위: [0.0f - 1.0f]
  • int[] intensityValues: 좌표의 개수만큼 배열의 길이를 지정합니다. 배열의 값은 좌표의 Intensity를 의미합니다. 배열 내 각 값의 유효 범위: [0 - 100]
  • int duration: 햅틱의 Duration(밀리초 단위)입니다. 100 이상을 권장합니다.

Returns​

요청 ID입니다. 요청 ID를 사용하여 햅틱을 중지할 수 있습니다. 실패 시 -1을 반환합니다.

다만 Hub에 연결된 경우, Hub는 반환 값을 제공하지 않으므로 실패한 호출이 -1을 반환하지 않습니다.

Example​

using Bhaptics.SDK2;

/* Assumption:
- For TactSuit Pro
- Coordinate with Intensity
- (X: 0.1, Y: 0.2) Intensity 40
- (X: 0.3, Y: 0.4) Intensity 80
- (X: 0.5, Y: 0.6) Intensity 10
- Duration 500ms(=0.5 second)
*/
public class TestHaptic : MonoBehaviour
{
public void OnCall()
{
BhapticsLibrary.PlayPath(
(int)PositionType.Vest, // Device type
new float[] { 0.1f, 0.3f, 0.5f }, // X Coordinates
new float[] { 0.2f, 0.4f, 0.6f }, // Y Coordinates
new int[] { 40, 80, 10 }, // Intensities
500 // Duration
);
}
}

정적 함수 — 기타​

using Bhaptics.SDK2;

public class TestHaptic : MonoBehaviour
{
public void OnCall()
{
int requestID = BhapticsLibrary.Play("TestHaptic");

if (BhapticsLibrary.IsPlayingByEventId("TestHaptic"))
{
BhapticsLibrary.StopByEventId("TestHaptic");
}

if (BhapticsLibrary.IsPlayingByRequestId(requestID))
{
BhapticsLibrary.StopInt(requestID);
}

if (BhapticsLibrary.IsPlaying())
{
BhapticsLibrary.StopAll();
}
}
}

StopByEventId​

public static bool StopByEventId(string eventId)

이벤트 ID로 햅틱 이벤트를 중지합니다. 중지 성공 여부를 반환합니다.

StopInt​

public static bool StopInt(int requestId)

햅틱을 실행하는 함수의 반환 값인 요청 ID를 사용하여 햅틱 이벤트를 중지합니다. 중지 성공 여부를 반환합니다.

StopAll​

public static bool StopAll()

현재 재생 중인 모든 햅틱을 중지합니다. 중지 성공 여부를 반환합니다.

IsPlaying​

public static bool IsPlaying()

현재 재생 중인 햅틱이 있는지 확인합니다.

IsPlayingByEventId​

public static bool IsPlayingByEventId(string eventId)

이 이벤트 ID에 해당하는 햅틱 이벤트가 현재 재생 중인지 확인합니다.

IsPlayingByRequestId​

public static bool IsPlayingByRequestId(int requestId)

이 요청 ID에 해당하는 햅틱 이벤트가 현재 재생 중인지 확인합니다.

PauseByEventId​

public static void PauseByEventId(string eventId)

재생 중인 햅틱 이벤트를 일시 정지합니다. 특정 햅틱 이벤트를 일시 정지하려면 PauseByEventId(string eventId)를 사용하세요. 일시 정지된 이벤트는 이후 ResumeByEventId(string eventId)를 사용하여 재개할 수 있습니다.

ResumeByEventId​

public static void ResumeByEventId(string eventId)

일시 정지된 햅틱 이벤트를 재개합니다. 일시 정지된 위치부터 재생을 재개하려면 ResumeByEventId(string eventId)를 사용하세요.