packages/sdl2.nuget.2.0.22/build/native/include/SDL_render.h

   1 /*
   2   Simple DirectMedia Layer
   3   Copyright (C) 1997-2022 Sam Lantinga <slouken@libsdl.org>
   4
   5   This software is provided 'as-is', without any express or implied
   6   warranty.  In no event will the authors be held liable for any damages
   7   arising from the use of this software.
   8
   9   Permission is granted to anyone to use this software for any purpose,
  10   including commercial applications, and to alter it and redistribute it
  11   freely, subject to the following restrictions:
  12
  13   1. The origin of this software must not be misrepresented; you must not
  14      claim that you wrote the original software. If you use this software
  15      in a product, an acknowledgment in the product documentation would be
  16      appreciated but is not required.
  17   2. Altered source versions must be plainly marked as such, and must not be
  18      misrepresented as being the original software.
  19   3. This notice may not be removed or altered from any source distribution.
  20 */
  21
  22 /**
  23  *  \file SDL_render.h
  24  *
  25  *  Header file for SDL 2D rendering functions.
  26  *
  27  *  This API supports the following features:
  28  *      * single pixel points
  29  *      * single pixel lines
  30  *      * filled rectangles
  31  *      * texture images
  32  *
  33  *  The primitives may be drawn in opaque, blended, or additive modes.
  34  *
  35  *  The texture images may be drawn in opaque, blended, or additive modes.
  36  *  They can have an additional color tint or alpha modulation applied to
  37  *  them, and may also be stretched with linear interpolation.
  38  *
  39  *  This API is designed to accelerate simple 2D operations. You may
  40  *  want more functionality such as polygons and particle effects and
  41  *  in that case you should use SDL's OpenGL/Direct3D support or one
  42  *  of the many good 3D engines.
  43  *
  44  *  These functions must be called from the main thread.
  45  *  See this bug for details: http://bugzilla.libsdl.org/show_bug.cgi?id=1995
  46  */
  47
  48 #ifndef SDL_render_h_
  49 #define SDL_render_h_
  50
  51 #include "SDL_stdinc.h"
  52 #include "SDL_rect.h"
  53 #include "SDL_video.h"
  54
  55 #include "begin_code.h"
  56 /* Set up for C function definitions, even when using C++ */
  57 #ifdef __cplusplus
  58 extern "C" {
  59 #endif
  60
  61 /**
  62  * Flags used when creating a rendering context
  63  */
  64 typedef enum
  65 {
  66     SDL_RENDERER_SOFTWARE = 0x00000001,         /**< The renderer is a software fallback */
  67     SDL_RENDERER_ACCELERATED = 0x00000002,      /**< The renderer uses hardware
  68                                                      acceleration */
  69     SDL_RENDERER_PRESENTVSYNC = 0x00000004,     /**< Present is synchronized
  70                                                      with the refresh rate */
  71     SDL_RENDERER_TARGETTEXTURE = 0x00000008     /**< The renderer supports
  72                                                      rendering to texture */
  73 } SDL_RendererFlags;
  74
  75 /**
  76  * Information on the capabilities of a render driver or context.
  77  */
  78 typedef struct SDL_RendererInfo
  79 {
  80     const char *name;           /**< The name of the renderer */
  81     Uint32 flags;               /**< Supported ::SDL_RendererFlags */
  82     Uint32 num_texture_formats; /**< The number of available texture formats */
  83     Uint32 texture_formats[16]; /**< The available texture formats */
  84     int max_texture_width;      /**< The maximum texture width */
  85     int max_texture_height;     /**< The maximum texture height */
  86 } SDL_RendererInfo;
  87
  88 /**
  89  *  Vertex structure
  90  */
  91 typedef struct SDL_Vertex
  92 {
  93     SDL_FPoint position;        /**< Vertex position, in SDL_Renderer coordinates  */
  94     SDL_Color  color;           /**< Vertex color */
  95     SDL_FPoint tex_coord;       /**< Normalized texture coordinates, if needed */
  96 } SDL_Vertex;
  97
  98 /**
  99  * The scaling mode for a texture.
 100  */
 101 typedef enum
 102 {
 103     SDL_ScaleModeNearest, /**< nearest pixel sampling */
 104     SDL_ScaleModeLinear,  /**< linear filtering */
 105     SDL_ScaleModeBest     /**< anisotropic filtering */
 106 } SDL_ScaleMode;
 107
 108 /**
 109  * The access pattern allowed for a texture.
 110  */
 111 typedef enum
 112 {
 113     SDL_TEXTUREACCESS_STATIC,    /**< Changes rarely, not lockable */
 114     SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */
 115     SDL_TEXTUREACCESS_TARGET     /**< Texture can be used as a render target */
 116 } SDL_TextureAccess;
 117
 118 /**
 119  * The texture channel modulation used in SDL_RenderCopy().
 120  */
 121 typedef enum
 122 {
 123     SDL_TEXTUREMODULATE_NONE = 0x00000000,     /**< No modulation */
 124     SDL_TEXTUREMODULATE_COLOR = 0x00000001,    /**< srcC = srcC * color */
 125     SDL_TEXTUREMODULATE_ALPHA = 0x00000002     /**< srcA = srcA * alpha */
 126 } SDL_TextureModulate;
 127
 128 /**
 129  * Flip constants for SDL_RenderCopyEx
 130  */
 131 typedef enum
 132 {
 133     SDL_FLIP_NONE = 0x00000000,     /**< Do not flip */
 134     SDL_FLIP_HORIZONTAL = 0x00000001,    /**< flip horizontally */
 135     SDL_FLIP_VERTICAL = 0x00000002     /**< flip vertically */
 136 } SDL_RendererFlip;
 137
 138 /**
 139  * A structure representing rendering state
 140  */
 141 struct SDL_Renderer;
 142 typedef struct SDL_Renderer SDL_Renderer;
 143
 144 /**
 145  * An efficient driver-specific representation of pixel data
 146  */
 147 struct SDL_Texture;
 148 typedef struct SDL_Texture SDL_Texture;
 149
 150 /* Function prototypes */
 151
 152 /**
 153  * Get the number of 2D rendering drivers available for the current display.
 154  *
 155  * A render driver is a set of code that handles rendering and texture
 156  * management on a particular display. Normally there is only one, but some
 157  * drivers may have several available with different capabilities.
 158  *
 159  * There may be none if SDL was compiled without render support.
 160  *
 161  * \returns a number >= 0 on success or a negative error code on failure; call
 162  *          SDL_GetError() for more information.
 163  *
 164  * \since This function is available since SDL 2.0.0.
 165  *
 166  * \sa SDL_CreateRenderer
 167  * \sa SDL_GetRenderDriverInfo
 168  */
 169 extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
 170
 171 /**
 172  * Get info about a specific 2D rendering driver for the current display.
 173  *
 174  * \param index the index of the driver to query information about
 175  * \param info an SDL_RendererInfo structure to be filled with information on
 176  *             the rendering driver
 177  * \returns 0 on success or a negative error code on failure; call
 178  *          SDL_GetError() for more information.
 179  *
 180  * \since This function is available since SDL 2.0.0.
 181  *
 182  * \sa SDL_CreateRenderer
 183  * \sa SDL_GetNumRenderDrivers
 184  */
 185 extern DECLSPEC int SDLCALL SDL_GetRenderDriverInfo(int index,
 186                                                     SDL_RendererInfo * info);
 187
 188 /**
 189  * Create a window and default renderer.
 190  *
 191  * \param width the width of the window
 192  * \param height the height of the window
 193  * \param window_flags the flags used to create the window (see
 194  *                     SDL_CreateWindow())
 195  * \param window a pointer filled with the window, or NULL on error
 196  * \param renderer a pointer filled with the renderer, or NULL on error
 197  * \returns 0 on success, or -1 on error; call SDL_GetError() for more
 198  *          information.
 199  *
 200  * \since This function is available since SDL 2.0.0.
 201  *
 202  * \sa SDL_CreateRenderer
 203  * \sa SDL_CreateWindow
 204  */
 205 extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(
 206                                 int width, int height, Uint32 window_flags,
 207                                 SDL_Window **window, SDL_Renderer **renderer);
 208
 209
 210 /**
 211  * Create a 2D rendering context for a window.
 212  *
 213  * \param window the window where rendering is displayed
 214  * \param index the index of the rendering driver to initialize, or -1 to
 215  *              initialize the first one supporting the requested flags
 216  * \param flags 0, or one or more SDL_RendererFlags OR'd together
 217  * \returns a valid rendering context or NULL if there was an error; call
 218  *          SDL_GetError() for more information.
 219  *
 220  * \since This function is available since SDL 2.0.0.
 221  *
 222  * \sa SDL_CreateSoftwareRenderer
 223  * \sa SDL_DestroyRenderer
 224  * \sa SDL_GetNumRenderDrivers
 225  * \sa SDL_GetRendererInfo
 226  */
 227 extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window * window,
 228                                                int index, Uint32 flags);
 229
 230 /**
 231  * Create a 2D software rendering context for a surface.
 232  *
 233  * Two other API which can be used to create SDL_Renderer:
 234  * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_
 235  * create a software renderer, but they are intended to be used with an
 236  * SDL_Window as the final destination and not an SDL_Surface.
 237  *
 238  * \param surface the SDL_Surface structure representing the surface where
 239  *                rendering is done
 240  * \returns a valid rendering context or NULL if there was an error; call
 241  *          SDL_GetError() for more information.
 242  *
 243  * \since This function is available since SDL 2.0.0.
 244  *
 245  * \sa SDL_CreateRenderer
 246  * \sa SDL_CreateWindowRenderer
 247  * \sa SDL_DestroyRenderer
 248  */
 249 extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface * surface);
 250
 251 /**
 252  * Get the renderer associated with a window.
 253  *
 254  * \param window the window to query
 255  * \returns the rendering context on success or NULL on failure; call
 256  *          SDL_GetError() for more information.
 257  *
 258  * \since This function is available since SDL 2.0.0.
 259  *
 260  * \sa SDL_CreateRenderer
 261  */
 262 extern DECLSPEC SDL_Renderer * SDLCALL SDL_GetRenderer(SDL_Window * window);
 263
 264 /**
 265  * Get the window associated with a renderer.
 266  *
 267  * \param renderer the renderer to query
 268  * \returns the window on success or NULL on failure; call SDL_GetError() for
 269  *          more information.
 270  *
 271  * \since This function is available since SDL 2.0.22.
 272  */
 273 extern DECLSPEC SDL_Window * SDLCALL SDL_RenderGetWindow(SDL_Renderer *renderer);
 274
 275 /**
 276  * Get information about a rendering context.
 277  *
 278  * \param renderer the rendering context
 279  * \param info an SDL_RendererInfo structure filled with information about the
 280  *             current renderer
 281  * \returns 0 on success or a negative error code on failure; call
 282  *          SDL_GetError() for more information.
 283  *
 284  * \since This function is available since SDL 2.0.0.
 285  *
 286  * \sa SDL_CreateRenderer
 287  */
 288 extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer * renderer,
 289                                                 SDL_RendererInfo * info);
 290
 291 /**
 292  * Get the output size in pixels of a rendering context.
 293  *
 294  * Due to high-dpi displays, you might end up with a rendering context that
 295  * has more pixels than the window that contains it, so use this instead of
 296  * SDL_GetWindowSize() to decide how much drawing area you have.
 297  *
 298  * \param renderer the rendering context
 299  * \param w an int filled with the width
 300  * \param h an int filled with the height
 301  * \returns 0 on success or a negative error code on failure; call
 302  *          SDL_GetError() for more information.
 303  *
 304  * \since This function is available since SDL 2.0.0.
 305  *
 306  * \sa SDL_GetRenderer
 307  */
 308 extern DECLSPEC int SDLCALL SDL_GetRendererOutputSize(SDL_Renderer * renderer,
 309                                                       int *w, int *h);
 310
 311 /**
 312  * Create a texture for a rendering context.
 313  *
 314  * You can set the texture scaling method by setting
 315  * `SDL_HINT_RENDER_SCALE_QUALITY` before creating the texture.
 316  *
 317  * \param renderer the rendering context
 318  * \param format one of the enumerated values in SDL_PixelFormatEnum
 319  * \param access one of the enumerated values in SDL_TextureAccess
 320  * \param w the width of the texture in pixels
 321  * \param h the height of the texture in pixels
 322  * \returns a pointer to the created texture or NULL if no rendering context
 323  *          was active, the format was unsupported, or the width or height
 324  *          were out of range; call SDL_GetError() for more information.
 325  *
 326  * \since This function is available since SDL 2.0.0.
 327  *
 328  * \sa SDL_CreateTextureFromSurface
 329  * \sa SDL_DestroyTexture
 330  * \sa SDL_QueryTexture
 331  * \sa SDL_UpdateTexture
 332  */
 333 extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTexture(SDL_Renderer * renderer,
 334                                                         Uint32 format,
 335                                                         int access, int w,
 336                                                         int h);
 337
 338 /**
 339  * Create a texture from an existing surface.
 340  *
 341  * The surface is not modified or freed by this function.
 342  *
 343  * The SDL_TextureAccess hint for the created texture is
 344  * `SDL_TEXTUREACCESS_STATIC`.
 345  *
 346  * The pixel format of the created texture may be different from the pixel
 347  * format of the surface. Use SDL_QueryTexture() to query the pixel format of
 348  * the texture.
 349  *
 350  * \param renderer the rendering context
 351  * \param surface the SDL_Surface structure containing pixel data used to fill
 352  *                the texture
 353  * \returns the created texture or NULL on failure; call SDL_GetError() for
 354  *          more information.
 355  *
 356  * \since This function is available since SDL 2.0.0.
 357  *
 358  * \sa SDL_CreateTexture
 359  * \sa SDL_DestroyTexture
 360  * \sa SDL_QueryTexture
 361  */
 362 extern DECLSPEC SDL_Texture * SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer * renderer, SDL_Surface * surface);
 363
 364 /**
 365  * Query the attributes of a texture.
 366  *
 367  * \param texture the texture to query
 368  * \param format a pointer filled in with the raw format of the texture; the
 369  *               actual format may differ, but pixel transfers will use this
 370  *               format (one of the SDL_PixelFormatEnum values). This argument
 371  *               can be NULL if you don't need this information.
 372  * \param access a pointer filled in with the actual access to the texture
 373  *               (one of the SDL_TextureAccess values). This argument can be
 374  *               NULL if you don't need this information.
 375  * \param w a pointer filled in with the width of the texture in pixels. This
 376  *          argument can be NULL if you don't need this information.
 377  * \param h a pointer filled in with the height of the texture in pixels. This
 378  *          argument can be NULL if you don't need this information.
 379  * \returns 0 on success or a negative error code on failure; call
 380  *          SDL_GetError() for more information.
 381  *
 382  * \since This function is available since SDL 2.0.0.
 383  *
 384  * \sa SDL_CreateTexture
 385  */
 386 extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture * texture,
 387                                              Uint32 * format, int *access,
 388                                              int *w, int *h);
 389
 390 /**
 391  * Set an additional color value multiplied into render copy operations.
 392  *
 393  * When this texture is rendered, during the copy operation each source color
 394  * channel is modulated by the appropriate color value according to the
 395  * following formula:
 396  *
 397  * `srcC = srcC * (color / 255)`
 398  *
 399  * Color modulation is not always supported by the renderer; it will return -1
 400  * if color modulation is not supported.
 401  *
 402  * \param texture the texture to update
 403  * \param r the red color value multiplied into copy operations
 404  * \param g the green color value multiplied into copy operations
 405  * \param b the blue color value multiplied into copy operations
 406  * \returns 0 on success or a negative error code on failure; call
 407  *          SDL_GetError() for more information.
 408  *
 409  * \since This function is available since SDL 2.0.0.
 410  *
 411  * \sa SDL_GetTextureColorMod
 412  * \sa SDL_SetTextureAlphaMod
 413  */
 414 extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture * texture,
 415                                                    Uint8 r, Uint8 g, Uint8 b);
 416
 417
 418 /**
 419  * Get the additional color value multiplied into render copy operations.
 420  *
 421  * \param texture the texture to query
 422  * \param r a pointer filled in with the current red color value
 423  * \param g a pointer filled in with the current green color value
 424  * \param b a pointer filled in with the current blue color value
 425  * \returns 0 on success or a negative error code on failure; call
 426  *          SDL_GetError() for more information.
 427  *
 428  * \since This function is available since SDL 2.0.0.
 429  *
 430  * \sa SDL_GetTextureAlphaMod
 431  * \sa SDL_SetTextureColorMod
 432  */
 433 extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture * texture,
 434                                                    Uint8 * r, Uint8 * g,
 435                                                    Uint8 * b);
 436
 437 /**
 438  * Set an additional alpha value multiplied into render copy operations.
 439  *
 440  * When this texture is rendered, during the copy operation the source alpha
 441  * value is modulated by this alpha value according to the following formula:
 442  *
 443  * `srcA = srcA * (alpha / 255)`
 444  *
 445  * Alpha modulation is not always supported by the renderer; it will return -1
 446  * if alpha modulation is not supported.
 447  *
 448  * \param texture the texture to update
 449  * \param alpha the source alpha value multiplied into copy operations
 450  * \returns 0 on success or a negative error code on failure; call
 451  *          SDL_GetError() for more information.
 452  *
 453  * \since This function is available since SDL 2.0.0.
 454  *
 455  * \sa SDL_GetTextureAlphaMod
 456  * \sa SDL_SetTextureColorMod
 457  */
 458 extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
 459                                                    Uint8 alpha);
 460
 461 /**
 462  * Get the additional alpha value multiplied into render copy operations.
 463  *
 464  * \param texture the texture to query
 465  * \param alpha a pointer filled in with the current alpha value
 466  * \returns 0 on success or a negative error code on failure; call
 467  *          SDL_GetError() for more information.
 468  *
 469  * \since This function is available since SDL 2.0.0.
 470  *
 471  * \sa SDL_GetTextureColorMod
 472  * \sa SDL_SetTextureAlphaMod
 473  */
 474 extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
 475                                                    Uint8 * alpha);
 476
 477 /**
 478  * Set the blend mode for a texture, used by SDL_RenderCopy().
 479  *
 480  * If the blend mode is not supported, the closest supported mode is chosen
 481  * and this function returns -1.
 482  *
 483  * \param texture the texture to update
 484  * \param blendMode the SDL_BlendMode to use for texture blending
 485  * \returns 0 on success or a negative error code on failure; call
 486  *          SDL_GetError() for more information.
 487  *
 488  * \since This function is available since SDL 2.0.0.
 489  *
 490  * \sa SDL_GetTextureBlendMode
 491  * \sa SDL_RenderCopy
 492  */
 493 extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture,
 494                                                     SDL_BlendMode blendMode);
 495
 496 /**
 497  * Get the blend mode used for texture copy operations.
 498  *
 499  * \param texture the texture to query
 500  * \param blendMode a pointer filled in with the current SDL_BlendMode
 501  * \returns 0 on success or a negative error code on failure; call
 502  *          SDL_GetError() for more information.
 503  *
 504  * \since This function is available since SDL 2.0.0.
 505  *
 506  * \sa SDL_SetTextureBlendMode
 507  */
 508 extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
 509                                                     SDL_BlendMode *blendMode);
 510
 511 /**
 512  * Set the scale mode used for texture scale operations.
 513  *
 514  * If the scale mode is not supported, the closest supported mode is chosen.
 515  *
 516  * \param texture The texture to update.
 517  * \param scaleMode the SDL_ScaleMode to use for texture scaling.
 518  * \returns 0 on success, or -1 if the texture is not valid.
 519  *
 520  * \since This function is available since SDL 2.0.12.
 521  *
 522  * \sa SDL_GetTextureScaleMode
 523  */
 524 extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
 525                                                     SDL_ScaleMode scaleMode);
 526
 527 /**
 528  * Get the scale mode used for texture scale operations.
 529  *
 530  * \param texture the texture to query.
 531  * \param scaleMode a pointer filled in with the current scale mode.
 532  * \return 0 on success, or -1 if the texture is not valid.
 533  *
 534  * \since This function is available since SDL 2.0.12.
 535  *
 536  * \sa SDL_SetTextureScaleMode
 537  */
 538 extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
 539                                                     SDL_ScaleMode *scaleMode);
 540
 541 /**
 542  * Associate a user-specified pointer with a texture.
 543  *
 544  * \param texture the texture to update.
 545  * \param userdata the pointer to associate with the texture.
 546  * \returns 0 on success, or -1 if the texture is not valid.
 547  *
 548  * \since This function is available since SDL 2.0.18.
 549  *
 550  * \sa SDL_GetTextureUserData
 551  */
 552 extern DECLSPEC int SDLCALL SDL_SetTextureUserData(SDL_Texture * texture,
 553                                                    void *userdata);
 554
 555 /**
 556  * Get the user-specified pointer associated with a texture
 557  *
 558  * \param texture the texture to query.
 559  * \return the pointer associated with the texture, or NULL if the texture is
 560  *         not valid.
 561  *
 562  * \since This function is available since SDL 2.0.18.
 563  *
 564  * \sa SDL_SetTextureUserData
 565  */
 566 extern DECLSPEC void * SDLCALL SDL_GetTextureUserData(SDL_Texture * texture);
 567
 568 /**
 569  * Update the given texture rectangle with new pixel data.
 570  *
 571  * The pixel data must be in the pixel format of the texture. Use
 572  * SDL_QueryTexture() to query the pixel format of the texture.
 573  *
 574  * This is a fairly slow function, intended for use with static textures that
 575  * do not change often.
 576  *
 577  * If the texture is intended to be updated often, it is preferred to create
 578  * the texture as streaming and use the locking functions referenced below.
 579  * While this function will work with streaming textures, for optimization
 580  * reasons you may not get the pixels back if you lock the texture afterward.
 581  *
 582  * \param texture the texture to update
 583  * \param rect an SDL_Rect structure representing the area to update, or NULL
 584  *             to update the entire texture
 585  * \param pixels the raw pixel data in the format of the texture
 586  * \param pitch the number of bytes in a row of pixel data, including padding
 587  *              between lines
 588  * \returns 0 on success or a negative error code on failure; call
 589  *          SDL_GetError() for more information.
 590  *
 591  * \since This function is available since SDL 2.0.0.
 592  *
 593  * \sa SDL_CreateTexture
 594  * \sa SDL_LockTexture
 595  * \sa SDL_UnlockTexture
 596  */
 597 extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
 598                                               const SDL_Rect * rect,
 599                                               const void *pixels, int pitch);
 600
 601 /**
 602  * Update a rectangle within a planar YV12 or IYUV texture with new pixel
 603  * data.
 604  *
 605  * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
 606  * block of Y and U/V planes in the proper order, but this function is
 607  * available if your pixel data is not contiguous.
 608  *
 609  * \param texture the texture to update
 610  * \param rect a pointer to the rectangle of pixels to update, or NULL to
 611  *             update the entire texture
 612  * \param Yplane the raw pixel data for the Y plane
 613  * \param Ypitch the number of bytes between rows of pixel data for the Y
 614  *               plane
 615  * \param Uplane the raw pixel data for the U plane
 616  * \param Upitch the number of bytes between rows of pixel data for the U
 617  *               plane
 618  * \param Vplane the raw pixel data for the V plane
 619  * \param Vpitch the number of bytes between rows of pixel data for the V
 620  *               plane
 621  * \returns 0 on success or -1 if the texture is not valid; call
 622  *          SDL_GetError() for more information.
 623  *
 624  * \since This function is available since SDL 2.0.1.
 625  *
 626  * \sa SDL_UpdateTexture
 627  */
 628 extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
 629                                                  const SDL_Rect * rect,
 630                                                  const Uint8 *Yplane, int Ypitch,
 631                                                  const Uint8 *Uplane, int Upitch,
 632                                                  const Uint8 *Vplane, int Vpitch);
 633
 634 /**
 635  * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
 636  *
 637  * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
 638  * block of NV12/21 planes in the proper order, but this function is available
 639  * if your pixel data is not contiguous.
 640  *
 641  * \param texture the texture to update
 642  * \param rect a pointer to the rectangle of pixels to update, or NULL to
 643  *             update the entire texture.
 644  * \param Yplane the raw pixel data for the Y plane.
 645  * \param Ypitch the number of bytes between rows of pixel data for the Y
 646  *               plane.
 647  * \param UVplane the raw pixel data for the UV plane.
 648  * \param UVpitch the number of bytes between rows of pixel data for the UV
 649  *                plane.
 650  * \return 0 on success, or -1 if the texture is not valid.
 651  *
 652  * \since This function is available since SDL 2.0.16.
 653  */
 654 extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture * texture,
 655                                                  const SDL_Rect * rect,
 656                                                  const Uint8 *Yplane, int Ypitch,
 657                                                  const Uint8 *UVplane, int UVpitch);
 658
 659 /**
 660  * Lock a portion of the texture for **write-only** pixel access.
 661  *
 662  * As an optimization, the pixels made available for editing don't necessarily
 663  * contain the old texture data. This is a write-only operation, and if you
 664  * need to keep a copy of the texture data you should do that at the
 665  * application level.
 666  *
 667  * You must use SDL_UnlockTexture() to unlock the pixels and apply any
 668  * changes.
 669  *
 670  * \param texture the texture to lock for access, which was created with
 671  *                `SDL_TEXTUREACCESS_STREAMING`
 672  * \param rect an SDL_Rect structure representing the area to lock for access;
 673  *             NULL to lock the entire texture
 674  * \param pixels this is filled in with a pointer to the locked pixels,
 675  *               appropriately offset by the locked area
 676  * \param pitch this is filled in with the pitch of the locked pixels; the
 677  *              pitch is the length of one row in bytes
 678  * \returns 0 on success or a negative error code if the texture is not valid
 679  *          or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
 680  *          SDL_GetError() for more information.
 681  *
 682  * \since This function is available since SDL 2.0.0.
 683  *
 684  * \sa SDL_UnlockTexture
 685  */
 686 extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture * texture,
 687                                             const SDL_Rect * rect,
 688                                             void **pixels, int *pitch);
 689
 690 /**
 691  * Lock a portion of the texture for **write-only** pixel access, and expose
 692  * it as a SDL surface.
 693  *
 694  * Besides providing an SDL_Surface instead of raw pixel data, this function
 695  * operates like SDL_LockTexture.
 696  *
 697  * As an optimization, the pixels made available for editing don't necessarily
 698  * contain the old texture data. This is a write-only operation, and if you
 699  * need to keep a copy of the texture data you should do that at the
 700  * application level.
 701  *
 702  * You must use SDL_UnlockTexture() to unlock the pixels and apply any
 703  * changes.
 704  *
 705  * The returned surface is freed internally after calling SDL_UnlockTexture()
 706  * or SDL_DestroyTexture(). The caller should not free it.
 707  *
 708  * \param texture the texture to lock for access, which was created with
 709  *                `SDL_TEXTUREACCESS_STREAMING`
 710  * \param rect a pointer to the rectangle to lock for access. If the rect is
 711  *             NULL, the entire texture will be locked
 712  * \param surface this is filled in with an SDL surface representing the
 713  *                locked area
 714  * \returns 0 on success, or -1 if the texture is not valid or was not created
 715  *          with `SDL_TEXTUREACCESS_STREAMING`
 716  *
 717  * \since This function is available since SDL 2.0.12.
 718  *
 719  * \sa SDL_LockTexture
 720  * \sa SDL_UnlockTexture
 721  */
 722 extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
 723                                             const SDL_Rect *rect,
 724                                             SDL_Surface **surface);
 725
 726 /**
 727  * Unlock a texture, uploading the changes to video memory, if needed.
 728  *
 729  * **Warning**: Please note that SDL_LockTexture() is intended to be
 730  * write-only; it will not guarantee the previous contents of the texture will
 731  * be provided. You must fully initialize any area of a texture that you lock
 732  * before unlocking it, as the pixels might otherwise be uninitialized memory.
 733  *
 734  * Which is to say: locking and immediately unlocking a texture can result in
 735  * corrupted textures, depending on the renderer in use.
 736  *
 737  * \param texture a texture locked by SDL_LockTexture()
 738  *
 739  * \since This function is available since SDL 2.0.0.
 740  *
 741  * \sa SDL_LockTexture
 742  */
 743 extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture * texture);
 744
 745 /**
 746  * Determine whether a renderer supports the use of render targets.
 747  *
 748  * \param renderer the renderer that will be checked
 749  * \returns SDL_TRUE if supported or SDL_FALSE if not.
 750  *
 751  * \since This function is available since SDL 2.0.0.
 752  *
 753  * \sa SDL_SetRenderTarget
 754  */
 755 extern DECLSPEC SDL_bool SDLCALL SDL_RenderTargetSupported(SDL_Renderer *renderer);
 756
 757 /**
 758  * Set a texture as the current rendering target.
 759  *
 760  * Before using this function, you should check the
 761  * `SDL_RENDERER_TARGETTEXTURE` bit in the flags of SDL_RendererInfo to see if
 762  * render targets are supported.
 763  *
 764  * The default render target is the window for which the renderer was created.
 765  * To stop rendering to a texture and render to the window again, call this
 766  * function with a NULL `texture`.
 767  *
 768  * \param renderer the rendering context
 769  * \param texture the targeted texture, which must be created with the
 770  *                `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
 771  *                window instead of a texture.
 772  * \returns 0 on success or a negative error code on failure; call
 773  *          SDL_GetError() for more information.
 774  *
 775  * \since This function is available since SDL 2.0.0.
 776  *
 777  * \sa SDL_GetRenderTarget
 778  */
 779 extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer,
 780                                                 SDL_Texture *texture);
 781
 782 /**
 783  * Get the current render target.
 784  *
 785  * The default render target is the window for which the renderer was created,
 786  * and is reported a NULL here.
 787  *
 788  * \param renderer the rendering context
 789  * \returns the current render target or NULL for the default render target.
 790  *
 791  * \since This function is available since SDL 2.0.0.
 792  *
 793  * \sa SDL_SetRenderTarget
 794  */
 795 extern DECLSPEC SDL_Texture * SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
 796
 797 /**
 798  * Set a device independent resolution for rendering.
 799  *
 800  * This function uses the viewport and scaling functionality to allow a fixed
 801  * logical resolution for rendering, regardless of the actual output
 802  * resolution. If the actual output resolution doesn't have the same aspect
 803  * ratio the output rendering will be centered within the output display.
 804  *
 805  * If the output display is a window, mouse and touch events in the window
 806  * will be filtered and scaled so they seem to arrive within the logical
 807  * resolution. The SDL_HINT_MOUSE_RELATIVE_SCALING hint controls whether
 808  * relative motion events are also scaled.
 809  *
 810  * If this function results in scaling or subpixel drawing by the rendering
 811  * backend, it will be handled using the appropriate quality hints.
 812  *
 813  * \param renderer the renderer for which resolution should be set
 814  * \param w the width of the logical resolution
 815  * \param h the height of the logical resolution
 816  * \returns 0 on success or a negative error code on failure; call
 817  *          SDL_GetError() for more information.
 818  *
 819  * \since This function is available since SDL 2.0.0.
 820  *
 821  * \sa SDL_RenderGetLogicalSize
 822  */
 823 extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h);
 824
 825 /**
 826  * Get device independent resolution for rendering.
 827  *
 828  * This may return 0 for `w` and `h` if the SDL_Renderer has never had its
 829  * logical size set by SDL_RenderSetLogicalSize() and never had a render
 830  * target set.
 831  *
 832  * \param renderer a rendering context
 833  * \param w an int to be filled with the width
 834  * \param h an int to be filled with the height
 835  *
 836  * \since This function is available since SDL 2.0.0.
 837  *
 838  * \sa SDL_RenderSetLogicalSize
 839  */
 840 extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h);
 841
 842 /**
 843  * Set whether to force integer scales for resolution-independent rendering.
 844  *
 845  * This function restricts the logical viewport to integer values - that is,
 846  * when a resolution is between two multiples of a logical size, the viewport
 847  * size is rounded down to the lower multiple.
 848  *
 849  * \param renderer the renderer for which integer scaling should be set
 850  * \param enable enable or disable the integer scaling for rendering
 851  * \returns 0 on success or a negative error code on failure; call
 852  *          SDL_GetError() for more information.
 853  *
 854  * \since This function is available since SDL 2.0.5.
 855  *
 856  * \sa SDL_RenderGetIntegerScale
 857  * \sa SDL_RenderSetLogicalSize
 858  */
 859 extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer,
 860                                                       SDL_bool enable);
 861
 862 /**
 863  * Get whether integer scales are forced for resolution-independent rendering.
 864  *
 865  * \param renderer the renderer from which integer scaling should be queried
 866  * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on
 867  *          failure; call SDL_GetError() for more information.
 868  *
 869  * \since This function is available since SDL 2.0.5.
 870  *
 871  * \sa SDL_RenderSetIntegerScale
 872  */
 873 extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer);
 874
 875 /**
 876  * Set the drawing area for rendering on the current target.
 877  *
 878  * When the window is resized, the viewport is reset to fill the entire new
 879  * window size.
 880  *
 881  * \param renderer the rendering context
 882  * \param rect the SDL_Rect structure representing the drawing area, or NULL
 883  *             to set the viewport to the entire target
 884  * \returns 0 on success or a negative error code on failure; call
 885  *          SDL_GetError() for more information.
 886  *
 887  * \since This function is available since SDL 2.0.0.
 888  *
 889  * \sa SDL_RenderGetViewport
 890  */
 891 extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer,
 892                                                   const SDL_Rect * rect);
 893
 894 /**
 895  * Get the drawing area for the current target.
 896  *
 897  * \param renderer the rendering context
 898  * \param rect an SDL_Rect structure filled in with the current drawing area
 899  *
 900  * \since This function is available since SDL 2.0.0.
 901  *
 902  * \sa SDL_RenderSetViewport
 903  */
 904 extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer,
 905                                                    SDL_Rect * rect);
 906
 907 /**
 908  * Set the clip rectangle for rendering on the specified target.
 909  *
 910  * \param renderer the rendering context for which clip rectangle should be
 911  *                 set
 912  * \param rect an SDL_Rect structure representing the clip area, relative to
 913  *             the viewport, or NULL to disable clipping
 914  * \returns 0 on success or a negative error code on failure; call
 915  *          SDL_GetError() for more information.
 916  *
 917  * \since This function is available since SDL 2.0.0.
 918  *
 919  * \sa SDL_RenderGetClipRect
 920  * \sa SDL_RenderIsClipEnabled
 921  */
 922 extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer,
 923                                                   const SDL_Rect * rect);
 924
 925 /**
 926  * Get the clip rectangle for the current target.
 927  *
 928  * \param renderer the rendering context from which clip rectangle should be
 929  *                 queried
 930  * \param rect an SDL_Rect structure filled in with the current clipping area
 931  *             or an empty rectangle if clipping is disabled
 932  *
 933  * \since This function is available since SDL 2.0.0.
 934  *
 935  * \sa SDL_RenderIsClipEnabled
 936  * \sa SDL_RenderSetClipRect
 937  */
 938 extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer,
 939                                                    SDL_Rect * rect);
 940
 941 /**
 942  * Get whether clipping is enabled on the given renderer.
 943  *
 944  * \param renderer the renderer from which clip state should be queried
 945  * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call
 946  *          SDL_GetError() for more information.
 947  *
 948  * \since This function is available since SDL 2.0.4.
 949  *
 950  * \sa SDL_RenderGetClipRect
 951  * \sa SDL_RenderSetClipRect
 952  */
 953 extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer);
 954
 955
 956 /**
 957  * Set the drawing scale for rendering on the current target.
 958  *
 959  * The drawing coordinates are scaled by the x/y scaling factors before they
 960  * are used by the renderer. This allows resolution independent drawing with a
 961  * single coordinate system.
 962  *
 963  * If this results in scaling or subpixel drawing by the rendering backend, it
 964  * will be handled using the appropriate quality hints. For best results use
 965  * integer scaling factors.
 966  *
 967  * \param renderer a rendering context
 968  * \param scaleX the horizontal scaling factor
 969  * \param scaleY the vertical scaling factor
 970  * \returns 0 on success or a negative error code on failure; call
 971  *          SDL_GetError() for more information.
 972  *
 973  * \since This function is available since SDL 2.0.0.
 974  *
 975  * \sa SDL_RenderGetScale
 976  * \sa SDL_RenderSetLogicalSize
 977  */
 978 extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer,
 979                                                float scaleX, float scaleY);
 980
 981 /**
 982  * Get the drawing scale for the current target.
 983  *
 984  * \param renderer the renderer from which drawing scale should be queried
 985  * \param scaleX a pointer filled in with the horizontal scaling factor
 986  * \param scaleY a pointer filled in with the vertical scaling factor
 987  *
 988  * \since This function is available since SDL 2.0.0.
 989  *
 990  * \sa SDL_RenderSetScale
 991  */
 992 extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
 993                                                float *scaleX, float *scaleY);
 994
 995 /**
 996  * Get logical coordinates of point in renderer when given real coordinates of
 997  * point in window.
 998  *
 999  * Logical coordinates will differ from real coordinates when render is scaled
1000  * and logical renderer size set
1001  *
1002  * \param renderer the renderer from which the logical coordinates should be
1003  *                 calcualted
1004  * \param windowX the real X coordinate in the window
1005  * \param windowY the real Y coordinate in the window
1006  * \param logicalX the pointer filled with the logical x coordinate
1007  * \param logicalY the pointer filled with the logical y coordinate
1008  *
1009  * \since This function is available since SDL 2.0.18.
1010  *
1011  * \sa SDL_RenderGetScale
1012  * \sa SDL_RenderSetScale
1013  * \sa SDL_RenderGetLogicalSize
1014  * \sa SDL_RenderSetLogicalSize
1015  */
1016 extern DECLSPEC void SDLCALL SDL_RenderWindowToLogical(SDL_Renderer * renderer,
1017                                                             int windowX, int windowY,
1018                                                             float *logicalX, float *logicalY);
1019
1020                                                   /**
1021  * Get real coordinates of point in window when given logical coordinates of point in renderer.
1022  * Logical coordinates will differ from real coordinates when render is scaled and logical renderer size set
1023  *
1024  * \param renderer the renderer from which the window coordinates should be calculated
1025  * \param logicalX the logical x coordinate
1026  * \param logicalY the logical y coordinate
1027  * \param windowX the pointer filled with the real X coordinate in the window
1028  * \param windowY the pointer filled with the real Y coordinate in the window
1029
1030  *
1031  * \since This function is available since SDL 2.0.18.
1032  *
1033  * \sa SDL_RenderGetScale
1034  * \sa SDL_RenderSetScale
1035  * \sa SDL_RenderGetLogicalSize
1036  * \sa SDL_RenderSetLogicalSize
1037  */
1038 extern DECLSPEC void SDLCALL SDL_RenderLogicalToWindow(SDL_Renderer * renderer,
1039                                                             float logicalX, float logicalY,
1040                                                             int *windowX, int *windowY);
1041
1042 /**
1043  * Set the color used for drawing operations (Rect, Line and Clear).
1044  *
1045  * Set the color for drawing or filling rectangles, lines, and points, and for
1046  * SDL_RenderClear().
1047  *
1048  * \param renderer the rendering context
1049  * \param r the red value used to draw on the rendering target
1050  * \param g the green value used to draw on the rendering target
1051  * \param b the blue value used to draw on the rendering target
1052  * \param a the alpha value used to draw on the rendering target; usually
1053  *          `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
1054  *          specify how the alpha channel is used
1055  * \returns 0 on success or a negative error code on failure; call
1056  *          SDL_GetError() for more information.
1057  *
1058  * \since This function is available since SDL 2.0.0.
1059  *
1060  * \sa SDL_GetRenderDrawColor
1061  * \sa SDL_RenderClear
1062  * \sa SDL_RenderDrawLine
1063  * \sa SDL_RenderDrawLines
1064  * \sa SDL_RenderDrawPoint
1065  * \sa SDL_RenderDrawPoints
1066  * \sa SDL_RenderDrawRect
1067  * \sa SDL_RenderDrawRects
1068  * \sa SDL_RenderFillRect
1069  * \sa SDL_RenderFillRects
1070  */
1071 extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer,
1072                                            Uint8 r, Uint8 g, Uint8 b,
1073                                            Uint8 a);
1074
1075 /**
1076  * Get the color used for drawing operations (Rect, Line and Clear).
1077  *
1078  * \param renderer the rendering context
1079  * \param r a pointer filled in with the red value used to draw on the
1080  *          rendering target
1081  * \param g a pointer filled in with the green value used to draw on the
1082  *          rendering target
1083  * \param b a pointer filled in with the blue value used to draw on the
1084  *          rendering target
1085  * \param a a pointer filled in with the alpha value used to draw on the
1086  *          rendering target; usually `SDL_ALPHA_OPAQUE` (255)
1087  * \returns 0 on success or a negative error code on failure; call
1088  *          SDL_GetError() for more information.
1089  *
1090  * \since This function is available since SDL 2.0.0.
1091  *
1092  * \sa SDL_SetRenderDrawColor
1093  */
1094 extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer,
1095                                            Uint8 * r, Uint8 * g, Uint8 * b,
1096                                            Uint8 * a);
1097
1098 /**
1099  * Set the blend mode used for drawing operations (Fill and Line).
1100  *
1101  * If the blend mode is not supported, the closest supported mode is chosen.
1102  *
1103  * \param renderer the rendering context
1104  * \param blendMode the SDL_BlendMode to use for blending
1105  * \returns 0 on success or a negative error code on failure; call
1106  *          SDL_GetError() for more information.
1107  *
1108  * \since This function is available since SDL 2.0.0.
1109  *
1110  * \sa SDL_GetRenderDrawBlendMode
1111  * \sa SDL_RenderDrawLine
1112  * \sa SDL_RenderDrawLines
1113  * \sa SDL_RenderDrawPoint
1114  * \sa SDL_RenderDrawPoints
1115  * \sa SDL_RenderDrawRect
1116  * \sa SDL_RenderDrawRects
1117  * \sa SDL_RenderFillRect
1118  * \sa SDL_RenderFillRects
1119  */
1120 extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer,
1121                                                        SDL_BlendMode blendMode);
1122
1123 /**
1124  * Get the blend mode used for drawing operations.
1125  *
1126  * \param renderer the rendering context
1127  * \param blendMode a pointer filled in with the current SDL_BlendMode
1128  * \returns 0 on success or a negative error code on failure; call
1129  *          SDL_GetError() for more information.
1130  *
1131  * \since This function is available since SDL 2.0.0.
1132  *
1133  * \sa SDL_SetRenderDrawBlendMode
1134  */
1135 extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer,
1136                                                        SDL_BlendMode *blendMode);
1137
1138 /**
1139  * Clear the current rendering target with the drawing color.
1140  *
1141  * This function clears the entire rendering target, ignoring the viewport and
1142  * the clip rectangle.
1143  *
1144  * \param renderer the rendering context
1145  * \returns 0 on success or a negative error code on failure; call
1146  *          SDL_GetError() for more information.
1147  *
1148  * \since This function is available since SDL 2.0.0.
1149  *
1150  * \sa SDL_SetRenderDrawColor
1151  */
1152 extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer);
1153
1154 /**
1155  * Draw a point on the current rendering target.
1156  *
1157  * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple,
1158  * use SDL_RenderDrawPoints() instead.
1159  *
1160  * \param renderer the rendering context
1161  * \param x the x coordinate of the point
1162  * \param y the y coordinate of the point
1163  * \returns 0 on success or a negative error code on failure; call
1164  *          SDL_GetError() for more information.
1165  *
1166  * \since This function is available since SDL 2.0.0.
1167  *
1168  * \sa SDL_RenderDrawLine
1169  * \sa SDL_RenderDrawLines
1170  * \sa SDL_RenderDrawPoints
1171  * \sa SDL_RenderDrawRect
1172  * \sa SDL_RenderDrawRects
1173  * \sa SDL_RenderFillRect
1174  * \sa SDL_RenderFillRects
1175  * \sa SDL_RenderPresent
1176  * \sa SDL_SetRenderDrawBlendMode
1177  * \sa SDL_SetRenderDrawColor
1178  */
1179 extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer,
1180                                                 int x, int y);
1181
1182 /**
1183  * Draw multiple points on the current rendering target.
1184  *
1185  * \param renderer the rendering context
1186  * \param points an array of SDL_Point structures that represent the points to
1187  *               draw
1188  * \param count the number of points to draw
1189  * \returns 0 on success or a negative error code on failure; call
1190  *          SDL_GetError() for more information.
1191  *
1192  * \since This function is available since SDL 2.0.0.
1193  *
1194  * \sa SDL_RenderDrawLine
1195  * \sa SDL_RenderDrawLines
1196  * \sa SDL_RenderDrawPoint
1197  * \sa SDL_RenderDrawRect
1198  * \sa SDL_RenderDrawRects
1199  * \sa SDL_RenderFillRect
1200  * \sa SDL_RenderFillRects
1201  * \sa SDL_RenderPresent
1202  * \sa SDL_SetRenderDrawBlendMode
1203  * \sa SDL_SetRenderDrawColor
1204  */
1205 extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer,
1206                                                  const SDL_Point * points,
1207                                                  int count);
1208
1209 /**
1210  * Draw a line on the current rendering target.
1211  *
1212  * SDL_RenderDrawLine() draws the line to include both end points. If you want
1213  * to draw multiple, connecting lines use SDL_RenderDrawLines() instead.
1214  *
1215  * \param renderer the rendering context
1216  * \param x1 the x coordinate of the start point
1217  * \param y1 the y coordinate of the start point
1218  * \param x2 the x coordinate of the end point
1219  * \param y2 the y coordinate of the end point
1220  * \returns 0 on success or a negative error code on failure; call
1221  *          SDL_GetError() for more information.
1222  *
1223  * \since This function is available since SDL 2.0.0.
1224  *
1225  * \sa SDL_RenderDrawLines
1226  * \sa SDL_RenderDrawPoint
1227  * \sa SDL_RenderDrawPoints
1228  * \sa SDL_RenderDrawRect
1229  * \sa SDL_RenderDrawRects
1230  * \sa SDL_RenderFillRect
1231  * \sa SDL_RenderFillRects
1232  * \sa SDL_RenderPresent
1233  * \sa SDL_SetRenderDrawBlendMode
1234  * \sa SDL_SetRenderDrawColor
1235  */
1236 extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer,
1237                                                int x1, int y1, int x2, int y2);
1238
1239 /**
1240  * Draw a series of connected lines on the current rendering target.
1241  *
1242  * \param renderer the rendering context
1243  * \param points an array of SDL_Point structures representing points along
1244  *               the lines
1245  * \param count the number of points, drawing count-1 lines
1246  * \returns 0 on success or a negative error code on failure; call
1247  *          SDL_GetError() for more information.
1248  *
1249  * \since This function is available since SDL 2.0.0.
1250  *
1251  * \sa SDL_RenderDrawLine
1252  * \sa SDL_RenderDrawPoint
1253  * \sa SDL_RenderDrawPoints
1254  * \sa SDL_RenderDrawRect
1255  * \sa SDL_RenderDrawRects
1256  * \sa SDL_RenderFillRect
1257  * \sa SDL_RenderFillRects
1258  * \sa SDL_RenderPresent
1259  * \sa SDL_SetRenderDrawBlendMode
1260  * \sa SDL_SetRenderDrawColor
1261  */
1262 extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer,
1263                                                 const SDL_Point * points,
1264                                                 int count);
1265
1266 /**
1267  * Draw a rectangle on the current rendering target.
1268  *
1269  * \param renderer the rendering context
1270  * \param rect an SDL_Rect structure representing the rectangle to draw, or
1271  *             NULL to outline the entire rendering target
1272  * \returns 0 on success or a negative error code on failure; call
1273  *          SDL_GetError() for more information.
1274  *
1275  * \since This function is available since SDL 2.0.0.
1276  *
1277  * \sa SDL_RenderDrawLine
1278  * \sa SDL_RenderDrawLines
1279  * \sa SDL_RenderDrawPoint
1280  * \sa SDL_RenderDrawPoints
1281  * \sa SDL_RenderDrawRects
1282  * \sa SDL_RenderFillRect
1283  * \sa SDL_RenderFillRects
1284  * \sa SDL_RenderPresent
1285  * \sa SDL_SetRenderDrawBlendMode
1286  * \sa SDL_SetRenderDrawColor
1287  */
1288 extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer,
1289                                                const SDL_Rect * rect);
1290
1291 /**
1292  * Draw some number of rectangles on the current rendering target.
1293  *
1294  * \param renderer the rendering context
1295  * \param rects an array of SDL_Rect structures representing the rectangles to
1296  *              be drawn
1297  * \param count the number of rectangles
1298  * \returns 0 on success or a negative error code on failure; call
1299  *          SDL_GetError() for more information.
1300  *
1301  * \since This function is available since SDL 2.0.0.
1302  *
1303  * \sa SDL_RenderDrawLine
1304  * \sa SDL_RenderDrawLines
1305  * \sa SDL_RenderDrawPoint
1306  * \sa SDL_RenderDrawPoints
1307  * \sa SDL_RenderDrawRect
1308  * \sa SDL_RenderFillRect
1309  * \sa SDL_RenderFillRects
1310  * \sa SDL_RenderPresent
1311  * \sa SDL_SetRenderDrawBlendMode
1312  * \sa SDL_SetRenderDrawColor
1313  */
1314 extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer,
1315                                                 const SDL_Rect * rects,
1316                                                 int count);
1317
1318 /**
1319  * Fill a rectangle on the current rendering target with the drawing color.
1320  *
1321  * The current drawing color is set by SDL_SetRenderDrawColor(), and the
1322  * color's alpha value is ignored unless blending is enabled with the
1323  * appropriate call to SDL_SetRenderDrawBlendMode().
1324  *
1325  * \param renderer the rendering context
1326  * \param rect the SDL_Rect structure representing the rectangle to fill, or
1327  *             NULL for the entire rendering target
1328  * \returns 0 on success or a negative error code on failure; call
1329  *          SDL_GetError() for more information.
1330  *
1331  * \since This function is available since SDL 2.0.0.
1332  *
1333  * \sa SDL_RenderDrawLine
1334  * \sa SDL_RenderDrawLines
1335  * \sa SDL_RenderDrawPoint
1336  * \sa SDL_RenderDrawPoints
1337  * \sa SDL_RenderDrawRect
1338  * \sa SDL_RenderDrawRects
1339  * \sa SDL_RenderFillRects
1340  * \sa SDL_RenderPresent
1341  * \sa SDL_SetRenderDrawBlendMode
1342  * \sa SDL_SetRenderDrawColor
1343  */
1344 extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer,
1345                                                const SDL_Rect * rect);
1346
1347 /**
1348  * Fill some number of rectangles on the current rendering target with the
1349  * drawing color.
1350  *
1351  * \param renderer the rendering context
1352  * \param rects an array of SDL_Rect structures representing the rectangles to
1353  *              be filled
1354  * \param count the number of rectangles
1355  * \returns 0 on success or a negative error code on failure; call
1356  *          SDL_GetError() for more information.
1357  *
1358  * \since This function is available since SDL 2.0.0.
1359  *
1360  * \sa SDL_RenderDrawLine
1361  * \sa SDL_RenderDrawLines
1362  * \sa SDL_RenderDrawPoint
1363  * \sa SDL_RenderDrawPoints
1364  * \sa SDL_RenderDrawRect
1365  * \sa SDL_RenderDrawRects
1366  * \sa SDL_RenderFillRect
1367  * \sa SDL_RenderPresent
1368  */
1369 extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer,
1370                                                 const SDL_Rect * rects,
1371                                                 int count);
1372
1373 /**
1374  * Copy a portion of the texture to the current rendering target.
1375  *
1376  * The texture is blended with the destination based on its blend mode set
1377  * with SDL_SetTextureBlendMode().
1378  *
1379  * The texture color is affected based on its color modulation set by
1380  * SDL_SetTextureColorMod().
1381  *
1382  * The texture alpha is affected based on its alpha modulation set by
1383  * SDL_SetTextureAlphaMod().
1384  *
1385  * \param renderer the rendering context
1386  * \param texture the source texture
1387  * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1388  * \param dstrect the destination SDL_Rect structure or NULL for the entire
1389  *                rendering target; the texture will be stretched to fill the
1390  *                given rectangle
1391  * \returns 0 on success or a negative error code on failure; call
1392  *          SDL_GetError() for more information.
1393  *
1394  * \since This function is available since SDL 2.0.0.
1395  *
1396  * \sa SDL_RenderCopyEx
1397  * \sa SDL_SetTextureAlphaMod
1398  * \sa SDL_SetTextureBlendMode
1399  * \sa SDL_SetTextureColorMod
1400  */
1401 extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
1402                                            SDL_Texture * texture,
1403                                            const SDL_Rect * srcrect,
1404                                            const SDL_Rect * dstrect);
1405
1406 /**
1407  * Copy a portion of the texture to the current rendering, with optional
1408  * rotation and flipping.
1409  *
1410  * Copy a portion of the texture to the current rendering target, optionally
1411  * rotating it by angle around the given center and also flipping it
1412  * top-bottom and/or left-right.
1413  *
1414  * The texture is blended with the destination based on its blend mode set
1415  * with SDL_SetTextureBlendMode().
1416  *
1417  * The texture color is affected based on its color modulation set by
1418  * SDL_SetTextureColorMod().
1419  *
1420  * The texture alpha is affected based on its alpha modulation set by
1421  * SDL_SetTextureAlphaMod().
1422  *
1423  * \param renderer the rendering context
1424  * \param texture the source texture
1425  * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1426  * \param dstrect the destination SDL_Rect structure or NULL for the entire
1427  *                rendering target
1428  * \param angle an angle in degrees that indicates the rotation that will be
1429  *              applied to dstrect, rotating it in a clockwise direction
1430  * \param center a pointer to a point indicating the point around which
1431  *               dstrect will be rotated (if NULL, rotation will be done
1432  *               around `dstrect.w / 2`, `dstrect.h / 2`)
1433  * \param flip a SDL_RendererFlip value stating which flipping actions should
1434  *             be performed on the texture
1435  * \returns 0 on success or a negative error code on failure; call
1436  *          SDL_GetError() for more information.
1437  *
1438  * \since This function is available since SDL 2.0.0.
1439  *
1440  * \sa SDL_RenderCopy
1441  * \sa SDL_SetTextureAlphaMod
1442  * \sa SDL_SetTextureBlendMode
1443  * \sa SDL_SetTextureColorMod
1444  */
1445 extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
1446                                            SDL_Texture * texture,
1447                                            const SDL_Rect * srcrect,
1448                                            const SDL_Rect * dstrect,
1449                                            const double angle,
1450                                            const SDL_Point *center,
1451                                            const SDL_RendererFlip flip);
1452
1453
1454 /**
1455  * Draw a point on the current rendering target at subpixel precision.
1456  *
1457  * \param renderer The renderer which should draw a point.
1458  * \param x The x coordinate of the point.
1459  * \param y The y coordinate of the point.
1460  * \return 0 on success, or -1 on error
1461  *
1462  * \since This function is available since SDL 2.0.10.
1463  */
1464 extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer,
1465                                                  float x, float y);
1466
1467 /**
1468  * Draw multiple points on the current rendering target at subpixel precision.
1469  *
1470  * \param renderer The renderer which should draw multiple points.
1471  * \param points The points to draw
1472  * \param count The number of points to draw
1473  * \return 0 on success, or -1 on error
1474  *
1475  * \since This function is available since SDL 2.0.10.
1476  */
1477 extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer,
1478                                                   const SDL_FPoint * points,
1479                                                   int count);
1480
1481 /**
1482  * Draw a line on the current rendering target at subpixel precision.
1483  *
1484  * \param renderer The renderer which should draw a line.
1485  * \param x1 The x coordinate of the start point.
1486  * \param y1 The y coordinate of the start point.
1487  * \param x2 The x coordinate of the end point.
1488  * \param y2 The y coordinate of the end point.
1489  * \return 0 on success, or -1 on error
1490  *
1491  * \since This function is available since SDL 2.0.10.
1492  */
1493 extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer,
1494                                                 float x1, float y1, float x2, float y2);
1495
1496 /**
1497  * Draw a series of connected lines on the current rendering target at
1498  * subpixel precision.
1499  *
1500  * \param renderer The renderer which should draw multiple lines.
1501  * \param points The points along the lines
1502  * \param count The number of points, drawing count-1 lines
1503  * \return 0 on success, or -1 on error
1504  *
1505  * \since This function is available since SDL 2.0.10.
1506  */
1507 extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
1508                                                  const SDL_FPoint * points,
1509                                                  int count);
1510
1511 /**
1512  * Draw a rectangle on the current rendering target at subpixel precision.
1513  *
1514  * \param renderer The renderer which should draw a rectangle.
1515  * \param rect A pointer to the destination rectangle, or NULL to outline the
1516  *             entire rendering target.
1517  * \return 0 on success, or -1 on error
1518  *
1519  * \since This function is available since SDL 2.0.10.
1520  */
1521 extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
1522                                                 const SDL_FRect * rect);
1523
1524 /**
1525  * Draw some number of rectangles on the current rendering target at subpixel
1526  * precision.
1527  *
1528  * \param renderer The renderer which should draw multiple rectangles.
1529  * \param rects A pointer to an array of destination rectangles.
1530  * \param count The number of rectangles.
1531  * \return 0 on success, or -1 on error
1532  *
1533  * \since This function is available since SDL 2.0.10.
1534  */
1535 extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
1536                                                  const SDL_FRect * rects,
1537                                                  int count);
1538
1539 /**
1540  * Fill a rectangle on the current rendering target with the drawing color at
1541  * subpixel precision.
1542  *
1543  * \param renderer The renderer which should fill a rectangle.
1544  * \param rect A pointer to the destination rectangle, or NULL for the entire
1545  *             rendering target.
1546  * \return 0 on success, or -1 on error
1547  *
1548  * \since This function is available since SDL 2.0.10.
1549  */
1550 extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer,
1551                                                 const SDL_FRect * rect);
1552
1553 /**
1554  * Fill some number of rectangles on the current rendering target with the
1555  * drawing color at subpixel precision.
1556  *
1557  * \param renderer The renderer which should fill multiple rectangles.
1558  * \param rects A pointer to an array of destination rectangles.
1559  * \param count The number of rectangles.
1560  * \return 0 on success, or -1 on error
1561  *
1562  * \since This function is available since SDL 2.0.10.
1563  */
1564 extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer,
1565                                                  const SDL_FRect * rects,
1566                                                  int count);
1567
1568 /**
1569  * Copy a portion of the texture to the current rendering target at subpixel
1570  * precision.
1571  *
1572  * \param renderer The renderer which should copy parts of a texture.
1573  * \param texture The source texture.
1574  * \param srcrect A pointer to the source rectangle, or NULL for the entire
1575  *                texture.
1576  * \param dstrect A pointer to the destination rectangle, or NULL for the
1577  *                entire rendering target.
1578  * \return 0 on success, or -1 on error
1579  *
1580  * \since This function is available since SDL 2.0.10.
1581  */
1582 extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
1583                                             SDL_Texture * texture,
1584                                             const SDL_Rect * srcrect,
1585                                             const SDL_FRect * dstrect);
1586
1587 /**
1588  * Copy a portion of the source texture to the current rendering target, with
1589  * rotation and flipping, at subpixel precision.
1590  *
1591  * \param renderer The renderer which should copy parts of a texture.
1592  * \param texture The source texture.
1593  * \param srcrect A pointer to the source rectangle, or NULL for the entire
1594  *                texture.
1595  * \param dstrect A pointer to the destination rectangle, or NULL for the
1596  *                entire rendering target.
1597  * \param angle An angle in degrees that indicates the rotation that will be
1598  *              applied to dstrect, rotating it in a clockwise direction
1599  * \param center A pointer to a point indicating the point around which
1600  *               dstrect will be rotated (if NULL, rotation will be done
1601  *               around dstrect.w/2, dstrect.h/2).
1602  * \param flip An SDL_RendererFlip value stating which flipping actions should
1603  *             be performed on the texture
1604  * \return 0 on success, or -1 on error
1605  *
1606  * \since This function is available since SDL 2.0.10.
1607  */
1608 extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
1609                                             SDL_Texture * texture,
1610                                             const SDL_Rect * srcrect,
1611                                             const SDL_FRect * dstrect,
1612                                             const double angle,
1613                                             const SDL_FPoint *center,
1614                                             const SDL_RendererFlip flip);
1615
1616 /**
1617  * Render a list of triangles, optionally using a texture and indices into the
1618  * vertex array Color and alpha modulation is done per vertex
1619  * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1620  *
1621  * \param renderer The rendering context.
1622  * \param texture (optional) The SDL texture to use.
1623  * \param vertices Vertices.
1624  * \param num_vertices Number of vertices.
1625  * \param indices (optional) An array of integer indices into the 'vertices'
1626  *                array, if NULL all vertices will be rendered in sequential
1627  *                order.
1628  * \param num_indices Number of indices.
1629  * \return 0 on success, or -1 if the operation is not supported
1630  *
1631  * \since This function is available since SDL 2.0.18.
1632  *
1633  * \sa SDL_RenderGeometryRaw
1634  * \sa SDL_Vertex
1635  */
1636 extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
1637                                                SDL_Texture *texture,
1638                                                const SDL_Vertex *vertices, int num_vertices,
1639                                                const int *indices, int num_indices);
1640
1641 /**
1642  * Render a list of triangles, optionally using a texture and indices into the
1643  * vertex arrays Color and alpha modulation is done per vertex
1644  * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1645  *
1646  * \param renderer The rendering context.
1647  * \param texture (optional) The SDL texture to use.
1648  * \param xy Vertex positions
1649  * \param xy_stride Byte size to move from one element to the next element
1650  * \param color Vertex colors (as SDL_Color)
1651  * \param color_stride Byte size to move from one element to the next element
1652  * \param uv Vertex normalized texture coordinates
1653  * \param uv_stride Byte size to move from one element to the next element
1654  * \param num_vertices Number of vertices.
1655  * \param indices (optional) An array of indices into the 'vertices' arrays,
1656  *                if NULL all vertices will be rendered in sequential order.
1657  * \param num_indices Number of indices.
1658  * \param size_indices Index size: 1 (byte), 2 (short), 4 (int)
1659  * \return 0 on success, or -1 if the operation is not supported
1660  *
1661  * \since This function is available since SDL 2.0.18.
1662  *
1663  * \sa SDL_RenderGeometry
1664  * \sa SDL_Vertex
1665  */
1666 extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer,
1667                                                SDL_Texture *texture,
1668                                                const float *xy, int xy_stride,
1669                                                const SDL_Color *color, int color_stride,
1670                                                const float *uv, int uv_stride,
1671                                                int num_vertices,
1672                                                const void *indices, int num_indices, int size_indices);
1673
1674 /**
1675  * Read pixels from the current rendering target to an array of pixels.
1676  *
1677  * **WARNING**: This is a very slow operation, and should not be used
1678  * frequently. If you're using this on the main rendering target, it should be
1679  * called after rendering and before SDL_RenderPresent().
1680  *
1681  * `pitch` specifies the number of bytes between rows in the destination
1682  * `pixels` data. This allows you to write to a subrectangle or have padded
1683  * rows in the destination. Generally, `pitch` should equal the number of
1684  * pixels per row in the `pixels` data times the number of bytes per pixel,
1685  * but it might contain additional padding (for example, 24bit RGB Windows
1686  * Bitmap data pads all rows to multiples of 4 bytes).
1687  *
1688  * \param renderer the rendering context
1689  * \param rect an SDL_Rect structure representing the area to read, or NULL
1690  *             for the entire render target
1691  * \param format an SDL_PixelFormatEnum value of the desired format of the
1692  *               pixel data, or 0 to use the format of the rendering target
1693  * \param pixels a pointer to the pixel data to copy into
1694  * \param pitch the pitch of the `pixels` parameter
1695  * \returns 0 on success or a negative error code on failure; call
1696  *          SDL_GetError() for more information.
1697  *
1698  * \since This function is available since SDL 2.0.0.
1699  */
1700 extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
1701                                                  const SDL_Rect * rect,
1702                                                  Uint32 format,
1703                                                  void *pixels, int pitch);
1704
1705 /**
1706  * Update the screen with any rendering performed since the previous call.
1707  *
1708  * SDL's rendering functions operate on a backbuffer; that is, calling a
1709  * rendering function such as SDL_RenderDrawLine() does not directly put a
1710  * line on the screen, but rather updates the backbuffer. As such, you compose
1711  * your entire scene and *present* the composed backbuffer to the screen as a
1712  * complete picture.
1713  *
1714  * Therefore, when using SDL's rendering API, one does all drawing intended
1715  * for the frame, and then calls this function once per frame to present the
1716  * final drawing to the user.
1717  *
1718  * The backbuffer should be considered invalidated after each present; do not
1719  * assume that previous contents will exist between frames. You are strongly
1720  * encouraged to call SDL_RenderClear() to initialize the backbuffer before
1721  * starting each new frame's drawing, even if you plan to overwrite every
1722  * pixel.
1723  *
1724  * \param renderer the rendering context
1725  *
1726  * \since This function is available since SDL 2.0.0.
1727  *
1728  * \sa SDL_RenderClear
1729  * \sa SDL_RenderDrawLine
1730  * \sa SDL_RenderDrawLines
1731  * \sa SDL_RenderDrawPoint
1732  * \sa SDL_RenderDrawPoints
1733  * \sa SDL_RenderDrawRect
1734  * \sa SDL_RenderDrawRects
1735  * \sa SDL_RenderFillRect
1736  * \sa SDL_RenderFillRects
1737  * \sa SDL_SetRenderDrawBlendMode
1738  * \sa SDL_SetRenderDrawColor
1739  */
1740 extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer);
1741
1742 /**
1743  * Destroy the specified texture.
1744  *
1745  * Passing NULL or an otherwise invalid texture will set the SDL error message
1746  * to "Invalid texture".
1747  *
1748  * \param texture the texture to destroy
1749  *
1750  * \since This function is available since SDL 2.0.0.
1751  *
1752  * \sa SDL_CreateTexture
1753  * \sa SDL_CreateTextureFromSurface
1754  */
1755 extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture);
1756
1757 /**
1758  * Destroy the rendering context for a window and free associated textures.
1759  *
1760  * \param renderer the rendering context
1761  *
1762  * \since This function is available since SDL 2.0.0.
1763  *
1764  * \sa SDL_CreateRenderer
1765  */
1766 extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
1767
1768 /**
1769  * Force the rendering context to flush any pending commands to the underlying
1770  * rendering API.
1771  *
1772  * You do not need to (and in fact, shouldn't) call this function unless you
1773  * are planning to call into OpenGL/Direct3D/Metal/whatever directly in
1774  * addition to using an SDL_Renderer.
1775  *
1776  * This is for a very-specific case: if you are using SDL's render API, you
1777  * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
1778  * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever
1779  * calls in addition to SDL render API calls. If all of this applies, you
1780  * should call SDL_RenderFlush() between calls to SDL's render API and the
1781  * low-level API you're using in cooperation.
1782  *
1783  * In all other cases, you can ignore this function. This is only here to get
1784  * maximum performance out of a specific situation. In all other cases, SDL
1785  * will do the right thing, perhaps at a performance loss.
1786  *
1787  * This function is first available in SDL 2.0.10, and is not needed in 2.0.9
1788  * and earlier, as earlier versions did not queue rendering commands at all,
1789  * instead flushing them to the OS immediately.
1790  *
1791  * \param renderer the rendering context
1792  * \returns 0 on success or a negative error code on failure; call
1793  *          SDL_GetError() for more information.
1794  *
1795  * \since This function is available since SDL 2.0.10.
1796  */
1797 extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer);
1798
1799
1800 /**
1801  * Bind an OpenGL/ES/ES2 texture to the current context.
1802  *
1803  * This is for use with OpenGL instructions when rendering OpenGL primitives
1804  * directly.
1805  *
1806  * If not NULL, `texw` and `texh` will be filled with the width and height
1807  * values suitable for the provided texture. In most cases, both will be 1.0,
1808  * however, on systems that support the GL_ARB_texture_rectangle extension,
1809  * these values will actually be the pixel width and height used to create the
1810  * texture, so this factor needs to be taken into account when providing
1811  * texture coordinates to OpenGL.
1812  *
1813  * You need a renderer to create an SDL_Texture, therefore you can only use
1814  * this function with an implicit OpenGL context from SDL_CreateRenderer(),
1815  * not with your own OpenGL context. If you need control over your OpenGL
1816  * context, you need to write your own texture-loading methods.
1817  *
1818  * Also note that SDL may upload RGB textures as BGR (or vice-versa), and
1819  * re-order the color channels in the shaders phase, so the uploaded texture
1820  * may have swapped color channels.
1821  *
1822  * \param texture the texture to bind to the current OpenGL/ES/ES2 context
1823  * \param texw a pointer to a float value which will be filled with the
1824  *             texture width or NULL if you don't need that value
1825  * \param texh a pointer to a float value which will be filled with the
1826  *             texture height or NULL if you don't need that value
1827  * \returns 0 on success, or -1 if the operation is not supported; call
1828  *          SDL_GetError() for more information.
1829  *
1830  * \since This function is available since SDL 2.0.0.
1831  *
1832  * \sa SDL_GL_MakeCurrent
1833  * \sa SDL_GL_UnbindTexture
1834  */
1835 extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh);
1836
1837 /**
1838  * Unbind an OpenGL/ES/ES2 texture from the current context.
1839  *
1840  * See SDL_GL_BindTexture() for examples on how to use these functions
1841  *
1842  * \param texture the texture to unbind from the current OpenGL/ES/ES2 context
1843  * \returns 0 on success, or -1 if the operation is not supported
1844  *
1845  * \since This function is available since SDL 2.0.0.
1846  *
1847  * \sa SDL_GL_BindTexture
1848  * \sa SDL_GL_MakeCurrent
1849  */
1850 extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
1851
1852 /**
1853  * Get the CAMetalLayer associated with the given Metal renderer.
1854  *
1855  * This function returns `void *`, so SDL doesn't have to include Metal's
1856  * headers, but it can be safely cast to a `CAMetalLayer *`.
1857  *
1858  * \param renderer The renderer to query
1859  * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
1860  *          Metal renderer
1861  *
1862  * \since This function is available since SDL 2.0.8.
1863  *
1864  * \sa SDL_RenderGetMetalCommandEncoder
1865  */
1866 extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
1867
1868 /**
1869  * Get the Metal command encoder for the current frame
1870  *
1871  * This function returns `void *`, so SDL doesn't have to include Metal's
1872  * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
1873  *
1874  * Note that as of SDL 2.0.18, this will return NULL if Metal refuses to give
1875  * SDL a drawable to render to, which might happen if the window is
1876  * hidden/minimized/offscreen. This doesn't apply to command encoders for
1877  * render targets, just the window's backbacker. Check your return values!
1878  *
1879  * \param renderer The renderer to query
1880  * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
1881  *          renderer isn't a Metal renderer or there was an error.
1882  *
1883  * \since This function is available since SDL 2.0.8.
1884  *
1885  * \sa SDL_RenderGetMetalLayer
1886  */
1887 extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer);
1888
1889 /**
1890  * Toggle VSync of the given renderer.
1891  *
1892  * \param renderer The renderer to toggle
1893  * \param vsync 1 for on, 0 for off. All other values are reserved
1894  * \returns a 0 int on success, or non-zero on failure
1895  *
1896  * \since This function is available since SDL 2.0.18.
1897  */
1898 extern DECLSPEC int SDLCALL SDL_RenderSetVSync(SDL_Renderer* renderer, int vsync);
1899
1900 /* Ends C function definitions when using C++ */
1901 #ifdef __cplusplus
1902 }
1903 #endif
1904 #include "close_code.h"
1905
1906 #endif /* SDL_render_h_ */
1907
1908 /* vi: set ts=4 sw=4 expandtab: */