SDL_Overlay

Name

SDL_Overlay -- YUV video overlay

Structure Definition

typedef struct{
  Uint32 format;
  int w, h;
  int planes;
  Uint16 *pitches;
  Uint8 **pixels;
  Uint32 hw_overlay:1;
} SDL_Overlay;

Structure Data

format	Overlay format (see below)
w, h	Width and height of overlay
planes	Number of planes in the overlay. Usually either 1 or 3
pitches	An array of pitches, one for each plane. Pitch is the length of a row in bytes.
pixels	An array of pointers to the data of each plane. The overlay should be locked before these pointers are used.
hw_overlay	This will be set to 1 if the overlay is hardware accelerated.

Description

A SDL_Overlay is similar to a SDL_Surface except it stores a YUV overlay. All the fields are read only, except for pixels which should be locked before use. The format field stores the format of the overlay which is one of the following:

#define SDL_YV12_OVERLAY  0x32315659  /* Planar mode: Y + V + U */
#define SDL_IYUV_OVERLAY  0x56555949  /* Planar mode: Y + U + V */
#define SDL_YUY2_OVERLAY  0x32595559  /* Packed mode: Y0+U0+Y1+V0 */
#define SDL_UYVY_OVERLAY  0x59565955  /* Packed mode: U0+Y0+V0+Y1 */
#define SDL_YVYU_OVERLAY  0x55595659  /* Packed mode: Y0+V0+Y1+U0 */

More information on YUV formats can be found at http://www.fourcc.org/indexyuv.htm.

Using Overlays

Overlays are the best method available for rendering video. They are based on the YUV color formats, which come in either packed or planar formats. See the link above for detailed information on the different formats and their structures.

Create a new overlay using SDL_CreateYUVOverlay. Pass this the width, height, and format of the overlay, as well as a pointer to the SDL display it should be displayed on. The overlays are scalable, meaning the width and height of the overlay do not need to be the same as the width and height of the surface. As mentioned on the CreateYUVOverlay page, SDL is fastest at 2x scaling. An example:

my_overlay = SDL_CreateYUVOverlay(640, 480, SDL_IYUV_OVERLAY, main_surface);

In the above example, SDL_YV12_OVERLAY may achieve better acceleration availability, in spite of the IYUV and YV12 only having U and V planes swapped as a difference.

Next you need to fill in the video data field of the overlay struct. The data is placed in the pixels member of the overlay struct. The pixels member is actually an array of arrays, usually one or three, that coincides with the YUV format you are using. If you are using a planar format, there will be 3 arrays here, one each for the Y, U, and V color components. A packed format will only have one plane. The number of planes is stored in the planes member. Lock the pixels before modifying them. Here is an example:

/* Display number of planes */
printf("Planes: %d\n", my_overlay->planes);

/* Fill in video data */
y_video_data = .....
u_video_data = .....
v_video_data = .....

/* Fill in pixel data - the pitches array contains the length of a line in each plane */
SDL_LockYUVOverlay(my_overlay);
memcpy(my_overlay->pixels[0], y_video_data, my_overlay->pitches[0]);
memcpy(my_overlay->pixels[1], u_video_data, my_overlay->pitches[1]);
memcpy(my_overlay->pixels[2], v_video_data, my_overlay->pitches[2]);

/* Draw a single pixel on (x, y) */
*(my_overlay->pixels[0] + y * my_overlay->pitches[0] + x) = 0x10;
*(my_overlay->pixels[1] + y/2 * my_overlay->pitches[1] + x/2) = 0x80;
*(my_overlay->pixels[2] + y/2 * my_overlay->pitches[2] + x/2) = 0x80; 
 
SDL_UnlockYUVOverlay(my_overlay);

Finally, to display the video, call SDL_DisplayYUVOverlay. This call needs the overlay as well as a SDL_Rect that indicates the width and height (most importantly) the video should be displayed, as well as the x and y positions. Using this rect is how scaling is achieved. Note that scaling can be performed by the video card under some circumstances (main_surface initialized with flags SDL_ANYFORMAT and SDL_HWSURFACE set).

video_rect.x = 0;
video_rect.y = 0;
video_rect.w = 800;
video_rect.h = 600;

SDL_DisplayYUVOverlay(my_overlay, &video_rect);