/*
SDL - Simple DirectMedia Layer
- Copyright (C) 1997-2006 Sam Lantinga
+ Copyright (C) 1997-2009 Sam Lantinga
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Lesser General Public
slouken@libsdl.org
*/
-/* Header file for access to the SDL raw framebuffer window */
+/** @file SDL_video.h
+ * Header file for access to the SDL raw framebuffer window
+ */
#ifndef _SDL_video_h
#define _SDL_video_h
extern "C" {
#endif
-/* Transparency definitions: These define alpha as the opacity of a surface */
+/** @name Transparency definitions
+ * These define alpha as the opacity of a surface
+ */
+/*@{*/
#define SDL_ALPHA_OPAQUE 255
#define SDL_ALPHA_TRANSPARENT 0
+/*@}*/
-/* Useful data types */
+/** @name Useful data types */
+/*@{*/
typedef struct SDL_Rect {
Sint16 x, y;
Uint16 w, h;
int ncolors;
SDL_Color *colors;
} SDL_Palette;
+/*@}*/
-/* Everything in the pixel format structure is read-only */
+/** Everything in the pixel format structure is read-only */
typedef struct SDL_PixelFormat {
SDL_Palette *palette;
Uint8 BitsPerPixel;
Uint32 Bmask;
Uint32 Amask;
- /* RGB color key information */
+ /** RGB color key information */
Uint32 colorkey;
- /* Alpha value information (per-surface alpha) */
+ /** Alpha value information (per-surface alpha) */
Uint8 alpha;
} SDL_PixelFormat;
-/* This structure should be treated as read-only, except for 'pixels',
- which, if not NULL, contains the raw pixel data for the surface.
-*/
+/** This structure should be treated as read-only, except for 'pixels',
+ * which, if not NULL, contains the raw pixel data for the surface.
+ */
typedef struct SDL_Surface {
- Uint32 flags; /* Read-only */
- SDL_PixelFormat *format; /* Read-only */
- int w, h; /* Read-only */
- Uint16 pitch; /* Read-only */
- void *pixels; /* Read-write */
- int offset; /* Private */
-
- /* Hardware-specific surface info */
+ Uint32 flags; /**< Read-only */
+ SDL_PixelFormat *format; /**< Read-only */
+ int w, h; /**< Read-only */
+ Uint16 pitch; /**< Read-only */
+ void *pixels; /**< Read-write */
+ int offset; /**< Private */
+
+ /** Hardware-specific surface info */
struct private_hwdata *hwdata;
- /* clipping information */
- SDL_Rect clip_rect; /* Read-only */
- Uint32 unused1; /* for binary compatibility */
+ /** clipping information */
+ SDL_Rect clip_rect; /**< Read-only */
+ Uint32 unused1; /**< for binary compatibility */
- /* Allow recursive locks */
- Uint32 locked; /* Private */
+ /** Allow recursive locks */
+ Uint32 locked; /**< Private */
- /* info for fast blit mapping to other surfaces */
- struct SDL_BlitMap *map; /* Private */
+ /** info for fast blit mapping to other surfaces */
+ struct SDL_BlitMap *map; /**< Private */
- /* format version, bumped at every change to invalidate blit maps */
- unsigned int format_version; /* Private */
+ /** format version, bumped at every change to invalidate blit maps */
+ unsigned int format_version; /**< Private */
- /* Reference count -- used when freeing surface */
- int refcount; /* Read-mostly */
+ /** Reference count -- used when freeing surface */
+ int refcount; /**< Read-mostly */
} SDL_Surface;
-/* These are the currently supported flags for the SDL_surface */
-/* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
-#define SDL_SWSURFACE 0x00000000 /* Surface is in system memory */
-#define SDL_HWSURFACE 0x00000001 /* Surface is in video memory */
-#define SDL_ASYNCBLIT 0x00000004 /* Use asynchronous blits if possible */
-/* Available for SDL_SetVideoMode() */
-#define SDL_ANYFORMAT 0x10000000 /* Allow any video depth/pixel-format */
-#define SDL_HWPALETTE 0x20000000 /* Surface has exclusive palette */
-#define SDL_DOUBLEBUF 0x40000000 /* Set up double-buffered video mode */
-#define SDL_FULLSCREEN 0x80000000 /* Surface is a full screen display */
-#define SDL_OPENGL 0x00000002 /* Create an OpenGL rendering context */
-#define SDL_OPENGLBLIT 0x0000000A /* Create an OpenGL rendering context and use it for blitting */
-#define SDL_RESIZABLE 0x00000010 /* This video mode may be resized */
-#define SDL_NOFRAME 0x00000020 /* No window caption or edge frame */
-/* Used internally (read-only) */
-#define SDL_HWACCEL 0x00000100 /* Blit uses hardware acceleration */
-#define SDL_SRCCOLORKEY 0x00001000 /* Blit uses a source color key */
-#define SDL_RLEACCELOK 0x00002000 /* Private flag */
-#define SDL_RLEACCEL 0x00004000 /* Surface is RLE encoded */
-#define SDL_SRCALPHA 0x00010000 /* Blit uses source alpha blending */
-#define SDL_PREALLOC 0x01000000 /* Surface uses preallocated memory */
-
-/* Evaluates to true if the surface needs to be locked before access */
+/** @name SDL_Surface Flags
+ * These are the currently supported flags for the SDL_surface
+ */
+/*@{*/
+
+/** Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
+/*@{*/
+#define SDL_SWSURFACE 0x00000000 /**< Surface is in system memory */
+#define SDL_HWSURFACE 0x00000001 /**< Surface is in video memory */
+#define SDL_ASYNCBLIT 0x00000004 /**< Use asynchronous blits if possible */
+/*@}*/
+
+/** Available for SDL_SetVideoMode() */
+/*@{*/
+#define SDL_ANYFORMAT 0x10000000 /**< Allow any video depth/pixel-format */
+#define SDL_HWPALETTE 0x20000000 /**< Surface has exclusive palette */
+#define SDL_DOUBLEBUF 0x40000000 /**< Set up double-buffered video mode */
+#define SDL_FULLSCREEN 0x80000000 /**< Surface is a full screen display */
+#define SDL_OPENGL 0x00000002 /**< Create an OpenGL rendering context */
+#define SDL_OPENGLBLIT 0x0000000A /**< Create an OpenGL rendering context and use it for blitting */
+#define SDL_RESIZABLE 0x00000010 /**< This video mode may be resized */
+#define SDL_NOFRAME 0x00000020 /**< No window caption or edge frame */
+/*@}*/
+
+/** Used internally (read-only) */
+/*@{*/
+#define SDL_HWACCEL 0x00000100 /**< Blit uses hardware acceleration */
+#define SDL_SRCCOLORKEY 0x00001000 /**< Blit uses a source color key */
+#define SDL_RLEACCELOK 0x00002000 /**< Private flag */
+#define SDL_RLEACCEL 0x00004000 /**< Surface is RLE encoded */
+#define SDL_SRCALPHA 0x00010000 /**< Blit uses source alpha blending */
+#define SDL_PREALLOC 0x01000000 /**< Surface uses preallocated memory */
+/*@}*/
+
+/*@}*/
+
+/** Evaluates to true if the surface needs to be locked before access */
#define SDL_MUSTLOCK(surface) \
(surface->offset || \
((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0))
-/* typedef for private surface blitting functions */
+/** typedef for private surface blitting functions */
typedef int (*SDL_blit)(struct SDL_Surface *src, SDL_Rect *srcrect,
struct SDL_Surface *dst, SDL_Rect *dstrect);
-/* Useful for determining the video hardware capabilities */
+/** Useful for determining the video hardware capabilities */
typedef struct SDL_VideoInfo {
- Uint32 hw_available :1; /* Flag: Can you create hardware surfaces? */
- Uint32 wm_available :1; /* Flag: Can you talk to a window manager? */
+ Uint32 hw_available :1; /**< Flag: Can you create hardware surfaces? */
+ Uint32 wm_available :1; /**< Flag: Can you talk to a window manager? */
Uint32 UnusedBits1 :6;
Uint32 UnusedBits2 :1;
- Uint32 blit_hw :1; /* Flag: Accelerated blits HW --> HW */
- Uint32 blit_hw_CC :1; /* Flag: Accelerated blits with Colorkey */
- Uint32 blit_hw_A :1; /* Flag: Accelerated blits with Alpha */
- Uint32 blit_sw :1; /* Flag: Accelerated blits SW --> HW */
- Uint32 blit_sw_CC :1; /* Flag: Accelerated blits with Colorkey */
- Uint32 blit_sw_A :1; /* Flag: Accelerated blits with Alpha */
- Uint32 blit_fill :1; /* Flag: Accelerated color fill */
+ Uint32 blit_hw :1; /**< Flag: Accelerated blits HW --> HW */
+ Uint32 blit_hw_CC :1; /**< Flag: Accelerated blits with Colorkey */
+ Uint32 blit_hw_A :1; /**< Flag: Accelerated blits with Alpha */
+ Uint32 blit_sw :1; /**< Flag: Accelerated blits SW --> HW */
+ Uint32 blit_sw_CC :1; /**< Flag: Accelerated blits with Colorkey */
+ Uint32 blit_sw_A :1; /**< Flag: Accelerated blits with Alpha */
+ Uint32 blit_fill :1; /**< Flag: Accelerated color fill */
Uint32 UnusedBits3 :16;
- Uint32 video_mem; /* The total amount of video memory (in K) */
- SDL_PixelFormat *vfmt; /* Value: The format of the video surface */
- int current_w; /* Value: The current video mode width */
- int current_h; /* Value: The current video mode height */
+ Uint32 video_mem; /**< The total amount of video memory (in K) */
+ SDL_PixelFormat *vfmt; /**< Value: The format of the video surface */
+ int current_w; /**< Value: The current video mode width */
+ int current_h; /**< Value: The current video mode height */
} SDL_VideoInfo;
-/* The most common video overlay formats.
- For an explanation of these pixel formats, see:
- http://www.webartz.com/fourcc/indexyuv.htm
-
- For information on the relationship between color spaces, see:
- http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
+/** @name Overlay Formats
+ * The most common video overlay formats.
+ * For an explanation of these pixel formats, see:
+ * http://www.webartz.com/fourcc/indexyuv.htm
+ *
+ * For information on the relationship between color spaces, see:
+ * http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
*/
-#define SDL_YV12_OVERLAY 0x32315659 /* Planar mode: Y + V + U (3 planes) */
-#define SDL_IYUV_OVERLAY 0x56555949 /* Planar mode: Y + U + V (3 planes) */
-#define SDL_YUY2_OVERLAY 0x32595559 /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
-#define SDL_UYVY_OVERLAY 0x59565955 /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
-#define SDL_YVYU_OVERLAY 0x55595659 /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
+/*@{*/
+#define SDL_YV12_OVERLAY 0x32315659 /**< Planar mode: Y + V + U (3 planes) */
+#define SDL_IYUV_OVERLAY 0x56555949 /**< Planar mode: Y + U + V (3 planes) */
+#define SDL_YUY2_OVERLAY 0x32595559 /**< Packed mode: Y0+U0+Y1+V0 (1 plane) */
+#define SDL_UYVY_OVERLAY 0x59565955 /**< Packed mode: U0+Y0+V0+Y1 (1 plane) */
+#define SDL_YVYU_OVERLAY 0x55595659 /**< Packed mode: Y0+V0+Y1+U0 (1 plane) */
+/*@}*/
-/* The YUV hardware video overlay */
+/** The YUV hardware video overlay */
typedef struct SDL_Overlay {
- Uint32 format; /* Read-only */
- int w, h; /* Read-only */
- int planes; /* Read-only */
- Uint16 *pitches; /* Read-only */
- Uint8 **pixels; /* Read-write */
-
- /* Hardware-specific surface info */
+ Uint32 format; /**< Read-only */
+ int w, h; /**< Read-only */
+ int planes; /**< Read-only */
+ Uint16 *pitches; /**< Read-only */
+ Uint8 **pixels; /**< Read-write */
+
+ /** @name Hardware-specific surface info */
+ /*@{*/
struct private_yuvhwfuncs *hwfuncs;
struct private_yuvhwdata *hwdata;
+ /*@{*/
- /* Special flags */
- Uint32 hw_overlay :1; /* Flag: This overlay hardware accelerated? */
+ /** @name Special flags */
+ /*@{*/
+ Uint32 hw_overlay :1; /**< Flag: This overlay hardware accelerated? */
Uint32 UnusedBits :31;
+ /*@}*/
} SDL_Overlay;
-/* Public enumeration for setting the OpenGL window attributes. */
+/** Public enumeration for setting the OpenGL window attributes. */
typedef enum {
SDL_GL_RED_SIZE,
SDL_GL_GREEN_SIZE,
SDL_GL_SWAP_CONTROL
} SDL_GLattr;
-/* flags for SDL_SetPalette() */
+/** @name flags for SDL_SetPalette() */
+/*@{*/
#define SDL_LOGPAL 0x01
#define SDL_PHYSPAL 0x02
+/*@}*/
/* Function prototypes */
-/* These functions are used internally, and should not be used unless you
+/**
+ * @name Video Init and Quit
+ * These functions are used internally, and should not be used unless you
* have a specific need to specify the video driver you want to use.
* You should normally use SDL_Init() or SDL_InitSubSystem().
- *
- * SDL_VideoInit() initializes the video subsystem -- sets up a connection
+ */
+/*@{*/
+/**
+ * Initializes the video subsystem. Sets up a connection
* to the window manager, etc, and determines the current video mode and
* pixel format, but does not initialize a window or graphics mode.
* Note that event handling is activated by this routine.
*/
extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags);
extern DECLSPEC void SDLCALL SDL_VideoQuit(void);
+/*@}*/
-/* This function fills the given character buffer with the name of the
+/**
+ * This function fills the given character buffer with the name of the
* video driver, and returns a pointer to it if the video driver has
* been initialized. It returns NULL if no driver has been initialized.
*/
extern DECLSPEC char * SDLCALL SDL_VideoDriverName(char *namebuf, int maxlen);
-/*
+/**
* This function returns a pointer to the current display surface.
* If SDL is doing format conversion on the display surface, this
* function returns the publicly visible surface, not the real video
*/
extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void);
-/*
+/**
* This function returns a read-only pointer to information about the
* video hardware. If this is called before SDL_SetVideoMode(), the 'vfmt'
* member of the returned structure will contain the pixel format of the
*/
extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void);
-/*
+/**
* Check to see if a particular video mode is supported.
* It returns 0 if the requested mode is not supported under any bit depth,
* or returns the bits-per-pixel of the closest available mode with the
*/
extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
-/*
+/**
* Return a pointer to an array of available screen dimensions for the
* given format and video flags, sorted largest to smallest. Returns
* NULL if there are no dimensions available for a particular format,
*/
extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
-/*
+/**
* Set up a video mode with the specified width, height and bits-per-pixel.
*
* If 'bpp' is 0, it is treated as the current display bits per pixel.
extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode
(int width, int height, int bpp, Uint32 flags);
-/*
- * Makes sure the given list of rectangles is updated on the given screen.
- * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
- * screen.
+/** @name SDL_Update Functions
* These functions should not be called while 'screen' is locked.
*/
+/*@{*/
+/**
+ * Makes sure the given list of rectangles is updated on the given screen.
+ */
extern DECLSPEC void SDLCALL SDL_UpdateRects
(SDL_Surface *screen, int numrects, SDL_Rect *rects);
+/**
+ * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
+ * screen.
+ */
extern DECLSPEC void SDLCALL SDL_UpdateRect
(SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
+/*@}*/
-/*
+/**
* On hardware that supports double-buffering, this function sets up a flip
* and returns. The hardware will wait for vertical retrace, and then swap
* video buffers before the next video surface blit or lock will return.
*/
extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen);
-/*
+/**
* Set the gamma correction for each of the color channels.
* The gamma values range (approximately) between 0.1 and 10.0
*
*/
extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue);
-/*
+/**
* Set the gamma translation table for the red, green, and blue channels
* of the video hardware. Each table is an array of 256 16-bit quantities,
* representing a mapping between the input and output for that channel.
*/
extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue);
-/*
+/**
* Retrieve the current values of the gamma translation tables.
*
* You must pass in valid pointers to arrays of 256 16-bit quantities.
*/
extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
-/*
+/**
* Sets a portion of the colormap for the given 8-bit surface. If 'surface'
* is not a palettized surface, this function does nothing, returning 0.
* If all of the colors were set as passed to SDL_SetColors(), it will
extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface,
SDL_Color *colors, int firstcolor, int ncolors);
-/*
+/**
* Sets a portion of the colormap for a given 8-bit surface.
* 'flags' is one or both of:
* SDL_LOGPAL -- set logical palette, which controls how blits are mapped
SDL_Color *colors, int firstcolor,
int ncolors);
-/*
+/**
* Maps an RGB triple to an opaque pixel value for a given pixel format
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGB
(const SDL_PixelFormat * const format,
const Uint8 r, const Uint8 g, const Uint8 b);
-/*
+/**
* Maps an RGBA quadruple to a pixel value for a given pixel format
*/
extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA
(const SDL_PixelFormat * const format,
const Uint8 r, const Uint8 g, const Uint8 b, const Uint8 a);
-/*
+/**
* Maps a pixel value into the RGB components for a given pixel format
*/
-extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
+extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel,
+ const SDL_PixelFormat * const fmt,
Uint8 *r, Uint8 *g, Uint8 *b);
-/*
+/**
* Maps a pixel value into the RGBA components for a given pixel format
*/
-extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
- Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
+extern DECLSPEC void SDLCALL SDL_GetRGBA(Uint32 pixel,
+ const SDL_PixelFormat * const fmt,
+ Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
-/*
+/** @sa SDL_CreateRGBSurface */
+#define SDL_AllocSurface SDL_CreateRGBSurface
+/**
* Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
* If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
* If the depth is greater than 8 bits, the pixel format is set using the
* reason the surface could not be placed in video memory, it will not have
* the SDL_HWSURFACE flag set, and will be created in system memory instead.
*/
-#define SDL_AllocSurface SDL_CreateRGBSurface
extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurface
(Uint32 flags, int width, int height, int depth,
Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
+/** @sa SDL_CreateRGBSurface */
extern DECLSPEC SDL_Surface * SDLCALL SDL_CreateRGBSurfaceFrom(void *pixels,
int width, int height, int depth, int pitch,
Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface *surface);
-/*
+/**
* SDL_LockSurface() sets up a surface for directly accessing the pixels.
* Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
* to and read from 'surface->pixels', using the pixel format stored in
extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface);
extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface);
-/*
+/**
* Load a surface from a seekable SDL data source (memory or file.)
* If 'freesrc' is non-zero, the source will be closed after being read.
* Returns the new surface, or NULL if there was an error.
*/
extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
-/* Convenience macro -- load a surface from a file */
+/** Convenience macro -- load a surface from a file */
#define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1)
-/*
+/**
* Save a surface to a seekable SDL data source (memory or file.)
* If 'freedst' is non-zero, the source will be closed after being written.
* Returns 0 if successful or -1 if there was an error.
extern DECLSPEC int SDLCALL SDL_SaveBMP_RW
(SDL_Surface *surface, SDL_RWops *dst, int freedst);
-/* Convenience macro -- save a surface to a file */
+/** Convenience macro -- save a surface to a file */
#define SDL_SaveBMP(surface, file) \
SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1)
-/*
+/**
* Sets the color key (transparent pixel) in a blittable surface.
* If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL),
* 'key' will be the transparent pixel in the source image of a blit.
extern DECLSPEC int SDLCALL SDL_SetColorKey
(SDL_Surface *surface, Uint32 flag, Uint32 key);
-/*
+/**
* This function sets the alpha value for the entire surface, as opposed to
* using the alpha component of each pixel. This value measures the range
* of transparency of the surface, 0 being completely transparent to 255
*/
extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
-/*
+/**
* Sets the clipping rectangle for the destination surface in a blit.
*
* If the clip rectangle is NULL, clipping will be disabled.
*/
extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect);
-/*
+/**
* Gets the clipping rectangle for the destination surface in a blit.
* 'rect' must be a pointer to a valid rectangle which will be filled
* with the correct values.
*/
extern DECLSPEC void SDLCALL SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
-/*
+/**
* Creates a new surface of the specified format, and then copies and maps
* the given surface to it so the blit of the converted surface will be as
* fast as possible. If this function fails, it returns NULL.
extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface
(SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
-/*
+/**
* This performs a fast blit from the source surface to the destination
* surface. It assumes that the source and destination rectangles are
* the same size. If either 'srcrect' or 'dstrect' are NULL, the entire
* If either of the surfaces were in video memory, and the blit returns -2,
* the video memory was lost, so it should be reloaded with artwork and
* re-blitted:
- while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
- while ( SDL_LockSurface(image) < 0 )
- Sleep(10);
- -- Write image pixels to image->pixels --
- SDL_UnlockSurface(image);
- }
+ * @code
+ * while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
+ * while ( SDL_LockSurface(image) < 0 )
+ * Sleep(10);
+ * -- Write image pixels to image->pixels --
+ * SDL_UnlockSurface(image);
+ * }
+ * @endcode
+ *
* This happens under DirectX 5.0 when the system switches away from your
* fullscreen application. The lock will also fail until you have access
* to the video memory again.
+ *
+ * You should call SDL_BlitSurface() unless you know exactly how SDL
+ * blitting works internally and how to use the other blit functions.
*/
-/* You should call SDL_BlitSurface() unless you know exactly how SDL
- blitting works internally and how to use the other blit functions.
-*/
#define SDL_BlitSurface SDL_UpperBlit
-/* This is the public blit function, SDL_BlitSurface(), and it performs
- rectangle validation and clipping before passing it to SDL_LowerBlit()
-*/
+/** This is the public blit function, SDL_BlitSurface(), and it performs
+ * rectangle validation and clipping before passing it to SDL_LowerBlit()
+ */
extern DECLSPEC int SDLCALL SDL_UpperBlit
(SDL_Surface *src, SDL_Rect *srcrect,
SDL_Surface *dst, SDL_Rect *dstrect);
-/* This is a semi-private blit function and it performs low-level surface
- blitting only.
-*/
+/** This is a semi-private blit function and it performs low-level surface
+ * blitting only.
+ */
extern DECLSPEC int SDLCALL SDL_LowerBlit
(SDL_Surface *src, SDL_Rect *srcrect,
SDL_Surface *dst, SDL_Rect *dstrect);
-/*
+/**
* This function performs a fast fill of the given rectangle with 'color'
* The given rectangle is clipped to the destination surface clip area
* and the final fill rectangle is saved in the passed in pointer.
extern DECLSPEC int SDLCALL SDL_FillRect
(SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
-/*
+/**
* This function takes a surface and copies it to a new surface of the
* pixel format and colors of the video framebuffer, suitable for fast
* blitting onto the display surface. It calls SDL_ConvertSurface()
*/
extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormat(SDL_Surface *surface);
-/*
+/**
* This function takes a surface and copies it to a new surface of the
* pixel format and colors of the video framebuffer (if possible),
* suitable for fast alpha blitting onto the display surface.
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* YUV video surface overlay functions */
+/** @name YUV video surface overlay functions */ /*@{*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* This function creates a video output overlay
- Calling the returned surface an overlay is something of a misnomer because
- the contents of the display surface underneath the area where the overlay
- is shown is undefined - it may be overwritten with the converted YUV data.
-*/
+/** This function creates a video output overlay
+ * Calling the returned surface an overlay is something of a misnomer because
+ * the contents of the display surface underneath the area where the overlay
+ * is shown is undefined - it may be overwritten with the converted YUV data.
+ */
extern DECLSPEC SDL_Overlay * SDLCALL SDL_CreateYUVOverlay(int width, int height,
Uint32 format, SDL_Surface *display);
-/* Lock an overlay for direct access, and unlock it when you are done */
+/** Lock an overlay for direct access, and unlock it when you are done */
extern DECLSPEC int SDLCALL SDL_LockYUVOverlay(SDL_Overlay *overlay);
extern DECLSPEC void SDLCALL SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
-/* Blit a video overlay to the display surface.
- The contents of the video surface underneath the blit destination are
- not defined.
- The width and height of the destination rectangle may be different from
- that of the overlay, but currently only 2x scaling is supported.
-*/
+/** Blit a video overlay to the display surface.
+ * The contents of the video surface underneath the blit destination are
+ * not defined.
+ * The width and height of the destination rectangle may be different from
+ * that of the overlay, but currently only 2x scaling is supported.
+ */
extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
-/* Free a video overlay */
+/** Free a video overlay */
extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay);
+/*@}*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* OpenGL support functions. */
+/** @name OpenGL support functions. */ /*@{*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/*
+/**
* Dynamically load an OpenGL library, or the default one if path is NULL
*
* If you do this, you need to retrieve all of the GL functions used in
*/
extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path);
-/*
+/**
* Get the address of a GL function
*/
extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc);
-/*
+/**
* Set an attribute of the OpenGL subsystem before intialization.
*/
extern DECLSPEC int SDLCALL SDL_GL_SetAttribute(SDL_GLattr attr, int value);
-/*
+/**
* Get an attribute of the OpenGL subsystem from the windowing
* interface, such as glX. This is of course different from getting
* the values from SDL's internal OpenGL subsystem, which only
*/
extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
-/*
+/**
* Swap the OpenGL buffers, if double-buffering is supported.
*/
extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
-/*
+/** @name OpenGL Internal Functions
* Internal functions that should not be called unless you have read
* and understood the source code for these functions.
*/
+/*@{*/
extern DECLSPEC void SDLCALL SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
extern DECLSPEC void SDLCALL SDL_GL_Lock(void);
extern DECLSPEC void SDLCALL SDL_GL_Unlock(void);
+/*@}*/
+
+/*@}*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/* These functions allow interaction with the window manager, if any. */
+/** @name Window Manager Functions */
+/** These functions allow interaction with the window manager, if any. */ /*@{*/
/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
-/*
- * Sets/Gets the title and icon text of the display window (UTF-8 encoded)
+/**
+ * Sets the title and icon text of the display window (UTF-8 encoded)
*/
extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon);
+/**
+ * Gets the title and icon text of the display window (UTF-8 encoded)
+ */
extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon);
-/*
+/**
* Sets the icon for the display window.
* This function must be called before the first call to SDL_SetVideoMode().
* It takes an icon surface, and a mask in MSB format.
*/
extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
-/*
+/**
* This function iconifies the window, and returns 1 if it succeeded.
* If the function succeeds, it generates an SDL_APPACTIVE loss event.
* This function is a noop and returns 0 in non-windowed environments.
*/
extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void);
-/*
+/**
* Toggle fullscreen mode without changing the contents of the screen.
* If the display surface does not require locking before accessing
* the pixel information, then the memory pointers will not change.
*/
extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface);
-/*
- * This function allows you to set and query the input grab state of
- * the application. It returns the new input grab state.
- */
typedef enum {
SDL_GRAB_QUERY = -1,
SDL_GRAB_OFF = 0,
SDL_GRAB_ON = 1,
- SDL_GRAB_FULLSCREEN /* Used internally */
+ SDL_GRAB_FULLSCREEN /**< Used internally */
} SDL_GrabMode;
-/*
+/**
+ * This function allows you to set and query the input grab state of
+ * the application. It returns the new input grab state.
+ *
* Grabbing means that the mouse is confined to the application window,
* and nearly all keyboard input is passed directly to the application,
* and not interpreted by a window manager, if any.
*/
extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode);
-/* Not in public API at the moment - do not use! */
+/*@}*/
+
+/** @internal Not in public API at the moment - do not use! */
extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
SDL_Surface *dst, SDL_Rect *dstrect);
projects / xonotic / xonotic.git / blobdiff