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

<HTML
><HEAD
><TITLE
>SDL_CreateRGBSurface</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_GetRGBA"
HREF="sdlgetrgba.html"><LINK
REL="NEXT"
TITLE="SDL_CreateRGBSurfaceFrom"
HREF="sdlcreatergbsurfacefrom.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="sdlgetrgba.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="sdlcreatergbsurfacefrom.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><H1
><A
NAME="SDLCREATERGBSURFACE"
></A
>SDL_CreateRGBSurface</H1
><DIV
CLASS="REFNAMEDIV"
><A
NAME="AEN1773"
></A
><H2
>Name</H2
>SDL_CreateRGBSurface&nbsp;--&nbsp;Create an empty SDL_Surface</DIV
><DIV
CLASS="REFSYNOPSISDIV"
><A
NAME="AEN1776"
></A
><H2
>Synopsis</H2
><DIV
CLASS="FUNCSYNOPSIS"
><A
NAME="AEN1777"
></A
><P
></P
><PRE
CLASS="FUNCSYNOPSISINFO"
>#include "SDL.h"</PRE
><P
><CODE
><CODE
CLASS="FUNCDEF"
>SDL_Surface *<B
CLASS="FSFUNC"
>SDL_CreateRGBSurface</B
></CODE
>(Uint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);</CODE
></P
><P
></P
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1783"
></A
><H2
>Description</H2
><P
>Allocate an empty surface (must be called after <A
HREF="sdlsetvideomode.html"
>SDL_SetVideoMode</A
>)</P
><P
>If <TT
CLASS="PARAMETER"
><I
>depth</I
></TT
> is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' <A
HREF="sdlpixelformat.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_PixelFormat</SPAN
></A
> is created using the <TT
CLASS="PARAMETER"
><I
>[RGBA]mask</I
></TT
>'s provided (see <A
HREF="sdlpixelformat.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_PixelFormat</SPAN
></A
>). The <TT
CLASS="PARAMETER"
><I
>flags</I
></TT
> specifies the type of surface that should be created, it is an OR'd combination of the following possible values.</P
><DIV
CLASS="INFORMALTABLE"
><A
NAME="AEN1795"
></A
><P
></P
><TABLE
BORDER="1"
CLASS="CALSTABLE"
><TBODY
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>SDL_SWSURFACE</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>SDL_HWSURFACE</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video-&#62;Video blits (which are often accelerated).</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>SDL_SRCCOLORKEY</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>This flag turns on colourkeying for blits from this surface. If
<TT
CLASS="LITERAL"
>SDL_HWSURFACE</TT
> is also specified and colourkeyed blits
are hardware-accelerated, then SDL will attempt to place the surface in
video memory.
Use <A
HREF="sdlsetcolorkey.html"
><TT
CLASS="FUNCTION"
>SDL_SetColorKey</TT
></A
>
to set or clear this flag after surface creation.</TD
></TR
><TR
><TD
ALIGN="LEFT"
VALIGN="TOP"
><TT
CLASS="LITERAL"
>SDL_SRCALPHA</TT
></TD
><TD
ALIGN="LEFT"
VALIGN="TOP"
>This flag turns on alpha-blending for blits from this surface. If
<TT
CLASS="LITERAL"
>SDL_HWSURFACE</TT
> is also specified and alpha-blending blits
are hardware-accelerated, then the surface will be placed in video memory if
possible.
Use <A
HREF="sdlsetalpha.html"
><TT
CLASS="FUNCTION"
>SDL_SetAlpha</TT
></A
> to
set or clear this flag after surface creation.</TD
></TR
></TBODY
></TABLE
><P
></P
></DIV
><DIV
CLASS="NOTE"
><BLOCKQUOTE
CLASS="NOTE"
><P
><B
>Note: </B
>If an alpha-channel is specified (that is, if <TT
CLASS="PARAMETER"
><I
>Amask</I
></TT
> is
nonzero), then the <TT
CLASS="LITERAL"
>SDL_SRCALPHA</TT
> flag is automatically
set. You may remove this flag by calling 
<A
HREF="sdlsetalpha.html"
><TT
CLASS="FUNCTION"
>SDL_SetAlpha</TT
></A
>
after surface creation.</P
></BLOCKQUOTE
></DIV
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1826"
></A
><H2
>Return Value</H2
><P
>Returns the created surface, or <SPAN
CLASS="RETURNVALUE"
>NULL</SPAN
> upon error.</P
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1830"
></A
><H2
>Example</H2
><PRE
CLASS="PROGRAMLISTING"
>    /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
       as expected by OpenGL for textures */
    SDL_Surface *surface;
    Uint32 rmask, gmask, bmask, amask;

    /* SDL interprets each pixel as a 32-bit number, so our masks must depend
       on the endianness (byte order) of the machine */
#if SDL_BYTEORDER == SDL_BIG_ENDIAN
    rmask = 0xff000000;
    gmask = 0x00ff0000;
    bmask = 0x0000ff00;
    amask = 0x000000ff;
#else
    rmask = 0x000000ff;
    gmask = 0x0000ff00;
    bmask = 0x00ff0000;
    amask = 0xff000000;
#endif

    surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,
                                   rmask, gmask, bmask, amask);
    if(surface == NULL) {
        fprintf(stderr, "CreateRGBSurface failed: %s\n", SDL_GetError());
        exit(1);
    }</PRE
></DIV
><DIV
CLASS="REFSECT1"
><A
NAME="AEN1833"
></A
><H2
>See Also</H2
><P
><A
HREF="sdlcreatergbsurfacefrom.html"
><TT
CLASS="FUNCTION"
>SDL_CreateRGBSurfaceFrom</TT
></A
>,
<A
HREF="sdlfreesurface.html"
><TT
CLASS="FUNCTION"
>SDL_FreeSurface</TT
></A
>,
<A
HREF="sdlsetvideomode.html"
><TT
CLASS="FUNCTION"
>SDL_SetVideoMode</TT
></A
>,
<A
HREF="sdllocksurface.html"
><TT
CLASS="FUNCTION"
>SDL_LockSurface</TT
></A
>,
<A
HREF="sdlpixelformat.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_PixelFormat</SPAN
></A
>,
<A
HREF="sdlsurface.html"
><SPAN
CLASS="STRUCTNAME"
>SDL_Surface</SPAN
></A
>
<A
HREF="sdlsetalpha.html"
><TT
CLASS="FUNCTION"
>SDL_SetAlpha</TT
></A
>
<A
HREF="sdlsetcolorkey.html"
><TT
CLASS="FUNCTION"
>SDL_SetColorKey</TT
></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="sdlgetrgba.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="sdlcreatergbsurfacefrom.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>SDL_GetRGBA</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_CreateRGBSurfaceFrom</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>SDL_CreateRGBSurface</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_GetRGBA"
	17	HREF="sdlgetrgba.html"><LINK
	18	REL="NEXT"
	19	TITLE="SDL_CreateRGBSurfaceFrom"
	20	HREF="sdlcreatergbsurfacefrom.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="sdlgetrgba.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="sdlcreatergbsurfacefrom.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="SDLCREATERGBSURFACE"
74	></A
75	>SDL_CreateRGBSurface</H1
76	><DIV
77	CLASS="REFNAMEDIV"
78	><A
79	NAME="AEN1773"
80	></A
81	><H2
82	>Name</H2
83	>SDL_CreateRGBSurface -- Create an empty SDL_Surface</DIV
84	><DIV
85	CLASS="REFSYNOPSISDIV"
86	><A
87	NAME="AEN1776"
88	></A
89	><H2
90	>Synopsis</H2
91	><DIV
92	CLASS="FUNCSYNOPSIS"
93	><A
94	NAME="AEN1777"
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	>SDL_Surface *<B
106	CLASS="FSFUNC"
107	>SDL_CreateRGBSurface</B
108	></CODE
109	>(Uint32 flags, int width, int height, int depth, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);</CODE
110	></P
111	><P
112	></P
113	></DIV
114	></DIV
115	><DIV
116	CLASS="REFSECT1"
117	><A
118	NAME="AEN1783"
119	></A
120	><H2
121	>Description</H2
122	><P
123	>Allocate an empty surface (must be called after <A
124	HREF="sdlsetvideomode.html"
125	>SDL_SetVideoMode</A
126	>)</P
127	><P
128	>If <TT
129	CLASS="PARAMETER"
130	><I
131	>depth</I
132	></TT
133	> is 8 bits an empty palette is allocated for the surface, otherwise a 'packed-pixel' <A
134	HREF="sdlpixelformat.html"
135	><SPAN
136	CLASS="STRUCTNAME"
137	>SDL_PixelFormat</SPAN
138	></A
139	> is created using the <TT
140	CLASS="PARAMETER"
141	><I
142	>[RGBA]mask</I
143	></TT
144	>'s provided (see <A
145	HREF="sdlpixelformat.html"
146	><SPAN
147	CLASS="STRUCTNAME"
148	>SDL_PixelFormat</SPAN
149	></A
150	>). The <TT
151	CLASS="PARAMETER"
152	><I
153	>flags</I
154	></TT
155	> specifies the type of surface that should be created, it is an OR'd combination of the following possible values.</P
156	><DIV
157	CLASS="INFORMALTABLE"
158	><A
159	NAME="AEN1795"
160	></A
161	><P
162	></P
163	><TABLE
164	BORDER="1"
165	CLASS="CALSTABLE"
166	><TBODY
167	><TR
168	><TD
169	ALIGN="LEFT"
170	VALIGN="TOP"
171	><TT
172	CLASS="LITERAL"
173	>SDL_SWSURFACE</TT
174	></TD
175	><TD
176	ALIGN="LEFT"
177	VALIGN="TOP"
178	>SDL will create the surface in system memory. This improves the performance of pixel level access, however you may not be able to take advantage of some types of hardware blitting.</TD
179	></TR
180	><TR
181	><TD
182	ALIGN="LEFT"
183	VALIGN="TOP"
184	><TT
185	CLASS="LITERAL"
186	>SDL_HWSURFACE</TT
187	></TD
188	><TD
189	ALIGN="LEFT"
190	VALIGN="TOP"
191	>SDL will attempt to create the surface in video memory. This will allow SDL to take advantage of Video->Video blits (which are often accelerated).</TD
192	></TR
193	><TR
194	><TD
195	ALIGN="LEFT"
196	VALIGN="TOP"
197	><TT
198	CLASS="LITERAL"
199	>SDL_SRCCOLORKEY</TT
200	></TD
201	><TD
202	ALIGN="LEFT"
203	VALIGN="TOP"
204	>This flag turns on colourkeying for blits from this surface. If
205	<TT
206	CLASS="LITERAL"
207	>SDL_HWSURFACE</TT
208	> is also specified and colourkeyed blits
209	are hardware-accelerated, then SDL will attempt to place the surface in
210	video memory.
211	Use <A
212	HREF="sdlsetcolorkey.html"
213	><TT
214	CLASS="FUNCTION"
215	>SDL_SetColorKey</TT
216	></A
217	>
218	to set or clear this flag after surface creation.</TD
219	></TR
220	><TR
221	><TD
222	ALIGN="LEFT"
223	VALIGN="TOP"
224	><TT
225	CLASS="LITERAL"
226	>SDL_SRCALPHA</TT
227	></TD
228	><TD
229	ALIGN="LEFT"
230	VALIGN="TOP"
231	>This flag turns on alpha-blending for blits from this surface. If
232	<TT
233	CLASS="LITERAL"
234	>SDL_HWSURFACE</TT
235	> is also specified and alpha-blending blits
236	are hardware-accelerated, then the surface will be placed in video memory if
237	possible.
238	Use <A
239	HREF="sdlsetalpha.html"
240	><TT
241	CLASS="FUNCTION"
242	>SDL_SetAlpha</TT
243	></A
244	> to
245	set or clear this flag after surface creation.</TD
246	></TR
247	></TBODY
248	></TABLE
249	><P
250	></P
251	></DIV
252	><DIV
253	CLASS="NOTE"
254	><BLOCKQUOTE
255	CLASS="NOTE"
256	><P
257	><B
258	>Note: </B
259	>If an alpha-channel is specified (that is, if <TT
260	CLASS="PARAMETER"
261	><I
262	>Amask</I
263	></TT
264	> is
265	nonzero), then the <TT
266	CLASS="LITERAL"
267	>SDL_SRCALPHA</TT
268	> flag is automatically
269	set. You may remove this flag by calling
270	<A
271	HREF="sdlsetalpha.html"
272	><TT
273	CLASS="FUNCTION"
274	>SDL_SetAlpha</TT
275	></A
276	>
277	after surface creation.</P
278	></BLOCKQUOTE
279	></DIV
280	></DIV
281	><DIV
282	CLASS="REFSECT1"
283	><A
284	NAME="AEN1826"
285	></A
286	><H2
287	>Return Value</H2
288	><P
289	>Returns the created surface, or <SPAN
290	CLASS="RETURNVALUE"
291	>NULL</SPAN
292	> upon error.</P
293	></DIV
294	><DIV
295	CLASS="REFSECT1"
296	><A
297	NAME="AEN1830"
298	></A
299	><H2
300	>Example</H2
301	><PRE
302	CLASS="PROGRAMLISTING"
303	> /* Create a 32-bit surface with the bytes of each pixel in R,G,B,A order,
304	as expected by OpenGL for textures */
305	SDL_Surface *surface;
306	Uint32 rmask, gmask, bmask, amask;
307
308	/* SDL interprets each pixel as a 32-bit number, so our masks must depend
309	on the endianness (byte order) of the machine */
310	#if SDL_BYTEORDER == SDL_BIG_ENDIAN
311	rmask = 0xff000000;
312	gmask = 0x00ff0000;
313	bmask = 0x0000ff00;
314	amask = 0x000000ff;
315	#else
316	rmask = 0x000000ff;
317	gmask = 0x0000ff00;
318	bmask = 0x00ff0000;
319	amask = 0xff000000;
320	#endif
321
322	surface = SDL_CreateRGBSurface(SDL_SWSURFACE, width, height, 32,
323	rmask, gmask, bmask, amask);
324	if(surface == NULL) {
325	fprintf(stderr, "CreateRGBSurface failed: %s\n", SDL_GetError());
326	exit(1);
327	}</PRE
328	></DIV
329	><DIV
330	CLASS="REFSECT1"
331	><A
332	NAME="AEN1833"
333	></A
334	><H2
335	>See Also</H2
336	><P
337	><A
338	HREF="sdlcreatergbsurfacefrom.html"
339	><TT
340	CLASS="FUNCTION"
341	>SDL_CreateRGBSurfaceFrom</TT
342	></A
343	>,
344	<A
345	HREF="sdlfreesurface.html"
346	><TT
347	CLASS="FUNCTION"
348	>SDL_FreeSurface</TT
349	></A
350	>,
351	<A
352	HREF="sdlsetvideomode.html"
353	><TT
354	CLASS="FUNCTION"
355	>SDL_SetVideoMode</TT
356	></A
357	>,
358	<A
359	HREF="sdllocksurface.html"
360	><TT
361	CLASS="FUNCTION"
362	>SDL_LockSurface</TT
363	></A
364	>,
365	<A
366	HREF="sdlpixelformat.html"
367	><SPAN
368	CLASS="STRUCTNAME"
369	>SDL_PixelFormat</SPAN
370	></A
371	>,
372	<A
373	HREF="sdlsurface.html"
374	><SPAN
375	CLASS="STRUCTNAME"
376	>SDL_Surface</SPAN
377	></A
378	>
379	<A
380	HREF="sdlsetalpha.html"
381	><TT
382	CLASS="FUNCTION"
383	>SDL_SetAlpha</TT
384	></A
385	>
386	<A
387	HREF="sdlsetcolorkey.html"
388	><TT
389	CLASS="FUNCTION"
390	>SDL_SetColorKey</TT
391	></A
392	></P
393	></DIV
394	><DIV
395	CLASS="NAVFOOTER"
396	><HR
397	ALIGN="LEFT"
398	WIDTH="100%"><TABLE
399	SUMMARY="Footer navigation table"
400	WIDTH="100%"
401	BORDER="0"
402	CELLPADDING="0"
403	CELLSPACING="0"
404	><TR
405	><TD
406	WIDTH="33%"
407	ALIGN="left"
408	VALIGN="top"
409	><A
410	HREF="sdlgetrgba.html"
411	ACCESSKEY="P"
412	>Prev</A
413	></TD
414	><TD
415	WIDTH="34%"
416	ALIGN="center"
417	VALIGN="top"
418	><A
419	HREF="index.html"
420	ACCESSKEY="H"
421	>Home</A
422	></TD
423	><TD
424	WIDTH="33%"
425	ALIGN="right"
426	VALIGN="top"
427	><A
428	HREF="sdlcreatergbsurfacefrom.html"
429	ACCESSKEY="N"
430	>Next</A
431	></TD
432	></TR
433	><TR
434	><TD
435	WIDTH="33%"
436	ALIGN="left"
437	VALIGN="top"
438	>SDL_GetRGBA</TD
439	><TD
440	WIDTH="34%"
441	ALIGN="center"
442	VALIGN="top"
443	><A
444	HREF="video.html"
445	ACCESSKEY="U"
446	>Up</A
447	></TD
448	><TD
449	WIDTH="33%"
450	ALIGN="right"
451	VALIGN="top"
452	>SDL_CreateRGBSurfaceFrom</TD
453	></TR
454	></TABLE
455	></DIV
456	></BODY
457	></HTML
458	>