Mercurial > sdl-ios-xcode

comparison include/SDL_pixels.h @ 3407:d3baf5ac4e37

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
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);