include/SDL_haptic.h
author Edgar Simo <bobbens@gmail.com>
Thu, 03 Jul 2008 09:58:27 +0000
branchgsoc2008_force_feedback
changeset 2495 66c02abeef0e
parent 2489 96adc8025331
child 2497 0893fbf73b3d
permissions -rw-r--r--
Added SDL_HapticGetEffectStatus().
More comments.
     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 #include "SDL_joystick.h"
    35 
    36 #include "begin_code.h"
    37 /* Set up for C function definitions, even when using C++ */
    38 #ifdef __cplusplus
    39 /* *INDENT-OFF* */
    40 extern "C" {
    41    /* *INDENT-ON* */                                                         
    42 #endif
    43 
    44 /* The haptic structure used to identify an SDL haptic */
    45 struct _SDL_Haptic;                                                     
    46 typedef struct _SDL_Haptic SDL_Haptic;
    47 
    48 
    49 /*
    50  * Different haptic features a device can have.
    51  */
    52 #define SDL_HAPTIC_CONSTANT   (1<<0) /* Constant effect supported */
    53 #define SDL_HAPTIC_SINE       (1<<1) /* Sine wave effect supported */
    54 #define SDL_HAPTIC_SQUARE     (1<<2) /* Square wave effect supported */
    55 #define SDL_HAPTIC_TRIANGLE   (1<<3) /* Triangle wave effect supported */
    56 #define SDL_HAPTIC_SAWTOOTHUP (1<<4) /* Sawtoothup wave effect supported */
    57 #define SDL_HAPTIC_SAWTOOTHDOWN (1<<5) /* Sawtoothdown wave effect supported */
    58 #define SDL_HAPTIC_RAMP       (1<<6) /* Ramp effect supported */
    59 #define SDL_HAPTIC_SPRING     (1<<7) /* Spring effect supported - uses axes position */
    60 #define SDL_HAPTIC_DAMPER     (1<<8) /* Damper effect supported - uses axes velocity */
    61 #define SDL_HAPTIC_INERTIA    (1<<9) /* Inertia effect supported - uses axes acceleration */
    62 #define SDL_HAPTIC_FRICTION   (1<<10) /* Friction effect supported - uses axes movement */
    63 #define SDL_HAPTIC_CUSTOM     (1<<11) /* Custom effect is supported */
    64 /* These last two are features the device has, not effects */
    65 #define SDL_HAPTIC_GAIN       (1<<12) /* Device can set global gain */
    66 #define SDL_HAPTIC_AUTOCENTER (1<<13) /* Device can set autocenter */
    67 #define SDL_HAPTIC_STATUS     (1<<14) /* Device can be queried for effect status */
    68 
    69 
    70 /*
    71  * All values max at 32767 (0x7fff).  Signed values also can be negative.
    72  * Time values unless specified otherwise are in milliseconds.
    73  *
    74  * Common parts:
    75  * 
    76  * Replay:
    77  *    Uint16 length;    Duration of effect.
    78  *    Uint16 delay;     Delay before starting effect.
    79  *
    80  * Trigger:
    81  *    Uint16 button;    Button that triggers effect.
    82  *    Uint16 interval;  How soon before effect can be triggered again.
    83  *
    84  * Envelope:
    85  *    Uint16 attack_length;   Duration of the attack.
    86  *    Uint16 attack_level;    Level at the start of the attack.
    87  *    Uint16 fade_length;     Duration of the fade out.
    88  *    Uint16 fade_level;      Level at the end of the fade.
    89  */
    90 typedef struct SDL_HapticConstant {
    91    /* Header */
    92    Uint16 type; /* SDL_HAPTIC_CONSTANT */
    93    Uint16 direction;
    94 
    95    /* Replay */
    96    Uint16 length;
    97    Uint16 delay;
    98 
    99    /* Trigger */
   100    Uint16 button;
   101    Uint16 interval;
   102 
   103    /* Constant */
   104    Sint16 level; /* Strength of the constant effect. */
   105 
   106    /* Envelope */
   107    Uint16 attack_length;
   108    Uint16 attack_level;
   109    Uint16 fade_length;
   110    Uint16 fade_level;
   111 } SDL_HapticConstant;
   112 typedef struct SDL_HapticPeriodic {
   113    /* Header */
   114    Uint16 type; /* SDL_HAPTIC_{SINE,SQUARE,TRIANGLE,SAWTOOTHUP,SAWTOOTHDOWN} */
   115    Uint16 direction;
   116 
   117    /* Replay */
   118    Uint16 length;
   119    Uint16 delay;
   120 
   121    /* Trigger */
   122    Uint16 button;
   123    Uint16 interval;
   124 
   125    /* Periodic */
   126    Uint16 period; /* Period of the wave */
   127    Sint16 magnitude; /* Peak value */
   128    Sint16 offset; /* Mean value of the wave */
   129    Uint16 phase; /* Horizontal shift */
   130 
   131    /* Envelope */
   132    Uint16 attack_length;
   133    Uint16 attack_level;
   134    Uint16 fade_length;
   135    Uint16 fade_level;
   136 } SDL_HapticPeriodic;
   137 typedef struct SDL_HapticCondition {
   138    /* Header */
   139    Uint16 type; /* SDL_HAPTIC_{SPRING,DAMPER,INERTIA,FRICTION} */
   140    Uint16 direction;
   141 
   142    /* Replay */
   143    Uint16 length;
   144    Uint16 delay;
   145 
   146    /* Trigger */
   147    Uint16 button;
   148    Uint16 interval;
   149 
   150    /* Condition */
   151    Uint16 right_sat; /* Level when joystick is to the right. */
   152    Uint16 left_sat; /* Level when joystick is to the left */
   153    Sint16 right_coeff; /* How fast to increase the force towards the right */
   154    Sint16 left_coeff; /* How fast to increase the force towards the left */
   155    Uint16 deadband; /* Size of the dead zone */
   156    Sint16 center; /* Position of the dead zone */
   157 } SDL_HapticCondition;
   158 typedef struct SDL_HapticRamp {
   159    /* Header */
   160    Uint16 type; /* SDL_HAPTIC_RAMP */
   161    Uint16 direction;
   162 
   163    /* Replay */
   164    Uint16 length;
   165    Uint16 delay;
   166 
   167    /* Trigger */
   168    Uint16 button;
   169    Uint16 interval;
   170 
   171    /* Ramp */
   172    Sint16 start; /* Beginning strength level. */
   173    Sint16 end; /* Ending strength level. */
   174 
   175    /* Envelope */
   176    Uint16 attack_length;
   177    Uint16 attack_level;
   178    Uint16 fade_length;
   179    Uint16 fade_level;
   180 } SDL_HapticRamp;
   181 
   182 typedef union SDL_HapticEffect {
   183    /* Common for all force feedback effects */
   184    Uint16 type; /* Effect type */
   185    SDL_HapticConstant constant; /* Constant effect */
   186    SDL_HapticPeriodic periodic; /* Periodic effect */
   187    SDL_HapticCondition condition; /* Condition effect */
   188    SDL_HapticRamp ramp; /* Ramp effect */
   189 } SDL_HapticEffect;
   190 
   191 
   192 /* Function prototypes */
   193 /*
   194  * Count the number of joysticks attached to the system
   195  */
   196 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   197 
   198 /*
   199  * Get the implementation dependent name of a Haptic device.
   200  * This can be called before any joysticks are opened.
   201  * If no name can be found, this function returns NULL.
   202  */
   203 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   204 
   205 /*
   206  * Opens a Haptic device for usage - the index passed as an
   207  * argument refers to the N'th Haptic device on this system.
   208  *
   209  * This function returns a Haptic device identifier, or Null
   210  * if an error occurred.
   211  */
   212 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   213 
   214 /*
   215  * Checks to see if a joystick has haptic features.
   216  *
   217  * Returns SDL_TRUE if the joystick is haptic, SDL_FALSE if it isn't
   218  * and -1 on error.
   219  */
   220 extern DECLSPEC int SDL_JoystickIsHaptic(SDL_Joystick * joystick);
   221 
   222 /*
   223  * Opens a Haptic device for usage from a Joystick device.
   224  *
   225  * Returns a valid pointer to a haptic device on success or NULL
   226  * if an error occurred.
   227  */
   228 extern DECLSPEC SDL_Haptic * SDL_HapticOpenFromJoystick(SDL_Joystick * joystick);
   229 
   230 /* 
   231  * Closes a Haptic device previously opened with SDL_HapticOpen.
   232  */
   233 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   234 
   235 /*
   236  * Returns the number of effects a haptic device can store.
   237  */
   238 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   239 
   240 /*
   241  * Returns the supported effects.  Individual effects can be queried by
   242  * bitwise operators.
   243  *
   244  * Example:  (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT)
   245  */
   246 extern DECLSPEC unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic);
   247 
   248 /*
   249  * Checks to see if effect is supported by haptic.
   250  *
   251  * Returns SDL_TRUE if effect is supported, SDL_FALSE if it isn't and -1
   252  * on error.
   253  */
   254 extern DECLSPEC int SDL_HapticEffectSupported(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   255 
   256 /*
   257  * Creates a new haptic effect on the device.
   258  *
   259  * Returns the id of the effect on success, -1 on failure.
   260  */
   261 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   262 
   263 /*
   264  * Uploads an effect.  Can be used dynamically, although behaviour when
   265  * dynamically changing direction may be strange.  Specifically the effect
   266  * may reupload itself and start playing from the start.  You cannot change
   267  * the type either when running UpdateEffect.
   268  *
   269  * Returns the id of the effect on success, -1 on failure.
   270  */
   271 extern DECLSPEC int SDL_HapticUpdateEffect(SDL_Haptic * haptic, int effect, SDL_HapticEffect * data);
   272 
   273 /*
   274  * Runs the haptic effect on it's assosciated haptic device.
   275  *
   276  * Returns 0 on success or -1 on failure.
   277  */
   278 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   279 
   280 /*
   281  * Stops the haptic effect on it's assosciated haptic device.
   282  *
   283  * Returns 0 on success or -1 on failure.
   284  */
   285 extern DECLSPEC int SDL_HapticStopEffect(SDL_Haptic * haptic, int effect);
   286 
   287 /*
   288  * Destroys a haptic effect on the device.  This will stop the effect if it's
   289  * running.
   290  */
   291 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   292 
   293 /*
   294  * Gets the status of the current effect on the haptic device.
   295  *
   296  * Returns 0 if it isn't playing, SDL_HAPTIC_PLAYING if it is playing
   297  * or -1 on failure.
   298  */
   299 extern DECLSPEC int SDL_HapticGetEffectStatus(SDL_Haptic *haptic, int effect);
   300 
   301 /*
   302  * Sets the global gain of the device.  Gain should be between 0 and 100.
   303  *
   304  * Returns 0 on success or -1 on failure.
   305  */
   306 extern DECLSPEC int SDL_HapticSetGain(SDL_Haptic * haptic, int gain);
   307 
   308 /*
   309  * Sets the global autocenter of the device.  Autocenter should be between
   310  * 0 and 100.  Setting it to 0 will disable autocentering.
   311  *
   312  * Returns 0 on success or -1 on failure.
   313  */
   314 extern DECLSPEC int SDL_HapticSetAutocenter(SDL_Haptic * haptic, int autocenter);
   315 
   316 
   317 /* Ends C function definitions when using C++ */
   318 #ifdef __cplusplus
   319 /* *INDENT-OFF* */
   320 }
   321 /* *INDENT-ON* */
   322 #endif
   323 #include "close_code.h"
   324 
   325 #endif /* _SDL_haptic_h */
   326 
   327 /* vi: set ts=4 sw=4 expandtab: */
   328 
   329