include/SDL_haptic.h
author Edgar Simo <bobbens@gmail.com>
Tue, 01 Jul 2008 16:19:54 +0000
branchgsoc2008_force_feedback
changeset 2486 24dd8b8669fa
parent 2485 67978eea6d10
child 2487 4c8e25ef2d97
permissions -rw-r--r--
Added SDL_HAPTIC_CUSTOM (not supported on linux).
Exposed SDL_HapticEffectSupported().
     1 /*
     2     SDL - Simple DirectMedia Layer
     3     Copyright (C) 2008 Edgar Simo
     4 
     5     This library is free software; you can redistribute it and/or
     6     modify it under the terms of the GNU Lesser General Public
     7     License as published by the Free Software Foundation; either
     8     version 2.1 of the License, or (at your option) any later version.
     9 
    10     This library is distributed in the hope that it will be useful,
    11     but WITHOUT ANY WARRANTY; without even the implied warranty of
    12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
    13     Lesser General Public License for more details.
    14 
    15     You should have received a copy of the GNU Lesser General Public
    16     License along with this library; if not, write to the Free Software
    17     Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
    18 
    19     Sam Lantinga
    20     slouken@libsdl.org
    21 */
    22 
    23 /**
    24  * \file SDL_haptic.h
    25  *
    26  * Include file for SDL haptic subsystem
    27  */
    28 
    29 #ifndef _SDL_haptic_h
    30 #define _SDL_haptic_h
    31 
    32 #include "SDL_stdinc.h"
    33 #include "SDL_error.h"
    34 
    35 #include "begin_code.h"
    36 /* Set up for C function definitions, even when using C++ */
    37 #ifdef __cplusplus
    38 /* *INDENT-OFF* */
    39 extern "C" {
    40    /* *INDENT-ON* */                                                         
    41 #endif
    42 
    43 /* The haptic structure used to identify an SDL haptic */
    44 struct _SDL_Haptic;                                                     
    45 typedef struct _SDL_Haptic SDL_Haptic;
    46 
    47 
    48 /* Different effects that can be generated */
    49 #define SDL_HAPTIC_CONSTANT   (1<<0)
    50 #define SDL_HAPTIC_PERIODIC   (1<<1)
    51 #define SDL_HAPTIC_RAMP       (1<<2)
    52 #define SDL_HAPTIC_SPRING     (1<<3)
    53 #define SDL_HAPTIC_FRICTION   (1<<4)
    54 #define SDL_HAPTIC_DAMPER     (1<<5)
    55 #define SDL_HAPTIC_INERTIA    (1<<6)
    56 #define SDL_HAPTIC_CUSTOM     (1<<7)
    57 #define SDL_HAPTIC_GAIN       (1<<8)
    58 #define SDL_HAPTIC_AUTOCENTER (1<<9)
    59 
    60 
    61 /*
    62  * Different waveforms a SDL_HAPTIC_PERIODIC effect can have.
    63  */
    64 typedef enum SDL_waveform {
    65    SDL_WAVEFORM_SINE,
    66    SDL_WAVEFORM_SQUARE,
    67    SDL_WAVEFORM_TRIANGLE,
    68    SDL_WAVEFORM_SAWTOOTHUP,
    69    SDL_WAVEFORM_SAWTOOTHDOWN,
    70    SDL_WAVEFORM_CUSTOM
    71 } SDL_waveform;
    72 
    73 
    74 /*
    75  * All values max at 32767 (0x7fff).  Signed values also can be negative.
    76  * Time values unless specified otherwise are in milliseconds.
    77  *
    78  * Common parts:
    79  * 
    80  * Replay:
    81  *    Uint16 length;    Duration of effect.
    82  *    Uint16 delay;     Delay before starting effect.
    83  *
    84  * Trigger:
    85  *    Uint16 button;    Button that triggers effect.
    86  *    Uint16 interval;  How soon before effect can be triggered again.
    87  *
    88  * Envelope:
    89  *    Uint16 attack_length;   Duration of the attack.
    90  *    Uint16 attack_level;    Level at the start of the attack.
    91  *    Uint16 fade_length;     Duration of the fade out.
    92  *    Uint16 fade_level;      Level at the end of the fade.
    93  */
    94 typedef struct SDL_HapticConstant {
    95    /* Header */
    96    Uint16 type; /* SDL_HAPTIC_CONSTANT */
    97    Uint16 direction;
    98 
    99    /* Replay */
   100    Uint16 length;
   101    Uint16 delay;
   102 
   103    /* Trigger */
   104    Uint16 button;
   105    Uint16 interval;
   106 
   107    /* Constant */
   108    Sint16 level; /* Strength of the constant effect. */
   109 
   110    /* Envelope */
   111    Uint16 attack_length;
   112    Uint16 attack_level;
   113    Uint16 fade_length;
   114    Uint16 fade_level;
   115 } SDL_HapticConstant;
   116 typedef struct SDL_HapticPeriodic {
   117    /* Header */
   118    Uint16 type; /* SDL_HAPTIC_PERIODIC */
   119    Uint16 direction;
   120 
   121    /* Replay */
   122    Uint16 length;
   123    Uint16 delay;
   124 
   125    /* Trigger */
   126    Uint16 button;
   127    Uint16 interval;
   128 
   129    /* Periodic */
   130    SDL_waveform waveform; /* Type of effect */
   131    Uint16 period; /* Period of the wave */
   132    Sint16 magnitude; /* Peak value */
   133    Sint16 offset; /* Mean value of the wave */
   134    Uint16 phase; /* Horizontal shift */
   135 
   136    /* Envelope */
   137    Uint16 attack_length;
   138    Uint16 attack_level;
   139    Uint16 fade_length;
   140    Uint16 fade_level;
   141 } SDL_HapticPeriodic;
   142 typedef struct SDL_HapticCondition {
   143    /* Header */
   144    Uint16 type; /* SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   145    Uint16 direction;
   146 
   147    /* Replay */
   148    Uint16 length;
   149    Uint16 delay;
   150 
   151    /* Trigger */
   152    Uint16 button;
   153    Uint16 interval;
   154 
   155    /* Condition */
   156    Uint16 right_sat; /* Level when joystick is to the right. */
   157    Uint16 left_sat; /* Level when joystick is to the left */
   158    Sint16 right_coeff; /* How fast to increase the force towards the right */
   159    Sint16 left_coeff; /* How fast to increase the force towards the left */
   160    Uint16 deadband; /* Size of the dead zone */
   161    Sint16 center; /* Position of the dead zone */
   162 } SDL_HapticCondition;
   163 typedef struct SDL_HapticRamp {
   164    /* Header */
   165    Uint16 type; /* SDL_HAPTIC_RAMP */
   166    Uint16 direction;
   167 
   168    /* Replay */
   169    Uint16 length;
   170    Uint16 delay;
   171 
   172    /* Trigger */
   173    Uint16 button;
   174    Uint16 interval;
   175 
   176    /* Ramp */
   177    Sint16 start;
   178    Sint16 end;
   179 
   180    /* Envelope */
   181    Uint16 attack_length;
   182    Uint16 attack_level;
   183    Uint16 fade_length;
   184    Uint16 fade_level;
   185 } SDL_HapticRamp;
   186 
   187 typedef union SDL_HapticEffect {
   188    /* Common for all force feedback effects */
   189    Uint16 type; /* Effect type */
   190    SDL_HapticConstant constant; /* Constant effect */
   191    SDL_HapticPeriodic periodic; /* Periodic effect */
   192    SDL_HapticCondition condition; /* Condition effect */
   193    SDL_HapticRamp ramp; /* Ramp effect */
   194 } SDL_HapticEffect;
   195 
   196 
   197 /* Function prototypes */
   198 /*
   199  * Count the number of joysticks attached to the system
   200  */
   201 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   202 
   203 /*
   204  * Get the implementation dependent name of a Haptic device.
   205  * This can be called before any joysticks are opened.
   206  * If no name can be found, this function returns NULL.
   207  */
   208 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   209 
   210 /*
   211  * Opens a Haptic device for usage - the index passed as an
   212  * argument refers to the N'th Haptic device on this system.
   213  *
   214  * This function returns a Haptic device identifier, or Null
   215  * if an error occurred.
   216  */
   217 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   218 
   219 /* 
   220  * Closes a Haptic device previously opened with SDL_HapticOpen.
   221  */
   222 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   223 
   224 /*
   225  * Returns the number of effects a haptic device can store.
   226  */
   227 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   228 
   229 /*
   230  * Returns the supported effects.  Individual effects can be queried by
   231  * bitwise operators.
   232  *
   233  * Example:  (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT)
   234  */
   235 extern DECLSPEC unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic);
   236 
   237 /*
   238  * Checks to see if effect is supported by haptic.
   239  *
   240  * Returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't and -1
   241  * on error.
   242  */
   243 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   244 
   245 /*
   246  * Creates a new haptic effect on the device.
   247  *
   248  * Returns the id of the effect on success, -1 on failure.
   249  */
   250 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   251 
   252 /*
   253  * Runs the haptic effect on it's assosciated haptic device.
   254  *
   255  * Returns 0 on success or -1 on failure.
   256  */
   257 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   258 
   259 /*
   260  * Stops the haptic effect on it's assosciated haptic device.
   261  *
   262  * Returns 0 on success or -1 on failure.
   263  */
   264 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   265 
   266 /*
   267  * Destroys a haptic effect on the device.  This will stop the effect if it's
   268  * running.
   269  */
   270 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   271 
   272 /*
   273  * Sets the global gain of the device.  Gain should be between 0 and 100.
   274  *
   275  * Returns 0 on success or -1 on failure.
   276  */
   277 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   278 
   279 /*
   280  * Sets the global autocenter of the device.  Autocenter should be between
   281  * 0 and 100.  Setting it to 0 will disable autocentering.
   282  *
   283  * Returns 0 on success or -1 on failure.
   284  */
   285 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   286 
   287 
   288 /* Ends C function definitions when using C++ */
   289 #ifdef __cplusplus
   290 /* *INDENT-OFF* */
   291 }
   292 /* *INDENT-ON* */
   293 #endif
   294 #include "close_code.h"
   295 
   296 #endif /* _SDL_haptic_h */
   297 
   298 /* vi: set ts=4 sw=4 expandtab: */
   299 
   300