Creating a window in libSDL

A window in an application is the most basic part of the drawing process. LibSDL offers a way to create one regardless of the graphical environment or operating system being used. Each window uses the surface object, which contains basic information about the drawing context, such as the inner window size, color depth, pixel format settings and optional flag variables to set up the drawing process. LuaSDL allows you to set up these window parameters in a simple manner.

Moreover, libSDL operates with the screen as the surface object representation. LibSDL 1.2 allows you to use only one window, while the current version of libSDL 2.0 allows multiple windows. This might be the deciding factor when deciding whether to use the older version of LuaSDL or the newer LuaSDL 2.

Getting ready

LibSDL 1.2 offers an old interface to set up a window but it's sufficient for simple games and multimedia applications. Most likely you'll want to use the whole screen for your application, so you'll need to set up a fullscreen mode. You can achieve this with the flag parameter SDL.SDL_FULLSCREEN in the SDL.SDL_SetVideoMode function. All flag parameters consist of bitmasks, so you need to use the binary OR operator to construct the final flag value.

LibSDL tries to use the accelerated window drawing if it's available on the target platform. Without this feature, all the drawing is processed in software mode, which is substantially slower than hardware-accelerated drawing. You can check for the hardware acceleration feature with the SDL.SDL_GetVideoInfo function. It returns a table with the following content:

Be aware that each field except vfmt contains a numerical value.

LibSDL 1.2 doesn't contain full support for DirectX acceleration on Windows platforms, so you may end up with windib video driver. This means you won't be able to use hardware-accelerated surfaces. Software-based blitting is generally a slow process as it accompanies RAM to RAM data copy. In this case, most of you will fall back to OpenGL acceleration, which is fine because OpenGL is known to be platform independent and almost every graphic card supports OpenGL nowadays.

To get the name of the current video driver, you need to call the SDL.SDL_VideoDriverName function. However, there's a catch to call this function properly mainly due to Lua++ binding.

The current workaround looks like this:

-- let Lua to allocate a string
local str = string.rep(" ", 256)
str = SDL.SDL_VideoDriverName(str, #str)

This will prepare the str variable to be able to contain at most 256 characters, which is sufficient in most cases. The str variable will be filled with a name of the current video driver. Fortunately, the length of the string variable indicates the maximum length of the video driver name. Longer driver names are truncated to the specified length. This issue is resolved in LuaSDL 2.

How to do it…

You can set up your screen with the SDL.SDL_SetVideoMode function with formal definition:

SDL.SDL_SetVideoMode(width, height, bpp, flags)

This function will return the surface object or nil on failure. Screen width and height are in pixels. Each pixel is represented by a color value stored in a binary form. Bits per pixel or the bpp parameter specifies how many bits are used to describe one pixel. Each color value uses the RGB (red, green, blue) color representation. Usually, each color channel uses the same amount of bits. However, other surface objects in the libSDL library may use other binary representations for colors. For instance, RGB channels may be in reverse order or there may be a different size for each color channel. The problematics of pixel format description and doing conversion between them is well explained in an article at https://www.opengl.org/wiki/Image_Format.

You can also use the bpp parameter with zero value in case you want to use the current screen bpp setting. This will automatically turn on the SDL.SDL_ANYFORMAT flag.

Optional flags define surface capabilities. You can combine them together with the binary OR operator from the bit library. The flag values are described in the following table:

How it works…

The first call of the SDL_SetVideoMode function will always try to create a window. It will allocate the necessary memory to store the window content in a surface object. However, this surface object is automatically freed upon the call of the SDL.SDL_Quit function and should not be freed manually.

Note that the SDL_SetVideoMode function will use the pixel format specified by the bpp parameter even if it's not supported by the current hardware. In such cases, the surface object is also called a shadow surface and it means that the libSDL library will do automatic pixel format conversion when you display content on the screen. This conversion will slow down screen rendering a bit. You can avoid this by using the SDL.SDL_ANYFORMAT flag in the SDL_SetVideMode function.