include/SDL_video.h
branchSDL-1.2
changeset 4217 4c4113c2162c
parent 4173 34068be6aa0b
child 6137 4720145f848b
     1.1 --- a/include/SDL_video.h	Mon Sep 21 09:27:08 2009 +0000
     1.2 +++ b/include/SDL_video.h	Mon Sep 21 09:38:10 2009 +0000
     1.3 @@ -20,7 +20,9 @@
     1.4      slouken@libsdl.org
     1.5  */
     1.6  
     1.7 -/* Header file for access to the SDL raw framebuffer window */
     1.8 +/** @file SDL_video.h
     1.9 + *  Header file for access to the SDL raw framebuffer window
    1.10 + */
    1.11  
    1.12  #ifndef _SDL_video_h
    1.13  #define _SDL_video_h
    1.14 @@ -35,11 +37,16 @@
    1.15  extern "C" {
    1.16  #endif
    1.17  
    1.18 -/* Transparency definitions: These define alpha as the opacity of a surface */
    1.19 +/** @name Transparency definitions
    1.20 + *  These define alpha as the opacity of a surface
    1.21 + */
    1.22 +/*@{*/
    1.23  #define SDL_ALPHA_OPAQUE 255
    1.24  #define SDL_ALPHA_TRANSPARENT 0
    1.25 +/*@}*/
    1.26  
    1.27 -/* Useful data types */
    1.28 +/** @name Useful data types */
    1.29 +/*@{*/
    1.30  typedef struct SDL_Rect {
    1.31  	Sint16 x, y;
    1.32  	Uint16 w, h;
    1.33 @@ -57,8 +64,9 @@
    1.34  	int       ncolors;
    1.35  	SDL_Color *colors;
    1.36  } SDL_Palette;
    1.37 +/*@}*/
    1.38  
    1.39 -/* Everything in the pixel format structure is read-only */
    1.40 +/** Everything in the pixel format structure is read-only */
    1.41  typedef struct SDL_PixelFormat {
    1.42  	SDL_Palette *palette;
    1.43  	Uint8  BitsPerPixel;
    1.44 @@ -76,128 +84,149 @@
    1.45  	Uint32 Bmask;
    1.46  	Uint32 Amask;
    1.47  
    1.48 -	/* RGB color key information */
    1.49 +	/** RGB color key information */
    1.50  	Uint32 colorkey;
    1.51 -	/* Alpha value information (per-surface alpha) */
    1.52 +	/** Alpha value information (per-surface alpha) */
    1.53  	Uint8  alpha;
    1.54  } SDL_PixelFormat;
    1.55  
    1.56 -/* This structure should be treated as read-only, except for 'pixels',
    1.57 -   which, if not NULL, contains the raw pixel data for the surface.
    1.58 -*/
    1.59 +/** This structure should be treated as read-only, except for 'pixels',
    1.60 + *  which, if not NULL, contains the raw pixel data for the surface.
    1.61 + */
    1.62  typedef struct SDL_Surface {
    1.63 -	Uint32 flags;				/* Read-only */
    1.64 -	SDL_PixelFormat *format;		/* Read-only */
    1.65 -	int w, h;				/* Read-only */
    1.66 -	Uint16 pitch;				/* Read-only */
    1.67 -	void *pixels;				/* Read-write */
    1.68 -	int offset;				/* Private */
    1.69 +	Uint32 flags;				/**< Read-only */
    1.70 +	SDL_PixelFormat *format;		/**< Read-only */
    1.71 +	int w, h;				/**< Read-only */
    1.72 +	Uint16 pitch;				/**< Read-only */
    1.73 +	void *pixels;				/**< Read-write */
    1.74 +	int offset;				/**< Private */
    1.75  
    1.76 -	/* Hardware-specific surface info */
    1.77 +	/** Hardware-specific surface info */
    1.78  	struct private_hwdata *hwdata;
    1.79  
    1.80 -	/* clipping information */
    1.81 -	SDL_Rect clip_rect;			/* Read-only */
    1.82 -	Uint32 unused1;				/* for binary compatibility */
    1.83 +	/** clipping information */
    1.84 +	SDL_Rect clip_rect;			/**< Read-only */
    1.85 +	Uint32 unused1;				/**< for binary compatibility */
    1.86  
    1.87 -	/* Allow recursive locks */
    1.88 -	Uint32 locked;				/* Private */
    1.89 +	/** Allow recursive locks */
    1.90 +	Uint32 locked;				/**< Private */
    1.91  
    1.92 -	/* info for fast blit mapping to other surfaces */
    1.93 -	struct SDL_BlitMap *map;		/* Private */
    1.94 +	/** info for fast blit mapping to other surfaces */
    1.95 +	struct SDL_BlitMap *map;		/**< Private */
    1.96  
    1.97 -	/* format version, bumped at every change to invalidate blit maps */
    1.98 -	unsigned int format_version;		/* Private */
    1.99 +	/** format version, bumped at every change to invalidate blit maps */
   1.100 +	unsigned int format_version;		/**< Private */
   1.101  
   1.102 -	/* Reference count -- used when freeing surface */
   1.103 -	int refcount;				/* Read-mostly */
   1.104 +	/** Reference count -- used when freeing surface */
   1.105 +	int refcount;				/**< Read-mostly */
   1.106  } SDL_Surface;
   1.107  
   1.108 -/* These are the currently supported flags for the SDL_surface */
   1.109 -/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
   1.110 -#define SDL_SWSURFACE	0x00000000	/* Surface is in system memory */
   1.111 -#define SDL_HWSURFACE	0x00000001	/* Surface is in video memory */
   1.112 -#define SDL_ASYNCBLIT	0x00000004	/* Use asynchronous blits if possible */
   1.113 -/* Available for SDL_SetVideoMode() */
   1.114 -#define SDL_ANYFORMAT	0x10000000	/* Allow any video depth/pixel-format */
   1.115 -#define SDL_HWPALETTE	0x20000000	/* Surface has exclusive palette */
   1.116 -#define SDL_DOUBLEBUF	0x40000000	/* Set up double-buffered video mode */
   1.117 -#define SDL_FULLSCREEN	0x80000000	/* Surface is a full screen display */
   1.118 -#define SDL_OPENGL      0x00000002      /* Create an OpenGL rendering context */
   1.119 -#define SDL_OPENGLBLIT	0x0000000A	/* Create an OpenGL rendering context and use it for blitting */
   1.120 -#define SDL_RESIZABLE	0x00000010	/* This video mode may be resized */
   1.121 -#define SDL_NOFRAME	0x00000020	/* No window caption or edge frame */
   1.122 -/* Used internally (read-only) */
   1.123 -#define SDL_HWACCEL	0x00000100	/* Blit uses hardware acceleration */
   1.124 -#define SDL_SRCCOLORKEY	0x00001000	/* Blit uses a source color key */
   1.125 -#define SDL_RLEACCELOK	0x00002000	/* Private flag */
   1.126 -#define SDL_RLEACCEL	0x00004000	/* Surface is RLE encoded */
   1.127 -#define SDL_SRCALPHA	0x00010000	/* Blit uses source alpha blending */
   1.128 -#define SDL_PREALLOC	0x01000000	/* Surface uses preallocated memory */
   1.129 +/** @name SDL_Surface Flags
   1.130 + *  These are the currently supported flags for the SDL_surface
   1.131 + */
   1.132 +/*@{*/
   1.133  
   1.134 -/* Evaluates to true if the surface needs to be locked before access */
   1.135 +/** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
   1.136 +/*@{*/
   1.137 +#define SDL_SWSURFACE	0x00000000	/**< Surface is in system memory */
   1.138 +#define SDL_HWSURFACE	0x00000001	/**< Surface is in video memory */
   1.139 +#define SDL_ASYNCBLIT	0x00000004	/**< Use asynchronous blits if possible */
   1.140 +/*@}*/
   1.141 +
   1.142 +/** Available for SDL_SetVideoMode() */
   1.143 +/*@{*/
   1.144 +#define SDL_ANYFORMAT	0x10000000	/**< Allow any video depth/pixel-format */
   1.145 +#define SDL_HWPALETTE	0x20000000	/**< Surface has exclusive palette */
   1.146 +#define SDL_DOUBLEBUF	0x40000000	/**< Set up double-buffered video mode */
   1.147 +#define SDL_FULLSCREEN	0x80000000	/**< Surface is a full screen display */
   1.148 +#define SDL_OPENGL      0x00000002      /**< Create an OpenGL rendering context */
   1.149 +#define SDL_OPENGLBLIT	0x0000000A	/**< Create an OpenGL rendering context and use it for blitting */
   1.150 +#define SDL_RESIZABLE	0x00000010	/**< This video mode may be resized */
   1.151 +#define SDL_NOFRAME	0x00000020	/**< No window caption or edge frame */
   1.152 +/*@}*/
   1.153 +
   1.154 +/** Used internally (read-only) */
   1.155 +/*@{*/
   1.156 +#define SDL_HWACCEL	0x00000100	/**< Blit uses hardware acceleration */
   1.157 +#define SDL_SRCCOLORKEY	0x00001000	/**< Blit uses a source color key */
   1.158 +#define SDL_RLEACCELOK	0x00002000	/**< Private flag */
   1.159 +#define SDL_RLEACCEL	0x00004000	/**< Surface is RLE encoded */
   1.160 +#define SDL_SRCALPHA	0x00010000	/**< Blit uses source alpha blending */
   1.161 +#define SDL_PREALLOC	0x01000000	/**< Surface uses preallocated memory */
   1.162 +/*@}*/
   1.163 +
   1.164 +/*@}*/
   1.165 +
   1.166 +/** Evaluates to true if the surface needs to be locked before access */
   1.167  #define SDL_MUSTLOCK(surface)	\
   1.168    (surface->offset ||		\
   1.169    ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
   1.170  
   1.171 -/* typedef for private surface blitting functions */
   1.172 +/** typedef for private surface blitting functions */
   1.173  typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
   1.174  			struct SDL_Surface *dst, SDL_Rect *dstrect);
   1.175  
   1.176  
   1.177 -/* Useful for determining the video hardware capabilities */
   1.178 +/** Useful for determining the video hardware capabilities */
   1.179  typedef struct SDL_VideoInfo {
   1.180 -	Uint32 hw_available :1;	/* Flag: Can you create hardware surfaces? */
   1.181 -	Uint32 wm_available :1;	/* Flag: Can you talk to a window manager? */
   1.182 +	Uint32 hw_available :1;	/**< Flag: Can you create hardware surfaces? */
   1.183 +	Uint32 wm_available :1;	/**< Flag: Can you talk to a window manager? */
   1.184  	Uint32 UnusedBits1  :6;
   1.185  	Uint32 UnusedBits2  :1;
   1.186 -	Uint32 blit_hw      :1;	/* Flag: Accelerated blits HW --> HW */
   1.187 -	Uint32 blit_hw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
   1.188 -	Uint32 blit_hw_A    :1;	/* Flag: Accelerated blits with Alpha */
   1.189 -	Uint32 blit_sw      :1;	/* Flag: Accelerated blits SW --> HW */
   1.190 -	Uint32 blit_sw_CC   :1;	/* Flag: Accelerated blits with Colorkey */
   1.191 -	Uint32 blit_sw_A    :1;	/* Flag: Accelerated blits with Alpha */
   1.192 -	Uint32 blit_fill    :1;	/* Flag: Accelerated color fill */
   1.193 +	Uint32 blit_hw      :1;	/**< Flag: Accelerated blits HW --> HW */
   1.194 +	Uint32 blit_hw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
   1.195 +	Uint32 blit_hw_A    :1;	/**< Flag: Accelerated blits with Alpha */
   1.196 +	Uint32 blit_sw      :1;	/**< Flag: Accelerated blits SW --> HW */
   1.197 +	Uint32 blit_sw_CC   :1;	/**< Flag: Accelerated blits with Colorkey */
   1.198 +	Uint32 blit_sw_A    :1;	/**< Flag: Accelerated blits with Alpha */
   1.199 +	Uint32 blit_fill    :1;	/**< Flag: Accelerated color fill */
   1.200  	Uint32 UnusedBits3  :16;
   1.201 -	Uint32 video_mem;	/* The total amount of video memory (in K) */
   1.202 -	SDL_PixelFormat *vfmt;	/* Value: The format of the video surface */
   1.203 -	int    current_w;	/* Value: The current video mode width */
   1.204 -	int    current_h;	/* Value: The current video mode height */
   1.205 +	Uint32 video_mem;	/**< The total amount of video memory (in K) */
   1.206 +	SDL_PixelFormat *vfmt;	/**< Value: The format of the video surface */
   1.207 +	int    current_w;	/**< Value: The current video mode width */
   1.208 +	int    current_h;	/**< Value: The current video mode height */
   1.209  } SDL_VideoInfo;
   1.210  
   1.211  
   1.212 -/* The most common video overlay formats.
   1.213 -   For an explanation of these pixel formats, see:
   1.214 -	http://www.webartz.com/fourcc/indexyuv.htm
   1.215 +/** @name Overlay Formats
   1.216 + *  The most common video overlay formats.
   1.217 + *  For an explanation of these pixel formats, see:
   1.218 + *	http://www.webartz.com/fourcc/indexyuv.htm
   1.219 + *
   1.220 + *  For information on the relationship between color spaces, see:
   1.221 + *  http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
   1.222 + */
   1.223 +/*@{*/
   1.224 +#define SDL_YV12_OVERLAY  0x32315659	/**< Planar mode: Y + V + U  (3 planes) */
   1.225 +#define SDL_IYUV_OVERLAY  0x56555949	/**< Planar mode: Y + U + V  (3 planes) */
   1.226 +#define SDL_YUY2_OVERLAY  0x32595559	/**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
   1.227 +#define SDL_UYVY_OVERLAY  0x59565955	/**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
   1.228 +#define SDL_YVYU_OVERLAY  0x55595659	/**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
   1.229 +/*@}*/
   1.230  
   1.231 -   For information on the relationship between color spaces, see:
   1.232 -   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
   1.233 - */
   1.234 -#define SDL_YV12_OVERLAY  0x32315659	/* Planar mode: Y + V + U  (3 planes) */
   1.235 -#define SDL_IYUV_OVERLAY  0x56555949	/* Planar mode: Y + U + V  (3 planes) */
   1.236 -#define SDL_YUY2_OVERLAY  0x32595559	/* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   1.237 -#define SDL_UYVY_OVERLAY  0x59565955	/* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   1.238 -#define SDL_YVYU_OVERLAY  0x55595659	/* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   1.239 +/** The YUV hardware video overlay */
   1.240 +typedef struct SDL_Overlay {
   1.241 +	Uint32 format;				/**< Read-only */
   1.242 +	int w, h;				/**< Read-only */
   1.243 +	int planes;				/**< Read-only */
   1.244 +	Uint16 *pitches;			/**< Read-only */
   1.245 +	Uint8 **pixels;				/**< Read-write */
   1.246  
   1.247 -/* The YUV hardware video overlay */
   1.248 -typedef struct SDL_Overlay {
   1.249 -	Uint32 format;				/* Read-only */
   1.250 -	int w, h;				/* Read-only */
   1.251 -	int planes;				/* Read-only */
   1.252 -	Uint16 *pitches;			/* Read-only */
   1.253 -	Uint8 **pixels;				/* Read-write */
   1.254 -
   1.255 -	/* Hardware-specific surface info */
   1.256 +	/** @name Hardware-specific surface info */
   1.257 +        /*@{*/
   1.258  	struct private_yuvhwfuncs *hwfuncs;
   1.259  	struct private_yuvhwdata *hwdata;
   1.260 +        /*@{*/
   1.261  
   1.262 -	/* Special flags */
   1.263 -	Uint32 hw_overlay :1;	/* Flag: This overlay hardware accelerated? */
   1.264 +	/** @name Special flags */
   1.265 +        /*@{*/
   1.266 +	Uint32 hw_overlay :1;	/**< Flag: This overlay hardware accelerated? */
   1.267  	Uint32 UnusedBits :31;
   1.268 +        /*@}*/
   1.269  } SDL_Overlay;
   1.270  
   1.271  
   1.272 -/* Public enumeration for setting the OpenGL window attributes. */
   1.273 +/** Public enumeration for setting the OpenGL window attributes. */
   1.274  typedef enum {
   1.275      SDL_GL_RED_SIZE,
   1.276      SDL_GL_GREEN_SIZE,
   1.277 @@ -218,17 +247,23 @@
   1.278      SDL_GL_SWAP_CONTROL
   1.279  } SDL_GLattr;
   1.280  
   1.281 -/* flags for SDL_SetPalette() */
   1.282 +/** @name flags for SDL_SetPalette() */
   1.283 +/*@{*/
   1.284  #define SDL_LOGPAL 0x01
   1.285  #define SDL_PHYSPAL 0x02
   1.286 +/*@}*/
   1.287  
   1.288  /* Function prototypes */
   1.289  
   1.290 -/* These functions are used internally, and should not be used unless you
   1.291 +/**
   1.292 + * @name Video Init and Quit
   1.293 + * These functions are used internally, and should not be used unless you
   1.294   * have a specific need to specify the video driver you want to use.
   1.295   * You should normally use SDL_Init() or SDL_InitSubSystem().
   1.296 - *
   1.297 - * SDL_VideoInit() initializes the video subsystem -- sets up a connection
   1.298 + */
   1.299 +/*@{*/
   1.300 +/**
   1.301 + * Initializes the video subsystem. Sets up a connection
   1.302   * to the window manager, etc, and determines the current video mode and
   1.303   * pixel format, but does not initialize a window or graphics mode.
   1.304   * Note that event handling is activated by this routine.
   1.305 @@ -239,14 +274,16 @@
   1.306   */
   1.307  extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
   1.308  extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
   1.309 +/*@}*/
   1.310  
   1.311 -/* This function fills the given character buffer with the name of the
   1.312 +/**
   1.313 + * This function fills the given character buffer with the name of the
   1.314   * video driver, and returns a pointer to it if the video driver has
   1.315   * been initialized.  It returns NULL if no driver has been initialized.
   1.316   */
   1.317  extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
   1.318  
   1.319 -/*
   1.320 +/**
   1.321   * This function returns a pointer to the current display surface.
   1.322   * If SDL is doing format conversion on the display surface, this
   1.323   * function returns the publicly visible surface, not the real video
   1.324 @@ -254,7 +291,7 @@
   1.325   */
   1.326  extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
   1.327  
   1.328 -/*
   1.329 +/**
   1.330   * This function returns a read-only pointer to information about the
   1.331   * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
   1.332   * member of the returned structure will contain the pixel format of the
   1.333 @@ -262,7 +299,7 @@
   1.334   */
   1.335  extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
   1.336  
   1.337 -/* 
   1.338 +/**
   1.339   * Check to see if a particular video mode is supported.
   1.340   * It returns 0 if the requested mode is not supported under any bit depth,
   1.341   * or returns the bits-per-pixel of the closest available mode with the
   1.342 @@ -275,7 +312,7 @@
   1.343   */
   1.344  extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
   1.345  
   1.346 -/*
   1.347 +/**
   1.348   * Return a pointer to an array of available screen dimensions for the
   1.349   * given format and video flags, sorted largest to smallest.  Returns 
   1.350   * NULL if there are no dimensions available for a particular format, 
   1.351 @@ -286,7 +323,7 @@
   1.352   */
   1.353  extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
   1.354  
   1.355 -/*
   1.356 +/**
   1.357   * Set up a video mode with the specified width, height and bits-per-pixel.
   1.358   *
   1.359   * If 'bpp' is 0, it is treated as the current display bits per pixel.
   1.360 @@ -347,18 +384,24 @@
   1.361  extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
   1.362  			(int width, int height, int bpp, Uint32 flags);
   1.363  
   1.364 -/*
   1.365 +/** @name SDL_Update Functions
   1.366 + * These functions should not be called while 'screen' is locked.
   1.367 + */
   1.368 +/*@{*/
   1.369 +/**
   1.370   * Makes sure the given list of rectangles is updated on the given screen.
   1.371 - * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   1.372 - * screen.
   1.373 - * These functions should not be called while 'screen' is locked.
   1.374   */
   1.375  extern DECLSPEC void SDLCALL SDL_UpdateRects
   1.376  		(SDL_Surface *screen, int numrects, SDL_Rect *rects);
   1.377 +/**
   1.378 + * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   1.379 + * screen.
   1.380 + */
   1.381  extern DECLSPEC void SDLCALL SDL_UpdateRect
   1.382  		(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   1.383 +/*@}*/
   1.384  
   1.385 -/*
   1.386 +/**
   1.387   * On hardware that supports double-buffering, this function sets up a flip
   1.388   * and returns.  The hardware will wait for vertical retrace, and then swap
   1.389   * video buffers before the next video surface blit or lock will return.
   1.390 @@ -370,7 +413,7 @@
   1.391   */
   1.392  extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
   1.393  
   1.394 -/*
   1.395 +/**
   1.396   * Set the gamma correction for each of the color channels.
   1.397   * The gamma values range (approximately) between 0.1 and 10.0
   1.398   * 
   1.399 @@ -380,7 +423,7 @@
   1.400   */
   1.401  extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
   1.402  
   1.403 -/*
   1.404 +/**
   1.405   * Set the gamma translation table for the red, green, and blue channels
   1.406   * of the video hardware.  Each table is an array of 256 16-bit quantities,
   1.407   * representing a mapping between the input and output for that channel.
   1.408 @@ -394,7 +437,7 @@
   1.409   */
   1.410  extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
   1.411  
   1.412 -/*
   1.413 +/**
   1.414   * Retrieve the current values of the gamma translation tables.
   1.415   * 
   1.416   * You must pass in valid pointers to arrays of 256 16-bit quantities.
   1.417 @@ -405,7 +448,7 @@
   1.418   */
   1.419  extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
   1.420  
   1.421 -/*
   1.422 +/**
   1.423   * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
   1.424   * is not a palettized surface, this function does nothing, returning 0.
   1.425   * If all of the colors were set as passed to SDL_SetColors(), it will
   1.426 @@ -423,7 +466,7 @@
   1.427  extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, 
   1.428  			SDL_Color *colors, int firstcolor, int ncolors);
   1.429  
   1.430 -/*
   1.431 +/**
   1.432   * Sets a portion of the colormap for a given 8-bit surface.
   1.433   * 'flags' is one or both of:
   1.434   * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
   1.435 @@ -443,35 +486,37 @@
   1.436  				   SDL_Color *colors, int firstcolor,
   1.437  				   int ncolors);
   1.438  
   1.439 -/*
   1.440 +/**
   1.441   * Maps an RGB triple to an opaque pixel value for a given pixel format
   1.442   */
   1.443  extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
   1.444  (const SDL_PixelFormat * const format,
   1.445   const Uint8 r, const Uint8 g, const Uint8 b);
   1.446  
   1.447 -/*
   1.448 +/**
   1.449   * Maps an RGBA quadruple to a pixel value for a given pixel format
   1.450   */
   1.451  extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
   1.452  (const SDL_PixelFormat * const format,
   1.453   const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
   1.454  
   1.455 -/*
   1.456 +/**
   1.457   * Maps a pixel value into the RGB components for a given pixel format
   1.458   */
   1.459  extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
   1.460  				const SDL_PixelFormat * const fmt,
   1.461  				Uint8 *r, Uint8 *g, Uint8 *b);
   1.462  
   1.463 -/*
   1.464 +/**
   1.465   * Maps a pixel value into the RGBA components for a given pixel format
   1.466   */
   1.467  extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
   1.468  				const SDL_PixelFormat * const fmt,
   1.469  				Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
   1.470  
   1.471 -/*
   1.472 +/** @sa SDL_CreateRGBSurface */
   1.473 +#define SDL_AllocSurface    SDL_CreateRGBSurface
   1.474 +/**
   1.475   * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
   1.476   * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
   1.477   * If the depth is greater than 8 bits, the pixel format is set using the
   1.478 @@ -505,16 +550,16 @@
   1.479   * reason the surface could not be placed in video memory, it will not have
   1.480   * the SDL_HWSURFACE flag set, and will be created in system memory instead.
   1.481   */
   1.482 -#define SDL_AllocSurface    SDL_CreateRGBSurface
   1.483  extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
   1.484  			(Uint32 flags, int width, int height, int depth, 
   1.485  			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   1.486 +/** @sa SDL_CreateRGBSurface */
   1.487  extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
   1.488  			int width, int height, int depth, int pitch,
   1.489  			Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   1.490  extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
   1.491  
   1.492 -/*
   1.493 +/**
   1.494   * SDL_LockSurface() sets up a surface for directly accessing the pixels.
   1.495   * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
   1.496   * to and read from 'surface->pixels', using the pixel format stored in 
   1.497 @@ -535,7 +580,7 @@
   1.498  extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
   1.499  extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
   1.500  
   1.501 -/*
   1.502 +/**
   1.503   * Load a surface from a seekable SDL data source (memory or file.)
   1.504   * If 'freesrc' is non-zero, the source will be closed after being read.
   1.505   * Returns the new surface, or NULL if there was an error.
   1.506 @@ -543,10 +588,10 @@
   1.507   */
   1.508  extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
   1.509  
   1.510 -/* Convenience macro -- load a surface from a file */
   1.511 +/** Convenience macro -- load a surface from a file */
   1.512  #define SDL_LoadBMP(file)	SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
   1.513  
   1.514 -/*
   1.515 +/**
   1.516   * Save a surface to a seekable SDL data source (memory or file.)
   1.517   * If 'freedst' is non-zero, the source will be closed after being written.
   1.518   * Returns 0 if successful or -1 if there was an error.
   1.519 @@ -554,11 +599,11 @@
   1.520  extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
   1.521  		(SDL_Surface *surface, SDL_RWops *dst, int freedst);
   1.522  
   1.523 -/* Convenience macro -- save a surface to a file */
   1.524 +/** Convenience macro -- save a surface to a file */
   1.525  #define SDL_SaveBMP(surface, file) \
   1.526  		SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
   1.527  
   1.528 -/*
   1.529 +/**
   1.530   * Sets the color key (transparent pixel) in a blittable surface.
   1.531   * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
   1.532   * 'key' will be the transparent pixel in the source image of a blit.
   1.533 @@ -570,7 +615,7 @@
   1.534  extern DECLSPEC int SDLCALL SDL_SetColorKey
   1.535  			(SDL_Surface *surface, Uint32 flag, Uint32 key);
   1.536  
   1.537 -/*
   1.538 +/**
   1.539   * This function sets the alpha value for the entire surface, as opposed to
   1.540   * using the alpha component of each pixel. This value measures the range
   1.541   * of transparency of the surface, 0 being completely transparent to 255
   1.542 @@ -587,7 +632,7 @@
   1.543   */
   1.544  extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
   1.545  
   1.546 -/*
   1.547 +/**
   1.548   * Sets the clipping rectangle for the destination surface in a blit.
   1.549   *
   1.550   * If the clip rectangle is NULL, clipping will be disabled.
   1.551 @@ -601,14 +646,14 @@
   1.552   */
   1.553  extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
   1.554  
   1.555 -/*
   1.556 +/**
   1.557   * Gets the clipping rectangle for the destination surface in a blit.
   1.558   * 'rect' must be a pointer to a valid rectangle which will be filled
   1.559   * with the correct values.
   1.560   */
   1.561  extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
   1.562  
   1.563 -/*
   1.564 +/**
   1.565   * Creates a new surface of the specified format, and then copies and maps 
   1.566   * the given surface to it so the blit of the converted surface will be as 
   1.567   * fast as possible.  If this function fails, it returns NULL.
   1.568 @@ -623,7 +668,7 @@
   1.569  extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
   1.570  			(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
   1.571  
   1.572 -/*
   1.573 +/**
   1.574   * This performs a fast blit from the source surface to the destination
   1.575   * surface.  It assumes that the source and destination rectangles are
   1.576   * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
   1.577 @@ -679,35 +724,38 @@
   1.578   * If either of the surfaces were in video memory, and the blit returns -2,
   1.579   * the video memory was lost, so it should be reloaded with artwork and 
   1.580   * re-blitted:
   1.581 -	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   1.582 -		while ( SDL_LockSurface(image) < 0 )
   1.583 -			Sleep(10);
   1.584 -		-- Write image pixels to image->pixels --
   1.585 -		SDL_UnlockSurface(image);
   1.586 -	}
   1.587 + * @code
   1.588 + *	while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
   1.589 + *		while ( SDL_LockSurface(image) < 0 )
   1.590 + *			Sleep(10);
   1.591 + *		-- Write image pixels to image->pixels --
   1.592 + *		SDL_UnlockSurface(image);
   1.593 + *	}
   1.594 + * @endcode
   1.595 + *
   1.596   * This happens under DirectX 5.0 when the system switches away from your
   1.597   * fullscreen application.  The lock will also fail until you have access
   1.598   * to the video memory again.
   1.599 + *
   1.600 + * You should call SDL_BlitSurface() unless you know exactly how SDL
   1.601 + * blitting works internally and how to use the other blit functions.
   1.602   */
   1.603 -/* You should call SDL_BlitSurface() unless you know exactly how SDL
   1.604 -   blitting works internally and how to use the other blit functions.
   1.605 -*/
   1.606  #define SDL_BlitSurface SDL_UpperBlit
   1.607  
   1.608 -/* This is the public blit function, SDL_BlitSurface(), and it performs
   1.609 -   rectangle validation and clipping before passing it to SDL_LowerBlit()
   1.610 -*/
   1.611 +/** This is the public blit function, SDL_BlitSurface(), and it performs
   1.612 + *  rectangle validation and clipping before passing it to SDL_LowerBlit()
   1.613 + */
   1.614  extern DECLSPEC int SDLCALL SDL_UpperBlit
   1.615  			(SDL_Surface *src, SDL_Rect *srcrect,
   1.616  			 SDL_Surface *dst, SDL_Rect *dstrect);
   1.617 -/* This is a semi-private blit function and it performs low-level surface
   1.618 -   blitting only.
   1.619 -*/
   1.620 +/** This is a semi-private blit function and it performs low-level surface
   1.621 + *  blitting only.
   1.622 + */
   1.623  extern DECLSPEC int SDLCALL SDL_LowerBlit
   1.624  			(SDL_Surface *src, SDL_Rect *srcrect,
   1.625  			 SDL_Surface *dst, SDL_Rect *dstrect);
   1.626  
   1.627 -/*
   1.628 +/**
   1.629   * This function performs a fast fill of the given rectangle with 'color'
   1.630   * The given rectangle is clipped to the destination surface clip area
   1.631   * and the final fill rectangle is saved in the passed in pointer.
   1.632 @@ -719,7 +767,7 @@
   1.633  extern DECLSPEC int SDLCALL SDL_FillRect
   1.634  		(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
   1.635  
   1.636 -/* 
   1.637 +/**
   1.638   * This function takes a surface and copies it to a new surface of the
   1.639   * pixel format and colors of the video framebuffer, suitable for fast
   1.640   * blitting onto the display surface.  It calls SDL_ConvertSurface()
   1.641 @@ -732,7 +780,7 @@
   1.642   */
   1.643  extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
   1.644  
   1.645 -/* 
   1.646 +/**
   1.647   * This function takes a surface and copies it to a new surface of the
   1.648   * pixel format and colors of the video framebuffer (if possible),
   1.649   * suitable for fast alpha blitting onto the display surface.
   1.650 @@ -748,38 +796,39 @@
   1.651  
   1.652  
   1.653  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.654 -/* YUV video surface overlay functions                                       */
   1.655 +/** @name YUV video surface overlay functions                                */ /*@{*/
   1.656  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.657  
   1.658 -/* This function creates a video output overlay
   1.659 -   Calling the returned surface an overlay is something of a misnomer because
   1.660 -   the contents of the display surface underneath the area where the overlay
   1.661 -   is shown is undefined - it may be overwritten with the converted YUV data.
   1.662 -*/
   1.663 +/** This function creates a video output overlay
   1.664 + *  Calling the returned surface an overlay is something of a misnomer because
   1.665 + *  the contents of the display surface underneath the area where the overlay
   1.666 + *  is shown is undefined - it may be overwritten with the converted YUV data.
   1.667 + */
   1.668  extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
   1.669  				Uint32 format, SDL_Surface *display);
   1.670  
   1.671 -/* Lock an overlay for direct access, and unlock it when you are done */
   1.672 +/** Lock an overlay for direct access, and unlock it when you are done */
   1.673  extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
   1.674  extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
   1.675  
   1.676 -/* Blit a video overlay to the display surface.
   1.677 -   The contents of the video surface underneath the blit destination are
   1.678 -   not defined.  
   1.679 -   The width and height of the destination rectangle may be different from
   1.680 -   that of the overlay, but currently only 2x scaling is supported.
   1.681 -*/
   1.682 +/** Blit a video overlay to the display surface.
   1.683 + *  The contents of the video surface underneath the blit destination are
   1.684 + *  not defined.  
   1.685 + *  The width and height of the destination rectangle may be different from
   1.686 + *  that of the overlay, but currently only 2x scaling is supported.
   1.687 + */
   1.688  extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
   1.689  
   1.690 -/* Free a video overlay */
   1.691 +/** Free a video overlay */
   1.692  extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
   1.693  
   1.694 +/*@}*/
   1.695  
   1.696  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.697 -/* OpenGL support functions.                                                 */
   1.698 +/** @name OpenGL support functions.                                          */ /*@{*/
   1.699  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.700  
   1.701 -/*
   1.702 +/**
   1.703   * Dynamically load an OpenGL library, or the default one if path is NULL
   1.704   *
   1.705   * If you do this, you need to retrieve all of the GL functions used in
   1.706 @@ -787,17 +836,17 @@
   1.707   */
   1.708  extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
   1.709  
   1.710 -/*
   1.711 +/**
   1.712   * Get the address of a GL function
   1.713   */
   1.714  extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
   1.715  
   1.716 -/*
   1.717 +/**
   1.718   * Set an attribute of the OpenGL subsystem before intialization.
   1.719   */
   1.720  extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
   1.721  
   1.722 -/*
   1.723 +/**
   1.724   * Get an attribute of the OpenGL subsystem from the windowing
   1.725   * interface, such as glX. This is of course different from getting
   1.726   * the values from SDL's internal OpenGL subsystem, which only
   1.727 @@ -808,30 +857,38 @@
   1.728   */
   1.729  extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
   1.730  
   1.731 -/*
   1.732 +/**
   1.733   * Swap the OpenGL buffers, if double-buffering is supported.
   1.734   */
   1.735  extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
   1.736  
   1.737 -/*
   1.738 +/** @name OpenGL Internal Functions
   1.739   * Internal functions that should not be called unless you have read
   1.740   * and understood the source code for these functions.
   1.741   */
   1.742 +/*@{*/
   1.743  extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
   1.744  extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
   1.745  extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
   1.746 +/*@}*/
   1.747 +
   1.748 +/*@}*/
   1.749  
   1.750  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.751 -/* These functions allow interaction with the window manager, if any.        */
   1.752 +/** @name Window Manager Functions                                           */
   1.753 +/** These functions allow interaction with the window manager, if any.       */ /*@{*/
   1.754  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.755  
   1.756 -/*
   1.757 - * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
   1.758 +/**
   1.759 + * Sets the title and icon text of the display window (UTF-8 encoded)
   1.760   */
   1.761  extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
   1.762 +/**
   1.763 + * Gets the title and icon text of the display window (UTF-8 encoded)
   1.764 + */
   1.765  extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
   1.766  
   1.767 -/*
   1.768 +/**
   1.769   * Sets the icon for the display window.
   1.770   * This function must be called before the first call to SDL_SetVideoMode().
   1.771   * It takes an icon surface, and a mask in MSB format.
   1.772 @@ -839,14 +896,14 @@
   1.773   */
   1.774  extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
   1.775  
   1.776 -/*
   1.777 +/**
   1.778   * This function iconifies the window, and returns 1 if it succeeded.
   1.779   * If the function succeeds, it generates an SDL_APPACTIVE loss event.
   1.780   * This function is a noop and returns 0 in non-windowed environments.
   1.781   */
   1.782  extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
   1.783  
   1.784 -/*
   1.785 +/**
   1.786   * Toggle fullscreen mode without changing the contents of the screen.
   1.787   * If the display surface does not require locking before accessing
   1.788   * the pixel information, then the memory pointers will not change.
   1.789 @@ -863,24 +920,25 @@
   1.790   */
   1.791  extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
   1.792  
   1.793 -/*
   1.794 - * This function allows you to set and query the input grab state of
   1.795 - * the application.  It returns the new input grab state.
   1.796 - */
   1.797  typedef enum {
   1.798  	SDL_GRAB_QUERY = -1,
   1.799  	SDL_GRAB_OFF = 0,
   1.800  	SDL_GRAB_ON = 1,
   1.801 -	SDL_GRAB_FULLSCREEN	/* Used internally */
   1.802 +	SDL_GRAB_FULLSCREEN	/**< Used internally */
   1.803  } SDL_GrabMode;
   1.804 -/*
   1.805 +/**
   1.806 + * This function allows you to set and query the input grab state of
   1.807 + * the application.  It returns the new input grab state.
   1.808 + *
   1.809   * Grabbing means that the mouse is confined to the application window,
   1.810   * and nearly all keyboard input is passed directly to the application,
   1.811   * and not interpreted by a window manager, if any.
   1.812   */
   1.813  extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
   1.814  
   1.815 -/* Not in public API at the moment - do not use! */
   1.816 +/*@}*/
   1.817 +
   1.818 +/** @internal Not in public API at the moment - do not use! */
   1.819  extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
   1.820                                      SDL_Surface *dst, SDL_Rect *dstrect);
   1.821