Structure Data Description See Also SDL_AddTimerName Synopsis Description . The timer callback function may run in a different thread than your -main program, and so shouldn't call any functions from within itself. SDL_PushEvent, however. The maximum resolution of this timer is 10 ms, which means that if +>The granularity of the timer is platform-dependent, but you should count +on it being at least 10 ms as this is the most common number. +This means that if you request a 16 ms timer, your callback will run approximately 20 ms later on an unloaded system. If you wanted to set a flag signaling a frame update at 30 frames per second (every 33 ms), you might set a @@ -173,7 +179,7 @@ > Return Value Examples See AlsoSDL_RemoveTimer, +SDL_PushEvent SDL_AudioCVTName Structure Definition Structure Data Description See Also SDL_AudioSpecName Structure Definition Structure Data Description See Also SDL_BlitSurfaceName Synopsis Description is not modified). The blit function should not be called on a locked surface. Note: The results of blitting operations vary greatly depending on whether SDL_SRCAPLHA is set or not. See SDL_SetAlpha. for an explaination of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting, as the following pseudo-code should hopefully explain. +if (source surface has SDL_SRCALPHA set) { + if (source surface has alpha channel (that is, format->Amask != 0)) + blit using per-pixel alpha, ignoring any colour key + else { + if (source surface has SDL_SRCCOLORKEY set) + blit using the colour key AND the per-surface alpha value + else + blit using the per-surface alpha value + } +} else { + if (source surface has SDL_SRCCOLORKEY set) + blit using the colour key + else + ordinary opaque rectangular blit +} Return Value See Also SDL_BuildAudioCVTName Synopsis Description Return Values Examples See Also SDL_CDName Structure Definition Structure Data Description Examples See Also SDL_CDCloseName Synopsis Description See Also SDL_CDEjectName Synopsis Description Return Value See Also SDL_CDNameName Synopsis Description Examples See Also SDL_CDNumDrivesName Synopsis Description See Also SDL_CDOpenName Synopsis Description Examples See Also SDL_CDPauseName Synopsis Description Return Value See Also SDL_CDPlayName Synopsis Description Return Values See Also SDL_CDPlayTracksName Synopsis Description Return Value Examples See Also SDL_CDResumeName Synopsis Description Return Value See Also SDL_CDStatusName Synopsis Description Example See Also SDL_CDStopName Synopsis Description Return Value See Also SDL_CDtrackName Structure Definition Structure Data Description See Also SDL_CloseAudioName Synopsis Description See Also SDL_ColorName Structure Definition Structure Data Description See Also SDL_CondBroadcastName Synopsis Description See Also SDL_CondSignalName Synopsis Description See Also SDL_CondWaitName Synopsis Description See Also SDL_CondWaitTimeoutName Synopsis Description See Also SDL_ConvertAudioName Synopsis Description Examples See Also SDL_ConvertSurfaceName Synopsis Description Return Value See Also SDL_CreateCondName Synopsis Description Examples See Also SDL_CreateCursorName Synopsis Description Example See Also SDL_CreateMutexName Synopsis Description Examples See Also SDL_CreateRGBSurfaceName Synopsis Description With this flag SDL will attempt to find the best location for this surface, either in system memory or video memory, to obtain hardware colorkey blitting support.This flag turns on colourkeying for blits from this surface. If +SDL_HWSURFACE is also specified and colourkeyed blits +are hardware-accelerated, then SDL will attempt to place the surface in +video memory. +Use SDL_SetColorKey +to set or clear this flag after surface creation.With this flag SDL will attempt to find the best location for this surface, either in system memory or video memory, to obtain hardware alpha supportThis flag turns on alpha-blending for blits from this surface. If +SDL_HWSURFACE is also specified and alpha-blending blits +are hardware-accelerated, then the surface will be placed in video memory if +possible. +Use SDL_SetAlpha to +set or clear this flag after surface creation. Note: If an alpha-channel is specified (that is, if Amask is +nonzero), then the SDL_SRCALPHA flag is automatically +set. You may remove this flag by calling +SDL_SetAlpha +after surface creation. Return Value Returns the created surface, or NULL upon error. Example /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order, + as expected by OpenGL for textures */ + SDL_Surface *surface; + Uint32 rmask, gmask, bmask, amask; + + /* SDL interprets each pixel as a 32-bit number, so our masks must depend + on the endianness (byte order) of the machine */ +#if SDL_BYTEORDER == SDL_BIG_ENDIAN + rmask = 0xff000000; + gmask = 0x00ff0000; + bmask = 0x0000ff00; + amask = 0x000000ff; +#else + rmask = 0x000000ff; + gmask = 0x0000ff00; + bmask = 0x00ff0000; + amask = 0xff000000; +#endif + + surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32, + rmask, gmask, bmask, amask); + if(surface == NULL) { + fprintf(stderr, "CreateRGBSurface failed: %s\n", SDL_GetError()); + exit(1); + } See AlsoSDL_Surface +SDL_SetAlpha +SDL_SetColorKey SDL_CreateRGBSurfaceFromName Synopsis Description specified in the parameter list. The pixel data is not copied into the SDL_Surface structure so it should no be freed until the surface has been freed with a called to structure so it should not be freed until the surface has been freed with a called to SDL_FreeSurface. Return Value Returns the created surface, or NULL upon error. See Also SDL_CreateSemaphoreName Synopsis Description Return Value Examples See Also SDL_CreateThreadName Synopsis Description See Also SDL_CreateYUVOverlayName Synopsis Description See Also SDL_DelayName Synopsis Description least the specified time, but possible longer due to OS scheduling. Note: Count on a delay granularity of at least 10 ms. +Some platforms have shorter clock ticks but this is the most common. See Also SDL_DestroyCondName Synopsis Description See Also SDL_DestroyMutexName Synopsis Description See Also SDL_DestroySemaphoreName Synopsis Description Examples See Also SDL_DisplayFormatName Synopsis Description Return Value See Also SDL_DisplayFormatAlphaName Synopsis DescriptionIf you want to take advantage of hardware colorkey or alpha blit acceleration, you should set the colorkey and alpha value before calling this function. This function can be used to convert a colourkey to an alpha channel, +if the SDL_SRCCOLORKEY flag is set on the surface. +The generated surface will then be transparent (alpha=0) where the +pixels match the colourkey, and opaque (alpha=255) elsewhere. Return Value See Also SDL_DisplayYUVOverlayName Synopsis Description See Also SDL_EnableKeyRepeatName Synopsis Description Return Value SDL_EnableUNICODEName Synopsis Description Return Value See Also SDL_EventName Structure Definition Structure Data Description Use See Also SDL_EventStateName Synopsis Description See Also SDL_FillRectName Synopsis Description Return Value See Also SDL_FlipName Synopsis Description Return Value See Also SDL_FreeCursorName Synopsis Description See Also SDL_FreeSurfaceName SDL_FreeSurface -- Frees (deletes) and SDL_Surface SDL_FreeSurface -- Frees (deletes) a SDL_Surface Synopsis Description See Also SDL_FreeWAVName Synopsis Description See Also SDL_FreeYUVOverlayName Synopsis Description See Also SDL_GetAppStateName Synopsis Description See Also SDL_GetAudioStatusName Synopsis Description See Also SDL_GetClipRectName Synopsis Description See Also SDL_GetCursorName Synopsis Description See Also SDL_GetEventFilterName Synopsis Description Return Value See Also SDL_GetGammaRampName Synopsis Description Return Value See Also SDL_GetKeyNameName Synopsis Description See Also SDL_GetKeyStateName Synopsis Description Example See Also SDL_GetModStateName Synopsis Description Return Value The return value can be an OR'd combination of the SDLMod enum. SDL also defines the following symbols for convenience: See Also SDL_GetMouseStateName Synopsis Description Example See Also SDL_GetRelativeMouseStateName Synopsis Description See Also SDL_GetRGBName Synopsis Description See Also SDL_GetRGBAName Synopsis Description See Also SDL_GetThreadIDName Synopsis Description See Also SDL_GetTicksName Synopsis Description See Also SDL_GetVideoInfoName Synopsis Description See Also SDL_GetVideoSurfaceName Synopsis Description See Also SDL_GLattrName Attributes Description See Also SDL_GL_GetAttributeName Synopsis Description Return Value See Also SDL_GL_GetProcAddressName Synopsis Description Example See Also SDL_GL_LoadLibraryName Synopsis Description See Also SDL_GL_SetAttributeName Synopsis Description Return Value Example See Also SDL_GL_SwapBuffersName Synopsis Description See Also SDL_InitName Synopsis Description Return Value See Also SDL_InitSubSystemName Synopsis Description Examples Return Value See Also SDL_JoyAxisEventName Structure Definition Structure Data Description See Also SDL_JoyBallEventName Structure Definition Structure Data Description See Also SDL_JoyButtonEventName Structure Definition Structure Data Description See Also SDL_JoyHatEventName Structure Definition Structure Data Description See Also SDL_JoystickCloseName Synopsis Description See Also SDL_JoystickEventStateName Synopsis Description Return Value See Also SDL_JoystickGetAxisName Synopsis Description Return Value Examples See Also SDL_JoystickGetBallName Synopsis Description Return Value Examples See Also SDL_JoystickGetButtonName Synopsis Description Return Value See Also SDL_JoystickGetHatName Synopsis Description Return Value See Also SDL_JoystickIndexName Synopsis Description Return Value See Also SDL_JoystickNameName Synopsis Description Return Value Examples See Also SDL_JoystickNumAxesName Synopsis Description Return Value See Also SDL_JoystickNumBallsName Synopsis Description Return Value See Also SDL_JoystickNumButtonsName Synopsis Description Return Value See Also SDL_JoystickNumHatsName Synopsis Description Return Value See Also SDL_JoystickOpenName Synopsis Description Return Value Examples See Also SDL_JoystickOpenedName Synopsis Description Return Value See Also SDL_JoystickUpdateName Synopsis Description See Also SDLKeyName Description SDL_KeyboardEvent NameStructure DefinitionStructure DataDescriptionSee Also SDL_keysymNameStructure DefinitionStructure Data Description See Also SDL_KillThreadName Synopsis Description See Also SDL_ListModesName Synopsis Description Example See Also SDL_LoadBMPName Synopsis Description Return Value See Also SDL_LoadWAVName Synopsis Description Example See Also SDL_LockAudioName Synopsis Description See Also SDL_LockSurfaceName Synopsis Description Return Value See Also SDL_LockYUVOverlayName Synopsis Description Return Value See Also SDL_MapRGBName Synopsis Description Return Value See Also SDL_MapRGBAName Synopsis Description Return Value See Also SDL_MixAudioName Synopsis Description This takes two audio buffers of the playing audio format and mixes -them, performing addition, volume adjustment, and overflow clipping. -The 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 - 128, -and should be set to ranges +from 0 to SDL_MIX_MAXVOLUME -for full audio volume. Note this does not change hardware volume. -This is provided for convenience -- you can mix your own audio data. and should be set to the maximum +value for full audio volume. Note this does not change hardware volume. This is +provided for convenience -- you can mix your own audio data. See Also SDL_MouseButtonEventName Structure Definition Structure Data Description See Also SDL_MouseMotionEventName Structure Definition Structure Data Description See Also SDL_mutexPName Synopsis Description See Also SDL_mutexVName Synopsis Description See Also SDL_NumJoysticksName Synopsis Description Return Value See Also SDL_OpenAudioName Synopsis Description Examples See Also SDL_OverlayName Structure Definition Structure Data Description See Also SDL_PaletteName Structure Definition Structure Data Description See Also SDL_PauseAudioName Synopsis Description See Also SDL_PeepEventsName Synopsis Description Return Value See Also SDL_PixelFormatName Structure Definition Structure Data Description Pixel formats above 8-bit are an entirely different experience. They are considered to be "TrueColor" formats and the color information is stored in the pixels themselves, not in a palette (packed-pixel). The mask, shift and loss fields tell us how the color information is encoded. The mask fields allow us to isolate each color component, the shift fields tell us how far left we have to shift the masked value and the loss fields tell us for far right we have to shift the final value to convert it to a full 8-bit color component. +>Pixel formats above 8-bit are an entirely different experience. They are +considered to be "TrueColor" formats and the color information is stored in the +pixels themselves, not in a palette. The mask, shift and loss fields tell us +how the color information is encoded. The mask fields allow us to isolate each +color component, the shift fields tell us the number of bits to the right of +each component in the pixel value and the loss fields tell us the number of +bits lost from each component when packing 8-bit color component in a pixel. /* Extracting color components from a 32-bit color value */ @@ -396,7 +402,7 @@ . fmt=surface->format; SDL_LockSurface(surface); -pixel=(Uint32*)surface->pixels; +pixel=*((Uint32*)surface->pixels); SDL_UnlockSurface(surface); /* Get Red component */ @@ -432,7 +438,7 @@ >See Also SDL_PollEventName Synopsis Description Examples See Also SDL_PumpEventsName Synopsis Description See Also SDL_PushEventName Synopsis Description Return Value Examples See Also SDL_QuitName Synopsis Description See Also SDL_QuitEventName Structure Definition Structure Data Description See Also SDL_QuitSubSystemName Synopsis Description See Also SDL_RectName Structure Definition Structure Data Description See Also SDL_RemoveTimerName Synopsis Description Return Value Examples See Also SDL_ResizeEventName Structure Definition Structure Data Description See Also SDL_SaveBMPName Synopsis Description Return Value See Also SDL_SemPostName Synopsis Description Return Value Examples See Also SDL_SemTryWaitName Synopsis Description Return Value Examples See Also SDL_SemValueName Synopsis Description Return Value Examples See Also SDL_SemWaitName Synopsis Description Return Value Examples See Also SDL_SemWaitTimeoutName Synopsis Description Return Value Examples See Also SDL_SetAlphaName Synopsis Description SDL_SetAlpha is used for setting the per-surface alpha and/or enabling and disabling per-pixel alpha blending. is used for setting the per-surface alpha +value and/or enabling and disabling alpha blending. The Thesurface parameter specifies which surface whose alpha attributes you wish to adjust. parameter specifies which surface whose alpha +attributes you wish to adjust. flags is used to specify whether alpha blending should be used ( is used to specify +whether alpha blending should be used (SDL_SRCALPHA) and whether the surface should use RLE acceleration for blitting () and +whether the surface should use RLE acceleration for blitting +(SDL_RLEACCEL). flags can be an OR'd combination of these two options, one of these options or 0. If can be an OR'd +combination of these two options, one of these options or 0. If +SDL_SRCALPHA is not passed as a flag then all alpha information is ignored when blitting the surface. The is not passed as a flag then all alpha +information is ignored when blitting the surface. The +alpha parameter is the per-surface alpha value, a surface need not have an alpha channel to use per-surface alpha and blitting can still be accelerated with parameter is the per-surface alpha value; a +surface need not have an alpha channel to use per-surface alpha and blitting +can still be accelerated with SDL_RLEACCEL. Setting the per-surface alpha value to 0 disables per-surface alpha blending. . Note: The per-surface alpha value of 128 is considered a special case and is optimised, so it's much faster than other per-surface values.The per-surface alpha value of 128 is considered a special case and +is optimised, so it's much faster than other per-surface values. The source is alpha-blended with the destination using the per-surface alpha value. If The source is alpha-blended with the destination using the per-surface alpha +value. If SDL_SRCCOLORKEYliteral> is set, only the pixels not matching the colorkey value are copied. is set, only the pixels not +matching the colorkey value are copied. The alpha channel of the copied pixels +is set to opaque. The RGB data is copied from the source and the destination alpha is zero to opaque. If The RGB data is copied from the source and the alpha value of the copied pixels +is set to opaque. If SDL_SRCCOLORKEY is set, only the pixels not matching the colorkey value are copied. is set, only the pixels +not matching the colorkey value are copied. The source is alpha-blended with the destination using the source alpha channel. The alpha channel in the destination surface is left untouched. The source is alpha-blended with the destination using the source alpha +channel. The alpha channel in the destination surface is left untouched. +SDL_SRCCOLORKEY is ignored. Note: Note that RGBA->RGBA blits (with SDL_SRCALPHA set) keep the alpha +of the destination surface. This means that you cannot compose two arbitrary +RGBA surfaces this way and get the result you would expect from "overlaying" +them; the destination alpha will work as a mask. Also note that per-pixel and per-surface alpha cannot be combined; +the per-pixel alpha is always used if available Return Value This function returns 0, or +-1 if there was an error. See Also SDL_SetClipRectName Synopsis Description See Also SDL_SetColorKeyName Synopsis Description Return Value See Also SDL_SetColorsName Synopsis Description Return Value Example See Also SDL_SetCursorName Synopsis Description See Also SDL_SetEventFilterName Synopsis Description See Also SDL_SetGammaName Synopsis Description Return Value See Also SDL_SetGammaRampName Synopsis Description Return Value See Also SDL_SetModStateName Synopsis Description See Also SDL_SetPaletteName Synopsis SDL_SetPalette(SDL_Surface *surface, int flags, int SDL_Color *colors, int firstcolor, int ncolors);(SDL_Surface *surface, int flags, SDL_Color *colors, int firstcolor, int ncolors); Description Return Value Example See Also SDL_SetTimerName Synopsis Description Note: This function is kept for compatibility but has been superceeded +>This function is kept for compatibility but has been superseded by the new timer functions Examples See Also SDL_SetVideoModeName Synopsis Description Enable double buffering. Calling Enable double buffering; only valid with SDL_HWSURFACE. Calling Return ValueSee Also SDL_ShowCursorNameSynopsisDescriptionReturn ValueSee Also SDL_SurfaceName Structure Definition Structure Data clip_minx, clip_maxxX clip coordsclip_rectDescription SDL_SRCOLORKEYSDL_SRCCOLORKEYSee Also SDL_SysWMEventName Description See Also SDL_ThreadIDName Synopsis Description SDL_UnlockAudioName Synopsis Description See Also SDL_UnlockSurfaceName Synopsis Description See Also SDL_UnlockYUVOverlayName Synopsis Description See Also SDL_UpdateRectName Synopsis Description Makes sure the given area is updated on the given screen.Makes sure the given area is updated on the given screen. The rectangle must +be confined within the screen boundaries (no clipping is done). If ' See Also SDL_UpdateRectsName Synopsis Description Makes sure the given list of rectangles is updated on the given screen.Makes sure the given list of rectangles is updated on the given screen. +The rectangles must all be confined within the screen boundaries (no +clipping is done). This function should not be called while locked. . Note: It is adviced to call this function only once per frame, since each +call has some processing overhead. This is no restriction since you +can pass any number of rectangles each time. The rectangles are not automatically merged or checked for overlap. In +general, the programmer can use his knowledge about his particular +rectangles to merge them in an efficient way, to avoid overdraw. See Also SDL_UserEventName Structure Definition Structure Data Description Examples See Also SDL_VideoDriverNameName Synopsis Description Return Value See Also SDL_VideoInfoName Structure Definition Structure Data Description See Also SDL_VideoModeOKName Synopsis Description Example See Also SDL_WaitEventName Synopsis Description See Also SDL_WaitThreadName Synopsis Description Return Value See Also SDL_WarpMouseName Synopsis Description See Also SDL_WasInitName Synopsis Description Return Value Examples See Also SDL_WM_GetCaptionName Synopsis Description See Also SDL_WM_GrabInputName Synopsis Description Return Value SDL_WM_IconifyWindowName Synopsis Description Return Value SDL_WM_SetCaptionName Synopsis Description See Also SDL_WM_SetIconName Synopsis Description Example See Also SDL_WM_ToggleFullScreenName Synopsis Description Return Value Multi-threaded ProgrammingTimeVideoSDL_FreeSurface — Frees (deletes) and SDL_Surface

PrefaceThe BasicsTime Examples

Time based game loop

Graphics and VideoNextChapter 2. Graphics and Video

Table of Contents
Introduction to SDL Video
Using OpenGL With SDL

Using OpenGL With SDLIntroduction to SDL Video

SDL has the ability to create and use OpenGL contexts on several platforms(Linux/X11, Win32, BeOS, MacOS Classic/Toolbox, MacOS X, FreeBSD/X11 and Solaris/X11). This allows you to use SDL's audio, event handling, threads and times in your OpenGL applications (a function often performed by GLUT).

Video is probably the most common thing that SDL is used for, and +so it has the most complete subsystem. Here are a few +examples to demonstrate the basics.

InitialisationInitializing the Video Display

Initialising SDL to use OpenGL is not very different to initialising SDL normally. There are three differences; you must pass SDL_OPENGL to SDL_SetVideoModeThis is what almost all SDL programs have to do in one way or +another.

, you must specify several GL attributes (depth buffer size, framebuffer sizes) using SDL_GL_SetAttribute and finally, if you wish to use double buffering you must specify it as a GL attribute, not by passing the SDL_DOUBLEBUF flag to SDL_SetVideoMode. -

Example 2-1. Initializing the Video Display
    /* Information about the current video settings. */
-    const SDL_VideoInfo* info = NULL;
-    /* Dimensions of our window. */
-    int width = 0;
-    int height = 0;
-    /* Color depth in bits of our window. */
-    int bpp = 0;
-    /* Flags we will pass into SDL_SetVideoMode. */
-    int flags = 0;
+>    SDL_Surface *screen;
 
-    /* First, initialize SDL's video subsystem. */
-    if( SDL_Init( SDL_INIT_VIDEO ) < 0 ) {
-        /* Failed, exit. */
-        fprintf( stderr, "Video initialization failed: %s\n",
-             SDL_GetError( ) );
-        quit_tutorial( 1 );
-    }
-
-    /* Let's get some video information. */
-    info = SDL_GetVideoInfo( );
-
-    if( !info ) {
-        /* This should probably never happen. */
-        fprintf( stderr, "Video query failed: %s\n",
-             SDL_GetError( ) );
-        quit_tutorial( 1 );
+    /* Initialize the SDL library */
+    if( SDL_Init(SDL_INIT_VIDEO) < 0 ) {
+        fprintf(stderr,
+                "Couldn't initialize SDL: %s\n", SDL_GetError());
+        exit(1);
     }
 
-    /*
-     * Set our width/height to 640/480 (you would
-     * of course let the user decide this in a normal
-     * app). We get the bpp we will request from
-     * the display. On X11, VidMode can't change
-     * resolution, so this is probably being overly
-     * safe. Under Win32, ChangeDisplaySettings
-     * can change the bpp.
-     */
-    width = 640;
-    height = 480;
-    bpp = info->vfmt->BitsPerPixel;
-
+    /* Clean up on exit */
+    atexit(SDL_Quit);
+    
     /*
-     * Now, we want to setup our requested
-     * window attributes for our OpenGL window.
-     * We want *at least* 5 bits of red, green
-     * and blue. We also want at least a 16-bit
-     * depth buffer.
-     *
-     * The last thing we do is request a double
-     * buffered window. '1' turns on double
-     * buffering, '0' turns it off.
-     *
-     * Note that we do not use SDL_DOUBLEBUF in
-     * the flags to SDL_SetVideoMode. That does
-     * not affect the GL attribute state, only
-     * the standard 2D blitting setup.
+     * Initialize the display in a 640x480 8-bit palettized mode,
+     * requesting a software surface
      */
-    SDL_GL_SetAttribute( SDL_GL_RED_SIZE, 5 );
-    SDL_GL_SetAttribute( SDL_GL_GREEN_SIZE, 5 );
-    SDL_GL_SetAttribute( SDL_GL_BLUE_SIZE, 5 );
-    SDL_GL_SetAttribute( SDL_GL_DEPTH_SIZE, 16 );
-    SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 );
-
-    /*
-     * We want to request that SDL provide us
-     * with an OpenGL window, in a fullscreen
-     * video mode.
-     *
-     * EXERCISE:
-     * Make starting windowed an option, and
-     * handle the resize events properly with
-     * glViewport.
-     */
-    flags = SDL_OPENGL | SDL_FULLSCREEN;
-
-    /*
-     * Set the video mode
-     */
-    if( SDL_SetVideoMode( width, height, bpp, flags ) == 0 ) {
-        /* 
-         * This could happen for a variety of reasons,
-         * including DISPLAY not being set, the specified
-         * resolution not being available, etc.
-         */
-        fprintf( stderr, "Video mode set failed: %s\n",
-             SDL_GetError( ) );
-        quit_tutorial( 1 );
+    screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE);
+    if ( screen == NULL ) {
+        fprintf(stderr, "Couldn't set 640x480x8 video mode: %s\n",
+                        SDL_GetError());
+        exit(1);
     }

Initializing the Best Video Mode

If you have a preference for a certain pixel depth but will accept any +other, use SDL_SetVideoMode with SDL_ANYFORMAT as below. You can also +use SDL_VideoModeOK() to find the native video mode that is closest to +the mode you request.

Example 2-2. Initializing the Best Video Mode

    /* Have a preference for 8-bit, but accept any depth */
+    screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE|SDL_ANYFORMAT);
+    if ( screen == NULL ) {
+        fprintf(stderr, "Couldn't set 640x480x8 video mode: %s\n",
+                        SDL_GetError());
+        exit(1);
+    }
+    printf("Set 640x480 at %d bits-per-pixel mode\n",
+           screen->format->BitsPerPixel);

DrawingLoading and Displaying a BMP File

Apart from initialisation, using OpenGL within SDL is the same as using. However if you have request a double buffered display (using SDL_GL_SetAttribute) and one (which can be checked by using SDL_GL_GetAttribute), then you must use SDL_GL_SwapBuffers() to swap the buffers and update the display.

A full example code listing is now presented below.

The following function loads and displays a BMP file given as +argument, once SDL is initialised and a video mode has been set.

Example 2-1. gl.c - SDL OpenGL ExampleExample 2-3. Loading and Displaying a BMP File

void display_bmp(char *file_name)
+{
+    SDL_Surface *image;
+
+    /* Load the BMP file into a surface */
+    image = SDL_LoadBMP(file_name);
+    if (image == NULL) {
+        fprintf(stderr, "Couldn't load %s: %s\n", file_name, SDL_GetError());
+        return;
+    }
+
+    /*
+     * Palettized screen modes will have a default palette (a standard
+     * 8*8*4 colour cube), but if the image is palettized as well we can
+     * use that palette for a nicer colour matching
+     */
+    if (image->format->palette && screen->format->palette) {
+    SDL_SetColors(screen, image->format->palette->colors, 0,
+                  image->format->palette->ncolors);
+    }
+
+    /* Blit onto the screen surface */
+    if(SDL_BlitSurface(image, NULL, screen, NULL) < 0)
+        fprintf(stderr, "BlitSurface error: %s\n", SDL_GetError());
+
+    SDL_UpdateRect(screen, 0, 0, image->w, image->h);
+
+    /* Free the allocated BMP surface */
+    SDL_FreeSurface(image);
+}

Drawing Directly to the Display

The following two functions can be used to get and set single +pixels of a surface. They are carefully written to work with any depth +currently supported by SDL. Remember to lock the surface before +calling them, and to unlock it before calling any other SDL +functions.

To convert between pixel values and their red, green, blue +components, use SDL_GetRGB() and SDL_MapRGB().

Example 2-4. getpixel()

/*
- * SDL OpenGL Tutorial.
- * (c) Michael Vance, 2000
- * briareos@lokigames.com
- *
- * Distributed under terms of the LGPL. 
+ * Return the pixel value at (x, y)
+ * NOTE: The surface must be locked before calling this!
  */
-
-#include <SDL/SDL.h>
-#include <GL/gl.h>
-#include <GL/glu.h>
-
-#include <stdio.h>
-#include <stdlib.h>
-
-static GLboolean should_rotate = GL_TRUE;
-
-static void quit_tutorial( int code )
+Uint32 getpixel(SDL_Surface *surface, int x, int y)
 {
-    /*
-     * Quit SDL so we can release the fullscreen
-     * mode and restore the previous video settings,
-     * etc.
-     */
-    SDL_Quit( );
+    int bpp = surface->format->BytesPerPixel;
+    /* Here p is the address to the pixel we want to retrieve */
+    Uint8 *p = (Uint8 *)surface->pixels + y * surface->pitch + x * bpp;
+
+    switch(bpp) {
+    case 1:
+        return *p;
 
-    /* Exit program. */
-    exit( code );
-}
+    case 2:
+        return *(Uint16 *)p;
 
-static void handle_key_down( SDL_keysym* keysym )
-{
+    case 3:
+        if(SDL_BYTEORDER == SDL_BIG_ENDIAN)
+            return p[0] << 16 | p[1] << 8 | p[2];
+        else
+            return p[0] | p[1] << 8 | p[2] << 16;
+
+    case 4:
+        return *(Uint32 *)p;
 
-    /* 
-     * We're only interested if 'Esc' has
-     * been presssed.
-     *
-     * EXERCISE: 
-     * Handle the arrow keys and have that change the
-     * viewing position/angle.
-     */
-    switch( keysym->sym ) {
-    case SDLK_ESCAPE:
-        quit_tutorial( 0 );
+    default:
+        return 0;       /* shouldn't happen, but avoids warnings */
+    }
+}

Example 2-5. putpixel()

/*
+ * Set the pixel at (x, y) to the given value
+ * NOTE: The surface must be locked before calling this!
+ */
+void putpixel(SDL_Surface *surface, int x, int y, Uint32 pixel)
+{
+    int bpp = surface->format->BytesPerPixel;
+    /* Here p is the address to the pixel we want to set */
+    Uint8 *p = (Uint8 *)surface->pixels + y * surface->pitch + x * bpp;
+
+    switch(bpp) {
+    case 1:
+        *p = pixel;
         break;
-    case SDLK_SPACE:
-        should_rotate = !should_rotate;
+
+    case 2:
+        *(Uint16 *)p = pixel;
         break;
-    default:
+
+    case 3:
+        if(SDL_BYTEORDER == SDL_BIG_ENDIAN) {
+            p[0] = (pixel >> 16) & 0xff;
+            p[1] = (pixel >> 8) & 0xff;
+            p[2] = pixel & 0xff;
+        } else {
+            p[0] = pixel & 0xff;
+            p[1] = (pixel >> 8) & 0xff;
+            p[2] = (pixel >> 16) & 0xff;
+        }
+        break;
+
+    case 4:
+        *(Uint32 *)p = pixel;
         break;
     }
-
-}
-
-static void process_events( void )
-{
-    /* Our SDL event placeholder. */
-    SDL_Event event;
-
-    /* Grab all the events off the queue. */
-    while( SDL_PollEvent( &event ) ) {
-
-        switch( event.type ) {
-        case SDL_KEYDOWN:
-            /* Handle key presses. */
-            handle_key_down( &event.key.keysym );
-            break;
-        case SDL_QUIT:
-            /* Handle quit requests (like Ctrl-c). */
-            quit_tutorial( 0 );
-            break;
-        }
-
-    }
-
-}
-
-static void draw_screen( void )
-{
-    /* Our angle of rotation. */
-    static float angle = 0.0f;
+}

The following code uses the putpixel() function above to set a +yellow pixel in the middle of the screen.

Example 2-6. Using putpixel()

    /* Code to set a yellow pixel at the center of the screen */
 
-    /*
-     * EXERCISE:
-     * Replace this awful mess with vertex
-     * arrays and a call to glDrawElements.
-     *
-     * EXERCISE:
-     * After completing the above, change
-     * it to use compiled vertex arrays.
-     *
-     * EXERCISE:
-     * Verify my windings are correct here ;).
-     */
-    static GLfloat v0[] = { -1.0f, -1.0f,  1.0f };
-    static GLfloat v1[] = {  1.0f, -1.0f,  1.0f };
-    static GLfloat v2[] = {  1.0f,  1.0f,  1.0f };
-    static GLfloat v3[] = { -1.0f,  1.0f,  1.0f };
-    static GLfloat v4[] = { -1.0f, -1.0f, -1.0f };
-    static GLfloat v5[] = {  1.0f, -1.0f, -1.0f };
-    static GLfloat v6[] = {  1.0f,  1.0f, -1.0f };
-    static GLfloat v7[] = { -1.0f,  1.0f, -1.0f };
-    static GLubyte red[]    = { 255,   0,   0, 255 };
-    static GLubyte green[]  = {   0, 255,   0, 255 };
-    static GLubyte blue[]   = {   0,   0, 255, 255 };
-    static GLubyte white[]  = { 255, 255, 255, 255 };
-    static GLubyte yellow[] = {   0, 255, 255, 255 };
-    static GLubyte black[]  = {   0,   0,   0, 255 };
-    static GLubyte orange[] = { 255, 255,   0, 255 };
-    static GLubyte purple[] = { 255,   0, 255,   0 };
+    int x, y;
+    Uint32 yellow;
+
+    /* Map the color yellow to this display (R=0xff, G=0xFF, B=0x00)
+       Note:  If the display is palettized, you must set the palette first.
+    */
+    yellow = SDL_MapRGB(screen->format, 0xff, 0xff, 0x00);
 
-    /* Clear the color and depth buffers. */
-    glClear( GL_COLOR_BUFFER_BIT | GL_DEPTH_BUFFER_BIT );
-
-    /* We don't want to modify the projection matrix. */
-    glMatrixMode( GL_MODELVIEW );
-    glLoadIdentity( );
-
-    /* Move down the z-axis. */
-    glTranslatef( 0.0, 0.0, -5.0 );
+    x = screen->w / 2;
+    y = screen->h / 2;
 
-    /* Rotate. */
-    glRotatef( angle, 0.0, 1.0, 0.0 );
-
-    if( should_rotate ) {
-
-        if( ++angle > 360.0f ) {
-            angle = 0.0f;
+    /* Lock the screen for direct access to the pixels */
+    if ( SDL_MUSTLOCK(screen) ) {
+        if ( SDL_LockSurface(screen) < 0 ) {
+            fprintf(stderr, "Can't lock screen: %s\n", SDL_GetError());
+            return;
         }
-
     }
 
-    /* Send our triangle data to the pipeline. */
-    glBegin( GL_TRIANGLES );
-
-    glColor4ubv( red );
-    glVertex3fv( v0 );
-    glColor4ubv( green );
-    glVertex3fv( v1 );
-    glColor4ubv( blue );
-    glVertex3fv( v2 );
-
-    glColor4ubv( red );
-    glVertex3fv( v0 );
-    glColor4ubv( blue );
-    glVertex3fv( v2 );
-    glColor4ubv( white );
-    glVertex3fv( v3 );
-
-    glColor4ubv( green );
-    glVertex3fv( v1 );
-    glColor4ubv( black );
-    glVertex3fv( v5 );
-    glColor4ubv( orange );
-    glVertex3fv( v6 );
-
-    glColor4ubv( green );
-    glVertex3fv( v1 );
-    glColor4ubv( orange );
-    glVertex3fv( v6 );
-    glColor4ubv( blue );
-    glVertex3fv( v2 );
-
-    glColor4ubv( black );
-    glVertex3fv( v5 );
-    glColor4ubv( yellow );
-    glVertex3fv( v4 );
-    glColor4ubv( purple );
-    glVertex3fv( v7 );
-
-    glColor4ubv( black );
-    glVertex3fv( v5 );
-    glColor4ubv( purple );
-    glVertex3fv( v7 );
-    glColor4ubv( orange );
-    glVertex3fv( v6 );
-
-    glColor4ubv( yellow );
-    glVertex3fv( v4 );
-    glColor4ubv( red );
-    glVertex3fv( v0 );
-    glColor4ubv( white );
-    glVertex3fv( v3 );
-
-    glColor4ubv( yellow );
-    glVertex3fv( v4 );
-    glColor4ubv( white );
-    glVertex3fv( v3 );
-    glColor4ubv( purple );
-    glVertex3fv( v7 );
-
-    glColor4ubv( white );
-    glVertex3fv( v3 );
-    glColor4ubv( blue );
-    glVertex3fv( v2 );
-    glColor4ubv( orange );
-    glVertex3fv( v6 );
-
-    glColor4ubv( white );
-    glVertex3fv( v3 );
-    glColor4ubv( orange );
-    glVertex3fv( v6 );
-    glColor4ubv( purple );
-    glVertex3fv( v7 );
-
-    glColor4ubv( green );
-    glVertex3fv( v1 );
-    glColor4ubv( red );
-    glVertex3fv( v0 );
-    glColor4ubv( yellow );
-    glVertex3fv( v4 );
-
-    glColor4ubv( green );
-    glVertex3fv( v1 );
-    glColor4ubv( yellow );
-    glVertex3fv( v4 );
-    glColor4ubv( black );
-    glVertex3fv( v5 );
-
-    glEnd( );
-
-    /*
-     * EXERCISE:
-     * Draw text telling the user that 'Spc'
-     * pauses the rotation and 'Esc' quits.
-     * Do it using vetors and textured quads.
-     */
-
-    /*
-     * Swap the buffers. This this tells the driver to
-     * render the next frame from the contents of the
-     * back-buffer, and to set all rendering operations
-     * to occur on what was the front-buffer.
-     *
-     * Double buffering prevents nasty visual tearing
-     * from the application drawing on areas of the
-     * screen that are being updated at the same time.
-     */
-    SDL_GL_SwapBuffers( );
-}
-
-static void setup_opengl( int width, int height )
-{
-    float ratio = (float) width / (float) height;
-
-    /* Our shading model--Gouraud (smooth). */
-    glShadeModel( GL_SMOOTH );
-
-    /* Culling. */
-    glCullFace( GL_BACK );
-    glFrontFace( GL_CCW );
-    glEnable( GL_CULL_FACE );
-
-    /* Set the clear color. */
-    glClearColor( 0, 0, 0, 0 );
-
-    /* Setup our viewport. */
-    glViewport( 0, 0, width, height );
+    putpixel(screen, x, y, yellow);
 
-    /*
-     * Change to the projection matrix and set
-     * our viewing volume.
-     */
-    glMatrixMode( GL_PROJECTION );
-    glLoadIdentity( );
-    /*
-     * EXERCISE:
-     * Replace this with a call to glFrustum.
-     */
-    gluPerspective( 60.0, ratio, 1.0, 1024.0 );
-}
-
-int main( int argc, char* argv[] )
-{
-    /* Information about the current video settings. */
-    const SDL_VideoInfo* info = NULL;
-    /* Dimensions of our window. */
-    int width = 0;
-    int height = 0;
-    /* Color depth in bits of our window. */
-    int bpp = 0;
-    /* Flags we will pass into SDL_SetVideoMode. */
-    int flags = 0;
-
-    /* First, initialize SDL's video subsystem. */
-    if( SDL_Init( SDL_INIT_VIDEO ) < 0 ) {
-        /* Failed, exit. */
-        fprintf( stderr, "Video initialization failed: %s\n",
-             SDL_GetError( ) );
-        quit_tutorial( 1 );
+    if ( SDL_MUSTLOCK(screen) ) {
+        SDL_UnlockSurface(screen);
     }
-
-    /* Let's get some video information. */
-    info = SDL_GetVideoInfo( );
-
-    if( !info ) {
-        /* This should probably never happen. */
-        fprintf( stderr, "Video query failed: %s\n",
-             SDL_GetError( ) );
-        quit_tutorial( 1 );
-    }
-
-    /*
-     * Set our width/height to 640/480 (you would
-     * of course let the user decide this in a normal
-     * app). We get the bpp we will request from
-     * the display. On X11, VidMode can't change
-     * resolution, so this is probably being overly
-     * safe. Under Win32, ChangeDisplaySettings
-     * can change the bpp.
-     */
-    width = 640;
-    height = 480;
-    bpp = info->vfmt->BitsPerPixel;
+    /* Update just the part of the display that we've changed */
+    SDL_UpdateRect(screen, x, y, 1, 1);
 
-    /*
-     * Now, we want to setup our requested
-     * window attributes for our OpenGL window.
-     * We want *at least* 5 bits of red, green
-     * and blue. We also want at least a 16-bit
-     * depth buffer.
-     *
-     * The last thing we do is request a double
-     * buffered window. '1' turns on double
-     * buffering, '0' turns it off.
-     *
-     * Note that we do not use SDL_DOUBLEBUF in
-     * the flags to SDL_SetVideoMode. That does
-     * not affect the GL attribute state, only
-     * the standard 2D blitting setup.
-     */
-    SDL_GL_SetAttribute( SDL_GL_RED_SIZE, 5 );
-    SDL_GL_SetAttribute( SDL_GL_GREEN_SIZE, 5 );
-    SDL_GL_SetAttribute( SDL_GL_BLUE_SIZE, 5 );
-    SDL_GL_SetAttribute( SDL_GL_DEPTH_SIZE, 16 );
-    SDL_GL_SetAttribute( SDL_GL_DOUBLEBUFFER, 1 );
-
-    /*
-     * We want to request that SDL provide us
-     * with an OpenGL window, in a fullscreen
-     * video mode.
-     *
-     * EXERCISE:
-     * Make starting windowed an option, and
-     * handle the resize events properly with
-     * glViewport.
-     */
-    flags = SDL_OPENGL | SDL_FULLSCREEN;
-
-    /*
-     * Set the video mode
-     */
-    if( SDL_SetVideoMode( width, height, bpp, flags ) == 0 ) {
-        /* 
-         * This could happen for a variety of reasons,
-         * including DISPLAY not being set, the specified
-         * resolution not being available, etc.
-         */
-        fprintf( stderr, "Video mode set failed: %s\n",
-             SDL_GetError( ) );
-        quit_tutorial( 1 );
-    }
-
-    /*
-     * At this point, we should have a properly setup
-     * double-buffered window for use with OpenGL.
-     */
-    setup_opengl( width, height );
-
-    /*
-     * Now we want to begin our normal app process--
-     * an event loop with a lot of redrawing.
-     */
-    while( 1 ) {
-        /* Process incoming events. */
-        process_events( );
-        /* Draw the screen. */
-        draw_screen( );
-    }
-
-    /*
-     * EXERCISE:
-     * Record timings using SDL_GetTicks() and
-     * and print out frames per second at program
-     * end.
-     */
-
-    /* Never reached. */
-    return 0;
-}

NextInput handlingUsing OpenGL With SDL

SDL Library Documentation
Prev	Chapter 2. Graphics and Video	Next