home *** CD-ROM | disk | FTP | other *** search
/ RISCWORLD 7 / RISCWORLD_VOL7.iso / Software / Issue2 / SDL.ARC / sdlhtmldox / sdlpixelfo < prev    next >
Encoding:
Text File  |  2001-05-09  |  8.1 KB  |  520 lines
  1. <HTML
  2. ><HEAD
  3. ><TITLE
  4. >SDL_PixelFormat</TITLE
  5. ><META
  6. NAME="GENERATOR"
  7. CONTENT="Modular DocBook HTML Stylesheet Version 1.64
  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_Palette"
  17. HREF="sdlpalette.html"><LINK
  18. REL="NEXT"
  19. TITLE="SDL_Surface"
  20. HREF="sdlsurface.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. WIDTH="100%"
  32. BORDER="0"
  33. CELLPADDING="0"
  34. CELLSPACING="0"
  35. ><TR
  36. ><TH
  37. COLSPAN="3"
  38. ALIGN="center"
  39. >SDL Library Documentation</TH
  40. ></TR
  41. ><TR
  42. ><TD
  43. WIDTH="10%"
  44. ALIGN="left"
  45. VALIGN="bottom"
  46. ><A
  47. HREF="sdlpalette.html"
  48. >Prev</A
  49. ></TD
  50. ><TD
  51. WIDTH="80%"
  52. ALIGN="center"
  53. VALIGN="bottom"
  54. ></TD
  55. ><TD
  56. WIDTH="10%"
  57. ALIGN="right"
  58. VALIGN="bottom"
  59. ><A
  60. HREF="sdlsurface.html"
  61. >Next</A
  62. ></TD
  63. ></TR
  64. ></TABLE
  65. ><HR
  66. ALIGN="LEFT"
  67. WIDTH="100%"></DIV
  68. ><H1
  69. ><A
  70. NAME="SDLPIXELFORMAT"
  71. >SDL_PixelFormat</A
  72. ></H1
  73. ><DIV
  74. CLASS="REFNAMEDIV"
  75. ><A
  76. NAME="AEN2762"
  77. ></A
  78. ><H2
  79. >Name</H2
  80. >SDL_PixelFormat -- Stores surface format information</DIV
  81. ><DIV
  82. CLASS="REFSECT1"
  83. ><A
  84. NAME="AEN2765"
  85. ></A
  86. ><H2
  87. >Structure Definition</H2
  88. ><PRE
  89. CLASS="PROGRAMLISTING"
  90. >typedef struct{
  91.   SDL_Palette *palette;
  92.   Uint8  BitsPerPixel;
  93.   Uint8  BytesPerPixel;
  94.   Uint32 Rmask, Gmask, Bmask, Amask;
  95.   Uint8  Rshift, Gshift, Bshift, Ashift;
  96.   Uint8  Rloss, Gloss, Bloss, Aloss;
  97.   Uint32 colorkey;
  98.   Uint8  alpha;
  99. } SDL_PixelFormat;</PRE
  100. ></DIV
  101. ><DIV
  102. CLASS="REFSECT1"
  103. ><A
  104. NAME="AEN2768"
  105. ></A
  106. ><H2
  107. >Structure Data</H2
  108. ><DIV
  109. CLASS="INFORMALTABLE"
  110. ><A
  111. NAME="AEN2770"
  112. ></A
  113. ><P
  114. ></P
  115. ><TABLE
  116. BORDER="0"
  117. CLASS="CALSTABLE"
  118. ><TBODY
  119. ><TR
  120. ><TD
  121. ALIGN="LEFT"
  122. VALIGN="TOP"
  123. ><TT
  124. CLASS="STRUCTFIELD"
  125. ><I
  126. >palette</I
  127. ></TT
  128. ></TD
  129. ><TD
  130. ALIGN="LEFT"
  131. VALIGN="TOP"
  132. >Pointer to the <A
  133. HREF="sdlpalette.html"
  134. >palette</A
  135. >, or <TT
  136. CLASS="LITERAL"
  137. >NULL</TT
  138. > if the <TT
  139. CLASS="STRUCTFIELD"
  140. ><I
  141. >BitsPerPixel</I
  142. ></TT
  143. >>8</TD
  144. ></TR
  145. ><TR
  146. ><TD
  147. ALIGN="LEFT"
  148. VALIGN="TOP"
  149. ><TT
  150. CLASS="STRUCTFIELD"
  151. ><I
  152. >BitsPerPixel</I
  153. ></TT
  154. ></TD
  155. ><TD
  156. ALIGN="LEFT"
  157. VALIGN="TOP"
  158. >The number of bits used to represent each pixel in a surface. Usually 8, 16, 24 or 32.</TD
  159. ></TR
  160. ><TR
  161. ><TD
  162. ALIGN="LEFT"
  163. VALIGN="TOP"
  164. ><TT
  165. CLASS="STRUCTFIELD"
  166. ><I
  167. >BytesPerPixel</I
  168. ></TT
  169. ></TD
  170. ><TD
  171. ALIGN="LEFT"
  172. VALIGN="TOP"
  173. >The number of bytes used to represent each pixel in a surface. Usually one to four.</TD
  174. ></TR
  175. ><TR
  176. ><TD
  177. ALIGN="LEFT"
  178. VALIGN="TOP"
  179. ><TT
  180. CLASS="STRUCTFIELD"
  181. ><I
  182. >[RGBA]mask</I
  183. ></TT
  184. ></TD
  185. ><TD
  186. ALIGN="LEFT"
  187. VALIGN="TOP"
  188. >Binary mask used to retrieve individual color values</TD
  189. ></TR
  190. ><TR
  191. ><TD
  192. ALIGN="LEFT"
  193. VALIGN="TOP"
  194. ><TT
  195. CLASS="STRUCTFIELD"
  196. ><I
  197. >[RGBA]loss</I
  198. ></TT
  199. ></TD
  200. ><TD
  201. ALIGN="LEFT"
  202. VALIGN="TOP"
  203. >Precision loss of each color component (2<SUP
  204. >[RGBA]loss</SUP
  205. >)</TD
  206. ></TR
  207. ><TR
  208. ><TD
  209. ALIGN="LEFT"
  210. VALIGN="TOP"
  211. ><TT
  212. CLASS="STRUCTFIELD"
  213. ><I
  214. >[RGBA]shift</I
  215. ></TT
  216. ></TD
  217. ><TD
  218. ALIGN="LEFT"
  219. VALIGN="TOP"
  220. >Binary left shift of each color component in the pixel value</TD
  221. ></TR
  222. ><TR
  223. ><TD
  224. ALIGN="LEFT"
  225. VALIGN="TOP"
  226. ><TT
  227. CLASS="STRUCTFIELD"
  228. ><I
  229. >colorkey</I
  230. ></TT
  231. ></TD
  232. ><TD
  233. ALIGN="LEFT"
  234. VALIGN="TOP"
  235. >Pixel value of transparent pixels</TD
  236. ></TR
  237. ><TR
  238. ><TD
  239. ALIGN="LEFT"
  240. VALIGN="TOP"
  241. ><TT
  242. CLASS="STRUCTFIELD"
  243. ><I
  244. >alpha</I
  245. ></TT
  246. ></TD
  247. ><TD
  248. ALIGN="LEFT"
  249. VALIGN="TOP"
  250. >Overall surface alpha value</TD
  251. ></TR
  252. ></TBODY
  253. ></TABLE
  254. ><P
  255. ></P
  256. ></DIV
  257. ></DIV
  258. ><DIV
  259. CLASS="REFSECT1"
  260. ><A
  261. NAME="AEN2809"
  262. ></A
  263. ><H2
  264. >Description</H2
  265. ><P
  266. >A <SPAN
  267. CLASS="STRUCTNAME"
  268. >SDL_PixelFormat</SPAN
  269. > describes the format of the pixel data stored at the <TT
  270. CLASS="STRUCTFIELD"
  271. ><I
  272. >pixels</I
  273. ></TT
  274. > field of a <A
  275. HREF="sdlsurface.html"
  276. ><SPAN
  277. CLASS="STRUCTNAME"
  278. >SDL_Surface</SPAN
  279. ></A
  280. >. Every surface stores a <SPAN
  281. CLASS="STRUCTNAME"
  282. >SDL_PixelFormat</SPAN
  283. > in the <TT
  284. CLASS="STRUCTFIELD"
  285. ><I
  286. >format</I
  287. ></TT
  288. > field.</P
  289. ><P
  290. >If you wish to do pixel level modifications on a surface, then understanding how SDL stores its color information is essential.</P
  291. ><P
  292. >8-bit pixel formats are the easiest to understand. Since its an 8-bit format, we have 8 <TT
  293. CLASS="STRUCTFIELD"
  294. ><I
  295. >BitsPerPixel</I
  296. ></TT
  297. > and 1 <TT
  298. CLASS="STRUCTFIELD"
  299. ><I
  300. >BytesPerPixel</I
  301. ></TT
  302. >. Since <TT
  303. CLASS="STRUCTFIELD"
  304. ><I
  305. >BytesPerPixel</I
  306. ></TT
  307. > is 1, all pixels are represented by a Uint8 which contains an index into <TT
  308. CLASS="STRUCTFIELD"
  309. ><I
  310. >palette</I
  311. ></TT
  312. >-><TT
  313. CLASS="STRUCTFIELD"
  314. ><I
  315. >colors</I
  316. ></TT
  317. >. So, to determine the color of a pixel in a 8-bit surface: we read the color index from <SPAN
  318. CLASS="STRUCTNAME"
  319. >surface</SPAN
  320. >-><TT
  321. CLASS="STRUCTFIELD"
  322. ><I
  323. >pixels</I
  324. ></TT
  325. > and we use that index to read the <A
  326. HREF="sdlcolor.html"
  327. ><SPAN
  328. CLASS="STRUCTNAME"
  329. >SDL_Color</SPAN
  330. ></A
  331. > structure from <SPAN
  332. CLASS="STRUCTNAME"
  333. >surface</SPAN
  334. >-><TT
  335. CLASS="STRUCTFIELD"
  336. ><I
  337. >format</I
  338. ></TT
  339. >-><TT
  340. CLASS="STRUCTFIELD"
  341. ><I
  342. >palette</I
  343. ></TT
  344. >-><TT
  345. CLASS="STRUCTFIELD"
  346. ><I
  347. >colors</I
  348. ></TT
  349. >. Like so:
  350. <PRE
  351. CLASS="PROGRAMLISTING"
  352. >SDL_Surface *surface;
  353. SDL_PixelFormat *fmt;
  354. SDL_Color *color;
  355. Uint8 index;
  356.  
  357. .
  358. .
  359.  
  360. /* Create surface */
  361. .
  362. .
  363. fmt=surface->format;
  364.  
  365. /* Check the bitdepth of the surface */
  366. if(fmt->BitsPerPixel!=8){
  367.   fprintf(stderr, "Not an 8-bit surface.\n");
  368.   return(-1);
  369. }
  370.  
  371. /* Lock the surface */
  372. SDL_LockSurface(surface);
  373.  
  374. /* Get the topleft pixel */
  375. index=*(Uint8 *)surface->pixels;
  376. color=fmt->palette->colors[index];
  377.  
  378. /* Unlock the surface */
  379. SDL_UnlockSurface(surface);
  380. printf("Pixel Color-> Red: %d, Green: %d, Blue: %d. Index: %d\n",
  381.           color->r, color->g, color->b, index);
  382. .
  383. .</PRE
  384. ></P
  385. ><P
  386. >Pixel formats above 8-bit are an entirely different experience. They are
  387. considered to be "TrueColor" formats and the color information is stored in the
  388. pixels themselves, not in a palette. The mask, shift and loss fields tell us
  389. how the color information is encoded. The mask fields allow us to isolate each
  390. color component, the shift fields tell us the number of bits to the right of
  391. each component in the pixel value and the loss fields tell us the number of
  392. bits lost from each component when packing 8-bit color component in a pixel.
  393. <PRE
  394. CLASS="PROGRAMLISTING"
  395. >/* Extracting color components from a 32-bit color value */
  396. SDL_PixelFormat *fmt;
  397. SDL_Surface *surface;
  398. Uint32 temp, pixel;
  399. Uint8 red, green, blue, alpha;
  400. .
  401. .
  402. .
  403. fmt=surface->format;
  404. SDL_LockSurface(surface);
  405. pixel=*((Uint32*)surface->pixels);
  406. SDL_UnlockSurface(surface);
  407.  
  408. /* Get Red component */
  409. temp=pixel&fmt->Rmask; /* Isolate red component */
  410. temp=temp>>fmt->Rshift;/* Shift it down to 8-bit */
  411. temp=temp<<fmt->Rloss; /* Expand to a full 8-bit number */
  412. red=(Uint8)temp;
  413.  
  414. /* Get Green component */
  415. temp=pixel&fmt->Gmask; /* Isolate green component */
  416. temp=temp>>fmt->Gshift;/* Shift it down to 8-bit */
  417. temp=temp<<fmt->Gloss; /* Expand to a full 8-bit number */
  418. green=(Uint8)temp;
  419.  
  420. /* Get Blue component */
  421. temp=pixel&fmt->Bmask; /* Isolate blue component */
  422. temp=temp>>fmt->Bshift;/* Shift it down to 8-bit */
  423. temp=temp<<fmt->Bloss; /* Expand to a full 8-bit number */
  424. blue=(Uint8)temp;
  425.  
  426. /* Get Alpha component */
  427. temp=pixel&fmt->Amask; /* Isolate alpha component */
  428. temp=temp>>fmt->Ashift;/* Shift it down to 8-bit */
  429. temp=temp<<fmt->Aloss; /* Expand to a full 8-bit number */
  430. alpha=(Uint8)temp;
  431.  
  432. printf("Pixel Color -> R: %d,  G: %d,  B: %d,  A: %d\n", red, green, blue, alpha);
  433. .
  434. .
  435. .</PRE
  436. ></P
  437. ></DIV
  438. ><DIV
  439. CLASS="REFSECT1"
  440. ><A
  441. NAME="AEN2836"
  442. ></A
  443. ><H2
  444. >See Also</H2
  445. ><P
  446. ><A
  447. HREF="sdlsurface.html"
  448. ><SPAN
  449. CLASS="STRUCTNAME"
  450. >SDL_Surface</SPAN
  451. ></A
  452. >,
  453. <A
  454. HREF="sdlmaprgb.html"
  455. ><TT
  456. CLASS="FUNCTION"
  457. >SDL_MapRGB</TT
  458. ></A
  459. ></P
  460. ></DIV
  461. ><DIV
  462. CLASS="NAVFOOTER"
  463. ><HR
  464. ALIGN="LEFT"
  465. WIDTH="100%"><TABLE
  466. WIDTH="100%"
  467. BORDER="0"
  468. CELLPADDING="0"
  469. CELLSPACING="0"
  470. ><TR
  471. ><TD
  472. WIDTH="33%"
  473. ALIGN="left"
  474. VALIGN="top"
  475. ><A
  476. HREF="sdlpalette.html"
  477. >Prev</A
  478. ></TD
  479. ><TD
  480. WIDTH="34%"
  481. ALIGN="center"
  482. VALIGN="top"
  483. ><A
  484. HREF="index.html"
  485. >Home</A
  486. ></TD
  487. ><TD
  488. WIDTH="33%"
  489. ALIGN="right"
  490. VALIGN="top"
  491. ><A
  492. HREF="sdlsurface.html"
  493. >Next</A
  494. ></TD
  495. ></TR
  496. ><TR
  497. ><TD
  498. WIDTH="33%"
  499. ALIGN="left"
  500. VALIGN="top"
  501. >SDL_Palette</TD
  502. ><TD
  503. WIDTH="34%"
  504. ALIGN="center"
  505. VALIGN="top"
  506. ><A
  507. HREF="video.html"
  508. >Up</A
  509. ></TD
  510. ><TD
  511. WIDTH="33%"
  512. ALIGN="right"
  513. VALIGN="top"
  514. >SDL_Surface</TD
  515. ></TR
  516. ></TABLE
  517. ></DIV
  518. ></BODY
  519. ></HTML
  520. >