docs/html/sdlblitsurface.html

   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&nbsp;--&nbsp;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-&#62;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)) &#60; 0 )
 229                         SDL_Delay(10);
 230                 -- Write image pixels to image-&#62;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 >