Contents  Basic Structures  SDL_Surface  Video Information  Creating and  Destroying Surfaces  Using SDL Video  Printable version  Discuss this article The Series  Setting Up Your  System for SDL  SDL Video

SDL_Surface

Just like the IDirectDrawSurface object in DirectDraw and the HDC in GDI, the SDL_Surface is the most important structure in the SDL video subsystem. It abstracts a rectangular area of pixel data. Here's what it looks like:

typedef struct SDL_Surface {
  Uint32 flags;
  SDL_PixelFormat *format;
  int w, h;
  Uint16 pitch;
  void *pixels;
  SDL_Rect clip_rect;
  int refcount;
} SDL_Surface;

There are actually more members than this, but they should not be publicly accessed, and so are not shown.

The flags member contains a combination of bit flags that describe what type of surface this is. These flags are listed and briefly explained in table 1.

*only the display surface may have these flags

The format member is a pointer to an SDL_PixelFormat structure that describes the pixel format for this surface.

The w and h members describe the width and height of the surface.

The pitch contains the number of bytes per scan line for the surface. Video cards being what they are, this value is often not the same as the BytesPerPixel times the width.

The pixels is a pointer to pixel data for the surface. It is used to read or write pixels to and from the surface.

The clip_rect member is an SDL_Rect that describes the clipping area of the surface. Any writing outside of this area will not be shown.

And finally, refcount is a reference count. When a surface is created, it is set to one. You can increment it manually. It is decremented whenever the surface is freed. Once it reaches 0, the surface is deleted from memory. This member is sort of like using AddRef for COM objects.

IMPORTANT NOTE: with the exception of refcount and the data pointed to by pixels, these members should not by modified by you directly. There are functions for dealing with and changing most of them.

SDL_VideoInfo

The last structure we're going to look at is SDL_VideoInfo. As you might expect, it contains information about the video display on the machine it is running on. Here's what it looks like:

typedef struct{
  Uint32 hw_available:1;
  Uint32 wm_available:1;
  Uint32 blit_hw:1;
  Uint32 blit_hw_CC:1;
  Uint32 blit_hw_A:1;
  Uint32 blit_sw:1;
  Uint32 blit_sw_CC:1;
  Uint32 blit_sw_A:1;
  Uint32 blit_fill:1;
  Uint32 video_mem;
  SDL_PixelFormat *vfmt;
} SDL_VideoInfo;

The closest equivalent in DirectDraw is the DDCAPS structure. SDL_VideoInfo, however, is much easier to read. Most of the members are single bits, and a value of 0 means that the feature in question is not supported, and 1 means that the feature is supported.

The hw_available indicates that you may create hardware surfaces, which naturally will be faster than software surface.

The wm_available indicates that a window manager is available. In WIN32, one is, but for other platforms, one might not be. The window manager is another subsystem of SDL that deals with some pretty basic settings for a window (if you are using windowed mode versus fullscreen).

The blit_hw, blit_hw_CC, and blit_hw_A all deal with the availability of hardware acceleration for blits between surface stored in hardware. The blit_hw bit specifies that generic hardware to hardware blits are accelerated, blit_hw_CC specifies that hardware to hardware colorkeyed blits are accelerated, and blit_hw_A specifies that hardware to hardware alpha blits are accelerated.

The blit_sw, blit_sw_CC, and blit_sw_A are much the same as the blit_hw members, except that they specify the capabilities for software to hardware blits instead.

The blit_fill member specifies that color fill operations are accelerated.

The video_mem contains, in kilobytes, the amount of video RAM for the system.

The vfmt member is a pointer to an SDL_PixelFormat. Depending on when you call it, it will contain either the "best" video format (the one with the most capabilities), or the current video format (depending on if you have already set up your display surface or not).

Next : Video Information