Section 3: library functions
SDL_PollEvent – Polls for currently pending events. Synopsis #include "SDL.h" int SDL_PollEvent(SDL_Event *event); Description Polls for currently pending events, and returns 1 if there are any pending events, or 0 if there are none available. If event is not NULL, the next event is removed from the queue and stored in that area. Examples SDL_Event…
SDL_PixelFormat – Stores surface format information Structure Definition typedef struct SDL_PixelFormat { SDL_Palette *palette; Uint8 BitsPerPixel; Uint8 BytesPerPixel; Uint8 Rloss, Gloss, Bloss, Aloss; Uint8 Rshift, Gshift, Bshift, Ashift; Uint32 Rmask, Gmask, Bmask, Amask; Uint32 colorkey; Uint8 alpha; } SDL_PixelFormat; Structure Data palette Pointer to the palette, or NULL if the BitsPerPixel>8 BitsPerPixel The number of…
SDL_PeepEvents – Checks the event queue for messages and optionally returns them. Synopsis #include "SDL.h" int SDL_PeepEvents(SDL_Event *events, int numevents, SDL_eventaction action, Uint32 mask); Description Checks the event queue for messages and optionally returns them. If action is SDL_ADDEVENT, up to numevents events will be added to the back of the event queue. If action…
SDL_PauseAudio – Pauses and unpauses the audio callback processing Synopsis #include "SDL.h" void SDL_PauseAudio(int pause_on); Description This function pauses and unpauses the audio callback processing. It should be called with pause_on=0 after opening the audio device to start playing sound. This is so you can safely initialize data for your callback function after opening the…
SDL_Palette – Color palette for 8-bit pixel formats Structure Definition typedef struct{ int ncolors; SDL_Color *colors; } SDL_Palette; Structure Data ncolors Number of colors used in this palette colors Pointer to SDL_Color structures that make up the palette. Description Each pixel in an 8-bit surface is an index into the colors field of the SDL_Palette…
SDL_Overlay – YUV video overlay Structure Definition typedef struct{ Uint32 format; int w, h; int planes; Uint16 *pitches; Uint8 **pixels; Uint32 hw_overlay:1; } SDL_Overlay; Structure Data format Overlay format (see below) w, h Width and height of overlay planes Number of planes in the overlay. Usually either 1 or 3 pitches An array of pitches,…
SDL_OpenAudio – Opens the audio device with the desired parameters. Synopsis #include "SDL.h" int SDL_OpenAudio(SDL_AudioSpec *desired, SDL_AudioSpec *obtained); Description This function opens the audio device with the desired parameters, and returns 0 if successful, placing the actual hardware parameters in the structure pointed to by obtained. If obtained is NULL, the audio data passed to…
SDL_NumJoysticks – Count available joysticks. Synopsis #include "SDL.h" int SDL_NumJoysticks(void); Description Counts the number of joysticks attached to the system. Return Value Returns the number of attached joysticks See Also SDL_JoystickName, SDL_JoystickOpen
SDL_MouseMotionEvent – Mouse motion event structure Structure Definition typedef struct{ Uint8 type; Uint8 state; Uint16 x, y; Sint16 xrel, yrel; } SDL_MouseMotionEvent; Structure Data type SDL_MOUSEMOTION state The current button state x, y The X/Y coordinates of the mouse xrel, yrel Relative motion in the X/Y direction Description SDL_MouseMotionEvent is a member of the SDL_Event…
SDL_MouseButtonEvent – Mouse button event structure Structure Definition typedef struct{ Uint8 type; Uint8 button; Uint8 state; Uint16 x, y; } SDL_MouseButtonEvent; Structure Data type SDL_MOUSEBUTTONDOWN or SDL_MOUSEBUTTONUP button The mouse button index (SDL_BUTTON_LEFT, SDL_BUTTON_MIDDLE, SDL_BUTTON_RIGHT) state SDL_PRESSED or SDL_RELEASED x, y The X/Y coordinates of the mouse at press/release time Description SDL_MouseButtonEvent is a member…
SDL_MixAudio – Mix audio data Synopsis #include "SDL.h" void SDL_MixAudio(Uint8 *dst, Uint8 *src, Uint32 len, int volume); Description This function takes two audio buffers of len bytes each of the playing audio format and mixes them, performing addition, volume adjustment, and overflow clipping. The volume ranges from 0 to SDL_MIX_MAXVOLUME and should be set to…
SDL_MapRGBA – Map a RGBA color value to a pixel format. Synopsis #include "SDL.h" Uint32 SDL_MapRGBA(SDL_PixelFormat *fmt, Uint8 r, Uint8 g, Uint8 b, Uint8 a); Description Maps the RGBA color value to the specified pixel format and returns the pixel value as a 32-bit int. If the format has a palette (8-bit) the index of…
SDL_MapRGB – Map a RGB color value to a pixel format. Synopsis #include "SDL.h" Uint32 SDL_MapRGB(SDL_PixelFormat *fmt, Uint8 r, Uint8 g, Uint8 b); Description Maps the RGB color value to the specified pixel format and returns the pixel value as a 32-bit int. If the format has a palette (8-bit) the index of the closest…
SDL_LockYUVOverlay – Lock an overlay Synopsis #include "SDL.h" int SDL_LockYUVOverlay(SDL_Overlay *overlay); Description Much the same as SDL_LockSurface, SDL_LockYUVOverlay locks the overlay for direct access to pixel data. Return Value Returns 0 on success, or -1 on an error. See Also SDL_UnlockYUVOverlay, SDL_CreateYUVOverlay, SDL_Overlay
SDL_LockSurface – Lock a surface for directly access. Synopsis #include "SDL.h" int SDL_LockSurface(SDL_Surface *surface); Description SDL_LockSurface sets up a surface for directly accessing the pixels. Between calls to SDL_LockSurface and SDL_UnlockSurface, you can write to and read from surface->pixels, using the pixel format stored in surface->format. Once you are done accessing the surface, you should…
SDL_LockAudio – Lock out the callback function Synopsis #include "SDL.h" void SDL_LockAudio(void) Description The lock manipulated by these functions protects the callback function. During a LockAudio period, you can be guaranteed that the callback function is not running. Do not call these from the callback function or you will cause deadlock. See Also SDL_OpenAudio
SDL_LoadWAV – Load a WAVE file Synopsis #include "SDL.h" SDL_AudioSpec *SDL_LoadWAV(const char *file, SDL_AudioSpec *spec, Uint8 **audio_buf, Uint32 *audio_len); Description SDL_LoadWAV This function loads a WAVE file into memory. If this function succeeds, it returns the given SDL_AudioSpec, filled with the audio data format of the wave data, and sets audio_buf to a malloc‘d buffer…
SDL_LoadBMP – Load a Windows BMP file into an SDL_Surface. Synopsis #include "SDL.h" SDL_Surface *SDL_LoadBMP(const char *file); Description Loads a surface from a named Windows BMP file. Return Value Returns the new surface, or NULL if there was an error. See Also SDL_SaveBMP
SDL_ListModes – Returns a pointer to an array of available screen dimensions for the given format and video flags Synopsis #include "SDL.h" SDL_Rect **SDL_ListModes(SDL_PixelFormat *format, Uint32 flags); Description Return a pointer to an array of available screen dimensions for the given format and video flags, sorted largest to smallest. Returns NULL if there are no…
SDL_KillThread – Gracelessly terminates the thread. Synopsis #include "SDL.h" #include "SDL_thread.h" void SDL_KillThread(SDL_Thread *thread); Description SDL_KillThread gracelessly terminates the thread associated with thread. If possible, you should use some other form of IPC to signal the thread to quit. See Also SDL_CreateThread, SDL_WaitThread