#pragma section-numbers off
#pragma disable-camelcase

= SDL_ConvertSurface =
Use this function to copy an existing surface into a new one that is optimized for blitting to a surface of a specified pixel format.

<<TableOfContents()>>


== Syntax ==
{{{#!highlight cpp
SDL_Surface* SDL_ConvertSurface(SDL_Surface*           src,
                                const SDL_PixelFormat* fmt,
                                Uint32                 flags)
}}}


== Function Parameters ==
||'''src'''||the existing [[SDL_Surface]] structure to convert||
||'''fmt'''||the [[SDL_PixelFormat]] structure that the new surface is optimized for||
||'''flags'''||the flags are unused and should be set to 0; this is a leftover from SDL 1.2's API||

== Return Value ==
Returns the new [[SDL_Surface]] structure that is created or NULL if it fails; call [[SDL_GetError]]() for more information.

== Code Examples ==
{{{#!highlight cpp

// SDL_Surface *input = ...;
SDL_PixelFormat *format = SDL_AllocFormat(SDL_PIXELFORMAT_RGBA32);
SDL_Surface *output = SDL_ConvertSurface(input, format, 0);
SDL_FreeFormat(format);

}}}

== Remarks ==
This function is used to optimize images for faster ''repeat'' blitting.  This is accomplished by converting the original and storing the result as a new surface. The new, optimized surface can then be used as the source for future blits, making them faster.


== Related Functions ==
 .[[SDL_AllocFormat]]
 .[[SDL_ConvertSurfaceFormat]]
 .[[SDL_CreateRGBSurface]]

----
[[CategoryAPI]], [[CategorySurface]]