Mercurial > sdl-ios-xcode
comparison include/SDL_pixels.h @ 3407:d3baf5ac4e37
Partial fix for bug #859
Header file update from Ken for improved doxygen output
author | Sam Lantinga <slouken@libsdl.org> |
---|---|
date | Mon, 19 Oct 2009 13:31:58 +0000 |
parents | efe3b3971e4f |
children | a54df8e52333 |
comparison
equal
deleted
inserted
replaced
3406:8ae607392409 | 3407:d3baf5ac4e37 |
---|---|
19 Sam Lantinga | 19 Sam Lantinga |
20 slouken@libsdl.org | 20 slouken@libsdl.org |
21 */ | 21 */ |
22 | 22 |
23 /** | 23 /** |
24 * \file SDL_pixels.h | 24 * \file SDL_pixels.h |
25 * | 25 * |
26 * Header for the enumerated pixel format definitions | 26 * Header for the enumerated pixel format definitions. |
27 */ | 27 */ |
28 | 28 |
29 #ifndef _SDL_pixels_h | 29 #ifndef _SDL_pixels_h |
30 #define _SDL_pixels_h | 30 #define _SDL_pixels_h |
31 | 31 |
35 /* *INDENT-OFF* */ | 35 /* *INDENT-OFF* */ |
36 extern "C" { | 36 extern "C" { |
37 /* *INDENT-ON* */ | 37 /* *INDENT-ON* */ |
38 #endif | 38 #endif |
39 | 39 |
40 /* Transparency definitions: These define alpha as the opacity of a surface */ | 40 /** |
41 * \name Transparency definitions | |
42 * | |
43 * These define alpha as the opacity of a surface. | |
44 */ | |
45 /*@{*/ | |
41 #define SDL_ALPHA_OPAQUE 255 | 46 #define SDL_ALPHA_OPAQUE 255 |
42 #define SDL_ALPHA_TRANSPARENT 0 | 47 #define SDL_ALPHA_TRANSPARENT 0 |
43 | 48 /*@}*/ |
44 enum | 49 |
45 { /* Pixel type */ | 50 /** Pixel type. */ |
51 enum | |
52 { | |
46 SDL_PIXELTYPE_UNKNOWN, | 53 SDL_PIXELTYPE_UNKNOWN, |
47 SDL_PIXELTYPE_INDEX1, | 54 SDL_PIXELTYPE_INDEX1, |
48 SDL_PIXELTYPE_INDEX4, | 55 SDL_PIXELTYPE_INDEX4, |
49 SDL_PIXELTYPE_INDEX8, | 56 SDL_PIXELTYPE_INDEX8, |
50 SDL_PIXELTYPE_PACKED8, | 57 SDL_PIXELTYPE_PACKED8, |
55 SDL_PIXELTYPE_ARRAYU32, | 62 SDL_PIXELTYPE_ARRAYU32, |
56 SDL_PIXELTYPE_ARRAYF16, | 63 SDL_PIXELTYPE_ARRAYF16, |
57 SDL_PIXELTYPE_ARRAYF32 | 64 SDL_PIXELTYPE_ARRAYF32 |
58 }; | 65 }; |
59 | 66 |
60 enum | 67 /** Bitmap pixel order, high bit -> low bit. */ |
61 { /* bitmap pixel order, high bit -> low bit */ | 68 enum |
69 { | |
62 SDL_BITMAPORDER_NONE, | 70 SDL_BITMAPORDER_NONE, |
63 SDL_BITMAPORDER_4321, | 71 SDL_BITMAPORDER_4321, |
64 SDL_BITMAPORDER_1234 | 72 SDL_BITMAPORDER_1234 |
65 }; | 73 }; |
66 enum | 74 |
67 { /* packed component order, high bit -> low bit */ | 75 /** Packed component order, high bit -> low bit. */ |
76 enum | |
77 { | |
68 SDL_PACKEDORDER_NONE, | 78 SDL_PACKEDORDER_NONE, |
69 SDL_PACKEDORDER_XRGB, | 79 SDL_PACKEDORDER_XRGB, |
70 SDL_PACKEDORDER_RGBX, | 80 SDL_PACKEDORDER_RGBX, |
71 SDL_PACKEDORDER_ARGB, | 81 SDL_PACKEDORDER_ARGB, |
72 SDL_PACKEDORDER_RGBA, | 82 SDL_PACKEDORDER_RGBA, |
73 SDL_PACKEDORDER_XBGR, | 83 SDL_PACKEDORDER_XBGR, |
74 SDL_PACKEDORDER_BGRX, | 84 SDL_PACKEDORDER_BGRX, |
75 SDL_PACKEDORDER_ABGR, | 85 SDL_PACKEDORDER_ABGR, |
76 SDL_PACKEDORDER_BGRA | 86 SDL_PACKEDORDER_BGRA |
77 }; | 87 }; |
78 enum | 88 |
79 { /* array component order, low byte -> high byte */ | 89 /** Array component order, low byte -> high byte. */ |
90 enum | |
91 { | |
80 SDL_ARRAYORDER_NONE, | 92 SDL_ARRAYORDER_NONE, |
81 SDL_ARRAYORDER_RGB, | 93 SDL_ARRAYORDER_RGB, |
82 SDL_ARRAYORDER_RGBA, | 94 SDL_ARRAYORDER_RGBA, |
83 SDL_ARRAYORDER_ARGB, | 95 SDL_ARRAYORDER_ARGB, |
84 SDL_ARRAYORDER_BGR, | 96 SDL_ARRAYORDER_BGR, |
85 SDL_ARRAYORDER_BGRA, | 97 SDL_ARRAYORDER_BGRA, |
86 SDL_ARRAYORDER_ABGR | 98 SDL_ARRAYORDER_ABGR |
87 }; | 99 }; |
88 | 100 |
89 enum | 101 /** Packed component layout. */ |
90 { /* Packed component layout */ | 102 enum |
103 { | |
91 SDL_PACKEDLAYOUT_NONE, | 104 SDL_PACKEDLAYOUT_NONE, |
92 SDL_PACKEDLAYOUT_332, | 105 SDL_PACKEDLAYOUT_332, |
93 SDL_PACKEDLAYOUT_4444, | 106 SDL_PACKEDLAYOUT_4444, |
94 SDL_PACKEDLAYOUT_1555, | 107 SDL_PACKEDLAYOUT_1555, |
95 SDL_PACKEDLAYOUT_5551, | 108 SDL_PACKEDLAYOUT_5551, |
199 SDL_PACKEDLAYOUT_8888, 32, 4), | 212 SDL_PACKEDLAYOUT_8888, 32, 4), |
200 SDL_PIXELFORMAT_ARGB2101010 = | 213 SDL_PIXELFORMAT_ARGB2101010 = |
201 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, | 214 SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB, |
202 SDL_PACKEDLAYOUT_2101010, 32, 4), | 215 SDL_PACKEDLAYOUT_2101010, 32, 4), |
203 | 216 |
204 SDL_PIXELFORMAT_YV12 = /* Planar mode: Y + V + U (3 planes) */ | 217 SDL_PIXELFORMAT_YV12 = /**< Planar mode: Y + V + U (3 planes) */ |
205 SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), | 218 SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'), |
206 SDL_PIXELFORMAT_IYUV = /* Planar mode: Y + U + V (3 planes) */ | 219 SDL_PIXELFORMAT_IYUV = /**< Planar mode: Y + U + V (3 planes) */ |
207 SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), | 220 SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'), |
208 SDL_PIXELFORMAT_YUY2 = /* Packed mode: Y0+U0+Y1+V0 (1 plane) */ | 221 SDL_PIXELFORMAT_YUY2 = /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */ |
209 SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), | 222 SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'), |
210 SDL_PIXELFORMAT_UYVY = /* Packed mode: U0+Y0+V0+Y1 (1 plane) */ | 223 SDL_PIXELFORMAT_UYVY = /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */ |
211 SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), | 224 SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'), |
212 SDL_PIXELFORMAT_YVYU = /* Packed mode: Y0+V0+Y1+U0 (1 plane) */ | 225 SDL_PIXELFORMAT_YVYU = /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */ |
213 SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U') | 226 SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U') |
214 }; | 227 }; |
215 | 228 |
216 typedef struct SDL_Color | 229 typedef struct SDL_Color |
217 { | 230 { |
239 | 252 |
240 int refcount; | 253 int refcount; |
241 SDL_PaletteWatch *watch; | 254 SDL_PaletteWatch *watch; |
242 }; | 255 }; |
243 | 256 |
244 /* Everything in the pixel format structure is read-only */ | 257 /** |
258 * \note Everything in the pixel format structure is read-only. | |
259 */ | |
245 typedef struct SDL_PixelFormat | 260 typedef struct SDL_PixelFormat |
246 { | 261 { |
247 SDL_Palette *palette; | 262 SDL_Palette *palette; |
248 Uint8 BitsPerPixel; | 263 Uint8 BitsPerPixel; |
249 Uint8 BytesPerPixel; | 264 Uint8 BytesPerPixel; |
260 Uint32 Bmask; | 275 Uint32 Bmask; |
261 Uint32 Amask; | 276 Uint32 Amask; |
262 } SDL_PixelFormat; | 277 } SDL_PixelFormat; |
263 | 278 |
264 /** | 279 /** |
265 * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask) | 280 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks. |
266 * | 281 * |
267 * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks. | 282 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible. |
268 * | 283 * |
269 * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible. | 284 * \sa SDL_MasksToPixelFormatEnum() |
270 * | |
271 * \sa SDL_MasksToPixelFormatEnum() | |
272 */ | 285 */ |
273 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, | 286 extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format, |
274 int *bpp, | 287 int *bpp, |
275 Uint32 * Rmask, | 288 Uint32 * Rmask, |
276 Uint32 * Gmask, | 289 Uint32 * Gmask, |
277 Uint32 * Bmask, | 290 Uint32 * Bmask, |
278 Uint32 * Amask); | 291 Uint32 * Amask); |
279 | 292 |
280 /** | 293 /** |
281 * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask) | 294 * \brief Convert a bpp and RGBA masks to an enumerated pixel format. |
282 * | 295 * |
283 * \brief Convert a bpp and RGBA masks to an enumerated pixel format. | 296 * \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion |
284 * | 297 * wasn't possible. |
285 * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible. | 298 * |
286 * | 299 * \sa SDL_PixelFormatEnumToMasks() |
287 * \sa SDL_PixelFormatEnumToMasks() | |
288 */ | 300 */ |
289 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, | 301 extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp, |
290 Uint32 Rmask, | 302 Uint32 Rmask, |
291 Uint32 Gmask, | 303 Uint32 Gmask, |
292 Uint32 Bmask, | 304 Uint32 Bmask, |
293 Uint32 Amask); | 305 Uint32 Amask); |
294 | 306 |
295 /** | 307 /** |
296 * \fn SDL_Palette *SDL_AllocPalette(int ncolors) | 308 * \brief Create a palette structure with the specified number of color |
297 * | 309 * entries. |
298 * \brief Create a palette structure with the specified number of color entries. | 310 * |
299 * | 311 * \return A new palette, or NULL if there wasn't enough memory. |
300 * \return A new palette, or NULL if there wasn't enough memory | 312 * |
301 * | 313 * \note The palette entries are initialized to white. |
302 * \note The palette entries are initialized to white. | 314 * |
303 * | 315 * \sa SDL_FreePalette() |
304 * \sa SDL_FreePalette() | |
305 */ | 316 */ |
306 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); | 317 extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors); |
307 | 318 |
308 /** | 319 /** |
309 * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata) | 320 * \brief Add a callback function which is called when the palette changes. |
310 * | 321 * |
311 * \brief Add a callback function which is called when the palette changes. | 322 * \sa SDL_DelPaletteWatch() |
312 * | |
313 * \sa SDL_DelPaletteWatch() | |
314 */ | 323 */ |
315 extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette, | 324 extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette, |
316 SDL_PaletteChangedFunc | 325 SDL_PaletteChangedFunc |
317 callback, void *userdata); | 326 callback, void *userdata); |
318 | 327 |
319 /** | 328 /** |
320 * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata) | 329 * \brief Remove a callback function previously added with |
321 * | 330 * SDL_AddPaletteWatch(). |
322 * \brief Remove a callback function previously added with SDL_AddPaletteWatch() | 331 * |
323 * | 332 * \sa SDL_AddPaletteWatch() |
324 * \sa SDL_AddPaletteWatch() | |
325 */ | 333 */ |
326 extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette, | 334 extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette, |
327 SDL_PaletteChangedFunc | 335 SDL_PaletteChangedFunc |
328 callback, void *userdata); | 336 callback, void *userdata); |
329 | 337 |
330 /** | 338 /** |
331 * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors) | 339 * \brief Set a range of colors in a palette. |
332 * | 340 * |
333 * \brief Set a range of colors in a palette. | 341 * \param palette The palette to modify. |
334 * | 342 * \param colors An array of colors to copy into the palette. |
335 * \param palette The palette to modify | 343 * \param firstcolor The index of the first palette entry to modify. |
336 * \param colors An array of colors to copy into the palette | 344 * \param ncolors The number of entries to modify. |
337 * \param firstcolor The index of the first palette entry to modify | 345 * |
338 * \param ncolors The number of entries to modify | 346 * \return 0 on success, or -1 if not all of the colors could be set. |
339 * | |
340 * \return 0 on success, or -1 if not all of the colors could be set | |
341 */ | 347 */ |
342 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, | 348 extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette, |
343 const SDL_Color * colors, | 349 const SDL_Color * colors, |
344 int firstcolor, int ncolors); | 350 int firstcolor, int ncolors); |
345 | 351 |
346 /** | 352 /** |
347 * \fn void SDL_FreePalette(SDL_Palette *palette) | 353 * \brief Free a palette created with SDL_AllocPalette(). |
348 * | 354 * |
349 * \brief Free a palette created with SDL_AllocPalette() | 355 * \sa SDL_AllocPalette() |
350 * | |
351 * \sa SDL_AllocPalette() | |
352 */ | 356 */ |
353 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); | 357 extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette); |
354 | 358 |
355 /** | 359 /** |
356 * \fn Uint32 SDL_MapRGB(const SDL_PixelFormat *format, | 360 * \brief Maps an RGB triple to an opaque pixel value for a given pixel format. |
357 * Uint8 r, Uint8 g, Uint8 b) | 361 * |
358 * | 362 * \sa SDL_MapRGBA |
359 * \brief Maps an RGB triple to an opaque pixel value for a given pixel format | |
360 * | |
361 * \sa SDL_MapRGBA | |
362 */ | 363 */ |
363 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, | 364 extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format, |
364 Uint8 r, Uint8 g, Uint8 b); | 365 Uint8 r, Uint8 g, Uint8 b); |
365 | 366 |
366 /** | 367 /** |
367 * \fn Uint32 SDL_MapRGBA(const SDL_PixelFormat *fmt, | 368 * \brief Maps an RGBA quadruple to a pixel value for a given pixel format. |
368 * Uint8 r, Uint8 g, Uint8 b, Uint8 a) | 369 * |
369 * | 370 * \sa SDL_MapRGB |
370 * \brief Maps an RGBA quadruple to a pixel value for a given pixel format | |
371 * | |
372 * \sa SDL_MapRGB | |
373 */ | 371 */ |
374 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, | 372 extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format, |
375 Uint8 r, Uint8 g, Uint8 b, | 373 Uint8 r, Uint8 g, Uint8 b, |
376 Uint8 a); | 374 Uint8 a); |
377 | 375 |
378 /** | 376 /** |
379 * \fn void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormat * format, | 377 * \brief Maps a pixel value into the RGB components for a given pixel format. |
380 * Uint8 * r, Uint8 * g, Uint8 * b) | 378 * |
381 * | 379 * \sa SDL_GetRGBA |
382 * \brief Maps a pixel value into the RGB components for a given pixel format | |
383 * | |
384 * \sa SDL_GetRGBA | |
385 */ | 380 */ |
386 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, | 381 extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, |
387 const SDL_PixelFormat * format, | 382 const SDL_PixelFormat * format, |
388 Uint8 * r, Uint8 * g, Uint8 * b); | 383 Uint8 * r, Uint8 * g, Uint8 * b); |
389 | 384 |
390 /** | 385 /** |
391 * \fn void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat * format, | 386 * \brief Maps a pixel value into the RGBA components for a given pixel format. |
392 * Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a) | 387 * |
393 * | 388 * \sa SDL_GetRGB |
394 * \brief Maps a pixel value into the RGBA components for a given pixel format | |
395 * | |
396 * \sa SDL_GetRGB | |
397 */ | 389 */ |
398 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, | 390 extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, |
399 const SDL_PixelFormat * format, | 391 const SDL_PixelFormat * format, |
400 Uint8 * r, Uint8 * g, Uint8 * b, | 392 Uint8 * r, Uint8 * g, Uint8 * b, |
401 Uint8 * a); | 393 Uint8 * a); |