1<HTML 2><HEAD 3><TITLE 4>SDL_BlitSurface</TITLE 5><META 6NAME="GENERATOR" 7CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ 8"><LINK 9REL="HOME" 10TITLE="SDL Library Documentation" 11HREF="index.html"><LINK 12REL="UP" 13TITLE="Video" 14HREF="video.html"><LINK 15REL="PREVIOUS" 16TITLE="SDL_ConvertSurface" 17HREF="sdlconvertsurface.html"><LINK 18REL="NEXT" 19TITLE="SDL_FillRect" 20HREF="sdlfillrect.html"></HEAD 21><BODY 22CLASS="REFENTRY" 23BGCOLOR="#FFF8DC" 24TEXT="#000000" 25LINK="#0000ee" 26VLINK="#551a8b" 27ALINK="#ff0000" 28><DIV 29CLASS="NAVHEADER" 30><TABLE 31SUMMARY="Header navigation table" 32WIDTH="100%" 33BORDER="0" 34CELLPADDING="0" 35CELLSPACING="0" 36><TR 37><TH 38COLSPAN="3" 39ALIGN="center" 40>SDL Library Documentation</TH 41></TR 42><TR 43><TD 44WIDTH="10%" 45ALIGN="left" 46VALIGN="bottom" 47><A 48HREF="sdlconvertsurface.html" 49ACCESSKEY="P" 50>Prev</A 51></TD 52><TD 53WIDTH="80%" 54ALIGN="center" 55VALIGN="bottom" 56></TD 57><TD 58WIDTH="10%" 59ALIGN="right" 60VALIGN="bottom" 61><A 62HREF="sdlfillrect.html" 63ACCESSKEY="N" 64>Next</A 65></TD 66></TR 67></TABLE 68><HR 69ALIGN="LEFT" 70WIDTH="100%"></DIV 71><H1 72><A 73NAME="SDLBLITSURFACE" 74></A 75>SDL_BlitSurface</H1 76><DIV 77CLASS="REFNAMEDIV" 78><A 79NAME="AEN2299" 80></A 81><H2 82>Name</H2 83>SDL_BlitSurface -- This performs a fast blit from the source surface to the destination surface.</DIV 84><DIV 85CLASS="REFSYNOPSISDIV" 86><A 87NAME="AEN2302" 88></A 89><H2 90>Synopsis</H2 91><DIV 92CLASS="FUNCSYNOPSIS" 93><A 94NAME="AEN2303" 95></A 96><P 97></P 98><PRE 99CLASS="FUNCSYNOPSISINFO" 100>#include "SDL.h"</PRE 101><P 102><CODE 103><CODE 104CLASS="FUNCDEF" 105>int <B 106CLASS="FSFUNC" 107>SDL_BlitSurface</B 108></CODE 109>(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect);</CODE 110></P 111><P 112></P 113></DIV 114></DIV 115><DIV 116CLASS="REFSECT1" 117><A 118NAME="AEN2309" 119></A 120><H2 121>Description</H2 122><P 123>This performs a fast blit from the source surface to the destination surface.</P 124><P 125>The width and height in <TT 126CLASS="PARAMETER" 127><I 128>srcrect</I 129></TT 130> determine the 131size of the copied rectangle. Only the position is used in the 132<TT 133CLASS="PARAMETER" 134><I 135>dstrect</I 136></TT 137> (the width and height are ignored).</P 138><P 139>If <TT 140CLASS="PARAMETER" 141><I 142>srcrect</I 143></TT 144> is <TT 145CLASS="LITERAL" 146>NULL</TT 147>, the 148entire surface is copied. If <TT 149CLASS="PARAMETER" 150><I 151>dstrect</I 152></TT 153> is 154<TT 155CLASS="LITERAL" 156>NULL</TT 157>, then the destination position (upper left 158corner) is (0, 0).</P 159><P 160>The final blit rectangle is saved in 161<TT 162CLASS="PARAMETER" 163><I 164>dstrect</I 165></TT 166> after all clipping is performed 167(<TT 168CLASS="PARAMETER" 169><I 170>srcrect</I 171></TT 172> is not modified).</P 173><P 174>The blit function should not be called on a locked surface.</P 175><P 176>The results of blitting operations vary greatly depending on whether <TT 177CLASS="LITERAL" 178>SDL_SRCAPLHA</TT 179> is set or not. See <A 180HREF="sdlsetalpha.html" 181>SDL_SetAlpha</A 182> for an explaination of how this affects your results. Colorkeying and alpha attributes also interact with surface blitting, as the following pseudo-code should hopefully explain. 183<PRE 184CLASS="PROGRAMLISTING" 185>if (source surface has SDL_SRCALPHA set) { 186 if (source surface has alpha channel (that is, format->Amask != 0)) 187 blit using per-pixel alpha, ignoring any colour key 188 else { 189 if (source surface has SDL_SRCCOLORKEY set) 190 blit using the colour key AND the per-surface alpha value 191 else 192 blit using the per-surface alpha value 193 } 194} else { 195 if (source surface has SDL_SRCCOLORKEY set) 196 blit using the colour key 197 else 198 ordinary opaque rectangular blit 199}</PRE 200></P 201></DIV 202><DIV 203CLASS="REFSECT1" 204><A 205NAME="AEN2328" 206></A 207><H2 208>Return Value</H2 209><P 210>If the blit is successful, it returns <SPAN 211CLASS="RETURNVALUE" 212>0</SPAN 213>, 214otherwise it returns <SPAN 215CLASS="RETURNVALUE" 216>-1</SPAN 217>.</P 218><P 219>If either of the surfaces were in video memory, and the blit returns 220<SPAN 221CLASS="RETURNVALUE" 222>-2</SPAN 223>, the video memory was lost, so it should be 224reloaded with artwork and re-blitted: 225<PRE 226CLASS="PROGRAMLISTING" 227> while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { 228 while ( SDL_LockSurface(image)) < 0 ) 229 SDL_Delay(10); 230 -- Write image pixels to image->pixels -- 231 SDL_UnlockSurface(image); 232 }</PRE 233> 234This happens under DirectX 5.0 when the system switches away from your 235fullscreen application. Locking the surface will also fail until you 236have access to the video memory again.</P 237></DIV 238><DIV 239CLASS="REFSECT1" 240><A 241NAME="AEN2336" 242></A 243><H2 244>See Also</H2 245><P 246><A 247HREF="sdllocksurface.html" 248><TT 249CLASS="FUNCTION" 250>SDL_LockSurface</TT 251></A 252>, 253<A 254HREF="sdlfillrect.html" 255><TT 256CLASS="FUNCTION" 257>SDL_FillRect</TT 258></A 259>, 260<A 261HREF="sdlsurface.html" 262><SPAN 263CLASS="STRUCTNAME" 264>SDL_Surface</SPAN 265></A 266>, 267<A 268HREF="sdlrect.html" 269><SPAN 270CLASS="STRUCTNAME" 271>SDL_Rect</SPAN 272></A 273></P 274></DIV 275><DIV 276CLASS="NAVFOOTER" 277><HR 278ALIGN="LEFT" 279WIDTH="100%"><TABLE 280SUMMARY="Footer navigation table" 281WIDTH="100%" 282BORDER="0" 283CELLPADDING="0" 284CELLSPACING="0" 285><TR 286><TD 287WIDTH="33%" 288ALIGN="left" 289VALIGN="top" 290><A 291HREF="sdlconvertsurface.html" 292ACCESSKEY="P" 293>Prev</A 294></TD 295><TD 296WIDTH="34%" 297ALIGN="center" 298VALIGN="top" 299><A 300HREF="index.html" 301ACCESSKEY="H" 302>Home</A 303></TD 304><TD 305WIDTH="33%" 306ALIGN="right" 307VALIGN="top" 308><A 309HREF="sdlfillrect.html" 310ACCESSKEY="N" 311>Next</A 312></TD 313></TR 314><TR 315><TD 316WIDTH="33%" 317ALIGN="left" 318VALIGN="top" 319>SDL_ConvertSurface</TD 320><TD 321WIDTH="34%" 322ALIGN="center" 323VALIGN="top" 324><A 325HREF="video.html" 326ACCESSKEY="U" 327>Up</A 328></TD 329><TD 330WIDTH="33%" 331ALIGN="right" 332VALIGN="top" 333>SDL_FillRect</TD 334></TR 335></TABLE 336></DIV 337></BODY 338></HTML 339>