SDL_SetVideoMode function

SDL_SetVideoMode -- Set up a video mode with the specified width, height and bits-per-pixel.


SDL_Surface* SDL_SetVideoMode(int width, int height, int bitsperpixel, Uint32 flags);


Set up a video mode with the specified width, height and bitsperpixel.


width [in]

height [in]

bitsperpixel [in]

flags [in]

List of flags values


Create the video surface in system memory


Create the video surface in video memory


Enables the use of asynchronous updates of the display surface. This will usually slow down blitting on single CPU machines, but may provide a speed increase on SMP systems.


Normally, if a video surface of the requested bits-per-pixel (bpp) is not available, SDL will emulate one with a shadow surface. Passing SDL_ANYFORMAT prevents this and causes SDL to use the video surface, regardless of its pixel depth.


Give SDL exclusive palette access. Without this flag you may not always get the colors you request with SDL_SetColors or SDL_SetPalette.


Enable hardware double buffering; only valid with SDL_HWSURFACE. Calling SDL_Flip will flip the buffers and update the screen. All drawing will take place on the surface that is not displayed at the moment. If double buffering could not be enabled then SDL_Flip will just perform a SDL_UpdateRect on the entire screen.


SDL will attempt to use a fullscreen mode. If a hardware resolution change is not possible (for whatever reason), the next higher resolution will be used and the display window centered on a black background.


Create an OpenGL rendering context. You should have previously set OpenGL video attributes with SDL_GL_SetAttribute.


Create an OpenGL rendering context, like above, but allow normal blitting operations. The screen (2D) surface may have an alpha channel, and SDL_UpdateRects must be used for updating changes to the screen surface. NOTE: This option is kept for compatibility only, and will be removed in next versions. Is not recommended for new code.


Create a resizable window. When the window is resized by the user a SDL_VIDEORESIZE event is generated and SDL_SetVideoMode can be called again with the new size.


If possible, SDL_NOFRAME causes SDL to create a window with no title bar or frame decoration. Fullscreen modes automatically have this flag set.

Note 1: Use SDL_SWSURFACE if you plan on doing per-pixel manipulations, or blit surfaces with alpha channels, and require a high framerate. When you use hardware surfaces (by passing the flag SDL_HWSURFACE as parameter), SDL copies the surfaces from video memory to system memory when you lock them, and back when you unlock them. This can cause a major performance hit. Be aware that you may request a hardware surface, but receive a software surface because the video driver doesn't support hardware surface. Many platforms can only provide a hardware surface when using SDL_FULLSCREEN. The SDL_HWSURFACE flag is best used when the surfaces you'll be blitting can also be stored in video memory.

Note 2: If you want to control the position on the screen when creating a windowed surface, you may do so by setting the environment variables SDL_VIDEO_CENTERED=center or SDL_VIDEO_WINDOW_POS=x,y. You can also set them via SDL_putenv.

Note 3: This function should be called in the main thread of your application.

User note 1: Some have found that enabling OpenGL attributes like SDL_GL_STENCIL_SIZE (the stencil buffer size) before the video mode has been set causes the application to simply ignore those attributes, while enabling attributes after the video mode has been set works fine.

User note 2: Also note that, in Windows, setting the video mode resets the current OpenGL context. You must execute again the OpenGL initialization code (set the clear color or the shade model, or reload textures, for example) after calling SDL_SetVideoMode. In Linux, however, it works fine, and the initialization code only needs to be executed after the first call to SDL_SetVideoMode (although there is no harm in executing the initialization code after each call to SDL_SetVideoMode, for example for a multiplatform application).

Return value


The requested framebuffer surface

See also

SDL_GetVideoSurface, SDL_GL_SetAttribute, SDL_LockSurface, SDL_SetColors, SDL_Flip, SDL_Surface, SDL_envvars


   1 #include <iostream>
   2 #include "SDL.h"
   4 // Initialize SDL and the video subsystem
   7 // Set the video mode
   8 SDL_Surface* myVideoSurface = SDL_SetVideoMode(640, 480, 16, SDL_DOUBLEBUF|SDL_FULLSCREEN);
  10 // Print out some information about the video surface
  11 if (myVideoSurface != NULL) {
  12     std::cout << "The current video surface bits per pixel is " << (int)myVideoSurface->format->BitsPerPixel << std::endl;
  13 }
  14 else {
  15     std::cerr << "Video initialization failed: " << SDL_GetError() << std::endl;
  16 }
  18 // Shut down the SDL and all its subsystems
  19 SDL_Quit();






Shared object




SDL_SetVideoMode (last edited 2010-02-16 00:32:51 by 4)