include/SDL_video.h
branchSDL-1.3
changeset 1670 eef792d31de8
parent 1669 9857d21967bb
child 1675 d33dcfc3fde7
     1.1 --- a/include/SDL_video.h	Mon May 29 05:08:33 2006 +0000
     1.2 +++ b/include/SDL_video.h	Wed Jun 07 16:10:28 2006 +0000
     1.3 @@ -46,111 +46,17 @@
     1.4  #define SDL_ALPHA_OPAQUE 255
     1.5  #define SDL_ALPHA_TRANSPARENT 0
     1.6  
     1.7 -/* Useful data types */
     1.8 +/**
     1.9 + * \struct SDL_Rect
    1.10 + *
    1.11 + * \brief A rectangle, with the origin at the upper left.
    1.12 + */
    1.13  typedef struct SDL_Rect
    1.14  {
    1.15      Sint16 x, y;
    1.16      Uint16 w, h;
    1.17  } SDL_Rect;
    1.18  
    1.19 -/* This structure should be treated as read-only, except for 'pixels',
    1.20 -   which, if not NULL, contains the raw pixel data for the surface.
    1.21 -*/
    1.22 -typedef struct SDL_Surface
    1.23 -{
    1.24 -    Uint32 flags;               /* Read-only */
    1.25 -    SDL_PixelFormat *format;    /* Read-only */
    1.26 -    int w, h;                   /* Read-only */
    1.27 -    Uint16 pitch;               /* Read-only */
    1.28 -    void *pixels;               /* Read-write */
    1.29 -    int offset;                 /* Private */
    1.30 -
    1.31 -    /* Hardware-specific surface info */
    1.32 -    struct private_hwdata *hwdata;
    1.33 -
    1.34 -    /* clipping information */
    1.35 -    SDL_Rect clip_rect;         /* Read-only */
    1.36 -    Uint32 unused1;             /* for binary compatibility */
    1.37 -
    1.38 -    /* Allow recursive locks */
    1.39 -    Uint32 locked;              /* Private */
    1.40 -
    1.41 -    /* info for fast blit mapping to other surfaces */
    1.42 -    struct SDL_BlitMap *map;    /* Private */
    1.43 -
    1.44 -    /* format version, bumped at every change to invalidate blit maps */
    1.45 -    unsigned int format_version;        /* Private */
    1.46 -
    1.47 -    /* Reference count -- used when freeing surface */
    1.48 -    int refcount;               /* Read-mostly */
    1.49 -} SDL_Surface;
    1.50 -
    1.51 -/* The most common video overlay formats.
    1.52 -   For an explanation of these pixel formats, see:
    1.53 -	http://www.webartz.com/fourcc/indexyuv.htm
    1.54 -
    1.55 -   For information on the relationship between color spaces, see:
    1.56 -   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
    1.57 - */
    1.58 -#define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
    1.59 -#define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
    1.60 -#define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
    1.61 -#define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
    1.62 -#define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
    1.63 -
    1.64 -/* The YUV hardware video overlay */
    1.65 -typedef struct SDL_Overlay
    1.66 -{
    1.67 -    Uint32 format;              /* Read-only */
    1.68 -    int w, h;                   /* Read-only */
    1.69 -    int planes;                 /* Read-only */
    1.70 -    Uint16 *pitches;            /* Read-only */
    1.71 -    Uint8 **pixels;             /* Read-write */
    1.72 -
    1.73 -    /* Hardware-specific surface info */
    1.74 -    struct private_yuvhwfuncs *hwfuncs;
    1.75 -    struct private_yuvhwdata *hwdata;
    1.76 -
    1.77 -    /* Special flags */
    1.78 -    Uint32 hw_overlay:1;        /* Flag: This overlay hardware accelerated? */
    1.79 -    Uint32 UnusedBits:31;
    1.80 -} SDL_Overlay;
    1.81 -
    1.82 -/* Evaluates to true if the surface needs to be locked before access */
    1.83 -#define SDL_MUSTLOCK(surface)	\
    1.84 -  (surface->offset ||		\
    1.85 -  ((surface->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0))
    1.86 -
    1.87 -/* typedef for private surface blitting functions */
    1.88 -typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
    1.89 -                         struct SDL_Surface * dst, SDL_Rect * dstrect);
    1.90 -
    1.91 -
    1.92 -/**
    1.93 - * \struct SDL_VideoInfo
    1.94 - *
    1.95 - * \brief Useful for determining the video hardware capabilities
    1.96 - */
    1.97 -typedef struct SDL_VideoInfo
    1.98 -{
    1.99 -    Uint32 hw_available:1;  /**< Flag: Can you create hardware surfaces? */
   1.100 -    Uint32 wm_available:1;  /**< Flag: Can you talk to a window manager? */
   1.101 -    Uint32 UnusedBits1:6;
   1.102 -    Uint32 UnusedBits2:1;
   1.103 -    Uint32 blit_hw:1;       /**< Flag: Accelerated blits HW --> HW */
   1.104 -    Uint32 blit_hw_CC:1;    /**< Flag: Accelerated blits with Colorkey */
   1.105 -    Uint32 blit_hw_A:1;     /**< Flag: Accelerated blits with Alpha */
   1.106 -    Uint32 blit_sw:1;       /**< Flag: Accelerated blits SW --> HW */
   1.107 -    Uint32 blit_sw_CC:1;    /**< Flag: Accelerated blits with Colorkey */
   1.108 -    Uint32 blit_sw_A:1;     /**< Flag: Accelerated blits with Alpha */
   1.109 -    Uint32 blit_fill:1;     /**< Flag: Accelerated color fill */
   1.110 -    Uint32 UnusedBits3:16;
   1.111 -    Uint32 video_mem;           /* The total amount of video memory (in K) */
   1.112 -
   1.113 -    /* Here for backwards compatibility */
   1.114 -    SDL_PixelFormat *vfmt;
   1.115 -} SDL_VideoInfo;
   1.116 -
   1.117  /**
   1.118   * \struct SDL_DisplayMode
   1.119   *
   1.120 @@ -204,6 +110,8 @@
   1.121   * \enum SDL_WindowFlags
   1.122   *
   1.123   * \brief The flags on a window
   1.124 + *
   1.125 + * \sa SDL_GetWindowFlags()
   1.126   */
   1.127  typedef enum
   1.128  {
   1.129 @@ -241,6 +149,163 @@
   1.130  } SDL_WindowEventID;
   1.131  
   1.132  /**
   1.133 + * \enum SDL_RendererFlags
   1.134 + *
   1.135 + * \brief Flags used when initializing a render manager.
   1.136 + */
   1.137 +typedef enum
   1.138 +{
   1.139 +    SDL_Renderer_PresentDiscard = 0x00000001,   /**< Present leaves the contents of the backbuffer undefined */
   1.140 +    SDL_Renderer_PresentCopy = 0x00000002,      /**< Present uses a copy from back buffer to the front buffer */
   1.141 +    SDL_Renderer_PresentFlip2 = 0x00000004,     /**< Present uses a flip, swapping back buffer and front buffer */
   1.142 +    SDL_Renderer_PresentFlip3 = 0x00000008,     /**< Present uses a flip, rotating between two back buffers and a front buffer */
   1.143 +    SDL_Renderer_PresentVSync = 0x00000010,     /**< Present is synchronized with the refresh rate */
   1.144 +    SDL_Renderer_RenderTarget = 0x00000020,     /**< The renderer can create texture render targets */
   1.145 +    SDL_Renderer_Accelerated = 0x00000040,      /**< The renderer uses hardware acceleration */
   1.146 +    SDL_Renderer_Minimal = 0x00000080,          /**< The renderer only supports the read/write pixel and present functions */
   1.147 +} SDL_RendererFlags;
   1.148 +
   1.149 +/**
   1.150 + * \struct SDL_RendererInfo
   1.151 + *
   1.152 + * \brief Information on the capabilities of a render manager.
   1.153 + */
   1.154 +typedef struct SDL_RendererInfo
   1.155 +{
   1.156 +    const char *name;           /**< The name of the renderer */
   1.157 +    Uint32 flags;               /**< Supported SDL_RendererFlags */
   1.158 +    Uint32 blend_modes;         /**< A mask of supported blend modes */
   1.159 +    Uint32 scale_modes;         /**< A mask of supported scale modes */
   1.160 +    Uint32 num_texture_formats; /**< The number of available texture formats */
   1.161 +    Uint32 texture_formats[32]; /**< The available texture formats */
   1.162 +    int max_texture_width;      /**< The maximimum texture width */
   1.163 +    int max_texture_height;     /**< The maximimum texture height */
   1.164 +} SDL_RendererInfo;
   1.165 +
   1.166 +/**
   1.167 + * \enum SDL_TextureAccess
   1.168 + *
   1.169 + * \brief The access pattern allowed for a texture
   1.170 + */
   1.171 +typedef enum
   1.172 +{
   1.173 +    SDL_TextureAccess_Render,   /**< Unlockable video memory, rendering allowed */
   1.174 +    SDL_TextureAccess_Remote,   /**< Unlockable video memory */
   1.175 +    SDL_TextureAccess_Local,    /**< Lockable system memory */
   1.176 +} SDL_TextureAccess;
   1.177 +
   1.178 +/**
   1.179 + * \enum SDL_TextureBlendMode
   1.180 + *
   1.181 + * \brief The blend mode used in SDL_RenderCopy()
   1.182 + */
   1.183 +typedef enum
   1.184 +{
   1.185 +    SDL_TextureBlendMode_None,  /**< No blending */
   1.186 +    SDL_TextureBlendMode_Mask,  /**< dst = A ? src : dst (alpha is mask) */
   1.187 +    SDL_TextureBlendMode_Blend, /**< dst = (src * A) + (dst * (1-A)) */
   1.188 +    SDL_TextureBlendMode_Add,   /**< dst = (src * A) + dst */
   1.189 +    SDL_TextureBlendMode_Mod,   /**< dst = src * dst */
   1.190 +} SDL_TextureBlendMode;
   1.191 +
   1.192 +/**
   1.193 + * \enum SDL_TextureScaleMode
   1.194 + *
   1.195 + * \brief The scale mode used in SDL_RenderCopy()
   1.196 + */
   1.197 +typedef enum
   1.198 +{
   1.199 +    SDL_TextureScaleMode_None,  /**< No scaling, rectangles must match dimensions */
   1.200 +    SDL_TextureScaleMode_Fast,  /**< Point sampling or equivalent algorithm */
   1.201 +    SDL_TextureScaleMode_Slow,  /**< Linear filtering or equivalent algorithm */
   1.202 +    SDL_TextureScaleMode_Best,  /**< Bicubic filtering or equivalent algorithm */
   1.203 +} SDL_TextureScaleMode;
   1.204 +
   1.205 +/**
   1.206 + * \typedef SDL_TextureID
   1.207 + *
   1.208 + * \brief An efficient driver-specific representation of pixel data
   1.209 + */
   1.210 +typedef Uint32 SDL_TextureID;
   1.211 +
   1.212 +
   1.213 +/* These are the currently supported flags for the SDL_surface */
   1.214 +/* Used internally (read-only) */
   1.215 +#define SDL_HWSURFACE       0x00000001  /* Surface represents a texture */
   1.216 +#define SDL_PREALLOC        0x00000002  /* Surface uses preallocated memory */
   1.217 +#define SDL_SRCALPHA        0x00000004  /* Blit uses source alpha blending */
   1.218 +#define SDL_SRCCOLORKEY     0x00000008  /* Blit uses a source color key */
   1.219 +#define SDL_RLEACCELOK      0x00000010  /* Private flag */
   1.220 +#define SDL_RLEACCEL        0x00000020  /* Surface is RLE encoded */
   1.221 +
   1.222 +/* Evaluates to true if the surface needs to be locked before access */
   1.223 +#define SDL_MUSTLOCK(S)	(((S)->flags & (SDL_HWSURFACE|SDL_RLEACCEL)) != 0)
   1.224 +
   1.225 +/* This structure should be treated as read-only, except for 'pixels',
   1.226 +   which, if not NULL, contains the raw pixel data for the surface.
   1.227 +*/
   1.228 +typedef struct SDL_Surface
   1.229 +{
   1.230 +    Uint32 flags;               /* Read-only */
   1.231 +    SDL_PixelFormat *format;    /* Read-only */
   1.232 +    int w, h;                   /* Read-only */
   1.233 +    int pitch;                  /* Read-only */
   1.234 +    void *pixels;               /* Read-write */
   1.235 +
   1.236 +    /* information needed for surfaces requiring locks */
   1.237 +    int locked;
   1.238 +    void *lock_data;
   1.239 +
   1.240 +    /* clipping information */
   1.241 +    SDL_Rect clip_rect;         /* Read-only */
   1.242 +
   1.243 +    /* info for fast blit mapping to other surfaces */
   1.244 +    struct SDL_BlitMap *map;    /* Private */
   1.245 +
   1.246 +    /* format version, bumped at every change to invalidate blit maps */
   1.247 +    unsigned int format_version;        /* Private */
   1.248 +
   1.249 +    /* Reference count -- used when freeing surface */
   1.250 +    int refcount;               /* Read-mostly */
   1.251 +} SDL_Surface;
   1.252 +
   1.253 +/* typedef for private surface blitting functions */
   1.254 +typedef int (*SDL_blit) (struct SDL_Surface * src, SDL_Rect * srcrect,
   1.255 +                         struct SDL_Surface * dst, SDL_Rect * dstrect);
   1.256 +
   1.257 +
   1.258 +/* The most common video overlay formats.
   1.259 +   For an explanation of these pixel formats, see:
   1.260 +   http://www.webartz.com/fourcc/indexyuv.htm
   1.261 +
   1.262 +   For information on the relationship between color spaces, see:
   1.263 +   http://www.neuro.sfc.keio.ac.jp/~aly/polygon/info/color-space-faq.html
   1.264 + */
   1.265 +#define SDL_YV12_OVERLAY  0x32315659    /* Planar mode: Y + V + U  (3 planes) */
   1.266 +#define SDL_IYUV_OVERLAY  0x56555949    /* Planar mode: Y + U + V  (3 planes) */
   1.267 +#define SDL_YUY2_OVERLAY  0x32595559    /* Packed mode: Y0+U0+Y1+V0 (1 plane) */
   1.268 +#define SDL_UYVY_OVERLAY  0x59565955    /* Packed mode: U0+Y0+V0+Y1 (1 plane) */
   1.269 +#define SDL_YVYU_OVERLAY  0x55595659    /* Packed mode: Y0+V0+Y1+U0 (1 plane) */
   1.270 +
   1.271 +/* The YUV hardware video overlay */
   1.272 +typedef struct SDL_Overlay
   1.273 +{
   1.274 +    Uint32 format;              /* Read-only */
   1.275 +    int w, h;                   /* Read-only */
   1.276 +    int planes;                 /* Read-only */
   1.277 +    Uint16 *pitches;            /* Read-only */
   1.278 +    Uint8 **pixels;             /* Read-write */
   1.279 +
   1.280 +    /* Hardware-specific surface info */
   1.281 +    struct private_yuvhwfuncs *hwfuncs;
   1.282 +    struct private_yuvhwdata *hwdata;
   1.283 +
   1.284 +    /* Special flags */
   1.285 +    Uint32 hw_overlay:1;        /* Flag: This overlay hardware accelerated? */
   1.286 +    Uint32 UnusedBits:31;
   1.287 +} SDL_Overlay;
   1.288 +
   1.289 +/**
   1.290   * \enum SDL_GLattr
   1.291   *
   1.292   * \brief OpenGL configuration attributes
   1.293 @@ -266,22 +331,6 @@
   1.294      SDL_GL_SWAP_CONTROL
   1.295  } SDL_GLattr;
   1.296  
   1.297 -/* These are the currently supported flags for the SDL_surface */
   1.298 -#define SDL_SWSURFACE	0x00000000      /* Surface is in system memory */
   1.299 -#define SDL_HWSURFACE	0x00000001      /* Surface is in video memory */
   1.300 -/* Available for SDL_CreateWindowSurface() */
   1.301 -#define SDL_ANYFORMAT	0x10000000      /* Allow any video depth/pixel-format */
   1.302 -#define SDL_HWPALETTE	0x20000000      /* Surface has exclusive palette */
   1.303 -#define SDL_DOUBLEBUF	0x40000000      /* Set up double-buffered surface */
   1.304 -/* Used internally (read-only) */
   1.305 -#define SDL_HWACCEL	0x00000100      /* Blit uses hardware acceleration */
   1.306 -#define SDL_SRCCOLORKEY	0x00001000      /* Blit uses a source color key */
   1.307 -#define SDL_RLEACCELOK	0x00002000      /* Private flag */
   1.308 -#define SDL_RLEACCEL	0x00004000      /* Surface is RLE encoded */
   1.309 -#define SDL_SRCALPHA	0x00010000      /* Blit uses source alpha blending */
   1.310 -#define SDL_PREALLOC	0x00100000      /* Surface uses preallocated memory */
   1.311 -#define SDL_SCREEN_SURFACE 0x01000000   /* Surface is a window screen surface */
   1.312 -#define SDL_SHADOW_SURFACE 0x02000000   /* Surface is a window shadow surface */
   1.313  
   1.314  /* Function prototypes */
   1.315  
   1.316 @@ -350,16 +399,6 @@
   1.317  extern DECLSPEC const char *SDLCALL SDL_GetCurrentVideoDriver(void);
   1.318  
   1.319  /**
   1.320 - * \fn const SDL_VideoInfo *SDL_GetVideoInfo(void)
   1.321 - *
   1.322 - * \brief Returns information about the currently initialized video driver.
   1.323 - *
   1.324 - * \return A read-only pointer to information about the video hardware,
   1.325 - *         or NULL if no video driver has been initialized.
   1.326 - */
   1.327 -extern DECLSPEC const SDL_VideoInfo *SDLCALL SDL_GetVideoInfo(void);
   1.328 -
   1.329 -/**
   1.330   * \fn int SDL_GetNumVideoDisplays(void)
   1.331   *
   1.332   * \brief Returns the number of available video displays.
   1.333 @@ -373,6 +412,8 @@
   1.334   *
   1.335   * \brief Set the index of the currently selected display.
   1.336   *
   1.337 + * \return The index of the currently selected display.
   1.338 + *
   1.339   * \note You can query the currently selected display by passing an index of -1.
   1.340   *
   1.341   * \sa SDL_GetNumVideoDisplays()
   1.342 @@ -452,6 +493,16 @@
   1.343  extern DECLSPEC int SDLCALL SDL_SetDisplayMode(const SDL_DisplayMode * mode);
   1.344  
   1.345  /**
   1.346 + * \fn int SDL_SetDisplayColormap(SDL_Color *colors, int firstcolor, int ncolors)
   1.347 + *
   1.348 + * \brief Set the colormap for indexed display modes.
   1.349 + *
   1.350 + * \return 0 on success, or -1 if not all the colors could be set.
   1.351 + */
   1.352 +extern DECLSPEC int SDLCALL SDL_SetDisplayColors(SDL_Color * colors,
   1.353 +                                                 int firstcolor, int ncolors);
   1.354 +
   1.355 +/**
   1.356   * \fn SDL_WindowID SDL_CreateWindow(const char *title, int x, int y, int w, int h, Uint32 flags)
   1.357   *
   1.358   * \brief Create a window with the specified position, dimensions, and flags.
   1.359 @@ -673,37 +724,294 @@
   1.360  extern DECLSPEC void SDLCALL SDL_DestroyWindow(SDL_WindowID windowID);
   1.361  
   1.362  /**
   1.363 - * \fn SDL_Surface *SDL_CreateWindowSurface (SDL_WindowID windowID, Uint32 format, Uint32 flags)
   1.364 + * \fn int SDL_GetNumRenderers(void)
   1.365 + *
   1.366 + * \brief Get the number of render managers on the current display.
   1.367 + *
   1.368 + * A render manager is a set of code that handles rendering and texture
   1.369 + * management on a particular display.  Normally there is only one, but
   1.370 + * some drivers may have several available with different capabilities.
   1.371 + *
   1.372 + * \sa SDL_GetRendererInfo()
   1.373 + * \sa SDL_CreateRenderer()
   1.374 + */
   1.375 +extern DECLSPEC int SDLCALL SDL_GetNumRenderers(void);
   1.376 +
   1.377 +/**
   1.378 + * \fn SDL_RendererInfo *SDL_GetRendererInfo(int index)
   1.379 + *
   1.380 + * \brief Get information about a specific render manager on the current
   1.381 + *        display.
   1.382 + *
   1.383 + * \sa SDL_CreateRenderer()
   1.384 + */
   1.385 +extern DECLSPEC int SDLCALL SDL_GetRendererInfo(int index,
   1.386 +                                                SDL_RendererInfo * info);
   1.387 +
   1.388 +/**
   1.389 + * \fn int SDL_CreateRenderer(SDL_WindowID window, int index, Uint32 flags)
   1.390 + *
   1.391 + * \brief Create and make active a 2D rendering context for a window.
   1.392 + *
   1.393 + * \param windowID The window used for rendering.
   1.394 + * \param index The index of the render manager to initialize, or -1 to initialize the first one supporting the requested flags.
   1.395 + * \param flags SDL_RendererFlags
   1.396   *
   1.397 - * \brief Create an SDL_Surface representing the drawing area of the window.
   1.398 + * \return 0 on success, -1 if the flags were not supported, or -2 if
   1.399 + *         there isn't enough memory to support the requested flags
   1.400 + *
   1.401 + * \sa SDL_SelectRenderer()
   1.402 + * \sa SDL_DestroyRenderer()
   1.403 + */
   1.404 +extern DECLSPEC int SDLCALL SDL_CreateRenderer(SDL_WindowID windowID,
   1.405 +                                               int index, Uint32 flags);
   1.406 +
   1.407 +/**
   1.408 + * \fn int SDL_SelectRenderer(SDL_WindowID windowID)
   1.409 + *
   1.410 + * \brief Select the rendering context for a particular window.
   1.411 + *
   1.412 + * \return 0 on success, -1 if the selected window doesn't have a
   1.413 + *         rendering context.
   1.414 + */
   1.415 +extern DECLSPEC int SDLCALL SDL_SelectRenderer(SDL_WindowID windowID);
   1.416 +
   1.417 +/**
   1.418 + * \fn SDL_TextureID SDL_CreateTexture(Uint32 format, int access, int w, int h)
   1.419 + *
   1.420 + * \brief Create a texture
   1.421 + *
   1.422 + * \param format The format of the texture
   1.423 + * \param access One of the enumerated values in SDL_TextureAccess
   1.424 + * \param w The width of the texture in pixels
   1.425 + * \param h The height of the texture in pixels
   1.426 + *
   1.427 + * \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.
   1.428 + *
   1.429 + * \sa SDL_QueryTexture()
   1.430 + * \sa SDL_DestroyTexture()
   1.431   */
   1.432 -extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateWindowSurface(SDL_WindowID
   1.433 -                                                             windowID,
   1.434 -                                                             Uint32 format,
   1.435 -                                                             Uint32 flags);
   1.436 +extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTexture(Uint32 format,
   1.437 +                                                        int access, int w,
   1.438 +                                                        int h);
   1.439 +
   1.440 +/**
   1.441 + * \fn SDL_TextureID SDL_CreateTextureFromSurface(Uint32 format, int access, SDL_Surface *surface)
   1.442 + *
   1.443 + * \brief Create a texture from an existing surface
   1.444 + *
   1.445 + * \param format The format of the texture, or 0 to pick an appropriate format
   1.446 + * \param access One of the enumerated values in SDL_TextureAccess
   1.447 + * \param surface The surface containing pixel data used to fill the texture
   1.448 + *
   1.449 + * \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.
   1.450 + *
   1.451 + * \note The surface is not modified or freed by this function.
   1.452 + *
   1.453 + * \sa SDL_QueryTexture()
   1.454 + * \sa SDL_DestroyTexture()
   1.455 + */
   1.456 +extern DECLSPEC SDL_TextureID SDLCALL SDL_CreateTextureFromSurface(Uint32
   1.457 +                                                                   format,
   1.458 +                                                                   int access,
   1.459 +                                                                   SDL_Surface
   1.460 +                                                                   * surface);
   1.461  
   1.462 -/*
   1.463 - * Makes sure the given list of rectangles is updated on the given screen.
   1.464 - * If 'x', 'y', 'w' and 'h' are all 0, SDL_UpdateRect will update the entire
   1.465 - * screen.
   1.466 - * These functions should not be called while 'screen' is locked.
   1.467 +/**
   1.468 + * \fn int SDL_QueryTexture(SDL_TextureID textureID, Uint32 *format, int *access, int *w, int *h)
   1.469 + *
   1.470 + * \brief Query the attributes of a texture
   1.471 + *
   1.472 + * \param texture A texture to be queried
   1.473 + * \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.
   1.474 + * \param access A pointer filled in with the actual access to the texture.
   1.475 + * \param w A pointer filled in with the width of the texture in pixels
   1.476 + * \param h A pointer filled in with the height of the texture in pixels
   1.477 + *
   1.478 + * \return 0 on success, or -1 if the texture is not valid
   1.479 + */
   1.480 +extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_TextureID textureID,
   1.481 +                                             Uint32 * format, int *access,
   1.482 +                                             int *w, int *h);
   1.483 +
   1.484 +/**
   1.485 + * \fn int SDL_SetTexturePalette(SDL_TextureID textureID, SDL_Color * colors, int firstcolor, int ncolors)
   1.486 + *
   1.487 + * \brief Update an indexed texture with a color palette
   1.488 + *
   1.489 + * \param texture The texture to update
   1.490 + * \param colors The array of RGB color data
   1.491 + * \param firstcolor The first index to update
   1.492 + * \param ncolors The number of palette entries to fill with the color data
   1.493 + *
   1.494 + * \return 0 on success, or -1 if the texture is not valid or not an indexed texture
   1.495 + */
   1.496 +extern DECLSPEC int SDLCALL SDL_SetTexturePalette(SDL_TextureID textureID,
   1.497 +                                                  SDL_Color * colors,
   1.498 +                                                  int firstcolor,
   1.499 +                                                  int ncolors);
   1.500 +
   1.501 +/**
   1.502 + * \fn int SDL_UpdateTexture(SDL_TextureID textureID, SDL_Rect *rect, const void *pixels, int pitch)
   1.503 + *
   1.504 + * \brief Update the given texture rectangle with new pixel data.
   1.505 + *
   1.506 + * \param texture The texture to update
   1.507 + * \param rect A pointer to the rectangle of pixels to update, or NULL to update the entire texture.
   1.508 + * \param pixels The raw pixel data
   1.509 + * \param pitch The number of bytes between rows of pixel data
   1.510 + *
   1.511 + * \return 0 on success, or -1 if the texture is not valid
   1.512 + *
   1.513 + * \note This is a very slow function for textures not created with SDL_TextureAccess_Local.
   1.514   */
   1.515 -extern DECLSPEC void SDLCALL SDL_UpdateRects
   1.516 -    (SDL_Surface * screen, int numrects, SDL_Rect * rects);
   1.517 -extern DECLSPEC void SDLCALL SDL_UpdateRect
   1.518 -    (SDL_Surface * screen, Sint32 x, Sint32 y, Uint32 w, Uint32 h);
   1.519 +extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_TextureID textureID,
   1.520 +                                              SDL_Rect * rect,
   1.521 +                                              const void *pixels, int pitch);
   1.522 +
   1.523 +/**
   1.524 + * \fn void SDL_LockTexture(SDL_TextureID textureID, SDL_Rect *rect, int markDirty, void **pixels, int *pitch)
   1.525 + *
   1.526 + * \brief Lock a portion of the texture for pixel access.
   1.527 + *
   1.528 + * \param texture The texture to lock for access, which must have been created with SDL_TextureAccess_Local.
   1.529 + * \param rect A pointer to the rectangle to lock for access. If the rect is NULL, the entire texture will be locked.
   1.530 + * \param markDirty If this is nonzero, the locked area will be marked dirty when the texture is unlocked.
   1.531 + * \param pixels This is filled in with a pointer to the locked pixels, appropriately offset by the locked area.
   1.532 + * \param pitch This is filled in with the pitch of the locked pixels.
   1.533 + *
   1.534 + * \return 0 on success, or -1 if the texture is not valid or was created with SDL_TextureAccess_Remote
   1.535 + *
   1.536 + * \sa SDL_DirtyTexture()
   1.537 + * \sa SDL_UnlockTexture()
   1.538 + */
   1.539 +extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_TextureID textureID,
   1.540 +                                            SDL_Rect * rect, int markDirty,
   1.541 +                                            void **pixels, int *pitch);
   1.542 +
   1.543 +/**
   1.544 + * \fn void SDL_UnlockTexture(SDL_TextureID textureID)
   1.545 + *
   1.546 + * \brief Unlock a texture, uploading the changes to video memory, if needed.
   1.547 + *
   1.548 + * \sa SDL_LockTexture()
   1.549 + * \sa SDL_DirtyTexture()
   1.550 + */
   1.551 +extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_TextureID textureID);
   1.552 +
   1.553 +/**
   1.554 + * \fn void SDL_DirtyTexture(SDL_TextureID textureID, int numrects, SDL_Rect * rects)
   1.555 + *
   1.556 + * \brief Mark the specified rectangles of the texture as dirty.
   1.557 + *
   1.558 + * \note The texture must have been created with SDL_TextureAccess_Local.
   1.559 + *
   1.560 + * \sa SDL_LockTexture()
   1.561 + * \sa SDL_UnlockTexture()
   1.562 + */
   1.563 +extern DECLSPEC void SDLCALL SDL_DirtyTexture(SDL_TextureID textureID,
   1.564 +                                              int numrects, SDL_Rect * rects);
   1.565 +
   1.566 +/**
   1.567 + * \fn void SDL_SelectRenderTexture(SDL_TextureID textureID)
   1.568 + *
   1.569 + * \brief Select a texture as the rendering target, or 0 to reselect the current window.
   1.570 + *
   1.571 + * \note The texture must have been created with SDL_TextureAccess_Render.
   1.572 + */
   1.573 +extern DECLSPEC void SDLCALL SDL_SelectRenderTexture(SDL_TextureID textureID);
   1.574 +
   1.575 +/**
   1.576 + * \fn void SDL_RenderFill(SDL_Rect *rect, Uint32 color)
   1.577 + *
   1.578 + * \brief Fill the current rendering target with the specified color.
   1.579 + *
   1.580 + * \param rect A pointer to the destination rectangle, or NULL for the entire rendering target.
   1.581 + * \param color An ARGB color value.
   1.582 + *
   1.583 + * \return 0 on success, or -1 if there is no renderer current
   1.584 + */
   1.585 +extern DECLSPEC int SDLCALL SDL_RenderFill(SDL_Rect * rect, Uint32 color);
   1.586  
   1.587 -/*
   1.588 - * On hardware that supports double-buffering, this function sets up a flip
   1.589 - * and returns.  The hardware will wait for vertical retrace, and then swap
   1.590 - * video buffers before the next video surface blit or lock will return.
   1.591 - * On hardware that doesn not support double-buffering, this is equivalent
   1.592 - * to calling SDL_UpdateRect(screen, 0, 0, 0, 0);
   1.593 - * The SDL_DOUBLEBUF flag must have been passed to SDL_SetVideoMode() when
   1.594 - * setting the video mode for this function to perform hardware flipping.
   1.595 - * This function returns 0 if successful, or -1 if there was an error.
   1.596 +/**
   1.597 + * \fn int SDL_RenderCopy(SDL_TextureID textureID, SDL_Rect *srcrect, SDL_Rect *dstrect, Uint32 blendMode, Uint32 scaleMode)
   1.598 + *
   1.599 + * \brief Copy a portion of the texture to the current rendering target.
   1.600 + *
   1.601 + * \param texture The source texture.
   1.602 + * \param srcrect A pointer to the source rectangle, or NULL for the entire texture.
   1.603 + * \param dstrect A pointer to the destination rectangle, or NULL for the entire rendering target.
   1.604 + * \param blendMode SDL_TextureBlendMode to be used if the source texture has an alpha channel.
   1.605 + * \param scaleMode SDL_TextureScaleMode to be used if the source and destination rectangles don't have the same width and height.
   1.606 + *
   1.607 + * \return 0 on success, or -1 if there is no renderer current, or the driver doesn't support the requested operation.
   1.608 + *
   1.609 + * \note You can check the video driver info to see what operations are supported.
   1.610 + */
   1.611 +extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_TextureID textureID,
   1.612 +                                           SDL_Rect * srcrect,
   1.613 +                                           SDL_Rect * dstrect, int blendMode,
   1.614 +                                           int scaleMode);
   1.615 +
   1.616 +/**
   1.617 + * \fn int SDL_RenderReadPixels(SDL_Rect *rect, void *pixels, int pitch)
   1.618 + *
   1.619 + * \brief Read pixels from the current rendering target.
   1.620 + *
   1.621 + * \param rect A pointer to the rectangle to read, or NULL for the entire render target
   1.622 + * \param pixels A pointer to be filled in with the pixel data
   1.623 + * \param pitch The pitch of the pixels parameter
   1.624 + *
   1.625 + * \return 0 on success, or -1 if pixel reading is not supported.
   1.626 + *
   1.627 + * \warning This is a very slow operation, and should not be used frequently.
   1.628   */
   1.629 -extern DECLSPEC int SDLCALL SDL_Flip(SDL_Surface * screen);
   1.630 +extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Rect * rect,
   1.631 +                                                 void *pixels, int pitch);
   1.632 +
   1.633 +/**
   1.634 + * \fn int SDL_RenderWritePixels(SDL_Rect *rect, const void *pixels, int pitch)
   1.635 + *
   1.636 + * \brief Write pixels to the current rendering target.
   1.637 + *
   1.638 + * \param rect A pointer to the rectangle to write, or NULL for the entire render target
   1.639 + * \param pixels A pointer to the pixel data to write
   1.640 + * \param pitch The pitch of the pixels parameter
   1.641 + *
   1.642 + * \return 0 on success, or -1 if pixel writing is not supported.
   1.643 + *
   1.644 + * \warning This is a very slow operation, and should not be used frequently.
   1.645 + */
   1.646 +extern DECLSPEC int SDLCALL SDL_RenderWritePixels(SDL_Rect * rect,
   1.647 +                                                  const void *pixels,
   1.648 +                                                  int pitch);
   1.649 +
   1.650 +/**
   1.651 + * \fn void SDL_RenderPresent(void)
   1.652 + *
   1.653 + * \brief Update the screen with rendering performed.
   1.654 + */
   1.655 +extern DECLSPEC void SDLCALL SDL_RenderPresent(void);
   1.656 +
   1.657 +/**
   1.658 + * \fn void SDL_DestroyTexture(SDL_TextureID textureID);
   1.659 + *
   1.660 + * \brief Destroy the specified texture.
   1.661 + *
   1.662 + * \sa SDL_CreateTexture()
   1.663 + * \sa SDL_CreateTextureFromSurface()
   1.664 + */
   1.665 +extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_TextureID textureID);
   1.666 +
   1.667 +/**
   1.668 + * \fn void SDL_DestroyRenderer(SDL_WindowID windowID);
   1.669 + *
   1.670 + * \brief Destroy the rendering context for a window and free associated
   1.671 + *        textures.
   1.672 + *
   1.673 + * \sa SDL_CreateRenderer()
   1.674 + */
   1.675 +extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_WindowID windowID);
   1.676  
   1.677  /*
   1.678   * Set the gamma correction for each of the color channels.
   1.679 @@ -796,33 +1104,9 @@
   1.680   * If the function runs out of memory, it will return NULL.
   1.681   *
   1.682   * The 'flags' tell what kind of surface to create.
   1.683 - * SDL_SWSURFACE means that the surface should be created in system memory.
   1.684 - * SDL_HWSURFACE means that the surface should be created in video memory,
   1.685 - * with the same format as the display surface.  This is useful for surfaces
   1.686 - * that will not change much, to take advantage of hardware acceleration
   1.687 - * when being blitted to the display surface.
   1.688 - * SDL_ASYNCBLIT means that SDL will try to perform asynchronous blits with
   1.689 - * this surface, but you must always lock it before accessing the pixels.
   1.690 - * SDL will wait for current blits to finish before returning from the lock.
   1.691   * SDL_SRCCOLORKEY indicates that the surface will be used for colorkey blits.
   1.692 - * If the hardware supports acceleration of colorkey blits between
   1.693 - * two surfaces in video memory, SDL will try to place the surface in
   1.694 - * video memory. If this isn't possible or if there is no hardware
   1.695 - * acceleration available, the surface will be placed in system memory.
   1.696 - * SDL_SRCALPHA means that the surface will be used for alpha blits and 
   1.697 - * if the hardware supports hardware acceleration of alpha blits between
   1.698 - * two surfaces in video memory, to place the surface in video memory
   1.699 - * if possible, otherwise it will be placed in system memory.
   1.700 - * If the surface is created in video memory, blits will be _much_ faster,
   1.701 - * but the surface format must be identical to the video surface format,
   1.702 - * and the only way to access the pixels member of the surface is to use
   1.703 - * the SDL_LockSurface() and SDL_UnlockSurface() calls.
   1.704 - * If the requested surface actually resides in video memory, SDL_HWSURFACE
   1.705 - * will be set in the flags member of the returned surface.  If for some
   1.706 - * reason the surface could not be placed in video memory, it will not have
   1.707 - * the SDL_HWSURFACE flag set, and will be created in system memory instead.
   1.708 + * SDL_SRCALPHA means that the surface will be used for alpha blits.
   1.709   */
   1.710 -#define SDL_AllocSurface    SDL_CreateRGBSurface
   1.711  extern DECLSPEC SDL_Surface *SDLCALL SDL_CreateRGBSurface
   1.712      (Uint32 flags, int width, int height, int depth,
   1.713       Uint32 Rmask, Uint32 Gmask, Uint32 Bmask, Uint32 Amask);
   1.714 @@ -835,6 +1119,8 @@
   1.715                                                                Uint32 Gmask,
   1.716                                                                Uint32 Bmask,
   1.717                                                                Uint32 Amask);
   1.718 +extern DECLSPEC SDL_Surface *SDLCALL
   1.719 +SDL_CreateRGBSurfaceFromTexture(SDL_TextureID textureID);
   1.720  extern DECLSPEC void SDLCALL SDL_FreeSurface(SDL_Surface * surface);
   1.721  
   1.722  /*
   1.723 @@ -846,9 +1132,7 @@
   1.724   *
   1.725   * Not all surfaces require locking.  If SDL_MUSTLOCK(surface) evaluates
   1.726   * to 0, then you can read and write to the surface at any time, and the
   1.727 - * pixel format of the surface will not change.  In particular, if the
   1.728 - * SDL_HWSURFACE flag is not given when calling SDL_SetVideoMode(), you
   1.729 - * will not need to lock the display surface before accessing it.
   1.730 + * pixel format of the surface will not change.
   1.731   * 
   1.732   * No operating system or library calls should be made between lock/unlock
   1.733   * pairs, as critical system locks may be held during this time.
   1.734 @@ -951,6 +1235,18 @@
   1.735      (SDL_Surface * src, SDL_PixelFormat * fmt, Uint32 flags);
   1.736  
   1.737  /*
   1.738 + * This function performs a fast fill of the given rectangle with 'color'
   1.739 + * The given rectangle is clipped to the destination surface clip area
   1.740 + * and the final fill rectangle is saved in the passed in pointer.
   1.741 + * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   1.742 + * The color should be a pixel of the format used by the surface, and 
   1.743 + * can be generated by the SDL_MapRGB() function.
   1.744 + * This function returns 0 on success, or -1 on error.
   1.745 + */
   1.746 +extern DECLSPEC int SDLCALL SDL_FillRect
   1.747 +    (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
   1.748 +
   1.749 +/*
   1.750   * This performs a fast blit from the source surface to the destination
   1.751   * surface.  It assumes that the source and destination rectangles are
   1.752   * the same size.  If either 'srcrect' or 'dstrect' are NULL, the entire
   1.753 @@ -1034,45 +1330,16 @@
   1.754      (SDL_Surface * src, SDL_Rect * srcrect,
   1.755       SDL_Surface * dst, SDL_Rect * dstrect);
   1.756  
   1.757 -/*
   1.758 - * This function performs a fast fill of the given rectangle with 'color'
   1.759 - * The given rectangle is clipped to the destination surface clip area
   1.760 - * and the final fill rectangle is saved in the passed in pointer.
   1.761 - * If 'dstrect' is NULL, the whole surface will be filled with 'color'
   1.762 - * The color should be a pixel of the format used by the surface, and 
   1.763 - * can be generated by the SDL_MapRGB() function.
   1.764 - * This function returns 0 on success, or -1 on error.
   1.765 - */
   1.766 -extern DECLSPEC int SDLCALL SDL_FillRect
   1.767 -    (SDL_Surface * dst, SDL_Rect * dstrect, Uint32 color);
   1.768 -
   1.769 -/* 
   1.770 - * This function takes a surface and copies it to a new surface of the
   1.771 - * pixel format and colors of the video framebuffer, suitable for fast
   1.772 - * blitting onto the display surface.  It calls SDL_ConvertSurface()
   1.773 +/**
   1.774 + * \fn int SDL_SoftStretch(SDL_Surface * src, SDL_Rect * srcrect, SDL_Surface * dst, SDL_Rect * dstrect)
   1.775   *
   1.776 - * If you want to take advantage of hardware colorkey or alpha blit
   1.777 - * acceleration, you should set the colorkey and alpha value before
   1.778 - * calling this function.
   1.779 - *
   1.780 - * If the conversion fails or runs out of memory, it returns NULL
   1.781 + * \brief Perform a fast, low quality, stretch blit between two surfaces of the same pixel format.
   1.782 + * \note This function uses a static buffer, and is not thread-safe.
   1.783   */
   1.784 -extern DECLSPEC SDL_Surface *SDLCALL SDL_DisplayFormat(SDL_Surface * surface);
   1.785 -
   1.786 -/* 
   1.787 - * This function takes a surface and copies it to a new surface of the
   1.788 - * pixel format and colors of the video framebuffer (if possible),
   1.789 - * suitable for fast alpha blitting onto the display surface.
   1.790 - * The new surface will always have an alpha channel.
   1.791 - *
   1.792 - * If you want to take advantage of hardware colorkey or alpha blit
   1.793 - * acceleration, you should set the colorkey and alpha value before
   1.794 - * calling this function.
   1.795 - *
   1.796 - * If the conversion fails or runs out of memory, it returns NULL
   1.797 - */
   1.798 -extern DECLSPEC SDL_Surface *SDLCALL SDL_DisplayFormatAlpha(SDL_Surface *
   1.799 -                                                            surface);
   1.800 +extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
   1.801 +                                            SDL_Rect * srcrect,
   1.802 +                                            SDL_Surface * dst,
   1.803 +                                            SDL_Rect * dstrect);
   1.804  
   1.805  
   1.806  /* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * */
   1.807 @@ -1145,12 +1412,6 @@
   1.808   */
   1.809  extern DECLSPEC void SDLCALL SDL_GL_SwapBuffers(void);
   1.810  
   1.811 -/* Not in public API at the moment - do not use! */
   1.812 -extern DECLSPEC int SDLCALL SDL_SoftStretch(SDL_Surface * src,
   1.813 -                                            SDL_Rect * srcrect,
   1.814 -                                            SDL_Surface * dst,
   1.815 -                                            SDL_Rect * dstrect);
   1.816 -
   1.817  /* Ends C function definitions when using C++ */
   1.818  #ifdef __cplusplus
   1.819  /* *INDENT-OFF* */