[sdl_omap.git] / docs / html / sdlblitsurface.html

<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&nbsp;--&nbsp;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-&#62;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)) &#60; 0 )
                        SDL_Delay(10);
                -- Write image pixels to image-&#62;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
>
Commit	Line	Data
e14743d1	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	>