SDL 1.3 API by Category

Basics

Video

Input Events

Force Feedback

Audio

File I/O Abstraction

Shared Object Support

Threads

Timers

Platform and CPU Information

Power Management

green

Introductory Information by Category

green

Introduction to Initialization

General
Functions in this category are used to set up SDL 1.3 for use and generally have global effects in your program.

Initialization
To begin using SDL in your program SDL_Init() must be called to initialize subsystems and enable use of other SDL funcions.

• The Event Handling, File I/O, and Threading subsystems are initialized by default. To initialize other subsystems you must specifically call them. Multiple subsystems may be or'd together.

• Example: SDL_Init(SDL_INIT_VIDEO|SDL_INIT_AUDIO);

  • Initializes the 3 default subsystems and the Video and Audio subsystems.

Shut Down
SDL_Quit() should be called before an SDL application exits to shut down all subsystems, including the default ones.

• It is not necessary to specify individual subsystems when using SDL_Quit(). It will automatically shut down all active subsystems.

Version
These functions are used to collect or display information about the version of SDL that is currently being used by the program.

• The version number consists of three segments (X.Y.Z)
  • X = Major Version, which increments with massive changes, additions, and enhancements
  • Y = Minor Version, which increments with backwards-compatible changes to the major revision

  • Z = Patchlevel, which increments with fixes to the minor revision
    

  Example: 1.3.0

There are four (4) macros green

that apply to this header.

• SDL_VERSION

  • This macro gathers information from SDL_MAJOR_VERSION, SDL_MINOR_VERSION, AND SDL_PATCHLEVEL (#defines) and fills the structure SDL_version with that information.

• SDL_VERSIONNUM

  • A minor macro that converts version numbers into a numeric value.

• SDL_COMPILEDVERSION

  • A minor macro that produces the current SDL version number (major.minor.patchlevel)

• SDL_VERSION_ATLEAST

  • A minor macro that confirms whether a program was compiled with a version no older than the specified version.

Introduction to Video

Introduction to Input

Introduction to Force Feedback

The SDL Haptic subsystem allows you to control haptic (force feedback) devices.

The basic usage is as follows:

1. Initialize the Subsystem (SDL_INIT_HAPTIC)
2. Open a Haptic Device

   1. SDL_HapticOpen() to open from index

   2. SDL_HapticOpenFromJoystick() to open from an existing joystick

3. Create an effect (SDL_HapticEffect) <<Color2: execution failed [No argument named ""] (see also the log)>>

4. Upload the effect with SDL_HapticNewEffect()

5. Run the effect with SDL_HapticRunEffect()

6. (optional) Free the effect with SDL_HapticDestroyEffect()

7. Close the haptic device with SDL_HapticClose()

Code Example:

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

 // Open the device
 haptic = SDL_HapticOpenFromJoystick( joystick );
 if (haptic == NULL) return -1; // Most likely joystick isn't haptic

 // See if it can do sine waves
 if ((SDL_HapticQuery(haptic) & SDL_HAPTIC_SINE)==0) {
  SDL_HapticClose(haptic); // No sine effect
  return -1;
 }

 // Create the effect
 memset( &effect, 0, sizeof(SDL_HapticEffect) ); // 0 is safe default
 effect.type = SDL_HAPTIC_SINE;
 effect.periodic.direction.type = SDL_HAPTIC_POLAR; // Polar coordinates
 effect.periodic.direction.dir[0] = 18000; // Force comes from south
 effect.periodic.period = 1000; // 1000 ms
 effect.periodic.magnitude = 20000; // 20000/32767 strength
 effect.periodic.length = 5000; // 5 seconds long
 effect.periodic.attack_length = 1000; // Takes 1 second to get max strength
 effect.periodic.fade_length = 1000; // Takes 1 second to fade away

 // Upload the effect
 effect_id = SDL_HapticNewEffect( haptic, &effect );

 // Test the effect
 SDL_HapticRunEffect( haptic, effect_id, 1 );
 SDL_Delay( 5000); // Wait for the effect to finish

 // We destroy the effect, although closing the device also does this
 SDL_HapticDestroyEffect( haptic, effect_id );

 // Close the device
 SDL_HapticClose(haptic);

 return 0; // Success
}

Introduction to Audio

Introduction to File I/O Abstraction

Introduction to Shared Object Support

Introduction to Threads

Introduction to Timers

Introduction to CPU Feature Detection

Introduction to Power Management

Introduction to Endian Independence (Byte Order and Byte Swapping)