home *** CD-ROM | disk | FTP | other *** search
/ GameStar Special 2004 August / GSSH0804.iso / Action / Parsec47 / Parsec47.exe / p47 / import / SDL_video.d < prev    next >
Text File  |  2003-11-29  |  36KB  |  896 lines
  1. /*
  2.     SDL - Simple DirectMedia Layer
  3.     Copyright (C) 1997, 1998, 1999, 2000, 2001  Sam Lantinga
  4.  
  5.     This library is free software; you can redistribute it and/or
  6.     modify it under the terms of the GNU Library General Public
  7.     License as published by the Free Software Foundation; either
  8.     version 2 of the License, or (at your option) any later version.
  9.  
  10.     This library is distributed in the hope that it will be useful,
  11.     but WITHOUT ANY WARRANTY; without even the implied warranty of
  12.     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13.     Library General Public License for more details.
  14.  
  15.     You should have received a copy of the GNU Library General Public
  16.     License along with this library; if not, write to the Free
  17.     Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  18.  
  19.     Sam Lantinga
  20.     slouken@devolution.com
  21. */
  22.  
  23. /* Header file for access to the SDL raw framebuffer window */
  24.  
  25. import SDL_types;
  26. import SDL_mutex;
  27. import SDL_rwops;
  28.  
  29. extern(C):
  30.  
  31. /* Transparency definitions: These define alpha as the opacity of a surface */
  32. const uint SDL_ALPHA_OPAQUE = 255;
  33. const uint SDL_ALPHA_TRANSPARENT = 0;
  34.  
  35. /* Useful data types */
  36. struct SDL_Rect {
  37.     Sint16 x, y;
  38.     Uint16 w, h;
  39. }
  40.  
  41. struct SDL_Color {
  42.     Uint8 r;
  43.     Uint8 g;
  44.     Uint8 b;
  45.     Uint8 unused;
  46. }
  47.  
  48. struct SDL_Palette {
  49.     int       ncolors;
  50.     SDL_Color *colors;
  51. }
  52.  
  53. /* Everything in the pixel format structure is read-only */
  54. struct SDL_PixelFormat {
  55.     SDL_Palette *palette;
  56.     Uint8  BitsPerPixel;
  57.     Uint8  BytesPerPixel;
  58.     Uint8  Rloss;
  59.     Uint8  Gloss;
  60.     Uint8  Bloss;
  61.     Uint8  Aloss;
  62.     Uint8  Rshift;
  63.     Uint8  Gshift;
  64.     Uint8  Bshift;
  65.     Uint8  Ashift;
  66.     Uint32 Rmask;
  67.     Uint32 Gmask;
  68.     Uint32 Bmask;
  69.     Uint32 Amask;
  70.  
  71.     /* RGB color key information */
  72.     Uint32 colorkey;
  73.     /* Alpha value information (per-surface alpha) */
  74.     Uint8  alpha;
  75. }
  76.  
  77. /* typedef for private surface blitting functions */
  78. typedef int (*SDL_blit)(SDL_Surface *src, SDL_Rect *srcrect,
  79.             SDL_Surface *dst, SDL_Rect *dstrect);
  80.  
  81. /* This structure should be treated as read-only, except for 'pixels',
  82.    which, if not NULL, contains the raw pixel data for the surface.
  83. */
  84. struct SDL_Surface {
  85.     Uint32 flags;                /* Read-only */
  86.     SDL_PixelFormat *format;        /* Read-only */
  87.     int w, h;                /* Read-only */
  88.     Uint16 pitch;                /* Read-only */
  89.     void *pixels;                /* Read-write */
  90.     int offset;                /* Private */
  91.  
  92.     /* Hardware-specific surface info */
  93.     void /*private_hwdata*/ *hwdata;
  94.  
  95.     /* clipping information */
  96.     SDL_Rect clip_rect;            /* Read-only */
  97.     Uint32 unused1;                /* for binary compatibility */
  98.  
  99.     /* Allow recursive locks */
  100.     Uint32 locked;                /* Private */
  101.  
  102.     /* info for fast blit mapping to other surfaces */
  103.     void /*SDL_BlitMap*/ *map;        /* Private */
  104.  
  105.     /* format version, bumped at every change to invalidate blit maps */
  106.     uint format_version;        /* Private */
  107.  
  108.     /* Reference count -- used when freeing surface */
  109.     int refcount;                /* Read-mostly */
  110. }
  111.  
  112. /* These are the currently supported flags for the SDL_surface */
  113. /* Available for SDL_CreateRGBSurface() or SDL_SetVideoMode() */
  114. const uint SDL_SWSURFACE    = 0x00000000;    /* Surface is in system memory */
  115. const uint SDL_HWSURFACE    = 0x00000001;    /* Surface is in video memory */
  116. const uint SDL_ASYNCBLIT    = 0x00000004;    /* Use asynchronous blits if possible */
  117. /* Available for SDL_SetVideoMode() */
  118. const uint SDL_ANYFORMAT    = 0x10000000;    /* Allow any video depth/pixel-format */
  119. const uint SDL_HWPALETTE    = 0x20000000;    /* Surface has exclusive palette */
  120. const uint SDL_DOUBLEBUF    = 0x40000000;    /* Set up double-buffered video mode */
  121. const uint SDL_FULLSCREEN    = 0x80000000;    /* Surface is a full screen display */
  122. const uint SDL_OPENGL        = 0x00000002;    /* Create an OpenGL rendering context */
  123. const uint SDL_OPENGLBLIT    = 0x0000000A;    /* Create an OpenGL rendering context and use it for blitting */
  124. const uint SDL_RESIZABLE    = 0x00000010;    /* This video mode may be resized */
  125. const uint SDL_NOFRAME    = 0x00000020;    /* No window caption or edge frame */
  126. /* Used internally (read-only) */
  127. const uint SDL_HWACCEL    = 0x00000100;    /* Blit uses hardware acceleration */
  128. const uint SDL_SRCCOLORKEY    = 0x00001000;    /* Blit uses a source color key */
  129. const uint SDL_RLEACCELOK    = 0x00002000;    /* Private flag */
  130. const uint SDL_RLEACCEL    = 0x00004000;    /* Surface is RLE encoded */
  131. const uint SDL_SRCALPHA    = 0x00010000;    /* Blit uses source alpha blending */
  132. const uint SDL_PREALLOC    = 0x01000000;    /* Surface uses preallocated memory */
  133.  
  134. /* Evaluates to true if the surface needs to be locked before access */
  135. bit SDL_MUSTLOCK(SDL_Surface *surface)
  136. {
  137.     return surface.offset || ((surface.flags &
  138.         (SDL_HWSURFACE | SDL_ASYNCBLIT | SDL_RLEACCEL)) != 0);
  139. }
  140.  
  141. /* Useful for determining the video hardware capabilities */
  142. struct SDL_VideoInfo {
  143.     Uint32 flags;
  144. //        Uint32 hw_available :1;    /* Flag: Can you create hardware surfaces? */
  145. //        Uint32 wm_available :1;    /* Flag: Can you talk to a window manager? */
  146. //        Uint32 UnusedBits1  :6;
  147. //        Uint32 UnusedBits2  :1;
  148. //        Uint32 blit_hw      :1;    /* Flag: Accelerated blits HW -. HW */
  149. //        Uint32 blit_hw_CC   :1;    /* Flag: Accelerated blits with Colorkey */
  150. //        Uint32 blit_hw_A    :1;    /* Flag: Accelerated blits with Alpha */
  151. //        Uint32 blit_sw      :1;    /* Flag: Accelerated blits SW -. HW */
  152. //        Uint32 blit_sw_CC   :1;    /* Flag: Accelerated blits with Colorkey */
  153. //        Uint32 blit_sw_A    :1;    /* Flag: Accelerated blits with Alpha */
  154. //        Uint32 blit_fill    :1;    /* Flag: Accelerated color fill */
  155. //        Uint32 UnusedBits3  :16;
  156.     Uint32 video_mem;    /* The total amount of video memory (in K) */
  157.     SDL_PixelFormat *vfmt;    /* Value: The format of the video surface */
  158. }
  159.  
  160.  
  161. /* The most common video overlay formats.
  162.    For an explanation of these pixel formats, see:
  163.     http://www.webartz.com/fourcc/indexyuv.htm
  164.  
  165.    For information on the relationship between color spaces, see:
  166.    http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
  167.  */
  168. const uint SDL_YV12_OVERLAY = 0x32315659;    /* Planar mode: Y + V + U  (3 planes) */
  169. const uint SDL_IYUV_OVERLAY = 0x56555949;    /* Planar mode: Y + U + V  (3 planes) */
  170. const uint SDL_YUY2_OVERLAY = 0x32595559;    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
  171. const uint SDL_UYVY_OVERLAY = 0x59565955;    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
  172. const uint SDL_YVYU_OVERLAY = 0x55595659;    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
  173.  
  174. /* The YUV hardware video overlay */
  175. struct SDL_Overlay {
  176.     Uint32 format;                /* Read-only */
  177.     int w, h;                /* Read-only */
  178.     int planes;                /* Read-only */
  179.     Uint16 *pitches;            /* Read-only */
  180.     Uint8 **pixels;                /* Read-write */
  181.  
  182.     /* Hardware-specific surface info */
  183.     void /*private_yuvhwfuncs*/ *hwfuncs;
  184.     void /*private_yuvhwdata*/ *hwdata;
  185.  
  186.     /* Special flags */
  187.     union
  188.     {
  189.         bit hw_overlay;
  190.         Uint32 _dummy;
  191.     }
  192. //        Uint32 hw_overlay :1;    /* Flag: This overlay hardware accelerated? */
  193. //        Uint32 UnusedBits :31;
  194. }
  195.  
  196.  
  197. /* Public enumeration for setting the OpenGL window attributes. */
  198. alias int SDL_GLattr;
  199. enum {
  200.     SDL_GL_RED_SIZE,
  201.     SDL_GL_GREEN_SIZE,
  202.     SDL_GL_BLUE_SIZE,
  203.     SDL_GL_ALPHA_SIZE,
  204.     SDL_GL_BUFFER_SIZE,
  205.     SDL_GL_DOUBLEBUFFER,
  206.     SDL_GL_DEPTH_SIZE,
  207.     SDL_GL_STENCIL_SIZE,
  208.     SDL_GL_ACCUM_RED_SIZE,
  209.     SDL_GL_ACCUM_GREEN_SIZE,
  210.     SDL_GL_ACCUM_BLUE_SIZE,
  211.     SDL_GL_ACCUM_ALPHA_SIZE
  212. }
  213.  
  214. /* flags for SDL_SetPalette() */
  215. const uint SDL_LOGPAL = 0x01;
  216. const uint SDL_PHYSPAL = 0x02;
  217.  
  218. /* Function prototypes */
  219.  
  220. /* These functions are used internally, and should not be used unless you
  221.  * have a specific need to specify the video driver you want to use.
  222.  * You should normally use SDL_Init() or SDL_InitSubSystem().
  223.  * 
  224.  * SDL_VideoInit() initializes the video subsystem -- sets up a connection
  225.  * to the window manager, etc, and determines the current video mode and
  226.  * pixel format, but does not initialize a window or graphics mode.
  227.  * Note that event handling is activated by this routine.
  228.  * 
  229.  * If you use both sound and video in your application, you need to call
  230.  * SDL_Init() before opening the sound device, otherwise under Win32 DirectX,
  231.  * you won't be able to set full-screen display modes.
  232.  */
  233. int SDL_VideoInit(char *driver_name, Uint32 flags);
  234. void SDL_VideoQuit();
  235.  
  236. /* This function fills the given character buffer with the name of the
  237.  * video driver, and returns a pointer to it if the video driver has
  238.  * been initialized.  It returns NULL if no driver has been initialized.
  239.  */
  240. char *SDL_VideoDriverName(char *namebuf, int maxlen);
  241.  
  242. /*
  243.  * This function returns a pointer to the current display surface.
  244.  * If SDL is doing format conversion on the display surface, this
  245.  * function returns the publicly visible surface, not the real video
  246.  * surface.
  247.  */
  248. SDL_Surface * SDL_GetVideoSurface();
  249.  
  250. /*
  251.  * This function returns a read-only pointer to information about the
  252.  * video hardware.  If this is called before SDL_SetVideoMode(), the 'vfmt'
  253.  * member of the returned structure will contain the pixel format of the
  254.  * "best" video mode.
  255.  */
  256. SDL_VideoInfo * SDL_GetVideoInfo();
  257.  
  258. /* 
  259.  * Check to see if a particular video mode is supported.
  260.  * It returns 0 if the requested mode is not supported under any bit depth,
  261.  * or returns the bits-per-pixel of the closest available mode with the
  262.  * given width and height.  If this bits-per-pixel is different from the
  263.  * one used when setting the video mode, SDL_SetVideoMode() will succeed,
  264.  * but will emulate the requested bits-per-pixel with a shadow surface.
  265.  * 
  266.  * The arguments to SDL_VideoModeOK() are the same ones you would pass to
  267.  * SDL_SetVideoMode()
  268.  */
  269. int SDL_VideoModeOK(int width, int height, int bpp, Uint32 flags);
  270.  
  271. /*
  272.  * Return a pointer to an array of available screen dimensions for the
  273.  * given format and video flags, sorted largest to smallest.  Returns 
  274.  * NULL if there are no dimensions available for a particular format, 
  275.  * or (SDL_Rect **)-1 if any dimension is okay for the given format.
  276.  * 
  277.  * If 'format' is NULL, the mode list will be for the format given 
  278.  * by SDL_GetVideoInfo().vfmt
  279.  */
  280. SDL_Rect ** SDL_ListModes(SDL_PixelFormat *format, Uint32 flags);
  281.  
  282. /*
  283.  * Set up a video mode with the specified width, height and bits-per-pixel.
  284.  * 
  285.  * If 'bpp' is 0, it is treated as the current display bits per pixel.
  286.  * 
  287.  * If SDL_ANYFORMAT is set in 'flags', the SDL library will try to set the
  288.  * requested bits-per-pixel, but will return whatever video pixel format is
  289.  * available.  The default is to emulate the requested pixel format if it
  290.  * is not natively available.
  291.  * 
  292.  * If SDL_HWSURFACE is set in 'flags', the video surface will be placed in
  293.  * video memory, if possible, and you may have to call SDL_LockSurface()
  294.  * in order to access the raw framebuffer.  Otherwise, the video surface
  295.  * will be created in system memory.
  296.  * 
  297.  * If SDL_ASYNCBLIT is set in 'flags', SDL will try to perform rectangle
  298.  * updates asynchronously, but you must always lock before accessing pixels.
  299.  * SDL will wait for updates to complete before returning from the lock.
  300.  * 
  301.  * If SDL_HWPALETTE is set in 'flags', the SDL library will guarantee
  302.  * that the colors set by SDL_SetColors() will be the colors you get.
  303.  * Otherwise, in 8-bit mode, SDL_SetColors() may not be able to set all
  304.  * of the colors exactly the way they are requested, and you should look
  305.  * at the video surface structure to determine the actual palette.
  306.  * If SDL cannot guarantee that the colors you request can be set, 
  307.  * i.e. if the colormap is shared, then the video surface may be created
  308.  * under emulation in system memory, overriding the SDL_HWSURFACE flag.
  309.  * 
  310.  * If SDL_FULLSCREEN is set in 'flags', the SDL library will try to set
  311.  * a fullscreen video mode.  The default is to create a windowed mode
  312.  * if the current graphics system has a window manager.
  313.  * If the SDL library is able to set a fullscreen video mode, this flag 
  314.  * will be set in the surface that is returned.
  315.  * 
  316.  * If SDL_DOUBLEBUF is set in 'flags', the SDL library will try to set up
  317.  * two surfaces in video memory and swap between them when you call 
  318.  * SDL_Flip().  This is usually slower than the normal single-buffering
  319.  * scheme, but prevents "tearing" artifacts caused by modifying video 
  320.  * memory while the monitor is refreshing.  It should only be used by 
  321.  * applications that redraw the entire screen on every update.
  322.  * 
  323.  * If SDL_RESIZABLE is set in 'flags', the SDL library will allow the
  324.  * window manager, if any, to resize the window at runtime.  When this
  325.  * occurs, SDL will send a SDL_VIDEORESIZE event to you application,
  326.  * and you must respond to the event by re-calling SDL_SetVideoMode()
  327.  * with the requested size (or another size that suits the application).
  328.  * 
  329.  * If SDL_NOFRAME is set in 'flags', the SDL library will create a window
  330.  * without any title bar or frame decoration.  Fullscreen video modes have
  331.  * this flag set automatically.
  332.  * 
  333.  * This function returns the video framebuffer surface, or NULL if it fails.
  334.  * 
  335.  * If you rely on functionality provided by certain video flags, check the
  336.  * flags of the returned surface to make sure that functionality is available.
  337.  * SDL will fall back to reduced functionality if the exact flags you wanted
  338.  * are not available.
  339.  */
  340. SDL_Surface *SDL_SetVideoMode
  341.             (int width, int height, int bpp, Uint32 flags);
  342.  
  343. /*
  344.  * Makes sure the given list of rectangles is updated on the given screen.
  345.  * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
  346.  * screen.
  347.  * These functions should not be called while 'screen' is locked.
  348.  */
  349. void SDL_UpdateRects
  350.         (SDL_Surface *screen, int numrects, SDL_Rect *rects);
  351. void SDL_UpdateRect
  352.         (SDL_Surface *screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
  353.  
  354. /*
  355.  * On hardware that supports double-buffering, this function sets up a flip
  356.  * and returns.  The hardware will wait for vertical retrace, and then swap
  357.  * video buffers before the next video surface blit or lock will return.
  358.  * On hardware that doesn not support double-buffering, this is equivalent
  359.  * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
  360.  * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
  361.  * setting the video mode for this function to perform hardware flipping.
  362.  * This function returns 0 if successful, or -1 if there was an error.
  363.  */
  364. int SDL_Flip(SDL_Surface *screen);
  365.  
  366. /*
  367.  * Set the gamma correction for each of the color channels.
  368.  * The gamma values range (approximately) between 0.1 and 10.0
  369.  * 
  370.  * If this function isn't supported directly by the hardware, it will
  371.  * be emulated using gamma ramps, if available.  If successful, this
  372.  * function returns 0, otherwise it returns -1.
  373.  */
  374. int SDL_SetGamma(float red, float green, float blue);
  375.  
  376. /*
  377.  * Set the gamma translation table for the red, green, and blue channels
  378.  * of the video hardware.  Each table is an array of 256 16-bit quantities,
  379.  * representing a mapping between the input and output for that channel.
  380.  * The input is the index into the array, and the output is the 16-bit
  381.  * gamma value at that index, scaled to the output color precision.
  382.  * 
  383.  * You may pass NULL for any of the channels to leave it unchanged.
  384.  * If the call succeeds, it will return 0.  If the display driver or
  385.  * hardware does not support gamma translation, or otherwise fails,
  386.  * this function will return -1.
  387.  */
  388. int SDL_SetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
  389.  
  390. /*
  391.  * Retrieve the current values of the gamma translation tables.
  392.  * 
  393.  * You must pass in valid pointers to arrays of 256 16-bit quantities.
  394.  * Any of the pointers may be NULL to ignore that channel.
  395.  * If the call succeeds, it will return 0.  If the display driver or
  396.  * hardware does not support gamma translation, or otherwise fails,
  397.  * this function will return -1.
  398.  */
  399. int SDL_GetGammaRamp(Uint16 *red, Uint16 *green, Uint16 *blue);
  400.  
  401. /*
  402.  * Sets a portion of the colormap for the given 8-bit surface.  If 'surface'
  403.  * is not a palettized surface, this function does nothing, returning 0.
  404.  * If all of the colors were set as passed to SDL_SetColors(), it will
  405.  * return 1.  If not all the color entries were set exactly as given,
  406.  * it will return 0, and you should look at the surface palette to
  407.  * determine the actual color palette.
  408.  * 
  409.  * When 'surface' is the surface associated with the current display, the
  410.  * display colormap will be updated with the requested colors.  If 
  411.  * SDL_HWPALETTE was set in SDL_SetVideoMode() flags, SDL_SetColors()
  412.  * will always return 1, and the palette is guaranteed to be set the way
  413.  * you desire, even if the window colormap has to be warped or run under
  414.  * emulation.
  415.  */
  416. int SDL_SetColors(SDL_Surface *surface, 
  417.             SDL_Color *colors, int firstcolor, int ncolors);
  418.  
  419. /*
  420.  * Sets a portion of the colormap for a given 8-bit surface.
  421.  * 'flags' is one or both of:
  422.  * SDL_LOGPAL  -- set logical palette, which controls how blits are mapped
  423.  *                to/from the surface,
  424.  * SDL_PHYSPAL -- set physical palette, which controls how pixels look on
  425.  *                the screen
  426.  * Only screens have physical palettes. Separate change of physical/logical
  427.  * palettes is only possible if the screen has SDL_HWPALETTE set.
  428.  * 
  429.  * The return value is 1 if all colours could be set as requested, and 0
  430.  * otherwise.
  431.  * 
  432.  * SDL_SetColors() is equivalent to calling this function with
  433.  *     flags = (SDL_LOGPAL|SDL_PHYSPAL).
  434.  */
  435. int SDL_SetPalette(SDL_Surface *surface, int flags,
  436.                    SDL_Color *colors, int firstcolor,
  437.                    int ncolors);
  438.  
  439. /*
  440.  * Maps an RGB triple to an opaque pixel value for a given pixel format
  441.  */
  442. Uint32 SDL_MapRGB
  443.             (SDL_PixelFormat *format, Uint8 r, Uint8 g, Uint8 b);
  444.  
  445. /*
  446.  * Maps an RGBA quadruple to a pixel value for a given pixel format
  447.  */
  448. Uint32 SDL_MapRGBA(SDL_PixelFormat *format,
  449.                    Uint8 r, Uint8 g, Uint8 b, Uint8 a);
  450.  
  451. /*
  452.  * Maps a pixel value into the RGB components for a given pixel format
  453.  */
  454. void SDL_GetRGB(Uint32 pixel, SDL_PixelFormat *fmt,
  455.                 Uint8 *r, Uint8 *g, Uint8 *b);
  456.  
  457. /*
  458.  * Maps a pixel value into the RGBA components for a given pixel format
  459.  */
  460. void SDL_GetRGBA(Uint32 pixel, SDL_PixelFormat *fmt,
  461.                  Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
  462.  
  463. /*
  464.  * Allocate and free an RGB surface (must be called after SDL_SetVideoMode)
  465.  * If the depth is 4 or 8 bits, an empty palette is allocated for the surface.
  466.  * If the depth is greater than 8 bits, the pixel format is set using the
  467.  * flags '[RGB]mask'.
  468.  * If the function runs out of memory, it will return NULL.
  469.  * 
  470.  * The 'flags' tell what kind of surface to create.
  471.  * SDL_SWSURFACE means that the surface should be created in system memory.
  472.  * SDL_HWSURFACE means that the surface should be created in video memory,
  473.  * with the same format as the display surface.  This is useful for surfaces
  474.  * that will not change much, to take advantage of hardware acceleration
  475.  * when being blitted to the display surface.
  476.  * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with
  477.  * this surface, but you must always lock it before accessing the pixels.
  478.  * SDL will wait for current blits to finish before returning from the lock.
  479.  * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
  480.  * If the hardware supports acceleration of colorkey blits between
  481.  * two surfaces in video memory, SDL will try to place the surface in
  482.  * video memory. If this isn't possible or if there is no hardware
  483.  * acceleration available, the surface will be placed in system memory.
  484.  * SDL_SRCALPHA means that the surface will be used for alpha blits and 
  485.  * if the hardware supports hardware acceleration of alpha blits between
  486.  * two surfaces in video memory, to place the surface in video memory
  487.  * if possible, otherwise it will be placed in system memory.
  488.  * If the surface is created in video memory, blits will be _much_ faster,
  489.  * but the surface format must be identical to the video surface format,
  490.  * and the only way to access the pixels member of the surface is to use
  491.  * the SDL_LockSurface() and SDL_UnlockSurface() calls.
  492.  * If the requested surface actually resides in video memory, SDL_HWSURFACE
  493.  * will be set in the flags member of the returned surface.  If for some
  494.  * reason the surface could not be placed in video memory, it will not have
  495.  * the SDL_HWSURFACE flag set, and will be created in system memory instead.
  496.  */
  497. SDL_Surface *SDL_CreateRGBSurface
  498.             (Uint32 flags, int width, int height, int depth, 
  499.             Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  500. SDL_Surface *SDL_CreateRGBSurfaceFrom(void *pixels,
  501.             int width, int height, int depth, int pitch,
  502.             Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
  503. void SDL_FreeSurface(SDL_Surface *surface);
  504.  
  505. SDL_Surface *SDL_AllocSurface
  506.             (Uint32 flags, int width, int height, int depth, 
  507.             Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask)
  508. {
  509.     return SDL_CreateRGBSurface(flags, width, height, depth,
  510.         Rmask, Gmask, Bmask, Amask);
  511. }            
  512.  
  513. /*
  514.  * SDL_LockSurface() sets up a surface for directly accessing the pixels.
  515.  * Between calls to SDL_LockSurface()/SDL_UnlockSurface(), you can write
  516.  * to and read from 'surface.pixels', using the pixel format stored in 
  517.  * 'surface.format'.  Once you are done accessing the surface, you should 
  518.  * use SDL_UnlockSurface() to release it.
  519.  * 
  520.  * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
  521.  * to 0, then you can read and write to the surface at any time, and the
  522.  * pixel format of the surface will not change.  In particular, if the
  523.  * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you
  524.  * will not need to lock the display surface before accessing it.
  525.  *  
  526.  * No operating system or library calls should be made between lock/unlock
  527.  * pairs, as critical system locks may be held during this time.
  528.  * 
  529.  * SDL_LockSurface() returns 0, or -1 if the surface couldn't be locked.
  530.  */
  531. int SDL_LockSurface(SDL_Surface *surface);
  532. void SDL_UnlockSurface(SDL_Surface *surface);
  533.  
  534. /*
  535.  * Load a surface from a seekable SDL data source (memory or file.)
  536.  * If 'freesrc' is non-zero, the source will be closed after being read.
  537.  * Returns the new surface, or NULL if there was an error.
  538.  * The new surface should be freed with SDL_FreeSurface().
  539.  */
  540. SDL_Surface * SDL_LoadBMP_RW(SDL_RWops *src, int freesrc);
  541.  
  542. /* Convenience macro -- load a surface from a file */
  543. SDL_Surface * SDL_LoadBMP(char* file)
  544. {
  545.     return SDL_LoadBMP_RW(SDL_RWFromFile(file, "rb"), 1);
  546. }
  547.  
  548. /*
  549.  * Save a surface to a seekable SDL data source (memory or file.)
  550.  * If 'freedst' is non-zero, the source will be closed after being written.
  551.  * Returns 0 if successful or -1 if there was an error.
  552.  */
  553. int SDL_SaveBMP_RW
  554.         (SDL_Surface *surface, SDL_RWops *dst, int freedst);
  555.  
  556. /* Convenience macro -- save a surface to a file */
  557. int SDL_SaveBMP(SDL_Surface *surface, char* file)
  558. {
  559.     return SDL_SaveBMP_RW(surface, SDL_RWFromFile(file, "wb"), 1);
  560. }
  561.  
  562. /*
  563.  * Sets the color key (transparent pixel) in a blittable surface.
  564.  * If 'flag' is SDL_SRCCOLORKEY (optionally OR'd with SDL_RLEACCEL), 
  565.  * 'key' will be the transparent pixel in the source image of a blit.
  566.  * SDL_RLEACCEL requests RLE acceleration for the surface if present,
  567.  * and removes RLE acceleration if absent.
  568.  * If 'flag' is 0, this function clears any current color key.
  569.  * This function returns 0, or -1 if there was an error.
  570.  */
  571. int SDL_SetColorKey
  572.             (SDL_Surface *surface, Uint32 flag, Uint32 key);
  573.  
  574. /*
  575.  * This function sets the alpha value for the entire surface, as opposed to
  576.  * using the alpha component of each pixel. This value measures the range
  577.  * of transparency of the surface, 0 being completely transparent to 255
  578.  * being completely opaque. An 'alpha' value of 255 causes blits to be
  579.  * opaque, the source pixels copied to the destination (the default). Note
  580.  * that per-surface alpha can be combined with colorkey transparency.
  581.  * 
  582.  * If 'flag' is 0, alpha blending is disabled for the surface.
  583.  * If 'flag' is SDL_SRCALPHA, alpha blending is enabled for the surface.
  584.  * OR:ing the flag with SDL_RLEACCEL requests RLE acceleration for the
  585.  * surface; if SDL_RLEACCEL is not specified, the RLE accel will be removed.
  586.  */
  587. int SDL_SetAlpha(SDL_Surface *surface, Uint32 flag, Uint8 alpha);
  588.  
  589. /*
  590.  * Sets the clipping rectangle for the destination surface in a blit.
  591.  * 
  592.  * If the clip rectangle is NULL, clipping will be disabled.
  593.  * If the clip rectangle doesn't intersect the surface, the function will
  594.  * return SDL_FALSE and blits will be completely clipped.  Otherwise the
  595.  * function returns SDL_TRUE and blits to the surface will be clipped to
  596.  * the intersection of the surface area and the clipping rectangle.
  597.  * 
  598.  * Note that blits are automatically clipped to the edges of the source
  599.  * and destination surfaces.
  600.  */
  601. SDL_bool SDL_SetClipRect(SDL_Surface *surface, SDL_Rect *rect);
  602.  
  603. /*
  604.  * Gets the clipping rectangle for the destination surface in a blit.
  605.  * 'rect' must be a pointer to a valid rectangle which will be filled
  606.  * with the correct values.
  607.  */
  608. void SDL_GetClipRect(SDL_Surface *surface, SDL_Rect *rect);
  609.  
  610. /*
  611.  * Creates a new surface of the specified format, and then copies and maps 
  612.  * the given surface to it so the blit of the converted surface will be as 
  613.  * fast as possible.  If this function fails, it returns NULL.
  614.  * 
  615.  * The 'flags' parameter is passed to SDL_CreateRGBSurface() and has those 
  616.  * semantics.  You can also pass SDL_RLEACCEL in the flags parameter and
  617.  * SDL will try to RLE accelerate colorkey and alpha blits in the resulting
  618.  * surface.
  619.  * 
  620.  * This function is used internally by SDL_DisplayFormat().
  621.  */
  622. SDL_Surface *SDL_ConvertSurface
  623.             (SDL_Surface *src, SDL_PixelFormat *fmt, Uint32 flags);
  624.  
  625. /*
  626.  * This performs a fast blit from the source surface to the destination
  627.  * surface.  It assumes that the source and destination rectangles are
  628.  * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
  629.  * surface (src or dst) is copied.  The final blit rectangles are saved
  630.  * in 'srcrect' and 'dstrect' after all clipping is performed.
  631.  * If the blit is successful, it returns 0, otherwise it returns -1.
  632.  * 
  633.  * The blit function should not be called on a locked surface.
  634.  * 
  635.  * The blit semantics for surfaces with and without alpha and colorkey
  636.  * are defined as follows:
  637.  * 
  638.  * RGBA.RGB:
  639.  *     SDL_SRCALPHA set:
  640.  *     alpha-blend (using alpha-channel).
  641.  *     SDL_SRCCOLORKEY ignored.
  642.  *     SDL_SRCALPHA not set:
  643.  *     copy RGB.
  644.  *     if SDL_SRCCOLORKEY set, only copy the pixels matching the
  645.  *     RGB values of the source colour key, ignoring alpha in the
  646.  *     comparison.
  647.  *  
  648.  * RGB.RGBA:
  649.  *     SDL_SRCALPHA set:
  650.  *     alpha-blend (using the source per-surface alpha value);
  651.  *     set destination alpha to opaque.
  652.  *     SDL_SRCALPHA not set:
  653.  *     copy RGB, set destination alpha to opaque.
  654.  *     both:
  655.  *     if SDL_SRCCOLORKEY set, only copy the pixels matching the
  656.  *     source colour key.
  657.  *  
  658.  * RGBA.RGBA:
  659.  *     SDL_SRCALPHA set:
  660.  *     alpha-blend (using the source alpha channel) the RGB values;
  661.  *     leave destination alpha untouched. [Note: is this correct?]
  662.  *     SDL_SRCCOLORKEY ignored.
  663.  *     SDL_SRCALPHA not set:
  664.  *     copy all of RGBA to the destination.
  665.  *     if SDL_SRCCOLORKEY set, only copy the pixels matching the
  666.  *     RGB values of the source colour key, ignoring alpha in the
  667.  *     comparison.
  668.  *  
  669.  * RGB.RGB: 
  670.  *     SDL_SRCALPHA set:
  671.  *     alpha-blend (using the source per-surface alpha value).
  672.  *     SDL_SRCALPHA not set:
  673.  *     copy RGB.
  674.  *     both:
  675.  *     if SDL_SRCCOLORKEY set, only copy the pixels matching the
  676.  *     source colour key.
  677.  * 
  678.  * If either of the surfaces were in video memory, and the blit returns -2,
  679.  * the video memory was lost, so it should be reloaded with artwork and 
  680.  * re-blitted:
  681.     while ( SDL_BlitSurface(image, imgrect, screen, dstrect) == -2 ) {
  682.         while ( SDL_LockSurface(image) < 0 )
  683.             Sleep(10);
  684.         -- Write image pixels to image.pixels --
  685.         SDL_UnlockSurface(image);
  686.     }
  687.  * This happens under DirectX 5.0 when the system switches away from your
  688.  * fullscreen application.  The lock will also fail until you have access
  689.  * to the video memory again.
  690.  */
  691. /* You should call SDL_BlitSurface() unless you know exactly how SDL
  692.    blitting works internally and how to use the other blit functions.
  693. */
  694.  
  695. /* This is the public blit function, SDL_BlitSurface(), and it performs
  696.    rectangle validation and clipping before passing it to SDL_LowerBlit()
  697. */
  698. int SDL_UpperBlit
  699.             (SDL_Surface *src, SDL_Rect *srcrect,
  700.              SDL_Surface *dst, SDL_Rect *dstrect);
  701. /* This is a semi-private blit function and it performs low-level surface
  702.    blitting only.
  703. */
  704. int SDL_LowerBlit
  705.             (SDL_Surface *src, SDL_Rect *srcrect,
  706.              SDL_Surface *dst, SDL_Rect *dstrect);
  707.  
  708. int SDL_BlitSurface
  709.             (SDL_Surface *src, SDL_Rect *srcrect,
  710.              SDL_Surface *dst, SDL_Rect *dstrect)
  711. {
  712.     return SDL_UpperBlit(src, srcrect, dst, dstrect);
  713. }
  714.              
  715. /*
  716.  * This function performs a fast fill of the given rectangle with 'color'
  717.  * The given rectangle is clipped to the destination surface clip area
  718.  * and the final fill rectangle is saved in the passed in pointer.
  719.  * If 'dstrect' is NULL, the whole surface will be filled with 'color'
  720.  * The color should be a pixel of the format used by the surface, and 
  721.  * can be generated by the SDL_MapRGB() function.
  722.  * This function returns 0 on success, or -1 on error.
  723.  */
  724. int SDL_FillRect
  725.         (SDL_Surface *dst, SDL_Rect *dstrect, Uint32 color);
  726.  
  727. /* 
  728.  * This function takes a surface and copies it to a new surface of the
  729.  * pixel format and colors of the video framebuffer, suitable for fast
  730.  * blitting onto the display surface.  It calls SDL_ConvertSurface()
  731.  * 
  732.  * If you want to take advantage of hardware colorkey or alpha blit
  733.  * acceleration, you should set the colorkey and alpha value before
  734.  * calling this function.
  735.  * 
  736.  * If the conversion fails or runs out of memory, it returns NULL
  737.  */
  738. SDL_Surface * SDL_DisplayFormat(SDL_Surface *surface);
  739.  
  740. /* 
  741.  * This function takes a surface and copies it to a new surface of the
  742.  * pixel format and colors of the video framebuffer (if possible),
  743.  * suitable for fast alpha blitting onto the display surface.
  744.  * The new surface will always have an alpha channel.
  745.  * 
  746.  * If you want to take advantage of hardware colorkey or alpha blit
  747.  * acceleration, you should set the colorkey and alpha value before
  748.  * calling this function.
  749.  * 
  750.  * If the conversion fails or runs out of memory, it returns NULL
  751.  */
  752. SDL_Surface * SDL_DisplayFormatAlpha(SDL_Surface *surface);
  753.  
  754.  
  755. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  756. /* YUV video surface overlay functions                                       */
  757. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  758.  
  759. /* This function creates a video output overlay
  760.    Calling the returned surface an overlay is something of a misnomer because
  761.    the contents of the display surface underneath the area where the overlay
  762.    is shown is undefined - it may be overwritten with the converted YUV data.
  763. */
  764. SDL_Overlay *SDL_CreateYUVOverlay(int width, int height,
  765.                 Uint32 format, SDL_Surface *display);
  766.  
  767. /* Lock an overlay for direct access, and unlock it when you are done */
  768. int SDL_LockYUVOverlay(SDL_Overlay *overlay);
  769. void SDL_UnlockYUVOverlay(SDL_Overlay *overlay);
  770.  
  771. /* Blit a video overlay to the display surface.
  772.    The contents of the video surface underneath the blit destination are
  773.    not defined.  
  774.    The width and height of the destination rectangle may be different from
  775.    that of the overlay, but currently only 2x scaling is supported.
  776. */
  777. int SDL_DisplayYUVOverlay(SDL_Overlay *overlay, SDL_Rect *dstrect);
  778.  
  779. /* Free a video overlay */
  780. void SDL_FreeYUVOverlay(SDL_Overlay *overlay);
  781.  
  782.  
  783. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  784. /* OpenGL support functions.                                                 */
  785. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  786.  
  787. /*
  788.  * Dynamically load a GL driver, if SDL is built with dynamic GL.
  789.  * 
  790.  * SDL links normally with the OpenGL library on your system by default,
  791.  * but you can compile it to dynamically load the GL driver at runtime.
  792.  * If you do this, you need to retrieve all of the GL functions used in
  793.  * your program from the dynamic library using SDL_GL_GetProcAddress().
  794.  * 
  795.  * This is disabled in default builds of SDL.
  796.  */
  797. int SDL_GL_LoadLibrary(char *path);
  798.  
  799. /*
  800.  * Get the address of a GL function (for extension functions)
  801.  */
  802. void *SDL_GL_GetProcAddress(char* proc);
  803.  
  804. /*
  805.  * Set an attribute of the OpenGL subsystem before intialization.
  806.  */
  807. int SDL_GL_SetAttribute(SDL_GLattr attr, int value);
  808.  
  809. /*
  810.  * Get an attribute of the OpenGL subsystem from the windowing
  811.  * interface, such as glX. This is of course different from getting
  812.  * the values from SDL's internal OpenGL subsystem, which only
  813.  * stores the values you request before initialization.
  814.  * 
  815.  * Developers should track the values they pass into SDL_GL_SetAttribute
  816.  * themselves if they want to retrieve these values.
  817.  */
  818. int SDL_GL_GetAttribute(SDL_GLattr attr, int* value);
  819.  
  820. /*
  821.  * Swap the OpenGL buffers, if double-buffering is supported.
  822.  */
  823. void SDL_GL_SwapBuffers();
  824.  
  825. /*
  826.  * Internal functions that should not be called unless you have read
  827.  * and understood the source code for these functions.
  828.  */
  829. void SDL_GL_UpdateRects(int numrects, SDL_Rect* rects);
  830. void SDL_GL_Lock();
  831. void SDL_GL_Unlock();
  832.  
  833. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  834. /* These functions allow interaction with the window manager, if any.        */
  835. /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
  836.  
  837. /*
  838.  * Sets/Gets the title and icon text of the display window
  839.  */
  840. void SDL_WM_SetCaption(char *title, char *icon);
  841. void SDL_WM_GetCaption(char **title, char **icon);
  842.  
  843. /*
  844.  * Sets the icon for the display window.
  845.  * This function must be called before the first call to SDL_SetVideoMode().
  846.  * It takes an icon surface, and a mask in MSB format.
  847.  * If 'mask' is NULL, the entire icon surface will be used as the icon.
  848.  */
  849. void SDL_WM_SetIcon(SDL_Surface *icon, Uint8 *mask);
  850.  
  851. /*
  852.  * This function iconifies the window, and returns 1 if it succeeded.
  853.  * If the function succeeds, it generates an SDL_APPACTIVE loss event.
  854.  * This function is a noop and returns 0 in non-windowed environments.
  855.  */
  856. int SDL_WM_IconifyWindow();
  857.  
  858. /*
  859.  * Toggle fullscreen mode without changing the contents of the screen.
  860.  * If the display surface does not require locking before accessing
  861.  * the pixel information, then the memory pointers will not change.
  862.  * 
  863.  * If this function was able to toggle fullscreen mode (change from 
  864.  * running in a window to fullscreen, or vice-versa), it will return 1.
  865.  * If it is not implemented, or fails, it returns 0.
  866.  * 
  867.  * The next call to SDL_SetVideoMode() will set the mode fullscreen
  868.  * attribute based on the flags parameter - if SDL_FULLSCREEN is not
  869.  * set, then the display will be windowed by default where supported.
  870.  * 
  871.  * This is currently only implemented in the X11 video driver.
  872.  */
  873. int SDL_WM_ToggleFullScreen(SDL_Surface *surface);
  874.  
  875. /*
  876.  * This function allows you to set and query the input grab state of
  877.  * the application.  It returns the new input grab state.
  878.  */
  879. alias int SDL_GrabMode;
  880. enum {
  881.     SDL_GRAB_QUERY = -1,
  882.     SDL_GRAB_OFF = 0,
  883.     SDL_GRAB_ON = 1,
  884.     SDL_GRAB_FULLSCREEN    /* Used internally */
  885. }
  886. /*
  887.  * Grabbing means that the mouse is confined to the application window,
  888.  * and nearly all keyboard input is passed directly to the application,
  889.  * and not interpreted by a window manager, if any.
  890.  */
  891. SDL_GrabMode SDL_WM_GrabInput(SDL_GrabMode mode);
  892.  
  893. /* Not in public API at the moment - do not use! */
  894. int SDL_SoftStretch(SDL_Surface *src, SDL_Rect *srcrect,
  895.                                     SDL_Surface *dst, SDL_Rect *dstrect);
  896.