1 <HTML 2 ><HEAD 3 ><TITLE 4 >SDL_BlitSurface</TITLE 5 ><META 6 NAME="GENERATOR" 7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ 8 "><LINK 9 REL="HOME" 10 TITLE="SDL Library Documentation" 11 HREF="index.html"><LINK 12 REL="UP" 13 TITLE="Video" 14 HREF="video.html"><LINK 15 REL="PREVIOUS" 16 TITLE="SDL_ConvertSurface" 17 HREF="sdlconvertsurface.html"><LINK 18 REL="NEXT" 19 TITLE="SDL_FillRect" 20 HREF="sdlfillrect.html"></HEAD 21 ><BODY 22 CLASS="REFENTRY" 23 BGCOLOR="#FFF8DC" 24 TEXT="#000000" 25 LINK="#0000ee" 26 VLINK="#551a8b" 27 ALINK="#ff0000" 28 ><DIV 29 CLASS="NAVHEADER" 30 ><TABLE 31 SUMMARY="Header navigation table" 32 WIDTH="100%" 33 BORDER="0" 34 CELLPADDING="0" 35 CELLSPACING="0" 36 ><TR 37 ><TH 38 COLSPAN="3" 39 ALIGN="center" 40 >SDL Library Documentation</TH 41 ></TR 42 ><TR 43 ><TD 44 WIDTH="10%" 45 ALIGN="left" 46 VALIGN="bottom" 47 ><A 48 HREF="sdlconvertsurface.html" 49 ACCESSKEY="P" 50 >Prev</A 51 ></TD 52 ><TD 53 WIDTH="80%" 54 ALIGN="center" 55 VALIGN="bottom" 56 ></TD 57 ><TD 58 WIDTH="10%" 59 ALIGN="right" 60 VALIGN="bottom" 61 ><A 62 HREF="sdlfillrect.html" 63 ACCESSKEY="N" 64 >Next</A 65 ></TD 66 ></TR 67 ></TABLE 68 ><HR 69 ALIGN="LEFT" 70 WIDTH="100%"></DIV 71 ><H1 72 ><A 73 NAME="SDLBLITSURFACE" 74 ></A 75 >SDL_BlitSurface</H1 76 ><DIV 77 CLASS="REFNAMEDIV" 78 ><A 79 NAME="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 85 CLASS="REFSYNOPSISDIV" 86 ><A 87 NAME="AEN2302" 88 ></A 89 ><H2 90 >Synopsis</H2 91 ><DIV 92 CLASS="FUNCSYNOPSIS" 93 ><A 94 NAME="AEN2303" 95 ></A 96 ><P 97 ></P 98 ><PRE 99 CLASS="FUNCSYNOPSISINFO" 100 >#include "SDL.h"</PRE 101 ><P 102 ><CODE 103 ><CODE 104 CLASS="FUNCDEF" 105 >int <B 106 CLASS="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 116 CLASS="REFSECT1" 117 ><A 118 NAME="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 126 CLASS="PARAMETER" 127 ><I 128 >srcrect</I 129 ></TT 130 > determine the 131 size of the copied rectangle. Only the position is used in the 132 <TT 133 CLASS="PARAMETER" 134 ><I 135 >dstrect</I 136 ></TT 137 > (the width and height are ignored).</P 138 ><P 139 >If <TT 140 CLASS="PARAMETER" 141 ><I 142 >srcrect</I 143 ></TT 144 > is <TT 145 CLASS="LITERAL" 146 >NULL</TT 147 >, the 148 entire surface is copied. If <TT 149 CLASS="PARAMETER" 150 ><I 151 >dstrect</I 152 ></TT 153 > is 154 <TT 155 CLASS="LITERAL" 156 >NULL</TT 157 >, then the destination position (upper left 158 corner) is (0, 0).</P 159 ><P 160 >The final blit rectangle is saved in 161 <TT 162 CLASS="PARAMETER" 163 ><I 164 >dstrect</I 165 ></TT 166 > after all clipping is performed 167 (<TT 168 CLASS="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 177 CLASS="LITERAL" 178 >SDL_SRCAPLHA</TT 179 > is set or not. See <A 180 HREF="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 184 CLASS="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 203 CLASS="REFSECT1" 204 ><A 205 NAME="AEN2328" 206 ></A 207 ><H2 208 >Return Value</H2 209 ><P 210 >If the blit is successful, it returns <SPAN 211 CLASS="RETURNVALUE" 212 >0</SPAN 213 >, 214 otherwise it returns <SPAN 215 CLASS="RETURNVALUE" 216 >-1</SPAN 217 >.</P 218 ><P 219 >If either of the surfaces were in video memory, and the blit returns 220 <SPAN 221 CLASS="RETURNVALUE" 222 >-2</SPAN 223 >, the video memory was lost, so it should be 224 reloaded with artwork and re-blitted: 225 <PRE 226 CLASS="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 > 234 This happens under DirectX 5.0 when the system switches away from your 235 fullscreen application. Locking the surface will also fail until you 236 have access to the video memory again.</P 237 ></DIV 238 ><DIV 239 CLASS="REFSECT1" 240 ><A 241 NAME="AEN2336" 242 ></A 243 ><H2 244 >See Also</H2 245 ><P 246 ><A 247 HREF="sdllocksurface.html" 248 ><TT 249 CLASS="FUNCTION" 250 >SDL_LockSurface</TT 251 ></A 252 >, 253 <A 254 HREF="sdlfillrect.html" 255 ><TT 256 CLASS="FUNCTION" 257 >SDL_FillRect</TT 258 ></A 259 >, 260 <A 261 HREF="sdlsurface.html" 262 ><SPAN 263 CLASS="STRUCTNAME" 264 >SDL_Surface</SPAN 265 ></A 266 >, 267 <A 268 HREF="sdlrect.html" 269 ><SPAN 270 CLASS="STRUCTNAME" 271 >SDL_Rect</SPAN 272 ></A 273 ></P 274 ></DIV 275 ><DIV 276 CLASS="NAVFOOTER" 277 ><HR 278 ALIGN="LEFT" 279 WIDTH="100%"><TABLE 280 SUMMARY="Footer navigation table" 281 WIDTH="100%" 282 BORDER="0" 283 CELLPADDING="0" 284 CELLSPACING="0" 285 ><TR 286 ><TD 287 WIDTH="33%" 288 ALIGN="left" 289 VALIGN="top" 290 ><A 291 HREF="sdlconvertsurface.html" 292 ACCESSKEY="P" 293 >Prev</A 294 ></TD 295 ><TD 296 WIDTH="34%" 297 ALIGN="center" 298 VALIGN="top" 299 ><A 300 HREF="index.html" 301 ACCESSKEY="H" 302 >Home</A 303 ></TD 304 ><TD 305 WIDTH="33%" 306 ALIGN="right" 307 VALIGN="top" 308 ><A 309 HREF="sdlfillrect.html" 310 ACCESSKEY="N" 311 >Next</A 312 ></TD 313 ></TR 314 ><TR 315 ><TD 316 WIDTH="33%" 317 ALIGN="left" 318 VALIGN="top" 319 >SDL_ConvertSurface</TD 320 ><TD 321 WIDTH="34%" 322 ALIGN="center" 323 VALIGN="top" 324 ><A 325 HREF="video.html" 326 ACCESSKEY="U" 327 >Up</A 328 ></TD 329 ><TD 330 WIDTH="33%" 331 ALIGN="right" 332 VALIGN="top" 333 >SDL_FillRect</TD 334 ></TR 335 ></TABLE 336 ></DIV 337 ></BODY 338 ></HTML 339 >
