include/SDL_haptic.h
author Edgar Simo <bobbens@gmail.com>
Tue, 01 Jul 2008 10:44:42 +0000
branchgsoc2008_force_feedback
changeset 2481 5d0ea4576f20
parent 2480 b883974445fc
child 2482 b51ad78812d5
permissions -rw-r--r--
More comments.
Clamped values in struct ff_effect.
Added waveforms.
     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_RUMBLE     (1<<6)
    56 #define SDL_HAPTIC_INERTIA    (1<<7)
    57 #define SDL_HAPTIC_GAIN       (1<<8)
    58 #define SDL_HAPTIC_AUTOCENTER (1<<9)
    59 
    60 typedef enum SDL_waveform {
    61    SDL_WAVEFORM_SINE,
    62    SDL_WAVEFORM_SQUARE,
    63    SDL_WAVEFORM_TRIANGLE,
    64    SDL_WAVEFORM_SAWTOOTHUP,
    65    SDL_WAVEFORM_SAWTOOTHDOWN
    66 } SDL_waveform;
    67 
    68 
    69 /*
    70  * All values max at 32767 (0x7fff).  Signed values also can be negative.
    71  * Time values unless specified otherwise are in milliseconds.
    72  *
    73  * Common parts:
    74  * 
    75  * Replay:
    76  *    Uint16 length;    Duration of effect.
    77  *    Uint16 delay;     Delay before starting effect.
    78  *
    79  * Trigger:
    80  *    Uint16 button;    Button that triggers effect.
    81  *    Uint16 interval;  How soon before effect can be triggered again.
    82  *
    83  * Envelope:
    84  *    Uint16 attack_length;   Duration of the attack.
    85  *    Uint16 attack_level;    Level at the start of the attack.
    86  *    Uint16 fade_length;     Duration of the fade out.
    87  *    Uint16 fade_level;      Level at the end of the fade.
    88  */
    89 typedef struct SDL_HapticConstant {
    90    /* Header */
    91    Uint16 type; /* SDL_HAPTIC_CONSTANT */
    92    Uint16 direction;
    93 
    94    /* Replay */
    95    Uint16 length;
    96    Uint16 delay;
    97 
    98    /* Trigger */
    99    Uint16 button;
   100    Uint16 interval;
   101 
   102    /* Constant */
   103    Sint16 level; /* Strength of the constant effect. */
   104 
   105    /* Envelope */
   106    Uint16 attack_length;
   107    Uint16 attack_level;
   108    Uint16 fade_length;
   109    Uint16 fade_level;
   110 } SDL_HapticConstant;
   111 typedef struct SDL_HapticPeriodic {
   112    /* Header */
   113    Uint16 type; /* SDL_HAPTIC_PERIODIC */
   114    Uint16 direction;
   115 
   116    /* Replay */
   117    Uint16 length;
   118    Uint16 delay;
   119 
   120    /* Trigger */
   121    Uint16 button;
   122    Uint16 interval;
   123 
   124    /* Periodic */
   125    SDL_waveform waveform; /* Type of effect */
   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 
   138 typedef union SDL_HapticEffect {
   139    /* Common for all force feedback effects */
   140    Uint16 type; /* Effect type */
   141    SDL_HapticConstant constant; /* Constant effect */
   142    SDL_HapticPeriodic periodic; /* Periodic effect */
   143 } SDL_HapticEffect;
   144 
   145 
   146 /* Function prototypes */
   147 /*
   148  * Count the number of joysticks attached to the system
   149  */
   150 extern DECLSPEC int SDLCALL SDL_NumHaptics(void);
   151 
   152 /*
   153  * Get the implementation dependent name of a Haptic device.
   154  * This can be called before any joysticks are opened.
   155  * If no name can be found, this function returns NULL.
   156  */
   157 extern DECLSPEC const char *SDLCALL SDL_HapticName(int device_index);
   158 
   159 /*
   160  * Opens a Haptic device for usage - the index passed as an
   161  * argument refers to the N'th Haptic device on this system.
   162  *
   163  * This function returns a Haptic device identifier, or Null
   164  * if an error occurred.
   165  */
   166 extern DECLSPEC SDL_Haptic * SDL_HapticOpen(int device_index);
   167 
   168 /* 
   169  * Closes a Haptic device previously opened with SDL_HapticOpen.
   170  */
   171 extern DECLSPEC void SDL_HapticClose(SDL_Haptic * haptic);
   172 
   173 /*
   174  * Returns the number of effects a haptic device can store.
   175  */
   176 extern DECLSPEC int SDL_HapticNumEffects(SDL_Haptic * haptic);
   177 
   178 /*
   179  * Returns the supported effects.  Individual effects can be queried by
   180  * bitwise operators.
   181  *
   182  * Example:  (SDL_HapticQueryEffects(haptic) & SDL_HAPTIC_CONSTANT)
   183  */
   184 extern DECLSPEC unsigned int SDL_HapticQueryEffects(SDL_Haptic * haptic);
   185 
   186 /*
   187  * Creates a new haptic effect on the device.
   188  */
   189 extern DECLSPEC int SDL_HapticNewEffect(SDL_Haptic * haptic, SDL_HapticEffect * effect);
   190 
   191 /*
   192  * Runs the haptic effect on it's assosciated haptic device.
   193  */
   194 extern DECLSPEC int SDL_HapticRunEffect(SDL_Haptic * haptic, int effect);
   195 
   196 /*
   197  * Destroys a haptic effect on the device.
   198  */
   199 extern DECLSPEC void SDL_HapticDestroyEffect(SDL_Haptic * haptic, int effect);
   200 
   201 
   202 /* Ends C function definitions when using C++ */
   203 #ifdef __cplusplus
   204 /* *INDENT-OFF* */
   205 }
   206 /* *INDENT-ON* */
   207 #endif
   208 #include "close_code.h"
   209 
   210 #endif /* _SDL_haptic_h */
   211 
   212 /* vi: set ts=4 sw=4 expandtab: */
   213 
   214