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

<HTML
><HEAD
><TITLE
>Initializing SDL</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="The Basics"
HREF="guidethebasics.html"><LINK
REL="PREVIOUS"
TITLE="The Basics"
HREF="guidethebasics.html"><LINK
REL="NEXT"
TITLE="Graphics and Video"
HREF="guidevideo.html"></HEAD
><BODY
CLASS="SECT1"
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="guidethebasics.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
>Chapter 1. The Basics</TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="guidevideo.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="GUIDEBASICSINIT"
></A
>Initializing SDL</H1
><P
>SDL is composed of eight subsystems - Audio, CDROM, Event Handling, File I/O, Joystick Handling, Threading, Timers and Video. Before you can use any of these subsystems they must be initialized by calling <A
HREF="sdlinit.html"
><TT
CLASS="FUNCTION"
>SDL_Init</TT
></A
> (or <A
HREF="sdlinitsubsystem.html"
><TT
CLASS="FUNCTION"
>SDL_InitSubSystem</TT
></A
>). <TT
CLASS="FUNCTION"
>SDL_Init</TT
> must be called before any other SDL function. It automatically initializes the Event Handling, File I/O and Threading subsystems and it takes a parameter specifying which other subsystems to initialize. So, to initialize the default subsystems and the Video subsystems you would call:
<PRE
CLASS="PROGRAMLISTING"
>    SDL_Init ( SDL_INIT_VIDEO );</PRE
>
To initialize the default subsystems, the Video subsystem and the Timers subsystem you would call:
<PRE
CLASS="PROGRAMLISTING"
>    SDL_Init ( SDL_INIT_VIDEO | SDL_INIT_TIMER );</PRE
></P
><P
><TT
CLASS="FUNCTION"
>SDL_Init</TT
> is complemented by <A
HREF="sdlquit.html"
><TT
CLASS="FUNCTION"
>SDL_Quit</TT
></A
> (and <A
HREF="sdlquitsubsystem.html"
><TT
CLASS="FUNCTION"
>SDL_QuitSubSystem</TT
></A
>). <TT
CLASS="FUNCTION"
>SDL_Quit</TT
> shuts down all subsystems, including the default ones. It should always be called before a SDL application exits.</P
><P
>With <TT
CLASS="FUNCTION"
>SDL_Init</TT
> and <TT
CLASS="FUNCTION"
>SDL_Quit</TT
> firmly embedded in your programmers toolkit you can write your first and most basic SDL application. However, we must be prepare to handle errors. Many SDL functions return a value and indicates whether the function has succeeded or failed, <TT
CLASS="FUNCTION"
>SDL_Init</TT
>, for instance, returns -1 if it could not initialize a subsystem. SDL provides a useful facility that allows you to determine exactly what the problem was, every time an error occurs within SDL an error message is stored which can be retrieved using <TT
CLASS="FUNCTION"
>SDL_GetError</TT
>. Use this often, you can never know too much about an error.</P
><DIV
CLASS="EXAMPLE"
><A
NAME="AEN60"
></A
><P
><B
>Example 1-1. Initializing SDL</B
></P
><PRE
CLASS="PROGRAMLISTING"
>#include "SDL.h"   /* All SDL App's need this */
#include &#60;stdio.h&#62;

int main(int argc, char *argv[]) {
    
    printf("Initializing SDL.\n");
    
    /* Initialize defaults, Video and Audio */
    if((SDL_Init(SDL_INIT_VIDEO|SDL_INIT_AUDIO)==-1)) { 
        printf("Could not initialize SDL: %s.\n", SDL_GetError());
        exit(-1);
    }

    printf("SDL initialized.\n");

    printf("Quiting SDL.\n");
    
    /* Shutdown all subsystems */
    SDL_Quit();
    
    printf("Quiting....\n");

    exit(0);
}&#13;</PRE
></DIV
></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="guidethebasics.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="guidevideo.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>The Basics</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="guidethebasics.html"
ACCESSKEY="U"
>Up</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Graphics and Video</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
Commit	Line	Data
e14743d1	1	<HTML
	2	><HEAD
	3	><TITLE
	4	>Initializing SDL</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="The Basics"
	14	HREF="guidethebasics.html"><LINK
	15	REL="PREVIOUS"
	16	TITLE="The Basics"
	17	HREF="guidethebasics.html"><LINK
	18	REL="NEXT"
	19	TITLE="Graphics and Video"
	20	HREF="guidevideo.html"></HEAD
	21	><BODY
	22	CLASS="SECT1"
	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="guidethebasics.html"
	49	ACCESSKEY="P"
	50	>Prev</A
	51	></TD
	52	><TD
	53	WIDTH="80%"
	54	ALIGN="center"
	55	VALIGN="bottom"
	56	>Chapter 1. The Basics</TD
	57	><TD
	58	WIDTH="10%"
	59	ALIGN="right"
	60	VALIGN="bottom"
	61	><A
	62	HREF="guidevideo.html"
	63	ACCESSKEY="N"
	64	>Next</A
65	></TD
66	></TR
67	></TABLE
68	><HR
69	ALIGN="LEFT"
70	WIDTH="100%"></DIV
71	><DIV
72	CLASS="SECT1"
73	><H1
74	CLASS="SECT1"
75	><A
76	NAME="GUIDEBASICSINIT"
77	></A
78	>Initializing SDL</H1
79	><P
80	>SDL is composed of eight subsystems - Audio, CDROM, Event Handling, File I/O, Joystick Handling, Threading, Timers and Video. Before you can use any of these subsystems they must be initialized by calling <A
81	HREF="sdlinit.html"
82	><TT
83	CLASS="FUNCTION"
84	>SDL_Init</TT
85	></A
86	> (or <A
87	HREF="sdlinitsubsystem.html"
88	><TT
89	CLASS="FUNCTION"
90	>SDL_InitSubSystem</TT
91	></A
92	>). <TT
93	CLASS="FUNCTION"
94	>SDL_Init</TT
95	> must be called before any other SDL function. It automatically initializes the Event Handling, File I/O and Threading subsystems and it takes a parameter specifying which other subsystems to initialize. So, to initialize the default subsystems and the Video subsystems you would call:
96	<PRE
97	CLASS="PROGRAMLISTING"
98	> SDL_Init ( SDL_INIT_VIDEO );</PRE
99	>
100	To initialize the default subsystems, the Video subsystem and the Timers subsystem you would call:
101	<PRE
102	CLASS="PROGRAMLISTING"
103	> SDL_Init ( SDL_INIT_VIDEO \| SDL_INIT_TIMER );</PRE
104	></P
105	><P
106	><TT
107	CLASS="FUNCTION"
108	>SDL_Init</TT
109	> is complemented by <A
110	HREF="sdlquit.html"
111	><TT
112	CLASS="FUNCTION"
113	>SDL_Quit</TT
114	></A
115	> (and <A
116	HREF="sdlquitsubsystem.html"
117	><TT
118	CLASS="FUNCTION"
119	>SDL_QuitSubSystem</TT
120	></A
121	>). <TT
122	CLASS="FUNCTION"
123	>SDL_Quit</TT
124	> shuts down all subsystems, including the default ones. It should always be called before a SDL application exits.</P
125	><P
126	>With <TT
127	CLASS="FUNCTION"
128	>SDL_Init</TT
129	> and <TT
130	CLASS="FUNCTION"
131	>SDL_Quit</TT
132	> firmly embedded in your programmers toolkit you can write your first and most basic SDL application. However, we must be prepare to handle errors. Many SDL functions return a value and indicates whether the function has succeeded or failed, <TT
133	CLASS="FUNCTION"
134	>SDL_Init</TT
135	>, for instance, returns -1 if it could not initialize a subsystem. SDL provides a useful facility that allows you to determine exactly what the problem was, every time an error occurs within SDL an error message is stored which can be retrieved using <TT
136	CLASS="FUNCTION"
137	>SDL_GetError</TT
138	>. Use this often, you can never know too much about an error.</P
139	><DIV
140	CLASS="EXAMPLE"
141	><A
142	NAME="AEN60"
143	></A
144	><P
145	><B
146	>Example 1-1. Initializing SDL</B
147	></P
148	><PRE
149	CLASS="PROGRAMLISTING"
150	>#include "SDL.h" /* All SDL App's need this */
151	#include <stdio.h>
152
153	int main(int argc, char *argv[]) {
154
155	printf("Initializing SDL.\n");
156
157	/* Initialize defaults, Video and Audio */
158	if((SDL_Init(SDL_INIT_VIDEO\|SDL_INIT_AUDIO)==-1)) {
159	printf("Could not initialize SDL: %s.\n", SDL_GetError());
160	exit(-1);
161	}
162
163	printf("SDL initialized.\n");
164
165	printf("Quiting SDL.\n");
166
167	/* Shutdown all subsystems */
168	SDL_Quit();
169
170	printf("Quiting....\n");
171
172	exit(0);
173	} </PRE
174	></DIV
175	></DIV
176	><DIV
177	CLASS="NAVFOOTER"
178	><HR
179	ALIGN="LEFT"
180	WIDTH="100%"><TABLE
181	SUMMARY="Footer navigation table"
182	WIDTH="100%"
183	BORDER="0"
184	CELLPADDING="0"
185	CELLSPACING="0"
186	><TR
187	><TD
188	WIDTH="33%"
189	ALIGN="left"
190	VALIGN="top"
191	><A
192	HREF="guidethebasics.html"
193	ACCESSKEY="P"
194	>Prev</A
195	></TD
196	><TD
197	WIDTH="34%"
198	ALIGN="center"
199	VALIGN="top"
200	><A
201	HREF="index.html"
202	ACCESSKEY="H"
203	>Home</A
204	></TD
205	><TD
206	WIDTH="33%"
207	ALIGN="right"
208	VALIGN="top"
209	><A
210	HREF="guidevideo.html"
211	ACCESSKEY="N"
212	>Next</A
213	></TD
214	></TR
215	><TR
216	><TD
217	WIDTH="33%"
218	ALIGN="left"
219	VALIGN="top"
220	>The Basics</TD
221	><TD
222	WIDTH="34%"
223	ALIGN="center"
224	VALIGN="top"
225	><A
226	HREF="guidethebasics.html"
227	ACCESSKEY="U"
228	>Up</A
229	></TD
230	><TD
231	WIDTH="33%"
232	ALIGN="right"
233	VALIGN="top"
234	>Graphics and Video</TD
235	></TR
236	></TABLE
237	></DIV
238	></BODY
239	></HTML
240	>