handle src buffer underflow corner cases
[sdl_omap.git] / docs / html / guidevideo.html
CommitLineData
e14743d1 1<HTML
2><HEAD
3><TITLE
4>Graphics and Video</TITLE
5><META
6NAME="GENERATOR"
7CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
8"><LINK
9REL="HOME"
10TITLE="SDL Library Documentation"
11HREF="index.html"><LINK
12REL="UP"
13TITLE="SDL Guide"
14HREF="guide.html"><LINK
15REL="PREVIOUS"
16TITLE="Initializing SDL"
17HREF="guidebasicsinit.html"><LINK
18REL="NEXT"
19TITLE="Using OpenGL With SDL"
20HREF="guidevideoopengl.html"></HEAD
21><BODY
22CLASS="CHAPTER"
23BGCOLOR="#FFF8DC"
24TEXT="#000000"
25LINK="#0000ee"
26VLINK="#551a8b"
27ALINK="#ff0000"
28><DIV
29CLASS="NAVHEADER"
30><TABLE
31SUMMARY="Header navigation table"
32WIDTH="100%"
33BORDER="0"
34CELLPADDING="0"
35CELLSPACING="0"
36><TR
37><TH
38COLSPAN="3"
39ALIGN="center"
40>SDL Library Documentation</TH
41></TR
42><TR
43><TD
44WIDTH="10%"
45ALIGN="left"
46VALIGN="bottom"
47><A
48HREF="guidebasicsinit.html"
49ACCESSKEY="P"
50>Prev</A
51></TD
52><TD
53WIDTH="80%"
54ALIGN="center"
55VALIGN="bottom"
56></TD
57><TD
58WIDTH="10%"
59ALIGN="right"
60VALIGN="bottom"
61><A
62HREF="guidevideoopengl.html"
63ACCESSKEY="N"
64>Next</A
65></TD
66></TR
67></TABLE
68><HR
69ALIGN="LEFT"
70WIDTH="100%"></DIV
71><DIV
72CLASS="CHAPTER"
73><H1
74><A
75NAME="GUIDEVIDEO"
76></A
77>Chapter 2. Graphics and Video</H1
78><DIV
79CLASS="TOC"
80><DL
81><DT
82><B
83>Table of Contents</B
84></DT
85><DT
86><A
87HREF="guidevideo.html#GUIDEVIDEOINTRO"
88>Introduction to SDL Video</A
89></DT
90><DT
91><A
92HREF="guidevideoopengl.html"
93>Using OpenGL With SDL</A
94></DT
95></DL
96></DIV
97><DIV
98CLASS="SECT1"
99><H1
100CLASS="SECT1"
101><A
102NAME="GUIDEVIDEOINTRO"
103></A
104>Introduction to SDL Video</H1
105><P
106>Video is probably the most common thing that SDL is used for, and
107so it has the most complete subsystem. Here are a few
108examples to demonstrate the basics.</P
109><DIV
110CLASS="SECT2"
111><H2
112CLASS="SECT2"
113><A
114NAME="AEN68"
115></A
116>Initializing the Video Display</H2
117><P
118>This is what almost all SDL programs have to do in one way or
119another.</P
120><DIV
121CLASS="EXAMPLE"
122><A
123NAME="AEN71"
124></A
125><P
126><B
127>Example 2-1. Initializing the Video Display</B
128></P
129><PRE
130CLASS="PROGRAMLISTING"
131> SDL_Surface *screen;
132
133 /* Initialize the SDL library */
134 if( SDL_Init(SDL_INIT_VIDEO) &#60; 0 ) {
135 fprintf(stderr,
136 "Couldn't initialize SDL: %s\n", SDL_GetError());
137 exit(1);
138 }
139
140 /* Clean up on exit */
141 atexit(SDL_Quit);
142
143 /*
144 * Initialize the display in a 640x480 8-bit palettized mode,
145 * requesting a software surface
146 */
147 screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE);
148 if ( screen == NULL ) {
149 fprintf(stderr, "Couldn't set 640x480x8 video mode: %s\n",
150 SDL_GetError());
151 exit(1);
152 }</PRE
153></DIV
154></DIV
155><DIV
156CLASS="SECT2"
157><H2
158CLASS="SECT2"
159><A
160NAME="AEN74"
161></A
162>Initializing the Best Video Mode</H2
163><P
164>If you have a preference for a certain pixel depth but will accept any
165other, use SDL_SetVideoMode with SDL_ANYFORMAT as below. You can also
166use SDL_VideoModeOK() to find the native video mode that is closest to
167the mode you request.</P
168><DIV
169CLASS="EXAMPLE"
170><A
171NAME="AEN77"
172></A
173><P
174><B
175>Example 2-2. Initializing the Best Video Mode</B
176></P
177><PRE
178CLASS="PROGRAMLISTING"
179> /* Have a preference for 8-bit, but accept any depth */
180 screen = SDL_SetVideoMode(640, 480, 8, SDL_SWSURFACE|SDL_ANYFORMAT);
181 if ( screen == NULL ) {
182 fprintf(stderr, "Couldn't set 640x480x8 video mode: %s\n",
183 SDL_GetError());
184 exit(1);
185 }
186 printf("Set 640x480 at %d bits-per-pixel mode\n",
187 screen-&#62;format-&#62;BitsPerPixel);</PRE
188></DIV
189></DIV
190><DIV
191CLASS="SECT2"
192><H2
193CLASS="SECT2"
194><A
195NAME="AEN80"
196></A
197>Loading and Displaying a BMP File</H2
198><P
199>The following function loads and displays a BMP file given as
200argument, once SDL is initialised and a video mode has been set.</P
201><DIV
202CLASS="EXAMPLE"
203><A
204NAME="AEN83"
205></A
206><P
207><B
208>Example 2-3. Loading and Displaying a BMP File</B
209></P
210><PRE
211CLASS="PROGRAMLISTING"
212>void display_bmp(char *file_name)
213{
214 SDL_Surface *image;
215
216 /* Load the BMP file into a surface */
217 image = SDL_LoadBMP(file_name);
218 if (image == NULL) {
219 fprintf(stderr, "Couldn't load %s: %s\n", file_name, SDL_GetError());
220 return;
221 }
222
223 /*
224 * Palettized screen modes will have a default palette (a standard
225 * 8*8*4 colour cube), but if the image is palettized as well we can
226 * use that palette for a nicer colour matching
227 */
228 if (image-&#62;format-&#62;palette &#38;&#38; screen-&#62;format-&#62;palette) {
229 SDL_SetColors(screen, image-&#62;format-&#62;palette-&#62;colors, 0,
230 image-&#62;format-&#62;palette-&#62;ncolors);
231 }
232
233 /* Blit onto the screen surface */
234 if(SDL_BlitSurface(image, NULL, screen, NULL) &#60; 0)
235 fprintf(stderr, "BlitSurface error: %s\n", SDL_GetError());
236
237 SDL_UpdateRect(screen, 0, 0, image-&#62;w, image-&#62;h);
238
239 /* Free the allocated BMP surface */
240 SDL_FreeSurface(image);
241}</PRE
242></DIV
243></DIV
244><DIV
245CLASS="SECT2"
246><H2
247CLASS="SECT2"
248><A
249NAME="AEN86"
250></A
251>Drawing Directly to the Display</H2
252><P
253>The following two functions can be used to get and set single
254pixels of a surface. They are carefully written to work with any depth
255currently supported by SDL. Remember to lock the surface before
256calling them, and to unlock it before calling any other SDL
257functions.</P
258><P
259>To convert between pixel values and their red, green, blue
260components, use SDL_GetRGB() and SDL_MapRGB().</P
261><DIV
262CLASS="EXAMPLE"
263><A
264NAME="AEN90"
265></A
266><P
267><B
268>Example 2-4. getpixel()</B
269></P
270><PRE
271CLASS="PROGRAMLISTING"
272>/*
273 * Return the pixel value at (x, y)
274 * NOTE: The surface must be locked before calling this!
275 */
276Uint32 getpixel(SDL_Surface *surface, int x, int y)
277{
278 int bpp = surface-&#62;format-&#62;BytesPerPixel;
279 /* Here p is the address to the pixel we want to retrieve */
280 Uint8 *p = (Uint8 *)surface-&#62;pixels + y * surface-&#62;pitch + x * bpp;
281
282 switch(bpp) {
283 case 1:
284 return *p;
285
286 case 2:
287 return *(Uint16 *)p;
288
289 case 3:
290 if(SDL_BYTEORDER == SDL_BIG_ENDIAN)
291 return p[0] &#60;&#60; 16 | p[1] &#60;&#60; 8 | p[2];
292 else
293 return p[0] | p[1] &#60;&#60; 8 | p[2] &#60;&#60; 16;
294
295 case 4:
296 return *(Uint32 *)p;
297
298 default:
299 return 0; /* shouldn't happen, but avoids warnings */
300 }
301}</PRE
302></DIV
303><DIV
304CLASS="EXAMPLE"
305><A
306NAME="AEN93"
307></A
308><P
309><B
310>Example 2-5. putpixel()</B
311></P
312><PRE
313CLASS="PROGRAMLISTING"
314>/*
315 * Set the pixel at (x, y) to the given value
316 * NOTE: The surface must be locked before calling this!
317 */
318void putpixel(SDL_Surface *surface, int x, int y, Uint32 pixel)
319{
320 int bpp = surface-&#62;format-&#62;BytesPerPixel;
321 /* Here p is the address to the pixel we want to set */
322 Uint8 *p = (Uint8 *)surface-&#62;pixels + y * surface-&#62;pitch + x * bpp;
323
324 switch(bpp) {
325 case 1:
326 *p = pixel;
327 break;
328
329 case 2:
330 *(Uint16 *)p = pixel;
331 break;
332
333 case 3:
334 if(SDL_BYTEORDER == SDL_BIG_ENDIAN) {
335 p[0] = (pixel &#62;&#62; 16) &#38; 0xff;
336 p[1] = (pixel &#62;&#62; 8) &#38; 0xff;
337 p[2] = pixel &#38; 0xff;
338 } else {
339 p[0] = pixel &#38; 0xff;
340 p[1] = (pixel &#62;&#62; 8) &#38; 0xff;
341 p[2] = (pixel &#62;&#62; 16) &#38; 0xff;
342 }
343 break;
344
345 case 4:
346 *(Uint32 *)p = pixel;
347 break;
348 }
349}</PRE
350></DIV
351><P
352>The following code uses the putpixel() function above to set a
353yellow pixel in the middle of the screen.</P
354><DIV
355CLASS="EXAMPLE"
356><A
357NAME="AEN97"
358></A
359><P
360><B
361>Example 2-6. Using putpixel()</B
362></P
363><PRE
364CLASS="PROGRAMLISTING"
365>&#13; /* Code to set a yellow pixel at the center of the screen */
366
367 int x, y;
368 Uint32 yellow;
369
370 /* Map the color yellow to this display (R=0xff, G=0xFF, B=0x00)
371 Note: If the display is palettized, you must set the palette first.
372 */
373 yellow = SDL_MapRGB(screen-&#62;format, 0xff, 0xff, 0x00);
374
375 x = screen-&#62;w / 2;
376 y = screen-&#62;h / 2;
377
378 /* Lock the screen for direct access to the pixels */
379 if ( SDL_MUSTLOCK(screen) ) {
380 if ( SDL_LockSurface(screen) &#60; 0 ) {
381 fprintf(stderr, "Can't lock screen: %s\n", SDL_GetError());
382 return;
383 }
384 }
385
386 putpixel(screen, x, y, yellow);
387
388 if ( SDL_MUSTLOCK(screen) ) {
389 SDL_UnlockSurface(screen);
390 }
391 /* Update just the part of the display that we've changed */
392 SDL_UpdateRect(screen, x, y, 1, 1);
393
394 return;&#13;</PRE
395></DIV
396></DIV
397></DIV
398></DIV
399><DIV
400CLASS="NAVFOOTER"
401><HR
402ALIGN="LEFT"
403WIDTH="100%"><TABLE
404SUMMARY="Footer navigation table"
405WIDTH="100%"
406BORDER="0"
407CELLPADDING="0"
408CELLSPACING="0"
409><TR
410><TD
411WIDTH="33%"
412ALIGN="left"
413VALIGN="top"
414><A
415HREF="guidebasicsinit.html"
416ACCESSKEY="P"
417>Prev</A
418></TD
419><TD
420WIDTH="34%"
421ALIGN="center"
422VALIGN="top"
423><A
424HREF="index.html"
425ACCESSKEY="H"
426>Home</A
427></TD
428><TD
429WIDTH="33%"
430ALIGN="right"
431VALIGN="top"
432><A
433HREF="guidevideoopengl.html"
434ACCESSKEY="N"
435>Next</A
436></TD
437></TR
438><TR
439><TD
440WIDTH="33%"
441ALIGN="left"
442VALIGN="top"
443>Initializing SDL</TD
444><TD
445WIDTH="34%"
446ALIGN="center"
447VALIGN="top"
448><A
449HREF="guide.html"
450ACCESSKEY="U"
451>Up</A
452></TD
453><TD
454WIDTH="33%"
455ALIGN="right"
456VALIGN="top"
457>Using OpenGL With SDL</TD
458></TR
459></TABLE
460></DIV
461></BODY
462></HTML
463>