include/SDL_pixels.h
changeset 3407 d3baf5ac4e37
parent 3177 efe3b3971e4f
child 3483 a54df8e52333
     1.1 --- a/include/SDL_pixels.h	Sun Oct 18 23:21:15 2009 +0000
     1.2 +++ b/include/SDL_pixels.h	Mon Oct 19 13:31:58 2009 +0000
     1.3 @@ -21,9 +21,9 @@
     1.4  */
     1.5  
     1.6  /**
     1.7 - * \file SDL_pixels.h
     1.8 - *
     1.9 - * Header for the enumerated pixel format definitions
    1.10 + *  \file SDL_pixels.h
    1.11 + *  
    1.12 + *  Header for the enumerated pixel format definitions.
    1.13   */
    1.14  
    1.15  #ifndef _SDL_pixels_h
    1.16 @@ -37,12 +37,19 @@
    1.17  /* *INDENT-ON* */
    1.18  #endif
    1.19  
    1.20 -/* Transparency definitions: These define alpha as the opacity of a surface */
    1.21 +/**
    1.22 + *  \name Transparency definitions
    1.23 + *  
    1.24 + *  These define alpha as the opacity of a surface.
    1.25 + */
    1.26 +/*@{*/
    1.27  #define SDL_ALPHA_OPAQUE 255
    1.28  #define SDL_ALPHA_TRANSPARENT 0
    1.29 +/*@}*/
    1.30  
    1.31 +/** Pixel type. */
    1.32  enum
    1.33 -{                               /* Pixel type */
    1.34 +{
    1.35      SDL_PIXELTYPE_UNKNOWN,
    1.36      SDL_PIXELTYPE_INDEX1,
    1.37      SDL_PIXELTYPE_INDEX4,
    1.38 @@ -57,14 +64,17 @@
    1.39      SDL_PIXELTYPE_ARRAYF32
    1.40  };
    1.41  
    1.42 +/** Bitmap pixel order, high bit -> low bit. */
    1.43  enum
    1.44 -{                               /* bitmap pixel order, high bit -> low bit */
    1.45 +{
    1.46      SDL_BITMAPORDER_NONE,
    1.47      SDL_BITMAPORDER_4321,
    1.48      SDL_BITMAPORDER_1234
    1.49  };
    1.50 +
    1.51 +/** Packed component order, high bit -> low bit. */
    1.52  enum
    1.53 -{                               /* packed component order, high bit -> low bit */
    1.54 +{
    1.55      SDL_PACKEDORDER_NONE,
    1.56      SDL_PACKEDORDER_XRGB,
    1.57      SDL_PACKEDORDER_RGBX,
    1.58 @@ -75,8 +85,10 @@
    1.59      SDL_PACKEDORDER_ABGR,
    1.60      SDL_PACKEDORDER_BGRA
    1.61  };
    1.62 +
    1.63 +/** Array component order, low byte -> high byte. */
    1.64  enum
    1.65 -{                               /* array component order, low byte -> high byte */
    1.66 +{
    1.67      SDL_ARRAYORDER_NONE,
    1.68      SDL_ARRAYORDER_RGB,
    1.69      SDL_ARRAYORDER_RGBA,
    1.70 @@ -86,8 +98,9 @@
    1.71      SDL_ARRAYORDER_ABGR
    1.72  };
    1.73  
    1.74 +/** Packed component layout. */
    1.75  enum
    1.76 -{                               /* Packed component layout */
    1.77 +{
    1.78      SDL_PACKEDLAYOUT_NONE,
    1.79      SDL_PACKEDLAYOUT_332,
    1.80      SDL_PACKEDLAYOUT_4444,
    1.81 @@ -201,15 +214,15 @@
    1.82          SDL_DEFINE_PIXELFORMAT(SDL_PIXELTYPE_PACKED32, SDL_PACKEDORDER_ARGB,
    1.83                                 SDL_PACKEDLAYOUT_2101010, 32, 4),
    1.84  
    1.85 -    SDL_PIXELFORMAT_YV12 =      /* Planar mode: Y + V + U  (3 planes) */
    1.86 +    SDL_PIXELFORMAT_YV12 =      /**< Planar mode: Y + V + U  (3 planes) */
    1.87          SDL_DEFINE_PIXELFOURCC('Y', 'V', '1', '2'),
    1.88 -    SDL_PIXELFORMAT_IYUV =      /* Planar mode: Y + U + V  (3 planes) */
    1.89 +    SDL_PIXELFORMAT_IYUV =      /**< Planar mode: Y + U + V  (3 planes) */
    1.90          SDL_DEFINE_PIXELFOURCC('I', 'Y', 'U', 'V'),
    1.91 -    SDL_PIXELFORMAT_YUY2 =      /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
    1.92 +    SDL_PIXELFORMAT_YUY2 =      /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
    1.93          SDL_DEFINE_PIXELFOURCC('Y', 'U', 'Y', '2'),
    1.94 -    SDL_PIXELFORMAT_UYVY =      /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
    1.95 +    SDL_PIXELFORMAT_UYVY =      /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
    1.96          SDL_DEFINE_PIXELFOURCC('U', 'Y', 'V', 'Y'),
    1.97 -    SDL_PIXELFORMAT_YVYU =      /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
    1.98 +    SDL_PIXELFORMAT_YVYU =      /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
    1.99          SDL_DEFINE_PIXELFOURCC('Y', 'V', 'Y', 'U')
   1.100  };
   1.101  
   1.102 @@ -241,7 +254,9 @@
   1.103      SDL_PaletteWatch *watch;
   1.104  };
   1.105  
   1.106 -/* Everything in the pixel format structure is read-only */
   1.107 +/**
   1.108 + *  \note Everything in the pixel format structure is read-only.
   1.109 + */
   1.110  typedef struct SDL_PixelFormat
   1.111  {
   1.112      SDL_Palette *palette;
   1.113 @@ -262,13 +277,11 @@
   1.114  } SDL_PixelFormat;
   1.115  
   1.116  /**
   1.117 - * \fn SDL_bool SDL_PixelFormatEnumToMasks(Uint32 format, int *bpp, Uint32 * Rmask, Uint32 * Gmask, Uint32 * Bmask, Uint32 * Amask)
   1.118 - *
   1.119 - * \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
   1.120 - *
   1.121 - * \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
   1.122 - *
   1.123 - * \sa SDL_MasksToPixelFormatEnum()
   1.124 + *  \brief Convert one of the enumerated pixel formats to a bpp and RGBA masks.
   1.125 + *  
   1.126 + *  \return SDL_TRUE, or SDL_FALSE if the conversion wasn't possible.
   1.127 + *  
   1.128 + *  \sa SDL_MasksToPixelFormatEnum()
   1.129   */
   1.130  extern DECLSPEC SDL_bool SDLCALL SDL_PixelFormatEnumToMasks(Uint32 format,
   1.131                                                              int *bpp,
   1.132 @@ -278,13 +291,12 @@
   1.133                                                              Uint32 * Amask);
   1.134  
   1.135  /**
   1.136 - * \fn Uint32 SDL_MasksToPixelFormatEnum(int bpp, Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
   1.137 - *
   1.138 - * \brief Convert a bpp and RGBA masks to an enumerated pixel format.
   1.139 - *
   1.140 - * \return The pixel format, or SDL_PixelFormat_Unknown if the conversion wasn't possible.
   1.141 - *
   1.142 - * \sa SDL_PixelFormatEnumToMasks()
   1.143 + *  \brief Convert a bpp and RGBA masks to an enumerated pixel format.
   1.144 + *  
   1.145 + *  \return The pixel format, or ::SDL_PIXELFORMAT_UNKNOWN if the conversion 
   1.146 + *          wasn't possible.
   1.147 + *  
   1.148 + *  \sa SDL_PixelFormatEnumToMasks()
   1.149   */
   1.150  extern DECLSPEC Uint32 SDLCALL SDL_MasksToPixelFormatEnum(int bpp,
   1.151                                                            Uint32 Rmask,
   1.152 @@ -293,107 +305,87 @@
   1.153                                                            Uint32 Amask);
   1.154  
   1.155  /**
   1.156 - * \fn SDL_Palette *SDL_AllocPalette(int ncolors)
   1.157 - *
   1.158 - * \brief Create a palette structure with the specified number of color entries.
   1.159 - *
   1.160 - * \return A new palette, or NULL if there wasn't enough memory
   1.161 - *
   1.162 - * \note The palette entries are initialized to white.
   1.163 - *
   1.164 - * \sa SDL_FreePalette()
   1.165 + *  \brief Create a palette structure with the specified number of color 
   1.166 + *         entries.
   1.167 + *  
   1.168 + *  \return A new palette, or NULL if there wasn't enough memory.
   1.169 + *  
   1.170 + *  \note The palette entries are initialized to white.
   1.171 + *  
   1.172 + *  \sa SDL_FreePalette()
   1.173   */
   1.174  extern DECLSPEC SDL_Palette *SDLCALL SDL_AllocPalette(int ncolors);
   1.175  
   1.176  /**
   1.177 - * \fn int SDL_AddPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
   1.178 - *
   1.179 - * \brief Add a callback function which is called when the palette changes.
   1.180 - *
   1.181 - * \sa SDL_DelPaletteWatch()
   1.182 + *  \brief Add a callback function which is called when the palette changes.
   1.183 + *  
   1.184 + *  \sa SDL_DelPaletteWatch()
   1.185   */
   1.186  extern DECLSPEC int SDLCALL SDL_AddPaletteWatch(SDL_Palette * palette,
   1.187                                                  SDL_PaletteChangedFunc
   1.188                                                  callback, void *userdata);
   1.189  
   1.190  /**
   1.191 - * \fn void SDL_DelPaletteWatch(SDL_Palette *palette, SDL_PaletteChangedFunc callback, void *userdata)
   1.192 - *
   1.193 - * \brief Remove a callback function previously added with SDL_AddPaletteWatch()
   1.194 - *
   1.195 - * \sa SDL_AddPaletteWatch()
   1.196 + *  \brief Remove a callback function previously added with 
   1.197 + *         SDL_AddPaletteWatch().
   1.198 + *  
   1.199 + *  \sa SDL_AddPaletteWatch()
   1.200   */
   1.201  extern DECLSPEC void SDLCALL SDL_DelPaletteWatch(SDL_Palette * palette,
   1.202                                                   SDL_PaletteChangedFunc
   1.203                                                   callback, void *userdata);
   1.204  
   1.205  /**
   1.206 - * \fn int SDL_SetPaletteColors(SDL_Palette *palette, const SDL_Colors *colors, int firstcolor, int numcolors)
   1.207 - *
   1.208 - * \brief Set a range of colors in a palette.
   1.209 - *
   1.210 - * \param palette The palette to modify
   1.211 - * \param colors An array of colors to copy into the palette
   1.212 - * \param firstcolor The index of the first palette entry to modify
   1.213 - * \param ncolors The number of entries to modify
   1.214 - *
   1.215 - * \return 0 on success, or -1 if not all of the colors could be set
   1.216 + *  \brief Set a range of colors in a palette.
   1.217 + *  
   1.218 + *  \param palette    The palette to modify.
   1.219 + *  \param colors     An array of colors to copy into the palette.
   1.220 + *  \param firstcolor The index of the first palette entry to modify.
   1.221 + *  \param ncolors    The number of entries to modify.
   1.222 + *  
   1.223 + *  \return 0 on success, or -1 if not all of the colors could be set.
   1.224   */
   1.225  extern DECLSPEC int SDLCALL SDL_SetPaletteColors(SDL_Palette * palette,
   1.226                                                   const SDL_Color * colors,
   1.227                                                   int firstcolor, int ncolors);
   1.228  
   1.229  /**
   1.230 - * \fn void SDL_FreePalette(SDL_Palette *palette)
   1.231 - *
   1.232 - * \brief Free a palette created with SDL_AllocPalette()
   1.233 - *
   1.234 - * \sa SDL_AllocPalette()
   1.235 + *  \brief Free a palette created with SDL_AllocPalette().
   1.236 + *  
   1.237 + *  \sa SDL_AllocPalette()
   1.238   */
   1.239  extern DECLSPEC void SDLCALL SDL_FreePalette(SDL_Palette * palette);
   1.240  
   1.241  /**
   1.242 - * \fn Uint32 SDL_MapRGB(const SDL_PixelFormat *format,
   1.243 - *                       Uint8 r, Uint8 g, Uint8 b)
   1.244 - *
   1.245 - * \brief Maps an RGB triple to an opaque pixel value for a given pixel format
   1.246 - *
   1.247 - * \sa SDL_MapRGBA
   1.248 + *  \brief Maps an RGB triple to an opaque pixel value for a given pixel format.
   1.249 + *  
   1.250 + *  \sa SDL_MapRGBA
   1.251   */
   1.252  extern DECLSPEC Uint32 SDLCALL SDL_MapRGB(const SDL_PixelFormat * format,
   1.253                                            Uint8 r, Uint8 g, Uint8 b);
   1.254  
   1.255  /**
   1.256 - * \fn Uint32 SDL_MapRGBA(const SDL_PixelFormat *fmt,
   1.257 - *                        Uint8 r, Uint8 g, Uint8 b, Uint8 a)
   1.258 - *
   1.259 - * \brief Maps an RGBA quadruple to a pixel value for a given pixel format
   1.260 - *
   1.261 - * \sa SDL_MapRGB
   1.262 + *  \brief Maps an RGBA quadruple to a pixel value for a given pixel format.
   1.263 + *  
   1.264 + *  \sa SDL_MapRGB
   1.265   */
   1.266  extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(const SDL_PixelFormat * format,
   1.267                                             Uint8 r, Uint8 g, Uint8 b,
   1.268                                             Uint8 a);
   1.269  
   1.270  /**
   1.271 - * \fn void SDL_GetRGB(Uint32 pixel, const SDL_PixelFormat * format,
   1.272 - *                     Uint8 * r, Uint8 * g, Uint8 * b)
   1.273 - *
   1.274 - * \brief Maps a pixel value into the RGB components for a given pixel format
   1.275 - *
   1.276 - * \sa SDL_GetRGBA
   1.277 + *  \brief Maps a pixel value into the RGB components for a given pixel format.
   1.278 + *  
   1.279 + *  \sa SDL_GetRGBA
   1.280   */
   1.281  extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   1.282                                          const SDL_PixelFormat * format,
   1.283                                          Uint8 * r, Uint8 * g, Uint8 * b);
   1.284  
   1.285  /**
   1.286 - * \fn void SDL_GetRGBA(Uint32 pixel, const SDL_PixelFormat * format,
   1.287 - *                      Uint8 * r, Uint8 * g, Uint8 * b, Uint8 * a)
   1.288 - *
   1.289 - * \brief Maps a pixel value into the RGBA components for a given pixel format
   1.290 - *
   1.291 - * \sa SDL_GetRGB
   1.292 + *  \brief Maps a pixel value into the RGBA components for a given pixel format.
   1.293 + *  
   1.294 + *  \sa SDL_GetRGB
   1.295   */
   1.296  extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   1.297                                           const SDL_PixelFormat * format,