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