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