Mercurial > sdl-ios-xcode
view docs/html/sdlblitsurface.html @ 1643:51038e80ae59
More general fix for bug #189
The clipping is done at a higher level, and the low level functions are
passed clipped rectangles. Drivers which don't support source clipping
have not been changed, so the image will be squished instead of clipped,
but at least they will no longer crash when the destination rect was out
of bounds.
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Mon, 17 Apr 2006 06:47:23 +0000 |
parents | 355632dca928 |
children |
line wrap: on
line source
<HTML ><HEAD ><TITLE >SDL_BlitSurface</TITLE ><META NAME="GENERATOR" CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+ "><LINK REL="HOME" TITLE="SDL Library Documentation" HREF="index.html"><LINK REL="UP" TITLE="Video" HREF="video.html"><LINK REL="PREVIOUS" TITLE="SDL_ConvertSurface" HREF="sdlconvertsurface.html"><LINK REL="NEXT" TITLE="SDL_FillRect" HREF="sdlfillrect.html"></HEAD ><BODY CLASS="REFENTRY" BGCOLOR="#FFF8DC" TEXT="#000000" LINK="#0000ee" VLINK="#551a8b" ALINK="#ff0000" ><DIV CLASS="NAVHEADER" ><TABLE SUMMARY="Header navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TH COLSPAN="3" ALIGN="center" >SDL Library Documentation</TH ></TR ><TR ><TD WIDTH="10%" ALIGN="left" VALIGN="bottom" ><A HREF="sdlconvertsurface.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="80%" ALIGN="center" VALIGN="bottom" ></TD ><TD WIDTH="10%" ALIGN="right" VALIGN="bottom" ><A HREF="sdlfillrect.html" ACCESSKEY="N" >Next</A ></TD ></TR ></TABLE ><HR ALIGN="LEFT" WIDTH="100%"></DIV ><H1 ><A NAME="SDLBLITSURFACE" ></A >SDL_BlitSurface</H1 ><DIV CLASS="REFNAMEDIV" ><A NAME="AEN2299" ></A ><H2 >Name</H2 >SDL_BlitSurface -- This performs a fast blit from the source surface to the destination surface.</DIV ><DIV CLASS="REFSYNOPSISDIV" ><A NAME="AEN2302" ></A ><H2 >Synopsis</H2 ><DIV CLASS="FUNCSYNOPSIS" ><A NAME="AEN2303" ></A ><P ></P ><PRE CLASS="FUNCSYNOPSISINFO" >#include "SDL.h"</PRE ><P ><CODE ><CODE CLASS="FUNCDEF" >int <B CLASS="FSFUNC" >SDL_BlitSurface</B ></CODE >(SDL_Surface *src, SDL_Rect *srcrect, SDL_Surface *dst, SDL_Rect *dstrect);</CODE ></P ><P ></P ></DIV ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN2309" ></A ><H2 >Description</H2 ><P >This performs a fast blit from the source surface to the destination surface.</P ><P >The width and height in <TT CLASS="PARAMETER" ><I >srcrect</I ></TT > determine the size of the copied rectangle. Only the position is used in the <TT CLASS="PARAMETER" ><I >dstrect</I ></TT > (the width and height are ignored).</P ><P >If <TT CLASS="PARAMETER" ><I >srcrect</I ></TT > is <TT CLASS="LITERAL" >NULL</TT >, the entire surface is copied. If <TT CLASS="PARAMETER" ><I >dstrect</I ></TT > is <TT CLASS="LITERAL" >NULL</TT >, then the destination position (upper left corner) is (0, 0).</P ><P >The final blit rectangle is saved in <TT CLASS="PARAMETER" ><I >dstrect</I ></TT > after all clipping is performed (<TT CLASS="PARAMETER" ><I >srcrect</I ></TT > is not modified).</P ><P >The blit function should not be called on a locked surface.</P ><P >The results of blitting operations vary greatly depending on whether <TT CLASS="LITERAL" >SDL_SRCAPLHA</TT > is set or not. See <A HREF="sdlsetalpha.html" >SDL_SetAlpha</A > 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. <PRE CLASS="PROGRAMLISTING" >if (source surface has SDL_SRCALPHA set) { if (source surface has alpha channel (that is, format->Amask != 0)) blit using per-pixel alpha, ignoring any colour key else { if (source surface has SDL_SRCCOLORKEY set) blit using the colour key AND the per-surface alpha value else blit using the per-surface alpha value } } else { if (source surface has SDL_SRCCOLORKEY set) blit using the colour key else ordinary opaque rectangular blit }</PRE ></P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN2328" ></A ><H2 >Return Value</H2 ><P >If the blit is successful, it returns <SPAN CLASS="RETURNVALUE" >0</SPAN >, otherwise it returns <SPAN CLASS="RETURNVALUE" >-1</SPAN >.</P ><P >If either of the surfaces were in video memory, and the blit returns <SPAN CLASS="RETURNVALUE" >-2</SPAN >, the video memory was lost, so it should be reloaded with artwork and re-blitted: <PRE CLASS="PROGRAMLISTING" > while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) { while ( SDL_LockSurface(image)) < 0 ) SDL_Delay(10); -- Write image pixels to image->pixels -- SDL_UnlockSurface(image); }</PRE > This happens under DirectX 5.0 when the system switches away from your fullscreen application. Locking the surface will also fail until you have access to the video memory again.</P ></DIV ><DIV CLASS="REFSECT1" ><A NAME="AEN2336" ></A ><H2 >See Also</H2 ><P ><A HREF="sdllocksurface.html" ><TT CLASS="FUNCTION" >SDL_LockSurface</TT ></A >, <A HREF="sdlfillrect.html" ><TT CLASS="FUNCTION" >SDL_FillRect</TT ></A >, <A HREF="sdlsurface.html" ><SPAN CLASS="STRUCTNAME" >SDL_Surface</SPAN ></A >, <A HREF="sdlrect.html" ><SPAN CLASS="STRUCTNAME" >SDL_Rect</SPAN ></A ></P ></DIV ><DIV CLASS="NAVFOOTER" ><HR ALIGN="LEFT" WIDTH="100%"><TABLE SUMMARY="Footer navigation table" WIDTH="100%" BORDER="0" CELLPADDING="0" CELLSPACING="0" ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" ><A HREF="sdlconvertsurface.html" ACCESSKEY="P" >Prev</A ></TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="index.html" ACCESSKEY="H" >Home</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" ><A HREF="sdlfillrect.html" ACCESSKEY="N" >Next</A ></TD ></TR ><TR ><TD WIDTH="33%" ALIGN="left" VALIGN="top" >SDL_ConvertSurface</TD ><TD WIDTH="34%" ALIGN="center" VALIGN="top" ><A HREF="video.html" ACCESSKEY="U" >Up</A ></TD ><TD WIDTH="33%" ALIGN="right" VALIGN="top" >SDL_FillRect</TD ></TR ></TABLE ></DIV ></BODY ></HTML >