• SDL_SetVideoMode

SDL_SetVideoMode function

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

Syntax

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

Description

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

Parameters

width [in]

• The desired width in pixels of the video mode to set

height [in]

• The desired height in pixels of the video mode to set. As of SDL 1.2.10, if width and height are both 0, SDL_SetVideoMode will use the width and height of the current video mode (or the desktop mode, if no mode has been set).

bitsperpixel [in]

• The desired bits per pixel of the video mode to set. If bitsperpixel is 0, it is treated as the current display bits per pixel. A bitsperpixel of 24 uses the packed representation of 3 bytes per pixel. For the more common 4 bytes per pixel mode, please use a bitsperpixel of 32. Somewhat oddly, both 15 and 16 bits per pixel modes will request a 2 bytes per pixel mode, but with different pixel formats.

flags [in]

• The possible values for the flags parameter are the same used by the SDL_Surface structure. OR'd combinations of the following values are valid.

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

NULL

• On error. Call SDL_GetError to retrieve the last error message

The requested framebuffer surface

• On success. The returned surface is freed by SDL_Quit and must not be freed by the caller. This rule also includes consecutive calls to SDL_!SetVideoMode (i.e. resize or resolution change) because the existing surface will be released automatically. Whatever flags SDL_!SetVideoMode could satisfy are set in the flags member of the returned surface.

See also

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

Example

   1 #include <iostream>
   2 #include "SDL.h"
   3 
   4 // Initialize SDL and the video subsystem
   5 SDL_Init(SDL_INIT_VIDEO);
   6 
   7 // Set the video mode
   8 SDL_Surface* myVideoSurface = SDL_SetVideoMode(640, 480, 16, SDL_DOUBLEBUF|SDL_FULLSCREEN);
   9 
  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 }
  17 
  18 // Shut down the SDL and all its subsystems
  19 SDL_Quit();

Requirements

CategorySDLVideo