目次 - SDL 3.0 API(機能別) - 力覚フィードバック

力覚フィードバック

概要

SDLハプティックサブシステムはハプティックデバイス(力覚装置)を扱う.

基本的な使い方は次の通りである.

  1. サブシステム(SDL_INIT_HAPTIC)を初期化する
  2. ハプティックデバイスを開く
  3. エフェクトを生成する (SDL_HapticEffect)
  4. エフェクトをSDL_CreateHapticEffect()でアップロードする
  5. エフェクトをSDL_RunHapticEffect()で再生する
  6. (任意) エフェクトをSDL_DestroyHapticEffect()で解放する
  7. ハプティックデバイスをSDL_CloseHaptic()で閉じる

振動させる簡単な例

   SDL_Haptic *haptic = NULL;

   // デバイスを開く
   SDL_HapticID *haptics = SDL_GetHaptics(NULL);
   if (haptics) {
       haptic = SDL_OpenHaptic(haptics[0]);
       SDL_free(haptics);
   }
   if (haptic == NULL)
      return;

   // 単純な振動で初期化する
   if (!SDL_InitHapticRumble(haptic))
      return;

   // 50%の強さで2秒間再生する
   if (!SDL_PlayHapticRumble(haptic, 0.5, 2000))
      return;
   SDL_Delay(2000);

   // 終了する
   SDL_CloseHaptic(haptic);

完全なコード

bool test_haptic(SDL_Joystick *joystick)
{
   SDL_Haptic *haptic;
   SDL_HapticEffect effect;
   SDL_HapticEffectID effect_id;

   // デバイスを開く
   haptic = SDL_OpenHapticFromJoystick(joystick);
   if (haptic == NULL) return false; // ジョイスティックにハプティックがない場合が大半

   // サイン波が可能か調べる
   if ((SDL_GetHapticFeatures(haptic) & SDL_HAPTIC_SINE)==0) {
      SDL_CloseHaptic(haptic); // サインエフェクトがない
      return false;
   }

   // エフェクトを生成する
   SDL_memset(&effect, 0, sizeof(SDL_HapticEffect)); // 安全のためデフォルトを0にする
   effect.type = SDL_HAPTIC_SINE;
   effect.periodic.direction.type = SDL_HAPTIC_POLAR; // 極座標系
   effect.periodic.direction.dir[0] = 18000; // エフェクトは南から来る
   effect.periodic.period = 1000; // 1000ミリ秒
   effect.periodic.magnitude = 20000; // 20000/32767 の強さ
   effect.periodic.length = 5000; // 5秒間
   effect.periodic.attack_length = 1000; // 1秒間で最大に達する
   effect.periodic.fade_length = 1000; // 1秒間で停止する

   // エフェクトをアップロードする
   effect_id = SDL_CreateHapticEffect(haptic, &effect);

   // エフェクトをテストする
   SDL_RunHapticEffect(haptic, effect_id, 1);
   SDL_Delay(5000); // エフェクトが終わるまで待つ

   // エフェクトを破棄する. これはデバイスを閉じても行われる
   SDL_DestroyHapticEffect(haptic, effect_id);

   // デバイスを閉じる
   SDL_CloseHaptic(haptic);

   return true; // 成功
}

SDLハプティックサブシステムはスレッドセーフではないので注意すること.

関数

  1. SDL_CloseHaptic - SDL_OpenHaptic()でオープンしたハプティックデバイスをクローズする
  2. SDL_CreateHapticEffect - ハプティックデバイスに新しいエフェクトを生成する
  3. SDL_DestroyHapticEffect - ハプティックデバイスのエフェクトを再生する
  4. SDL_GetHapticEffectStatus - ハプティックデバイスのエフェクトの再生状態を得る
  5. SDL_GetHapticFeatures - ハプティックデバイスの対応する機能を得る
  6. SDL_GetHapticFromID - オープンされている場合, インスタンスIDからハプティックデバイスオブジェクトを得る
  7. SDL_GetHapticID - オープンされたハプティックデバイスからインスタンスIDを得る
  8. SDL_GetHapticName - オープンされたハプティックデバイスの実装に依存する名前を得る
  9. SDL_GetHapticNameForID - インスタンスIDからハプティックデバイスの実装に依存する名前を得る
  10. SDL_GetHaptics - 接続されているハプティックデバイスの一覧を得る
  11. SDL_GetMaxHapticEffects - ハプティックデバイスに格納できるエフェクトの数を得る
  12. SDL_GetMaxHapticEffectsPlaying - ハプティックデバイスが同時に再生できるエフェクトの数を得る
  13. SDL_GetNumHapticAxes - ハプティックデバイスの方向の数を得る
  14. SDL_HapticEffectSupported - ハプティックデバイスがエフェクトに対応しているかチェックする
  15. SDL_HapticRumbleSupported - ハプティックデバイスが単純な振動に対応しているかチェックする
  16. SDL_InitHapticRumble - ジョイスティックにハプティックの機能があるかチェックする
  17. SDL_IsJoystickHaptic - ジョイスティックにハプティックの機能があるかチェックする
  18. SDL_IsMouseHaptic - マウスにハプティックの機能があるかチェックする
  19. SDL_OpenHaptic - ハプティックデバイスを使用するためにオープンする
  20. SDL_OpenHapticFromJoystick - ジョイスティックからハプティックデバイスをオープンする
  21. SDL_OpenHapticFromMouse - 使用中のマウスからハプティックデバイスをオープンする
  22. SDL_PauseHaptic - ハプティックデバイスを一時停止する
  23. SDL_PlayHapticRumble - ハプティックデバイスの単純な振動を開始する
  24. SDL_ResumeHaptic - 一時停止中のハプティックデバイスを再開する
  25. SDL_RunHapticEffect - ハプティックデバイスのエフェクトを再生する
  26. SDL_SetHapticAutocenter - ハプティックデバイスの自動センタリングを設定する
  27. SDL_SetHapticGain - 指定のハプティックデバイスのゲインを設定する
  28. SDL_StopHapticEffect - ハプティックデバイスの再生中のエフェクトを停止する
  29. SDL_StopHapticEffects - ハプティックデバイスの再生中のエフェクトを全て停止する
  30. SDL_StopHapticRumble - ハプティックデバイスの単純な振動を停止する
  31. SDL_UpdateHapticEffect - ハプティックデバイスのエフェクトのパラメータを変更する

型

  1. SDL_Haptic - SDLハプティックデバイスオブジェクトの型
  2. SDL_HapticDirectionType - ハプティックの方向で使用する座標系の型
  3. SDL_HapticEffectID - ハプティックエフェクトIDの型
  4. SDL_HapticEffectType - ハプティックエフェクトの種類の型
  5. SDL_HapticID - システムに接続されたハプティックデバイスのユニークなIDの型

構造体

  1. SDL_HapticCondition - 条件エフェクトのテンプレートの構造体
  2. SDL_HapticConstant - 一定エフェクトのテンプレートの構造体
  3. SDL_HapticCustom - カスタムエフェクトのテンプレートの構造体
  4. SDL_HapticDirection - エフェクトの方向の構造体
  5. SDL_HapticEffect - ハプティックエフェクトの全テンプレートの共用体
  6. SDL_HapticLeftRight - 左右エフェクトのテンプレートの構造体
  7. SDL_HapticPeriodic - 周期エフェクトのテンプレートの構造体
  8. SDL_HapticRamp - 増減エフェクトのテンプレートの構造体

マクロ

  1. SDL_HAPTIC_AUTOCENTER - ハプティックデバイスが自動センタリングに対応していることを表すマクロ
  2. SDL_HAPTIC_CARTESIAN - ハプティックデバイスのエフェクトの方向で直交座標を使用することを表すマクロ
  3. SDL_HAPTIC_CONSTANT - ハプティックデバイスの一定エフェクトを表すマクロ
  4. SDL_HAPTIC_CUSTOM - ハプティックデバイスのカスタムエフェクトを表すマクロ
  5. SDL_HAPTIC_DAMPER - ハプティックデバイスのダンパーエフェクト(速度を使用)を表すマクロ
  6. SDL_HAPTIC_FRICTION - ハプティックデバイスの摩擦エフェクト(運動を使用)を表すマクロ
  7. SDL_HAPTIC_GAIN - ハプティックデバイス全体のゲインを設定できることを表すマクロ
  8. SDL_HAPTIC_INERTIA - ハプティックデバイスの慣性エフェクト(加速度を使用)を表すマクロ
  9. SDL_HAPTIC_INFINITY - ハプティックデバイスの無限の再生回数のマクロ
  10. SDL_HAPTIC_LEFTRIGHT - ハプティックデバイスの左右エフェクトを表すマクロ
  11. SDL_HAPTIC_PAUSE - ハプティックデバイスが一時停止可能であることを表すマクロ
  12. SDL_HAPTIC_POLAR - ハプティックデバイスのエフェクトの方向で極座標を使用することを表すマクロ
  13. SDL_HAPTIC_RAMP - ハプティックデバイスの増減エフェクトを表すマクロ
  14. SDL_HAPTIC_RESERVED1 - ハプティックデバイスの将来のための予約
  15. SDL_HAPTIC_RESERVED2 - ハプティックデバイスの将来のための予約
  16. SDL_HAPTIC_RESERVED3 - ハプティックデバイスの将来のための予約
  17. SDL_HAPTIC_SAWTOOTHDOWN - ハプティックデバイスの下降ノコギリ波エフェクトを表すマクロ
  18. SDL_HAPTIC_SAWTOOTHUP - ハプティックデバイスの上昇ノコギリ波エフェクトを表すマクロ
  19. SDL_HAPTIC_SINE - ハプティックデバイスのサイン波エフェクトを表すマクロ
  20. SDL_HAPTIC_SPHERICAL - ハプティックデバイスのエフェクトの方向で球面座標を使用することを表すマクロ
  21. SDL_HAPTIC_SPRING - ハプティックデバイスのバネエフェクト(位置を使用)を表すマクロ
  22. SDL_HAPTIC_SQUARE - ハプティックデバイスの矩形波エフェクトを表すマクロ
  23. SDL_HAPTIC_STATUS - ハプティックデバイスの状態を得られることを表すマクロ
  24. SDL_HAPTIC_STEERING_AXIS - ハンドル型コントローラのエフェクトで使用する座標系のマクロ
  25. SDL_HAPTIC_TRIANGLE - ハプティックデバイスの三角波エフェクトを表すマクロ

SDL Wikiへのリンク

SDL3/CategoryHaptic - SDL Wiki