Mercurial > sdl-ios-xcode
diff include/SDL_video.h @ 1895:c121d94672cb
SDL 1.2 is moving to a branch, and SDL 1.3 is becoming the head.
| author | Sam Lantinga <slouken@libsdl.org> |
|---|---|
| date | Mon, 10 Jul 2006 21:04:37 +0000 |
| parents | eacc5bc01d1c |
| children | c2a27da60b18 |
line wrap: on
line diff
--- a/include/SDL_video.h Thu Jul 06 18:01:37 2006 +0000 +++ b/include/SDL_video.h Mon Jul 10 21:04:37 2006 +0000 @@ -20,185 +20,293 @@ 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 #include "SDL_stdinc.h" #include "SDL_error.h" +#include "SDL_pixels.h" #include "SDL_rwops.h" #include "begin_code.h" /* Set up for C function definitions, even when using C++ */ #ifdef __cplusplus +/* *INDENT-OFF* */ extern "C" { +/* *INDENT-ON* */ #endif /* Transparency definitions: These define alpha as the opacity of a surface */ #define SDL_ALPHA_OPAQUE 255 #define SDL_ALPHA_TRANSPARENT 0 -/* Useful data types */ -typedef struct SDL_Rect { - Sint16 x, y; - Uint16 w, h; +/** + * \struct SDL_Rect + * + * \brief A rectangle, with the origin at the upper left. + */ +typedef struct SDL_Rect +{ + int x, y; + int w, h; } SDL_Rect; -typedef struct SDL_Color { - Uint8 r; - Uint8 g; - Uint8 b; - Uint8 unused; -} SDL_Color; -#define SDL_Colour SDL_Color +/** + * \struct SDL_DisplayMode + * + * \brief The structure that defines a display mode + * + * \sa SDL_GetNumDisplayModes() + * \sa SDL_GetDisplayMode() + * \sa SDL_GetDesktopDisplayMode() + * \sa SDL_GetCurrentDisplayMode() + * \sa SDL_GetClosestDisplayMode() + * \sa SDL_SetDisplayMode() + */ +typedef struct +{ + Uint32 format; /**< pixel format */ + int w; /**< width */ + int h; /**< height */ + int refresh_rate; /**< refresh rate (or zero for unspecified) */ + void *driverdata; /**< driver-specific data, initialize to 0 */ +} SDL_DisplayMode; -typedef struct SDL_Palette { - int ncolors; - SDL_Color *colors; -} SDL_Palette; +/** + * \typedef SDL_WindowID + * + * \brief The type used to identify a window + * + * \sa SDL_CreateWindow() + * \sa SDL_CreateWindowFrom() + * \sa SDL_DestroyWindow() + * \sa SDL_GetWindowData() + * \sa SDL_GetWindowFlags() + * \sa SDL_GetWindowGrab() + * \sa SDL_GetWindowPosition() + * \sa SDL_GetWindowSize() + * \sa SDL_GetWindowTitle() + * \sa SDL_HideWindow() + * \sa SDL_MaximizeWindow() + * \sa SDL_MinimizeWindow() + * \sa SDL_RaiseWindow() + * \sa SDL_RestoreWindow() + * \sa SDL_SetWindowData() + * \sa SDL_SetWindowFullscreen() + * \sa SDL_SetWindowGrab() + * \sa SDL_SetWindowIcon() + * \sa SDL_SetWindowPosition() + * \sa SDL_SetWindowSize() + * \sa SDL_SetWindowTitle() + * \sa SDL_ShowWindow() + */ +typedef Uint32 SDL_WindowID; + +/** + * \enum SDL_WindowFlags + * + * \brief The flags on a window + * + * \sa SDL_GetWindowFlags() + */ +typedef enum +{ + SDL_WINDOW_FULLSCREEN = 0x00000001, /**< fullscreen window, implies borderless */ + SDL_WINDOW_OPENGL = 0x00000002, /**< window usable with OpenGL context */ + SDL_WINDOW_SHOWN = 0x00000004, /**< window is visible */ + SDL_WINDOW_BORDERLESS = 0x00000008, /**< no window decoration */ + SDL_WINDOW_RESIZABLE = 0x00000010, /**< window can be resized */ + SDL_WINDOW_MINIMIZED = 0x00000020, /**< minimized */ + SDL_WINDOW_MAXIMIZED = 0x00000040, /**< maximized */ + SDL_WINDOW_INPUT_GRABBED = 0x00000100, /**< window has grabbed input focus */ + SDL_WINDOW_INPUT_FOCUS = 0x00000200, /**< window has input focus */ + SDL_WINDOW_MOUSE_FOCUS = 0x00000400, /**< window has mouse focus */ +} SDL_WindowFlags; + +/** + * \def SDL_WINDOWPOS_UNDEFINED + * \brief Used to indicate that you don't care what the window position is. + */ +#define SDL_WINDOWPOS_UNDEFINED 0x7FFFFFF +/** + * \def SDL_WINDOWPOS_CENTERED + * \brief Used to indicate that the window position should be centered. + */ +#define SDL_WINDOWPOS_CENTERED 0x7FFFFFE -/* Everything in the pixel format structure is read-only */ -typedef struct SDL_PixelFormat { - SDL_Palette *palette; - Uint8 BitsPerPixel; - Uint8 BytesPerPixel; - Uint8 Rloss; - Uint8 Gloss; - Uint8 Bloss; - Uint8 Aloss; - Uint8 Rshift; - Uint8 Gshift; - Uint8 Bshift; - Uint8 Ashift; - Uint32 Rmask; - Uint32 Gmask; - Uint32 Bmask; - Uint32 Amask; +/** + * \enum SDL_WindowEventID + * + * \brief Event subtype for window events + */ +typedef enum +{ + SDL_WINDOWEVENT_NONE, /**< Never used */ + SDL_WINDOWEVENT_SHOWN, /**< Window has been shown */ + SDL_WINDOWEVENT_HIDDEN, /**< Window has been hidden */ + SDL_WINDOWEVENT_EXPOSED, /**< Window has been exposed and should be redrawn */ + SDL_WINDOWEVENT_MOVED, /**< Window has been moved to data1,data2 */ + SDL_WINDOWEVENT_RESIZED, /**< Window size changed to data1xdata2 */ + SDL_WINDOWEVENT_MINIMIZED, /**< Window has been minimized */ + SDL_WINDOWEVENT_MAXIMIZED, /**< Window has been maximized */ + SDL_WINDOWEVENT_RESTORED, /**< Window has been restored to normal size and position */ + SDL_WINDOWEVENT_ENTER, /**< The window has gained mouse focus */ + SDL_WINDOWEVENT_LEAVE, /**< The window has lost mouse focus */ + SDL_WINDOWEVENT_FOCUS_GAINED, /**< The window has gained keyboard focus */ + SDL_WINDOWEVENT_FOCUS_LOST, /**< The window has lost keyboard focus */ + SDL_WINDOWEVENT_CLOSE, /**< The window manager requests that the window be closed */ +} SDL_WindowEventID; + +/** + * \enum SDL_RendererFlags + * + * \brief Flags used when initializing a render manager. + */ +typedef enum +{ + SDL_Renderer_PresentDiscard = 0x00000001, /**< Present leaves the contents of the backbuffer undefined */ + SDL_Renderer_PresentCopy = 0x00000002, /**< Present uses a copy from back buffer to the front buffer */ + SDL_Renderer_PresentFlip2 = 0x00000004, /**< Present uses a flip, swapping back buffer and front buffer */ + SDL_Renderer_PresentFlip3 = 0x00000008, /**< Present uses a flip, rotating between two back buffers and a front buffer */ + SDL_Renderer_PresentVSync = 0x00000010, /**< Present is synchronized with the refresh rate */ + SDL_Renderer_RenderTarget = 0x00000020, /**< The renderer can create texture render targets */ + SDL_Renderer_Accelerated = 0x00000040, /**< The renderer uses hardware acceleration */ + SDL_Renderer_ = 0x00000080, /**< The renderer uses hardware acceleration */ + SDL_Renderer_Minimal = 0x00000100, /**< The renderer only supports the read/write pixel and present functions */ +} SDL_RendererFlags; + +/** + * \struct SDL_RendererInfo + * + * \brief Information on the capabilities of a render manager. + */ +typedef struct SDL_RendererInfo +{ + const char *name; /**< The name of the renderer */ + Uint32 flags; /**< Supported SDL_RendererFlags */ + Uint32 blend_modes; /**< A mask of supported blend modes */ + Uint32 scale_modes; /**< A mask of supported scale modes */ + Uint32 num_texture_formats; /**< The number of available texture formats */ + Uint32 texture_formats[32]; /**< The available texture formats */ + int max_texture_width; /**< The maximimum texture width */ + int max_texture_height; /**< The maximimum texture height */ +} SDL_RendererInfo; - /* RGB color key information */ - Uint32 colorkey; - /* Alpha value information (per-surface alpha) */ - Uint8 alpha; -} SDL_PixelFormat; +/** + * \enum SDL_TextureAccess + * + * \brief The access pattern allowed for a texture + */ +typedef enum +{ + SDL_TextureAccess_Render, /**< Unlockable video memory, rendering allowed */ + SDL_TextureAccess_Remote, /**< Unlockable video memory */ + SDL_TextureAccess_Local, /**< Lockable system memory */ +} SDL_TextureAccess; + +/** + * \enum SDL_TextureBlendMode + * + * \brief The blend mode used in SDL_RenderCopy() + */ +typedef enum +{ + SDL_TextureBlendMode_None = 0x00000000, /**< No blending */ + SDL_TextureBlendMode_Mask = 0x00000001, /**< dst = A ? src : dst (alpha is mask) */ + SDL_TextureBlendMode_Blend = 0x00000002, /**< dst = (src * A) + (dst * (1-A)) */ + SDL_TextureBlendMode_Add = 0x00000004, /**< dst = (src * A) + dst */ + SDL_TextureBlendMode_Mod = 0x00000008, /**< dst = src * dst */ +} SDL_TextureBlendMode; + +/** + * \enum SDL_TextureScaleMode + * + * \brief The scale mode used in SDL_RenderCopy() + */ +typedef enum +{ + SDL_TextureScaleMode_None = 0x00000000, /**< No scaling, rectangles must match dimensions */ + SDL_TextureScaleMode_Fast = 0x00000001, /**< Point sampling or equivalent algorithm */ + SDL_TextureScaleMode_Slow = 0x00000002, /**< Linear filtering or equivalent algorithm */ + SDL_TextureScaleMode_Best = 0x00000004, /**< Bicubic filtering or equivalent algorithm */ +} SDL_TextureScaleMode; + +/** + * \typedef SDL_TextureID + * + * \brief An efficient driver-specific representation of pixel data + */ +typedef Uint32 SDL_TextureID; + +/** + * \typedef SDL_GLContext + * + * \brief An opaque handle to an OpenGL context. + */ +typedef void *SDL_GLContext; + + +/* These are the currently supported flags for the SDL_surface */ +/* Used internally (read-only) */ +#define SDL_HWSURFACE 0x00000001 /* Surface represents a texture */ +#define SDL_PREALLOC 0x00000002 /* Surface uses preallocated memory */ +#define SDL_SRCALPHA 0x00000004 /* Blit uses source alpha blending */ +#define SDL_SRCCOLORKEY 0x00000008 /* Blit uses a source color key */ +#define SDL_RLEACCELOK 0x00000010 /* Private flag */ +#define SDL_RLEACCEL 0x00000020 /* Surface is RLE encoded */ + +/* Evaluates to true if the surface needs to be locked before access */ +#define SDL_MUSTLOCK(S) (((S)->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0) /* 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 */ +typedef struct SDL_Surface +{ + Uint32 flags; /* Read-only */ + SDL_PixelFormat *format; /* Read-only */ + int w, h; /* Read-only */ + int pitch; /* Read-only */ + void *pixels; /* Read-write */ - /* Hardware-specific surface info */ - struct private_hwdata *hwdata; + /* texture associated with the surface, if any */ + SDL_TextureID textureID; - /* clipping information */ - SDL_Rect clip_rect; /* Read-only */ - Uint32 unused1; /* for binary compatibility */ + /* information needed for surfaces requiring locks */ + int locked; + void *lock_data; - /* Allow recursive locks */ - Uint32 locked; /* Private */ + /* clipping information */ + SDL_Rect clip_rect; /* Read-only */ - /* 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 */ -#define SDL_MUSTLOCK(surface) \ - (surface->offset || \ - ((surface->flags & (SDL_HWSURFACE|SDL_ASYNCBLIT|SDL_RLEACCEL)) != 0)) - /* 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 */ -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 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 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 */ -} SDL_VideoInfo; +typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect, + struct SDL_Surface * dst, SDL_Rect * dstrect); -/* 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 +/** + * \enum SDL_GLattr + * + * \brief OpenGL configuration attributes */ -#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 */ -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 */ - struct private_yuvhwfuncs *hwfuncs; - struct private_yuvhwdata *hwdata; - - /* Special flags */ - Uint32 hw_overlay :1; /* Flag: This overlay hardware accelerated? */ - Uint32 UnusedBits :31; -} SDL_Overlay; - - -/* Public enumeration for setting the OpenGL window attributes. */ -typedef enum { +typedef enum +{ SDL_GL_RED_SIZE, SDL_GL_GREEN_SIZE, SDL_GL_BLUE_SIZE, @@ -214,258 +322,854 @@ SDL_GL_STEREO, SDL_GL_MULTISAMPLEBUFFERS, SDL_GL_MULTISAMPLESAMPLES, - SDL_GL_ACCELERATED_VISUAL, - SDL_GL_SWAP_CONTROL + SDL_GL_ACCELERATED_VISUAL } SDL_GLattr; -/* 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 - * have a specific need to specify the video driver you want to use. - * You should normally use SDL_Init() or SDL_InitSubSystem(). +/** + * \fn int SDL_GetNumVideoDrivers(void) + * + * \brief Get the number of video drivers compiled into SDL + * + * \sa SDL_GetVideoDriver() + */ +extern DECLSPEC int SDLCALL SDL_GetNumVideoDrivers(void); + +/** + * \fn const char *SDL_GetVideoDriver(int index) + * + * \brief Get the name of a built in video driver. + * + * \note The video drivers are presented in the order in which they are + * normally checked during initialization. + * + * \sa SDL_GetNumVideoDrivers() + */ +extern DECLSPEC const char *SDLCALL SDL_GetVideoDriver(int index); + +/** + * \fn int SDL_VideoInit(const char *driver_name, Uint32 flags) * - * SDL_VideoInit() 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. + * \brief Initialize the video subsystem, optionally specifying a video driver. + * + * \param driver_name Initialize a specific driver by name, or NULL for the default video driver. + * \param flags FIXME: Still needed? + * + * \return 0 on success, -1 on error + * + * This function initializes the video subsystem; setting up a connection + * to the window manager, etc, and determines the available display modes + * and pixel formats, but does not initialize a window or graphics mode. * - * If you use both sound and video in your application, you need to call - * SDL_Init() before opening the sound device, otherwise under Win32 DirectX, - * you won't be able to set full-screen display modes. + * \sa SDL_VideoQuit() */ -extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, Uint32 flags); +extern DECLSPEC int SDLCALL SDL_VideoInit(const char *driver_name, + Uint32 flags); + +/** + * \fn void SDL_VideoQuit(void) + * + * \brief Shuts down the video subsystem. + * + * This function closes all windows, and restores the original video mode. + * + * \sa SDL_VideoInit() + */ extern DECLSPEC void SDLCALL SDL_VideoQuit(void); -/* 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. +/** + * \fn const char *SDL_GetCurrentVideoDriver(void) + * + * \brief Returns the name of the currently initialized video driver. + * + * \return The name of the current video driver or NULL if no driver + * has been initialized + * + * \sa SDL_GetNumVideoDrivers() + * \sa SDL_GetVideoDriver() */ -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 - * surface. - */ -extern DECLSPEC SDL_Surface * SDLCALL SDL_GetVideoSurface(void); +extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(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 - * "best" video mode. +/** + * \fn int SDL_GetNumVideoDisplays(void) + * + * \brief Returns the number of available video displays. + * + * \sa SDL_SelectVideoDisplay() */ -extern DECLSPEC const SDL_VideoInfo * SDLCALL SDL_GetVideoInfo(void); +extern DECLSPEC int SDLCALL SDL_GetNumVideoDisplays(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 - * given width and height. If this bits-per-pixel is different from the - * one used when setting the video mode, SDL_SetVideoMode() will succeed, - * but will emulate the requested bits-per-pixel with a shadow surface. +/** + * \fn int SDL_SelectVideoDisplay(int index) + * + * \brief Set the index of the currently selected display. + * + * \return The index of the currently selected display. + * + * \note You can query the currently selected display by passing an index of -1. * - * The arguments to SDL_VideoModeOK() are the same ones you would pass to - * SDL_SetVideoMode() + * \sa SDL_GetNumVideoDisplays() */ -extern DECLSPEC int SDLCALL SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags); +extern DECLSPEC int SDLCALL SDL_SelectVideoDisplay(int index); -/* - * 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, - * or (SDL_Rect **)-1 if any dimension is okay for the given format. +/** + * \fn int SDL_GetNumDisplayModes(void) * - * If 'format' is NULL, the mode list will be for the format given - * by SDL_GetVideoInfo()->vfmt + * \brief Returns the number of available display modes for the current display. + * + * \sa SDL_GetDisplayMode() */ -extern DECLSPEC SDL_Rect ** SDLCALL SDL_ListModes(SDL_PixelFormat *format, Uint32 flags); +extern DECLSPEC int SDLCALL SDL_GetNumDisplayModes(void); -/* - * Set up a video mode with the specified width, height and bits-per-pixel. +/** + * \fn const SDL_DisplayMode *SDL_GetDisplayMode(int index) + * + * \brief Retrieve information about a specific display mode. * - * If 'bpp' is 0, it is treated as the current display bits per pixel. + * \note The display modes are sorted in this priority: + * \li bits per pixel -> more colors to fewer colors + * \li width -> largest to smallest + * \li height -> largest to smallest + * \li refresh rate -> highest to lowest * - * If SDL_ANYFORMAT is set in 'flags', the SDL library will try to set the - * requested bits-per-pixel, but will return whatever video pixel format is - * available. The default is to emulate the requested pixel format if it - * is not natively available. + * \sa SDL_GetNumDisplayModes() + */ +extern DECLSPEC const SDL_DisplayMode *SDLCALL SDL_GetDisplayMode(int index); + +/** + * \fn const SDL_DisplayMode *SDL_GetDesktopDisplayMode(void) * - * If SDL_HWSURFACE is set in 'flags', the video surface will be placed in - * video memory, if possible, and you may have to call SDL_LockSurface() - * in order to access the raw framebuffer. Otherwise, the video surface - * will be created in system memory. - * - * If SDL_ASYNCBLIT is set in 'flags', SDL will try to perform rectangle - * updates asynchronously, but you must always lock before accessing pixels. - * SDL will wait for updates to complete before returning from the lock. + * \brief Retrieve information about the desktop display mode for the current display. + */ +extern DECLSPEC const SDL_DisplayMode *SDLCALL +SDL_GetDesktopDisplayMode(void); + +/** + * \fn const SDL_DisplayMode *SDL_GetCurrentDisplayMode(void) * - * If SDL_HWPALETTE is set in 'flags', the SDL library will guarantee - * that the colors set by SDL_SetColors() will be the colors you get. - * Otherwise, in 8-bit mode, SDL_SetColors() may not be able to set all - * of the colors exactly the way they are requested, and you should look - * at the video surface structure to determine the actual palette. - * If SDL cannot guarantee that the colors you request can be set, - * i.e. if the colormap is shared, then the video surface may be created - * under emulation in system memory, overriding the SDL_HWSURFACE flag. + * \brief Retrieve information about the current display mode. + */ +extern DECLSPEC const SDL_DisplayMode *SDLCALL +SDL_GetCurrentDisplayMode(void); + +/** + * \fn SDL_DisplayMode *SDL_GetClosestDisplayMode(const SDL_DisplayMode *mode, SDL_DisplayMode *closest) * - * If SDL_FULLSCREEN is set in 'flags', the SDL library will try to set - * a fullscreen video mode. The default is to create a windowed mode - * if the current graphics system has a window manager. - * If the SDL library is able to set a fullscreen video mode, this flag - * will be set in the surface that is returned. + * \brief Get the closest match to the requested display mode. + * + * \param mode The desired display mode + * \param closest A pointer to a display mode to be filled in with the closest match of the available display modes. + * + * \return The passed in value 'closest', or NULL if no matching video mode was available. + * + * The available display modes are scanned, and 'closest' is filled in with the closest mode matching the requested mode and returned. The mode format and refresh_rate default to the desktop mode if they are 0. The modes are scanned with size being first priority, format being second priority, and finally checking the refresh_rate. If all the available modes are too small, then NULL is returned. * - * If SDL_DOUBLEBUF is set in 'flags', the SDL library will try to set up - * two surfaces in video memory and swap between them when you call - * SDL_Flip(). This is usually slower than the normal single-buffering - * scheme, but prevents "tearing" artifacts caused by modifying video - * memory while the monitor is refreshing. It should only be used by - * applications that redraw the entire screen on every update. + * \sa SDL_GetNumDisplayModes() + * \sa SDL_GetDisplayMode() + */ +extern DECLSPEC SDL_DisplayMode *SDLCALL SDL_GetClosestDisplayMode(const + SDL_DisplayMode + * mode, + SDL_DisplayMode + * closest); + +/** + * \fn int SDL_SetFullscreenDisplayMode(const SDL_DisplayMode *mode) * - * If SDL_RESIZABLE is set in 'flags', the SDL library will allow the - * window manager, if any, to resize the window at runtime. When this - * occurs, SDL will send a SDL_VIDEORESIZE event to you application, - * and you must respond to the event by re-calling SDL_SetVideoMode() - * with the requested size (or another size that suits the application). + * \brief Set the display mode used when a fullscreen window is visible + * on the currently selected display. * - * If SDL_NOFRAME is set in 'flags', the SDL library will create a window - * without any title bar or frame decoration. Fullscreen video modes have - * this flag set automatically. + * \param mode The mode to use, or NULL for the desktop mode. * - * This function returns the video framebuffer surface, or NULL if it fails. + * \return 0 on success, or -1 if setting the display mode failed. * - * If you rely on functionality provided by certain video flags, check the - * flags of the returned surface to make sure that functionality is available. - * SDL will fall back to reduced functionality if the exact flags you wanted - * are not available. + * \sa SDL_SetWindowFullscreen() */ -extern DECLSPEC SDL_Surface * SDLCALL SDL_SetVideoMode - (int width, int height, int bpp, Uint32 flags); +extern DECLSPEC int SDLCALL SDL_SetFullscreenDisplayMode(const SDL_DisplayMode + * mode); -/* - * 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. - * These functions should not be called while 'screen' is locked. +/** + * \fn const SDL_DisplayMode *SDL_GetFullscreenDisplayMode(void) + * + * \brief Query the display mode used when a fullscreen window is visible + * on the currently selected display. */ -extern DECLSPEC void SDLCALL SDL_UpdateRects - (SDL_Surface *screen, int numrects, SDL_Rect *rects); -extern DECLSPEC void SDLCALL SDL_UpdateRect - (SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h); +extern DECLSPEC const SDL_DisplayMode *SDLCALL +SDL_GetFullscreenDisplayMode(void); -/* - * 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. - * On hardware that doesn not support double-buffering, this is equivalent - * to calling SDL_UpdateRect(screen, 0, 0, 0, 0); - * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when - * setting the video mode for this function to perform hardware flipping. - * This function returns 0 if successful, or -1 if there was an error. +/** + * \fn int SDL_SetDisplayPalette(const SDL_Color *colors, int firstcolor, int ncolors) + * + * \brief Set the palette entries for indexed display modes. + * + * \return 0 on success, or -1 if the display mode isn't palettized or the colors couldn't be set. */ -extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface *screen); +extern DECLSPEC int SDLCALL SDL_SetDisplayPalette(const SDL_Color * colors, + int firstcolor, + int ncolors); -/* - * Set the gamma correction for each of the color channels. - * The gamma values range (approximately) between 0.1 and 10.0 - * - * If this function isn't supported directly by the hardware, it will - * be emulated using gamma ramps, if available. If successful, this - * function returns 0, otherwise it returns -1. +/** + * \fn int SDL_GetDisplayPalette(SDL_Color *colors, int firstcolor, int ncolors) + * + * \brief Gets the palette entries for indexed display modes. + * + * \return 0 on success, or -1 if the display mode isn't palettized + */ +extern DECLSPEC int SDLCALL SDL_GetDisplayPalette(SDL_Color * colors, + int firstcolor, + int ncolors); + +/** + * \fn int SDL_SetGamma(float red, float green, float blue) + * + * \brief Set the gamma correction for each of the color channels on the currently selected display. + * + * \return 0 on success, or -1 if setting the gamma isn't supported. + * + * \sa SDL_SetGammaRamp() */ extern DECLSPEC int SDLCALL SDL_SetGamma(float red, float green, float blue); -/* +/** + * \fn int SDL_SetGammaRamp(const Uint16 * red, const Uint16 * green, const Uint16 * blue) + * + * \brief Set the gamma ramp for the currently selected display. + * + * \param red The translation table for the red channel, or NULL + * \param green The translation table for the green channel, or NULL + * \param blue The translation table for the blue channel, or NULL + * + * \return 0 on success, or -1 if gamma ramps are unsupported. + * * 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. * The input is the index into the array, and the output is the 16-bit * gamma value at that index, scaled to the output color precision. * - * You may pass NULL for any of the channels to leave it unchanged. - * If the call succeeds, it will return 0. If the display driver or - * hardware does not support gamma translation, or otherwise fails, - * this function will return -1. + * \sa SDL_GetGammaRamp() */ -extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 *red, const Uint16 *green, const Uint16 *blue); +extern DECLSPEC int SDLCALL SDL_SetGammaRamp(const Uint16 * red, + const Uint16 * green, + const Uint16 * blue); -/* - * Retrieve the current values of the gamma translation tables. +/** + * \fn int SDL_GetGammaRamp(Uint16 * red, Uint16 * green, Uint16 * blue) + * + * \brief Get the gamma ramp for the currently selected display. + * + * \param red A pointer to a 256 element array of 16-bit quantities to hold the translation table for the red channel, or NULL. + * \param green A pointer to a 256 element array of 16-bit quantities to hold the translation table for the green channel, or NULL. + * \param blue A pointer to a 256 element array of 16-bit quantities to hold the translation table for the blue channel, or NULL. * - * You must pass in valid pointers to arrays of 256 16-bit quantities. - * Any of the pointers may be NULL to ignore that channel. - * If the call succeeds, it will return 0. If the display driver or - * hardware does not support gamma translation, or otherwise fails, - * this function will return -1. + * \return 0 on success, or -1 if gamma ramps are unsupported. + * + * \sa SDL_SetGammaRamp() + */ +extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 * red, Uint16 * green, + Uint16 * blue); + + +/** + * \fn SDL_WindowID SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags) + * + * \brief Create a window with the specified position, dimensions, and flags. + * + * \param title The title of the window + * \param x The x position of the window + * \param y The y position of the window + * \param w The width of the window + * \param h The height of the window + * \param flags The flags for the window, a mask of any of the following: SDL_WINDOW_FULLSCREEN, SDL_WINDOW_OPENGL, SDL_WINDOW_SHOWN, SDL_WINDOW_BORDERLESS, SDL_WINDOW_RESIZABLE, SDL_WINDOW_MAXIMIZED, SDL_WINDOW_MINIMIZED, SDL_WINDOW_INPUT_GRABBED + * + * \return The id of the window created, or zero if window creation failed. + * + * \note Setting the position to -1, -1, indicates any position is fine. + * + * \sa SDL_DestroyWindow() + */ +extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindow(const char *title, + int x, int y, int w, + int h, Uint32 flags); + +/** + * \fn SDL_WindowID SDL_CreateWindowFrom(void *data) + * + * \brief Create an SDL window struct from an existing native window. + * + * \param data A pointer to driver-dependent window creation data + * + * \return The id of the window created, or zero if window creation failed. + * + * \warning This function is NOT SUPPORTED, use at your own risk! + * + * \sa SDL_DestroyWindow() + */ +extern DECLSPEC SDL_WindowID SDLCALL SDL_CreateWindowFrom(const void *data); + +/** + * \fn Uint32 SDL_GetWindowFlags(SDL_WindowID windowID) + * + * \brief Get the window flags. + */ +extern DECLSPEC Uint32 SDLCALL SDL_GetWindowFlags(SDL_WindowID windowID); + +/** + * \fn void SDL_SetWindowTitle(SDL_WindowID windowID, const char *title) + * + * \brief Set the title of the window, in UTF-8 format. + * + * \sa SDL_GetWindowTitle() */ -extern DECLSPEC int SDLCALL SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue); +extern DECLSPEC void SDLCALL SDL_SetWindowTitle(SDL_WindowID windowID, + const char *title); + +/** + * \fn const char *SDL_GetWindowTitle(SDL_WindowID windowID) + * + * \brief Get the title of the window, in UTF-8 format. + * + * \sa SDL_SetWindowTitle() + */ +extern DECLSPEC const char *SDLCALL SDL_GetWindowTitle(SDL_WindowID windowID); + +/** + * \fn void SDL_SetWindowIcon(SDL_Surface *icon) + * + * \brief Set the icon of the window. + * + * \param icon The icon for the window + * + * FIXME: The icon needs to be set before the window is first shown. Should some icon representation be part of the window creation data? + */ +extern DECLSPEC void SDLCALL SDL_SetWindowIcon(SDL_Surface * icon); + +/** + * \fn void SDL_SetWindowData(SDL_WindowID windowID, void *userdata) + * + * \brief Associate an arbitrary pointer with the window. + * + * \sa SDL_GetWindowData() + */ +extern DECLSPEC void SDLCALL SDL_SetWindowData(SDL_WindowID windowID, + void *userdata); + +/** + * \fn void *SDL_GetWindowData(SDL_WindowID windowID) + * + * \brief Retrieve the data pointer associated with the window. + * + * \sa SDL_SetWindowData() + */ +extern DECLSPEC void *SDLCALL SDL_GetWindowData(SDL_WindowID windowID); + +/** + * \fn void SDL_SetWindowPosition(SDL_WindowID windowID, int x, int y) + * + * \brief Set the position of the window. + * + * \param windowID The window to reposition + * \param x The x coordinate of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED + * \param y The y coordinate of the window, SDL_WINDOWPOS_CENTERED, or SDL_WINDOWPOS_UNDEFINED + * + * \note The window coordinate origin is the upper left of the display. + * + * \sa SDL_GetWindowPosition() + */ +extern DECLSPEC void SDLCALL SDL_SetWindowPosition(SDL_WindowID windowID, + int x, int y); + +/** + * \fn void SDL_GetWindowPosition(SDL_WindowID windowID, int *x, int *y) + * + * \brief Get the position of the window. + * + * \sa SDL_SetWindowPosition() + */ +extern DECLSPEC void SDLCALL SDL_GetWindowPosition(SDL_WindowID windowID, + int *x, int *y); -/* - * 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 - * return 1. If not all the color entries were set exactly as given, - * it will return 0, and you should look at the surface palette to - * determine the actual color palette. +/** + * \fn void SDL_SetWindowSize(SDL_WindowID windowID, int w, int w) + * + * \brief Set the size of the window's client area. + * + * \note You can't change the size of a fullscreen window, it automatically + * matches the size of the display mode. + * + * \sa SDL_GetWindowSize() + */ +extern DECLSPEC void SDLCALL SDL_SetWindowSize(SDL_WindowID windowID, int w, + int h); + +/** + * \fn void SDL_GetWindowSize(SDL_WindowID windowID, int *w, int *w) + * + * \brief Get the size of the window's client area. + * + * \sa SDL_SetWindowSize() + */ +extern DECLSPEC void SDLCALL SDL_GetWindowSize(SDL_WindowID windowID, int *w, + int *h); + +/** + * \fn void SDL_ShowWindow(SDL_WindowID windowID) + * + * \brief Show the window + * + * \sa SDL_HideWindow() + */ +extern DECLSPEC void SDLCALL SDL_ShowWindow(SDL_WindowID windowID); + +/** + * \fn void SDL_HideWindow(SDL_WindowID windowID) + * + * \brief Hide the window + * + * \sa SDL_ShowWindow() + */ +extern DECLSPEC void SDLCALL SDL_HideWindow(SDL_WindowID windowID); + +/** + * \fn void SDL_RaiseWindow(SDL_WindowID windowID) + * + * \brief Raise the window above other windows and set the input focus. + */ +extern DECLSPEC void SDLCALL SDL_RaiseWindow(SDL_WindowID windowID); + +/** + * \fn void SDL_MaximizeWindow(SDL_WindowID windowID) + * + * \brief Make the window as large as possible. + * + * \sa SDL_RestoreWindow() + */ +extern DECLSPEC void SDLCALL SDL_MaximizeWindow(SDL_WindowID windowID); + +/** + * \fn void SDL_MinimizeWindow(SDL_WindowID windowID) + * + * \brief Minimize the window to an iconic representation. + * + * \sa SDL_RestoreWindow() + */ +extern DECLSPEC void SDLCALL SDL_MinimizeWindow(SDL_WindowID windowID); + +/** + * \fn void SDL_RestoreWindow(SDL_WindowID windowID) + * + * \brief Restore the size and position of a minimized or maximized window. + * + * \sa SDL_MaximizeWindow() + * \sa SDL_MinimizeWindow() + */ +extern DECLSPEC void SDLCALL SDL_RestoreWindow(SDL_WindowID windowID); + +/** + * \fn int SDL_SetWindowFullscreen(SDL_WindowID windowID, int fullscreen) + * + * \brief Set the window's fullscreen state. + * + * \return 0 on success, or -1 if setting the display mode failed. + * + * \sa SDL_SetFullscreenDisplayMode() + */ +extern DECLSPEC int SDLCALL SDL_SetWindowFullscreen(SDL_WindowID windowID, + int fullscreen); + +/** + * \fn void SDL_SetWindowGrab(SDL_WindowID windowID, int mode) + * + * \brief Set the window's input grab mode. + * + * \param mode This is 1 to grab input, and 0 to release input. + * + * \sa SDL_GetWindowGrab() + */ +extern DECLSPEC void SDLCALL SDL_SetWindowGrab(SDL_WindowID windowID, + int mode); + +/** + * \fn int SDL_GetWindowGrab(SDL_WindowID windowID) + * + * \brief Get the window's input grab mode. + * + * \return This returns 1 if input is grabbed, and 0 otherwise. + * + * \sa SDL_SetWindowGrab() + */ +extern DECLSPEC int SDLCALL SDL_GetWindowGrab(SDL_WindowID windowID); + +/** + * \fn SDL_bool SDL_GetWindowWMInfo(SDL_WindowID windowID, struct SDL_SysWMinfo * info) + * + * \brief Get driver specific information about a window. + * + * \note Include SDL_syswm.h for the declaration of SDL_SysWMinfo. + */ +struct SDL_SysWMinfo; +extern DECLSPEC SDL_bool SDLCALL SDL_GetWindowWMInfo(SDL_WindowID windowID, + struct SDL_SysWMinfo + *info); + +/** + * \fn void SDL_DestroyWindow(SDL_WindowID windowID) + * + * \brief Destroy a window. + */ +extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID); + +/** + * \fn int SDL_GetNumRenderers(void) + * + * \brief Get the number of render managers on the current display. + * + * A render manager is a set of code that handles rendering and texture + * management on a particular display. Normally there is only one, but + * some drivers may have several available with different capabilities. + * + * \sa SDL_GetRendererInfo() + * \sa SDL_CreateRenderer() + */ +extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void); + +/** + * \fn SDL_RendererInfo *SDL_GetRendererInfo(int index) + * + * \brief Get information about a specific render manager on the current + * display. * - * When 'surface' is the surface associated with the current display, the - * display colormap will be updated with the requested colors. If - * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors() - * will always return 1, and the palette is guaranteed to be set the way - * you desire, even if the window colormap has to be warped or run under - * emulation. + * \sa SDL_CreateRenderer() + */ +extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index, + SDL_RendererInfo * info); + +/** + * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags) + * + * \brief Create and make active a 2D rendering context for a window. + * + * \param windowID The window used for rendering + * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags. + * \param flags SDL_RendererFlags + * + * \return 0 on success, -1 if the flags were not supported, or -2 if + * there isn't enough memory to support the requested flags + * + * \sa SDL_SelectRenderer() + * \sa SDL_DestroyRenderer() + */ +extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID, + int index, Uint32 flags); + +/** + * \fn int SDL_SelectRenderer(SDL_WindowID windowID) + * + * \brief Select the rendering context for a particular window. + * + * \return 0 on success, -1 if the selected window doesn't have a + * rendering context. + */ +extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID); + +/** + * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h) + * + * \brief Create a texture for the current rendering context. + * + * \param format The format of the texture + * \param access One of the enumerated values in SDL_TextureAccess + * \param w The width of the texture in pixels + * \param h The height of the texture in pixels + * + * \return The created texture is returned, or 0 if no render manager was active, the format was unsupported, or the width or height were out of range. + * + * \sa SDL_QueryTexture() + * \sa SDL_DestroyTexture() + */ +extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format, + int access, int w, + int h); + +/** + * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, int access, SDL_Surface *surface) + * + * \brief Create a texture from an existing surface. + * + * \param format The format of the texture, or 0 to pick an appropriate format + * \param access One of the enumerated values in SDL_TextureAccess + * \param surface The surface containing pixel data used to fill the texture + * + * \return The created texture is returned, or 0 if no render manager was active, the format was unsupported, or the surface width or height were out of range. + * + * \note The surface is not modified or freed by this function. + * + * \sa SDL_QueryTexture() + * \sa SDL_DestroyTexture() */ -extern DECLSPEC int SDLCALL SDL_SetColors(SDL_Surface *surface, - SDL_Color *colors, int firstcolor, int ncolors); +extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32 + format, + int access, + SDL_Surface + * surface); + +/** + * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h) + * + * \brief Query the attributes of a texture + * + * \param texture A texture to be queried + * \param format A pointer filled in with the raw format of the texture. The actual format may differ, but pixel transfers will use this format. + * \param access A pointer filled in with the actual access to the texture. + * \param w A pointer filled in with the width of the texture in pixels + * \param h A pointer filled in with the height of the texture in pixels + * + * \return 0 on success, or -1 if the texture is not valid + */ +extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_TextureID textureID, + Uint32 * format, int *access, + int *w, int *h); + +/** + * \fn int SDL_QueryTexturePixels(SDL_TextureID textureID, void **pixels, int pitch) + * + * \brief Query the pixels of a texture, if the texture does not need to be locked for pixel access. + * + * \param texture A texture to be queried, which was created with SDL_TextureAccess_Local + * \param pixels A pointer filled with a pointer to the pixels for the texture + * \param pitch A pointer filled in with the pitch of the pixel data + * + * \return 0 on success, or -1 if the texture is not valid, or must be locked for pixel access. + */ +extern DECLSPEC int SDLCALL SDL_QueryTexturePixels(SDL_TextureID textureID, + void **pixels, int *pitch); + +/** + * \fn int SDL_SetTexturePalette(SDL_TextureID textureID, const SDL_Color * colors, int firstcolor, int ncolors) + * + * \brief Update an indexed texture with a color palette + * + * \param texture The texture to update + * \param colors The array of RGB color data + * \param firstcolor The first index to update + * \param ncolors The number of palette entries to fill with the color data + * + * \return 0 on success, or -1 if the texture is not valid or not an indexed texture + */ +extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_TextureID textureID, + const SDL_Color * colors, + int firstcolor, + int ncolors); + +/** + * \fn int SDL_GetTexturePalette(SDL_TextureID textureID, SDL_Color * colors, int firstcolor, int ncolors) + * + * \brief Update an indexed texture with a color palette + * + * \param texture The texture to update + * \param colors The array to fill with RGB color data + * \param firstcolor The first index to retrieve + * \param ncolors The number of palette entries to retrieve + * + * \return 0 on success, or -1 if the texture is not valid or not an indexed texture + */ +extern DECLSPEC int SDLCALL SDL_GetTexturePalette(SDL_TextureID textureID, + 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 - * to/from the surface, - * SDL_PHYSPAL -- set physical palette, which controls how pixels look on - * the screen - * Only screens have physical palettes. Separate change of physical/logical - * palettes is only possible if the screen has SDL_HWPALETTE set. +/** + * \fn int SDL_UpdateTexture(SDL_TextureID textureID, const SDL_Rect *rect, const void *pixels, int pitch) + * + * \brief Update the given texture rectangle with new pixel data. + * + * \param texture The texture to update + * \param rect A pointer to the rectangle of pixels to update, or NULL to update the entire texture. + * \param pixels The raw pixel data + * \param pitch The number of bytes between rows of pixel data + * + * \return 0 on success, or -1 if the texture is not valid + * + * \note This is a very slow function for textures not created with SDL_TextureAccess_Local. + */ +extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID, + const SDL_Rect * rect, + const void *pixels, int pitch); + +/** + * \fn void SDL_LockTexture(SDL_TextureID textureID, const SDL_Rect *rect, int markDirty, void **pixels, int *pitch) + * + * \brief Lock a portion of the texture for pixel access. + * + * \param texture The texture to lock for access, which must have been created with SDL_TextureAccess_Local. + * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked. + * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked. + * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area. + * \param pitch This is filled in with the pitch of the locked pixels. + * + * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TextureAccess_Remote + * + * \sa SDL_DirtyTexture() + * \sa SDL_UnlockTexture() + */ +extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID, + const SDL_Rect * rect, + int markDirty, void **pixels, + int *pitch); + +/** + * \fn void SDL_UnlockTexture(SDL_TextureID textureID) + * + * \brief Unlock a texture, uploading the changes to video memory, if needed. + * + * \sa SDL_LockTexture() + * \sa SDL_DirtyTexture() + */ +extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_TextureID textureID); + +/** + * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, const SDL_Rect * rects) + * + * \brief Mark the specified rectangles of the texture as dirty. + * + * \note The texture must have been created with SDL_TextureAccess_Local. + * + * \sa SDL_LockTexture() + * \sa SDL_UnlockTexture() + */ +extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID, + int numrects, + const SDL_Rect * rects); + +/** + * \fn void SDL_SelectRenderTexture(SDL_TextureID textureID) + * + * \brief Select a texture as the rendering target, or 0 to reselect the current window. + * + * \note The texture must have been created with SDL_TextureAccess_Render. + */ +extern DECLSPEC void SDLCALL SDL_SelectRenderTexture(SDL_TextureID textureID); + +/** + * \fn void SDL_RenderFill(const SDL_Rect *rect, Uint32 color) + * + * \brief Fill the current rendering target with the specified color. + * + * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target. + * \param color An ARGB color value. * - * The return value is 1 if all colours could be set as requested, and 0 - * otherwise. + * \return 0 on success, or -1 if there is no renderer current + */ +extern DECLSPEC int SDLCALL SDL_RenderFill(const SDL_Rect * rect, + Uint32 color); + +/** + * \fn int SDL_RenderCopy(SDL_TextureID textureID, const SDL_Rect *srcrect, const SDL_Rect *dstrect, Uint32 blendMode, Uint32 scaleMode) + * + * \brief Copy a portion of the texture to the current rendering target. + * + * \param texture The source texture. + * \param srcrect A pointer to the source rectangle, or NULL for the entire texture. + * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target. + * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel. + * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height. + * + * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation. + * + * \note You can check the video driver info to see what operations are supported. + */ +extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID, + const SDL_Rect * srcrect, + const SDL_Rect * dstrect, + int blendMode, int scaleMode); + +/** + * \fn int SDL_RenderReadPixels(const SDL_Rect *rect, void *pixels, int pitch) + * + * \brief Read pixels from the current rendering target. + * + * \param rect A pointer to the rectangle to read, or NULL for the entire render target + * \param pixels A pointer to be filled in with the pixel data + * \param pitch The pitch of the pixels parameter + * + * \return 0 on success, or -1 if pixel reading is not supported. * - * SDL_SetColors() is equivalent to calling this function with - * flags = (SDL_LOGPAL|SDL_PHYSPAL). + * \warning This is a very slow operation, and should not be used frequently. + */ +extern DECLSPEC int SDLCALL SDL_RenderReadPixels(const SDL_Rect * rect, + void *pixels, int pitch); + +/** + * \fn int SDL_RenderWritePixels(const SDL_Rect *rect, const void *pixels, int pitch) + * + * \brief Write pixels to the current rendering target. + * + * \param rect A pointer to the rectangle to write, or NULL for the entire render target + * \param pixels A pointer to the pixel data to write + * \param pitch The pitch of the pixels parameter + * + * \return 0 on success, or -1 if pixel writing is not supported. + * + * \warning This is a very slow operation, and should not be used frequently. */ -extern DECLSPEC int SDLCALL SDL_SetPalette(SDL_Surface *surface, int flags, - SDL_Color *colors, int firstcolor, - int ncolors); +extern DECLSPEC int SDLCALL SDL_RenderWritePixels(const SDL_Rect * rect, + const void *pixels, + int pitch); + +/** + * \fn void SDL_RenderPresent(void) + * + * \brief Update the screen with rendering performed. + */ +extern DECLSPEC void SDLCALL SDL_RenderPresent(void); + +/** + * \fn void SDL_DestroyTexture(SDL_TextureID textureID); + * + * \brief Destroy the specified texture. + * + * \sa SDL_CreateTexture() + * \sa SDL_CreateTextureFromSurface() + */ +extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_TextureID textureID); + +/** + * \fn void SDL_DestroyRenderer(SDL_WindowID windowID); + * + * \brief Destroy the rendering context for a window and free associated + * textures. + * + * \sa SDL_CreateRenderer() + */ +extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_WindowID windowID); /* * Maps an RGB triple to an opaque pixel value for a given pixel format */ extern DECLSPEC Uint32 SDLCALL SDL_MapRGB - (SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b); + (SDL_PixelFormat * format, Uint8 r, Uint8 g, Uint8 b); /* * Maps an RGBA quadruple to a pixel value for a given pixel format */ -extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat *format, - Uint8 r, Uint8 g, Uint8 b, Uint8 a); +extern DECLSPEC Uint32 SDLCALL SDL_MapRGBA(SDL_PixelFormat * format, + Uint8 r, Uint8 g, Uint8 b, + 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, - Uint8 *r, Uint8 *g, Uint8 *b); +extern DECLSPEC void SDLCALL SDL_GetRGB(Uint32 pixel, SDL_PixelFormat * 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, SDL_PixelFormat * fmt, + Uint8 * r, Uint8 * g, Uint8 * b, + Uint8 * a); /* * Allocate and free an RGB surface (must be called after SDL_SetVideoMode) @@ -475,40 +1179,36 @@ * If the function runs out of memory, it will return NULL. * * The 'flags' tell what kind of surface to create. - * SDL_SWSURFACE means that the surface should be created in system memory. - * SDL_HWSURFACE means that the surface should be created in video memory, - * with the same format as the display surface. This is useful for surfaces - * that will not change much, to take advantage of hardware acceleration - * when being blitted to the display surface. - * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with - * this surface, but you must always lock it before accessing the pixels. - * SDL will wait for current blits to finish before returning from the lock. * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits. - * If the hardware supports acceleration of colorkey blits between - * two surfaces in video memory, SDL will try to place the surface in - * video memory. If this isn't possible or if there is no hardware - * acceleration available, the surface will be placed in system memory. - * SDL_SRCALPHA means that the surface will be used for alpha blits and - * if the hardware supports hardware acceleration of alpha blits between - * two surfaces in video memory, to place the surface in video memory - * if possible, otherwise it will be placed in system memory. - * If the surface is created in video memory, blits will be _much_ faster, - * but the surface format must be identical to the video surface format, - * and the only way to access the pixels member of the surface is to use - * the SDL_LockSurface() and SDL_UnlockSurface() calls. - * If the requested surface actually resides in video memory, SDL_HWSURFACE - * will be set in the flags member of the returned surface. If for some - * 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. + * SDL_SRCALPHA means that the surface will be used for alpha blits. */ -#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); -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); +extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface + (Uint32 flags, int width, int height, int depth, + Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask); +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 SDL_Surface *SDLCALL +SDL_CreateRGBSurfaceFromTexture(SDL_TextureID textureID); +extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface); + +/** + * \fn int SDL_SetSurfacePalette(SDL_Surface *surface, SDL_Palette *palette) + * + * \brief Set the palette used by a surface. + * + * \return 0, or -1 if the surface format doesn't use a palette. + * + * \note A single palette can be shared with many surfaces. + */ +extern DECLSPEC int SDLCALL SDL_SetSurfacePalette(SDL_Surface * surface, + SDL_Palette * palette); /* * SDL_LockSurface() sets up a surface for directly accessing the pixels. @@ -519,17 +1219,15 @@ * * Not all surfaces require locking. If SDL_MUSTLOCK(surface) evaluates * to 0, then you can read and write to the surface at any time, and the - * pixel format of the surface will not change. In particular, if the - * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you - * will not need to lock the display surface before accessing it. + * pixel format of the surface will not change. * * No operating system or library calls should be made between lock/unlock * pairs, as critical system locks may be held during this time. * * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked. */ -extern DECLSPEC int SDLCALL SDL_LockSurface(SDL_Surface *surface); -extern DECLSPEC void SDLCALL SDL_UnlockSurface(SDL_Surface *surface); +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.) @@ -537,7 +1235,8 @@ * Returns the new surface, or NULL if there was an error. * The new surface should be freed with SDL_FreeSurface(). */ -extern DECLSPEC SDL_Surface * SDLCALL SDL_LoadBMP_RW(SDL_RWops *src, int freesrc); +extern DECLSPEC SDL_Surface *SDLCALL SDL_LoadBMP_RW(SDL_RWops * src, + int freesrc); /* Convenience macro -- load a surface from a file */ #define SDL_LoadBMP(file) SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1) @@ -548,7 +1247,7 @@ * 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); + (SDL_Surface * surface, SDL_RWops * dst, int freedst); /* Convenience macro -- save a surface to a file */ #define SDL_SaveBMP(surface, file) \ @@ -564,7 +1263,7 @@ * This function returns 0, or -1 if there was an error. */ extern DECLSPEC int SDLCALL SDL_SetColorKey - (SDL_Surface *surface, Uint32 flag, Uint32 key); + (SDL_Surface * surface, Uint32 flag, Uint32 key); /* * This function sets the alpha value for the entire surface, as opposed to @@ -581,7 +1280,8 @@ * * The 'alpha' parameter is ignored for surfaces that have an alpha channel. */ -extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha); +extern DECLSPEC int SDLCALL SDL_SetAlpha(SDL_Surface * surface, Uint32 flag, + Uint8 alpha); /* * Sets the clipping rectangle for the destination surface in a blit. @@ -595,14 +1295,16 @@ * Note that blits are automatically clipped to the edges of the source * and destination surfaces. */ -extern DECLSPEC SDL_bool SDLCALL SDL_SetClipRect(SDL_Surface *surface, const SDL_Rect *rect); +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); +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 @@ -616,8 +1318,20 @@ * * This function is used internally by SDL_DisplayFormat(). */ -extern DECLSPEC SDL_Surface * SDLCALL SDL_ConvertSurface - (SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags); +extern DECLSPEC SDL_Surface *SDLCALL SDL_ConvertSurface + (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags); + +/* + * 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. + * If 'dstrect' is NULL, the whole surface will be filled with 'color' + * The color should be a pixel of the format used by the surface, and + * can be generated by the SDL_MapRGB() function. + * This function returns 0 on success, or -1 on error. + */ +extern DECLSPEC int SDLCALL SDL_FillRect + (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color); /* * This performs a fast blit from the source surface to the destination @@ -694,196 +1408,177 @@ 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); + (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. */ 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. - * If 'dstrect' is NULL, the whole surface will be filled with 'color' - * The color should be a pixel of the format used by the surface, and - * can be generated by the SDL_MapRGB() function. - * This function returns 0 on success, or -1 on error. - */ -extern DECLSPEC int SDLCALL SDL_FillRect - (SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color); + (SDL_Surface * src, SDL_Rect * srcrect, + SDL_Surface * dst, SDL_Rect * dstrect); -/* - * 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() - * - * If you want to take advantage of hardware colorkey or alpha blit - * acceleration, you should set the colorkey and alpha value before - * calling this function. - * - * If the conversion fails or runs out of memory, it returns NULL - */ -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. - * The new surface will always have an alpha channel. +/** + * \fn int SDL_SoftStretch(SDL_Surface * src, SDL_Rect * srcrect, SDL_Surface * dst, SDL_Rect * dstrect) * - * If you want to take advantage of hardware colorkey or alpha blit - * acceleration, you should set the colorkey and alpha value before - * calling this function. + * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format. * - * If the conversion fails or runs out of memory, it returns NULL + * \note This function uses a static buffer, and is not thread-safe. */ -extern DECLSPEC SDL_Surface * SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *surface); - - -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* 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. -*/ -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 */ -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. -*/ -extern DECLSPEC int SDLCALL SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect); - -/* Free a video overlay */ -extern DECLSPEC void SDLCALL SDL_FreeYUVOverlay(SDL_Overlay *overlay); - +extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src, + SDL_Rect * srcrect, + SDL_Surface * dst, + SDL_Rect * dstrect); /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ /* OpenGL support functions. */ /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ -/* - * Dynamically load an OpenGL library, or the default one if path is NULL +/** + * \fn int SDL_GL_LoadLibrary(const char *path) + * + * \brief Dynamically load an OpenGL library. + * + * \param path The platform dependent OpenGL library name, or NULL to open the default OpenGL library * - * If you do this, you need to retrieve all of the GL functions used in - * your program from the dynamic library using SDL_GL_GetProcAddress(). + * \return 0 on success, or -1 if the library couldn't be loaded + * + * \note If you do this, you need to retrieve all of the GL functions used in + * your program from the dynamic library using SDL_GL_GetProcAddress(). + * + * \sa SDL_GL_GetProcAddress() */ extern DECLSPEC int SDLCALL SDL_GL_LoadLibrary(const char *path); -/* - * Get the address of a GL function +/** + * \fn void *SDL_GL_GetProcAddress(const char *proc) + * + * \brief Get the address of an OpenGL function. */ -extern DECLSPEC void * SDLCALL SDL_GL_GetProcAddress(const char* proc); +extern DECLSPEC void *SDLCALL SDL_GL_GetProcAddress(const char *proc); -/* - * Set an attribute of the OpenGL subsystem before intialization. +/** + * \fn int SDL_GL_SetAttribute(SDL_GLattr attr, int value) + * + * \brief Set an OpenGL window attribute before window creation. */ 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 - * stores the values you request before initialization. +/** + * \fn int SDL_GL_GetWindowAttribute(SDL_WindowID windowID, SDL_GLattr attr, int *value) + * + * \brief Get the actual value for an OpenGL window attribute. + */ +extern DECLSPEC int SDLCALL SDL_GL_GetWindowAttribute(SDL_WindowID windowID, + SDL_GLattr attr, + int *value); + +/** + * \fn SDL_GLContext SDL_GL_CreateContext(SDL_WindowID windowID) + * + * \brief Create an OpenGL context for use with an OpenGL window, and make it current. + * + * \sa SDL_GL_DeleteContext() + */ +extern DECLSPEC SDL_GLContext SDLCALL SDL_GL_CreateContext(SDL_WindowID + windowID); + +/** + * \fn int SDL_GL_MakeCurrent(SDL_WindowID windowID, SDL_GLContext context) + * + * \brief Set up an OpenGL context for rendering into an OpenGL window. * - * Developers should track the values they pass into SDL_GL_SetAttribute - * themselves if they want to retrieve these values. + * \note The context must have been created with a compatible window. + */ +extern DECLSPEC int SDLCALL SDL_GL_MakeCurrent(SDL_WindowID windowID, + SDL_GLContext context); + +/** + * \fn int SDL_GL_SetSwapInterval(int interval) + * + * \brief Set the swap interval for the current OpenGL context. + * + * \sa SDL_GL_GetSwapInterval() */ -extern DECLSPEC int SDLCALL SDL_GL_GetAttribute(SDL_GLattr attr, int* value); +extern DECLSPEC int SDLCALL SDL_GL_SetSwapInterval(int interval); -/* +/** + * \fn int SDL_GL_GetSwapInterval(void) + * + * \brief Get the swap interval for the current OpenGL context. + * + * \sa SDL_GL_SetSwapInterval() + */ +extern DECLSPEC int SDLCALL SDL_GL_GetSwapInterval(void); + +/** + * \fn void SDL_GL_SwapBuffers(void) + * * Swap the OpenGL buffers, if double-buffering is supported. */ extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void); -/* - * 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. */ -/* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */ - -/* - * Sets/Gets the title and icon text of the display window (UTF-8 encoded) +/** + * \fn void SDL_GL_DeleteContext(SDL_GLContext context) + * + * \brief Delete an OpenGL context. + * + * \sa SDL_GL_CreateContext() */ -extern DECLSPEC void SDLCALL SDL_WM_SetCaption(const char *title, const char *icon); -extern DECLSPEC void SDLCALL SDL_WM_GetCaption(char **title, char **icon); +extern DECLSPEC void SDLCALL SDL_GL_DeleteContext(SDL_GLContext context); -/* - * 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. - * If 'mask' is NULL, the entire icon surface will be used as the icon. +/** + * \def SDL_RectEmpty() + * + * \brief Returns true if the rectangle has no area. */ -extern DECLSPEC void SDLCALL SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask); +#define SDL_RectEmpty(X) (((X)->w <= 0) || ((X)->h <= 0)) -/* - * 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. +/** + * \def SDL_RectEquals() + * + * \brief Returns true if the two rectangles are equal. */ -extern DECLSPEC int SDLCALL SDL_WM_IconifyWindow(void); +#define SDL_RectEquals(A, B) (((A)->x == (B)->x) && ((A)->y == (B)->y) && \ + ((A)->w == (B)->w) && ((A)->h == (B)->h)) -/* - * 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. +/** + * \fn SDL_bool SDL_HasIntersection(const SDL_Rect * A, const SDL_Rect * B); + * + * \brief Determine whether two rectangles intersect. * - * If this function was able to toggle fullscreen mode (change from - * running in a window to fullscreen, or vice-versa), it will return 1. - * If it is not implemented, or fails, it returns 0. - * - * The next call to SDL_SetVideoMode() will set the mode fullscreen - * attribute based on the flags parameter - if SDL_FULLSCREEN is not - * set, then the display will be windowed by default where supported. - * - * This is currently only implemented in the X11 video driver. + * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise. */ -extern DECLSPEC int SDLCALL SDL_WM_ToggleFullScreen(SDL_Surface *surface); +extern DECLSPEC SDL_bool SDLCALL SDL_HasIntersection(const SDL_Rect * A, + const SDL_Rect * B); -/* - * This function allows you to set and query the input grab state of - * the application. It returns the new input grab state. +/** + * \fn SDL_bool SDL_IntersectRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result) + * + * \brief Calculate the intersection of two rectangles. + * + * \return SDL_TRUE if there is an intersection, SDL_FALSE otherwise. */ -typedef enum { - SDL_GRAB_QUERY = -1, - SDL_GRAB_OFF = 0, - SDL_GRAB_ON = 1, - SDL_GRAB_FULLSCREEN /* Used internally */ -} SDL_GrabMode; -/* - * 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_bool SDLCALL SDL_IntersectRect(const SDL_Rect * A, + const SDL_Rect * B, + SDL_Rect * result); + +/** + * \fn void SDL_UnionRect(const SDL_Rect * A, const SDL_Rect * B, SDL_Rect * result) + * + * \brief Calculate the union of two rectangles */ -extern DECLSPEC SDL_GrabMode SDLCALL SDL_WM_GrabInput(SDL_GrabMode mode); +extern DECLSPEC void SDLCALL SDL_UnionRect(const SDL_Rect * A, + const SDL_Rect * B, + SDL_Rect * result); -/* 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); - /* Ends C function definitions when using C++ */ #ifdef __cplusplus +/* *INDENT-OFF* */ } +/* *INDENT-ON* */ #endif #include "close_code.h" #endif /* _SDL_video_h */ + +/* vi: set ts=4 sw=4 expandtab: */