docs/html/sdlblitsurface.html
changeset 3352 6dc250ebdd80
parent 3351 8e0182c236d8
child 3353 6b14223dd5c7
equal deleted inserted replaced
3351:8e0182c236d8 3352:6dc250ebdd80
     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 >