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
58extern "C" {
59#endif
60
61/**
62 * Flags used when creating a rendering context
63 */
64typedef enum
65{
66 SDL_RENDERER_SOFTWARE = 0x00000001, /**< The renderer is a software fallback */
67 SDL_RENDERER_ACCELERATED = 0x00000002, /**< The renderer uses hardware
68 acceleration */
69 SDL_RENDERER_PRESENTVSYNC = 0x00000004, /**< Present is synchronized
70 with the refresh rate */
71 SDL_RENDERER_TARGETTEXTURE = 0x00000008 /**< The renderer supports
72 rendering to texture */
73} SDL_RendererFlags;
74
75/**
76 * Information on the capabilities of a render driver or context.
77 */
78typedef struct SDL_RendererInfo
79{
80 const char *name; /**< The name of the renderer */
81 Uint32 flags; /**< Supported ::SDL_RendererFlags */
82 Uint32 num_texture_formats; /**< The number of available texture formats */
83 Uint32 texture_formats[16]; /**< The available texture formats */
84 int max_texture_width; /**< The maximum texture width */
85 int max_texture_height; /**< The maximum texture height */
86} SDL_RendererInfo;
87
88/**
89 * The scaling mode for a texture.
90 */
91typedef enum
92{
93 SDL_ScaleModeNearest, /**< nearest pixel sampling */
94 SDL_ScaleModeLinear, /**< linear filtering */
95 SDL_ScaleModeBest /**< anisotropic filtering */
96} SDL_ScaleMode;
97
98/**
99 * The access pattern allowed for a texture.
100 */
101typedef 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 */
106} SDL_TextureAccess;
107
108/**
109 * The texture channel modulation used in SDL_RenderCopy().
110 */
111typedef 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 */
116} SDL_TextureModulate;
117
118/**
119 * Flip constants for SDL_RenderCopyEx
120 */
121typedef enum
122{
123 SDL_FLIP_NONE = 0x00000000, /**< Do not flip */
124 SDL_FLIP_HORIZONTAL = 0x00000001, /**< flip horizontally */
125 SDL_FLIP_VERTICAL = 0x00000002 /**< flip vertically */
126} SDL_RendererFlip;
127
128/**
129 * A structure representing rendering state
130 */
131struct SDL_Renderer;
132typedef struct SDL_Renderer SDL_Renderer;
133
134/**
135 * An efficient driver-specific representation of pixel data
136 */
137struct SDL_Texture;
138typedef 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 */
160extern 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 */
174extern 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 */
192extern 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 */
212extern 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 */
232extern 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 */
243extern 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 */
256extern 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 */
276extern 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 */
299extern 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 */
326extern 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 */
344extern 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 */
370extern 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 */
387extern 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 */
410extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture * texture,
411 Uint8 alpha);
412
413/**
414 * Get the additional alpha value multiplied into render
415 * copy operations.
416 *
417 * \param texture the texture to query
418 * \param alpha a pointer filled in with the current alpha value
419 * \returns 0 on success or a negative error code on failure; call
420 * SDL_GetError() for more information.
421 *
422 * \sa SDL_GetTextureColorMod
423 * \sa SDL_SetTextureAlphaMod
424 */
425extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture * texture,
426 Uint8 * alpha);
427
428/**
429 * Set the blend mode for a texture, used by
430 * SDL_RenderCopy().
431 *
432 * If the blend mode is not supported, the closest supported mode is chosen
433 * and this function returns -1.
434 *
435 * \param texture the texture to update
436 * \param blendMode the SDL_BlendMode to use for texture blending
437 * \returns 0 on success or a negative error code on failure; call
438 * SDL_GetError() for more information.
439 *
440 * \sa SDL_GetTextureBlendMode
441 * \sa SDL_RenderCopy
442 */
443extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture * texture,
444 SDL_BlendMode blendMode);
445
446/**
447 * Get the blend mode used for texture copy operations.
448 *
449 * \param texture the texture to query
450 * \param blendMode a pointer filled in with the current SDL_BlendMode
451 * \returns 0 on success or a negative error code on failure; call
452 * SDL_GetError() for more information.
453 *
454 * \sa SDL_SetTextureBlendMode
455 */
456extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture * texture,
457 SDL_BlendMode *blendMode);
458
459/**
460 * Set the scale mode used for texture scale operations.
461 *
462 * If the scale mode is not supported, the closest supported mode is chosen.
463 *
464 * \param texture The texture to update.
465 * \param scaleMode the SDL_ScaleMode to use for texture scaling.
466 * \returns 0 on success, or -1 if the texture is not valid.
467 *
468 * \sa SDL_GetTextureScaleMode()
469 */
470extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture * texture,
471 SDL_ScaleMode scaleMode);
472
473/**
474 * Get the scale mode used for texture scale operations.
475 *
476 * \param texture the texture to query.
477 * \param scaleMode a pointer filled in with the current scale mode.
478 * \return 0 on success, or -1 if the texture is not valid.
479 *
480 * \sa SDL_SetTextureScaleMode()
481 */
482extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture * texture,
483 SDL_ScaleMode *scaleMode);
484
485/**
486 * Update the given texture rectangle with new pixel data.
487 *
488 * The pixel data must be in the pixel format of the texture. Use
489 * SDL_QueryTexture() to query the pixel format of the texture.
490 *
491 * This is a fairly slow function, intended for use with static textures that
492 * do not change often.
493 *
494 * If the texture is intended to be updated often, it is preferred to create
495 * the texture as streaming and use the locking functions referenced below.
496 * While this function will work with streaming textures, for optimization
497 * reasons you may not get the pixels back if you lock the texture afterward.
498 *
499 * \param texture the texture to update
500 * \param rect an SDL_Rect structure representing the area to update, or NULL
501 * to update the entire texture
502 * \param pixels the raw pixel data in the format of the texture
503 * \param pitch the number of bytes in a row of pixel data, including padding
504 * between lines
505 * \returns 0 on success or a negative error code on failure; call
506 * SDL_GetError() for more information.
507 *
508 * \sa SDL_CreateTexture
509 * \sa SDL_LockTexture
510 * \sa SDL_UnlockTexture
511 */
512extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture * texture,
513 const SDL_Rect * rect,
514 const void *pixels, int pitch);
515
516/**
517 * Update a rectangle within a planar YV12 or IYUV
518 * texture with new pixel data.
519 *
520 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
521 * block of Y and U/V planes in the proper order, but this function is
522 * available if your pixel data is not contiguous.
523 *
524 * \param texture the texture to update
525 * \param rect a pointer to the rectangle of pixels to update, or NULL to
526 * update the entire texture
527 * \param Yplane the raw pixel data for the Y plane
528 * \param Ypitch the number of bytes between rows of pixel data for the Y
529 * plane
530 * \param Uplane the raw pixel data for the U plane
531 * \param Upitch the number of bytes between rows of pixel data for the U
532 * plane
533 * \param Vplane the raw pixel data for the V plane
534 * \param Vpitch the number of bytes between rows of pixel data for the V
535 * plane
536 * \returns 0 on success or -1 if the texture is not valid; call
537 * SDL_GetError() for more information.
538 *
539 * \since This function is available since SDL 2.0.1.
540 *
541 * \sa SDL_UpdateTexture
542 */
543extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture * texture,
544 const SDL_Rect * rect,
545 const Uint8 *Yplane, int Ypitch,
546 const Uint8 *Uplane, int Upitch,
547 const Uint8 *Vplane, int Vpitch);
548
549/**
550 * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
551 *
552 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
553 * block of NV12/21 planes in the proper order, but this function is available
554 * if your pixel data is not contiguous.
555 *
556 * \param texture the texture to update
557 * \param rect a pointer to the rectangle of pixels to update, or NULL to
558 * update the entire texture.
559 * \param Yplane the raw pixel data for the Y plane.
560 * \param Ypitch the number of bytes between rows of pixel data for the Y plane.
561 * \param UVplane the raw pixel data for the UV plane.
562 * \param UVpitch the number of bytes between rows of pixel data for the UV plane.
563 * \return 0 on success, or -1 if the texture is not valid.
564 */
565extern 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 */
595extern 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 */
629extern 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
642 * in corrupted textures, depending on the renderer in use.
643 *
644 * \param texture a texture locked by SDL_LockTexture()
645 *
646 * \sa SDL_LockTexture
647 */
648extern 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 */
660extern 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
667 * if 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
676 * to render to the 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 */
684extern 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 */
700extern 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.
713 *
714 * If this function results in scaling or subpixel drawing by the rendering
715 * backend, it will be handled using the appropriate quality hints.
716 *
717 * \param renderer the renderer for which resolution should be set
718 * \param w the width of the logical resolution
719 * \param h the height of the logical resolution
720 * \returns 0 on success or a negative error code on failure; call
721 * SDL_GetError() for more information.
722 *
723 * \since This function is available since SDL 2.0.0.
724 *
725 * \sa SDL_RenderGetLogicalSize
726 */
727extern DECLSPEC int SDLCALL SDL_RenderSetLogicalSize(SDL_Renderer * renderer, int w, int h);
728
729/**
730 * Get device independent resolution for rendering.
731 *
732 * This may return 0 for `w` and `h` if the SDL_Renderer has never had its
733 * logical size set by SDL_RenderSetLogicalSize() and never had a render
734 * target set.
735 *
736 * \param renderer a rendering context
737 * \param w an int to be filled with the width
738 * \param h an int to be filled with the height
739 *
740 * \since This function is available since SDL 2.0.0.
741 *
742 * \sa SDL_RenderSetLogicalSize
743 */
744extern DECLSPEC void SDLCALL SDL_RenderGetLogicalSize(SDL_Renderer * renderer, int *w, int *h);
745
746/**
747 * Set whether to force integer scales for resolution-independent rendering.
748 *
749 * This function restricts the logical viewport to integer values - that is,
750 * when a resolution is between two multiples of a logical size, the viewport
751 * size is rounded down to the lower multiple.
752 *
753 * \param renderer the renderer for which integer scaling should be set
754 * \param enable enable or disable the integer scaling for rendering
755 * \returns 0 on success or a negative error code on failure; call
756 * SDL_GetError() for more information.
757 *
758 * \since This function is available since SDL 2.0.5.
759 *
760 * \sa SDL_RenderGetIntegerScale
761 * \sa SDL_RenderSetLogicalSize
762 */
763extern DECLSPEC int SDLCALL SDL_RenderSetIntegerScale(SDL_Renderer * renderer,
764 SDL_bool enable);
765
766/**
767 * Get whether integer scales are forced for resolution-independent rendering.
768 *
769 * \param renderer the renderer from which integer scaling should be queried
770 * \returns SDL_TRUE if integer scales are forced or SDL_FALSE if not and on
771 * failure; call SDL_GetError() for more information.
772 *
773 * \since This function is available since SDL 2.0.5.
774 *
775 * \sa SDL_RenderSetIntegerScale
776 */
777extern DECLSPEC SDL_bool SDLCALL SDL_RenderGetIntegerScale(SDL_Renderer * renderer);
778
779/**
780 * Set the drawing area for rendering on the current target.
781 *
782 * When the window is resized, the viewport is reset to fill the entire
783 * new window size.
784 *
785 * \param renderer the rendering context
786 * \param rect the SDL_Rect structure representing the drawing area, or NULL
787 * to set the viewport to the entire target
788 * \returns 0 on success or a negative error code on failure; call
789 * SDL_GetError() for more information.
790 *
791 * \sa SDL_RenderGetViewport
792 */
793extern DECLSPEC int SDLCALL SDL_RenderSetViewport(SDL_Renderer * renderer,
794 const SDL_Rect * rect);
795
796/**
797 * Get the drawing area for the current target.
798 *
799 * \param renderer the rendering context
800 * \param rect an SDL_Rect structure filled in with the current drawing area
801 *
802 * \sa SDL_RenderSetViewport
803 */
804extern DECLSPEC void SDLCALL SDL_RenderGetViewport(SDL_Renderer * renderer,
805 SDL_Rect * rect);
806
807/**
808 * Set the clip rectangle for rendering on the specified target.
809 *
810 * \param renderer the rendering context for which clip rectangle should be
811 * set
812 * \param rect an SDL_Rect structure representing the clip area, relative to
813 * the viewport, or NULL to disable clipping
814 * \returns 0 on success or a negative error code on failure; call
815 * SDL_GetError() for more information.
816 *
817 * \sa SDL_RenderGetClipRect
818 * \sa SDL_RenderIsClipEnabled
819 */
820extern DECLSPEC int SDLCALL SDL_RenderSetClipRect(SDL_Renderer * renderer,
821 const SDL_Rect * rect);
822
823/**
824 * Get the clip rectangle for the current target.
825 *
826 * \param renderer the rendering context from which clip rectangle should be
827 * queried
828 * \param rect an SDL_Rect structure filled in with the current clipping area
829 * or an empty rectangle if clipping is disabled
830 *
831 * \sa SDL_RenderIsClipEnabled
832 * \sa SDL_RenderSetClipRect
833 */
834extern DECLSPEC void SDLCALL SDL_RenderGetClipRect(SDL_Renderer * renderer,
835 SDL_Rect * rect);
836
837/**
838 * Get whether clipping is enabled on the given renderer.
839 *
840 * \param renderer the renderer from which clip state should be queried
841 * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call
842 * SDL_GetError() for more information.
843 *
844 * \since This function is available since SDL 2.0.4.
845 *
846 * \sa SDL_RenderGetClipRect
847 * \sa SDL_RenderSetClipRect
848 */
849extern DECLSPEC SDL_bool SDLCALL SDL_RenderIsClipEnabled(SDL_Renderer * renderer);
850
851
852/**
853 * Set the drawing scale for rendering on the current target.
854 *
855 * The drawing coordinates are scaled by the x/y scaling factors before they
856 * are used by the renderer. This allows resolution independent drawing with a
857 * single coordinate system.
858 *
859 * If this results in scaling or subpixel drawing by the rendering backend, it
860 * will be handled using the appropriate quality hints. For best results use
861 * integer scaling factors.
862 *
863 * \param renderer a rendering context
864 * \param scaleX the horizontal scaling factor
865 * \param scaleY the vertical scaling factor
866 * \returns 0 on success or a negative error code on failure; call
867 * SDL_GetError() for more information.
868 *
869 * \since This function is available since SDL 2.0.0.
870 *
871 * \sa SDL_RenderGetScale
872 * \sa SDL_RenderSetLogicalSize
873 */
874extern DECLSPEC int SDLCALL SDL_RenderSetScale(SDL_Renderer * renderer,
875 float scaleX, float scaleY);
876
877/**
878 * Get the drawing scale for the current target.
879 *
880 * \param renderer the renderer from which drawing scale should be queried
881 * \param scaleX a pointer filled in with the horizontal scaling factor
882 * \param scaleY a pointer filled in with the vertical scaling factor
883 *
884 * \since This function is available since SDL 2.0.0.
885 *
886 * \sa SDL_RenderSetScale
887 */
888extern DECLSPEC void SDLCALL SDL_RenderGetScale(SDL_Renderer * renderer,
889 float *scaleX, float *scaleY);
890
891/**
892 * Set the color used for drawing operations (Rect, Line and Clear).
893 *
894 * Set the color for drawing or filling rectangles, lines, and points,
895 * and for SDL_RenderClear().
896 *
897 * \param renderer the rendering context
898 * \param r the red value used to draw on the rendering target
899 * \param g the green value used to draw on the rendering target
900 * \param b the blue value used to draw on the rendering target
901 * \param a the alpha value used to draw on the rendering target; usually
902 * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
903 * specify how the alpha channel is used
904 * \returns 0 on success or a negative error code on failure; call
905 * SDL_GetError() for more information.
906 *
907 * \sa SDL_GetRenderDrawColor
908 * \sa SDL_RenderClear
909 * \sa SDL_RenderDrawLine
910 * \sa SDL_RenderDrawLines
911 * \sa SDL_RenderDrawPoint
912 * \sa SDL_RenderDrawPoints
913 * \sa SDL_RenderDrawRect
914 * \sa SDL_RenderDrawRects
915 * \sa SDL_RenderFillRect
916 * \sa SDL_RenderFillRects
917 */
918extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer * renderer,
919 Uint8 r, Uint8 g, Uint8 b,
920 Uint8 a);
921
922/**
923 * Get the color used for drawing operations (Rect, Line and Clear).
924 *
925 * \param renderer the rendering context
926 * \param r a pointer filled in with the red value used to draw on the
927 * rendering target
928 * \param g a pointer filled in with the green value used to draw on the
929 * rendering target
930 * \param b a pointer filled in with the blue value used to draw on the
931 * rendering target
932 * \param a a pointer filled in with the alpha value used to draw on the
933 * rendering target; usually `SDL_ALPHA_OPAQUE` (255)
934 * \returns 0 on success or a negative error code on failure; call
935 * SDL_GetError() for more information.
936 *
937 * \sa SDL_SetRenderDrawColor
938 */
939extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer * renderer,
940 Uint8 * r, Uint8 * g, Uint8 * b,
941 Uint8 * a);
942
943/**
944 * Set the blend mode used for drawing operations (Fill and Line).
945 *
946 * If the blend mode is not supported, the closest supported mode is chosen.
947 *
948 * \param renderer the rendering context
949 * \param blendMode the SDL_BlendMode to use for blending
950 * \returns 0 on success or a negative error code on failure; call
951 * SDL_GetError() for more information.
952 *
953 * \sa SDL_GetRenderDrawBlendMode
954 * \sa SDL_RenderDrawLine
955 * \sa SDL_RenderDrawLines
956 * \sa SDL_RenderDrawPoint
957 * \sa SDL_RenderDrawPoints
958 * \sa SDL_RenderDrawRect
959 * \sa SDL_RenderDrawRects
960 * \sa SDL_RenderFillRect
961 * \sa SDL_RenderFillRects
962 */
963extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer * renderer,
964 SDL_BlendMode blendMode);
965
966/**
967 * Get the blend mode used for drawing operations.
968 *
969 * \param renderer the rendering context
970 * \param blendMode a pointer filled in with the current SDL_BlendMode
971 * \returns 0 on success or a negative error code on failure; call
972 * SDL_GetError() for more information.
973 *
974 * \sa SDL_SetRenderDrawBlendMode
975 */
976extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer * renderer,
977 SDL_BlendMode *blendMode);
978
979/**
980 * Clear the current rendering target with the drawing color.
981 *
982 * This function clears the entire rendering target, ignoring the viewport and
983 * the clip rectangle.
984 *
985 * \param renderer the rendering context
986 * \returns 0 on success or a negative error code on failure; call
987 * SDL_GetError() for more information.
988 *
989 * \since This function is available since SDL 2.0.0.
990 *
991 * \sa SDL_SetRenderDrawColor
992 */
993extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer * renderer);
994
995/**
996 * Draw a point on the current rendering target.
997 *
998 * SDL_RenderDrawPoint() draws a single point. If you want to draw multiple,
999 * use SDL_RenderDrawPoints() instead.
1000 *
1001 * \param renderer the rendering context
1002 * \param x the x coordinate of the point
1003 * \param y the y coordinate of the point
1004 * \returns 0 on success or a negative error code on failure; call
1005 * SDL_GetError() for more information.
1006 *
1007 * \sa SDL_RenderDrawLine
1008 * \sa SDL_RenderDrawLines
1009 * \sa SDL_RenderDrawPoints
1010 * \sa SDL_RenderDrawRect
1011 * \sa SDL_RenderDrawRects
1012 * \sa SDL_RenderFillRect
1013 * \sa SDL_RenderFillRects
1014 * \sa SDL_RenderPresent
1015 * \sa SDL_SetRenderDrawBlendMode
1016 * \sa SDL_SetRenderDrawColor
1017 */
1018extern DECLSPEC int SDLCALL SDL_RenderDrawPoint(SDL_Renderer * renderer,
1019 int x, int y);
1020
1021/**
1022 * Draw multiple points on the current rendering target.
1023 *
1024 * \param renderer the rendering context
1025 * \param points an array of SDL_Point structures that represent the points to
1026 * draw
1027 * \param count the number of points to draw
1028 * \returns 0 on success or a negative error code on failure; call
1029 * SDL_GetError() for more information.
1030 *
1031 * \sa SDL_RenderDrawLine
1032 * \sa SDL_RenderDrawLines
1033 * \sa SDL_RenderDrawPoint
1034 * \sa SDL_RenderDrawRect
1035 * \sa SDL_RenderDrawRects
1036 * \sa SDL_RenderFillRect
1037 * \sa SDL_RenderFillRects
1038 * \sa SDL_RenderPresent
1039 * \sa SDL_SetRenderDrawBlendMode
1040 * \sa SDL_SetRenderDrawColor
1041 */
1042extern DECLSPEC int SDLCALL SDL_RenderDrawPoints(SDL_Renderer * renderer,
1043 const SDL_Point * points,
1044 int count);
1045
1046/**
1047 * Draw a line on the current rendering target.
1048 *
1049 * SDL_RenderDrawLine() draws the line to include both end points. If you want
1050 * to draw multiple, connecting lines use SDL_RenderDrawLines() instead.
1051 *
1052 * \param renderer the rendering context
1053 * \param x1 the x coordinate of the start point
1054 * \param y1 the y coordinate of the start point
1055 * \param x2 the x coordinate of the end point
1056 * \param y2 the y coordinate of the end point
1057 * \returns 0 on success or a negative error code on failure; call
1058 * SDL_GetError() for more information.
1059 *
1060 * \since This function is available since SDL 2.0.0.
1061 *
1062 * \sa SDL_RenderDrawLines
1063 * \sa SDL_RenderDrawPoint
1064 * \sa SDL_RenderDrawPoints
1065 * \sa SDL_RenderDrawRect
1066 * \sa SDL_RenderDrawRects
1067 * \sa SDL_RenderFillRect
1068 * \sa SDL_RenderFillRects
1069 * \sa SDL_RenderPresent
1070 * \sa SDL_SetRenderDrawBlendMode
1071 * \sa SDL_SetRenderDrawColor
1072 */
1073extern DECLSPEC int SDLCALL SDL_RenderDrawLine(SDL_Renderer * renderer,
1074 int x1, int y1, int x2, int y2);
1075
1076/**
1077 * Draw a series of connected lines on the current rendering target.
1078 *
1079 * \param renderer the rendering context
1080 * \param points an array of SDL_Point structures representing points along
1081 * the lines
1082 * \param count the number of points, drawing count-1 lines
1083 * \returns 0 on success or a negative error code on failure; call
1084 * SDL_GetError() for more information.
1085 *
1086 * \since This function is available since SDL 2.0.0.
1087 *
1088 * \sa SDL_RenderDrawLine
1089 * \sa SDL_RenderDrawPoint
1090 * \sa SDL_RenderDrawPoints
1091 * \sa SDL_RenderDrawRect
1092 * \sa SDL_RenderDrawRects
1093 * \sa SDL_RenderFillRect
1094 * \sa SDL_RenderFillRects
1095 * \sa SDL_RenderPresent
1096 * \sa SDL_SetRenderDrawBlendMode
1097 * \sa SDL_SetRenderDrawColor
1098 */
1099extern DECLSPEC int SDLCALL SDL_RenderDrawLines(SDL_Renderer * renderer,
1100 const SDL_Point * points,
1101 int count);
1102
1103/**
1104 * Draw a rectangle on the current rendering target.
1105 *
1106 * \param renderer the rendering context
1107 * \param rect an SDL_Rect structure representing the rectangle to draw, or
1108 * NULL to outline the entire rendering target
1109 * \returns 0 on success or a negative error code on failure; call
1110 * SDL_GetError() for more information.
1111 *
1112 * \sa SDL_RenderDrawLine
1113 * \sa SDL_RenderDrawLines
1114 * \sa SDL_RenderDrawPoint
1115 * \sa SDL_RenderDrawPoints
1116 * \sa SDL_RenderDrawRects
1117 * \sa SDL_RenderFillRect
1118 * \sa SDL_RenderFillRects
1119 * \sa SDL_RenderPresent
1120 * \sa SDL_SetRenderDrawBlendMode
1121 * \sa SDL_SetRenderDrawColor
1122 */
1123extern DECLSPEC int SDLCALL SDL_RenderDrawRect(SDL_Renderer * renderer,
1124 const SDL_Rect * rect);
1125
1126/**
1127 * Draw some number of rectangles on the current rendering target.
1128 *
1129 * \param renderer the rendering context
1130 * \param rects an array of SDL_Rect structures representing the rectangles to
1131 * be drawn
1132 * \param count the number of rectangles
1133 * \returns 0 on success or a negative error code on failure; call
1134 * SDL_GetError() for more information.
1135 *
1136 * \sa SDL_RenderDrawLine
1137 * \sa SDL_RenderDrawLines
1138 * \sa SDL_RenderDrawPoint
1139 * \sa SDL_RenderDrawPoints
1140 * \sa SDL_RenderDrawRect
1141 * \sa SDL_RenderFillRect
1142 * \sa SDL_RenderFillRects
1143 * \sa SDL_RenderPresent
1144 * \sa SDL_SetRenderDrawBlendMode
1145 * \sa SDL_SetRenderDrawColor
1146 */
1147extern DECLSPEC int SDLCALL SDL_RenderDrawRects(SDL_Renderer * renderer,
1148 const SDL_Rect * rects,
1149 int count);
1150
1151/**
1152 * Fill a rectangle on the current rendering target with the drawing color.
1153 *
1154 * The current drawing color is set by SDL_SetRenderDrawColor(), and the
1155 * color's alpha value is ignored unless blending is enabled with the
1156 * appropriate call to SDL_SetRenderDrawBlendMode().
1157 *
1158 * \param renderer the rendering context
1159 * \param rect the SDL_Rect structure representing the rectangle to fill, or
1160 * NULL for the entire rendering target
1161 * \returns 0 on success or a negative error code on failure; call
1162 * SDL_GetError() for more information.
1163 *
1164 * \sa SDL_RenderDrawLine
1165 * \sa SDL_RenderDrawLines
1166 * \sa SDL_RenderDrawPoint
1167 * \sa SDL_RenderDrawPoints
1168 * \sa SDL_RenderDrawRect
1169 * \sa SDL_RenderDrawRects
1170 * \sa SDL_RenderFillRects
1171 * \sa SDL_RenderPresent
1172 * \sa SDL_SetRenderDrawBlendMode
1173 * \sa SDL_SetRenderDrawColor
1174 */
1175extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer * renderer,
1176 const SDL_Rect * rect);
1177
1178/**
1179 * Fill some number of rectangles on the current rendering target with the
1180 * drawing color.
1181 *
1182 * \param renderer the rendering context
1183 * \param rects an array of SDL_Rect structures representing the rectangles to
1184 * be filled
1185 * \param count the number of rectangles
1186 * \returns 0 on success or a negative error code on failure; call
1187 * SDL_GetError() for more information.
1188 *
1189 * \sa SDL_RenderDrawLine
1190 * \sa SDL_RenderDrawLines
1191 * \sa SDL_RenderDrawPoint
1192 * \sa SDL_RenderDrawPoints
1193 * \sa SDL_RenderDrawRect
1194 * \sa SDL_RenderDrawRects
1195 * \sa SDL_RenderFillRect
1196 * \sa SDL_RenderPresent
1197 */
1198extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer * renderer,
1199 const SDL_Rect * rects,
1200 int count);
1201
1202/**
1203 * Copy a portion of the texture to the current rendering target.
1204 *
1205 * The texture is blended with the destination based on its blend mode set
1206 * with SDL_SetTextureBlendMode().
1207 *
1208 * The texture color is affected based on its color modulation set by
1209 * SDL_SetTextureColorMod().
1210 *
1211 * The texture alpha is affected based on its alpha modulation set by
1212 * SDL_SetTextureAlphaMod().
1213 *
1214 * \param renderer the rendering context
1215 * \param texture the source texture
1216 * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1217 * \param dstrect the destination SDL_Rect structure or NULL for the entire
1218 * rendering target; the texture will be stretched to fill the
1219 * given rectangle
1220 * \returns 0 on success or a negative error code on failure; call
1221 * SDL_GetError() for more information.
1222 *
1223 * \sa SDL_RenderCopyEx
1224 * \sa SDL_SetTextureAlphaMod
1225 * \sa SDL_SetTextureBlendMode
1226 * \sa SDL_SetTextureColorMod
1227 */
1228extern DECLSPEC int SDLCALL SDL_RenderCopy(SDL_Renderer * renderer,
1229 SDL_Texture * texture,
1230 const SDL_Rect * srcrect,
1231 const SDL_Rect * dstrect);
1232
1233/**
1234 * Copy a portion of the texture to the current rendering, with optional
1235 * rotation and flipping.
1236 *
1237 * Copy a portion of the texture to the current rendering
1238 * target, optionally rotating it by angle around the given center and also
1239 * flipping it top-bottom and/or left-right.
1240 *
1241 * The texture is blended with the destination based on its blend mode set
1242 * with SDL_SetTextureBlendMode().
1243 *
1244 * The texture color is affected based on its color modulation set by
1245 * SDL_SetTextureColorMod().
1246 *
1247 * The texture alpha is affected based on its alpha modulation set by
1248 * SDL_SetTextureAlphaMod().
1249 *
1250 * \param renderer the rendering context
1251 * \param texture the source texture
1252 * \param srcrect the source SDL_Rect structure or NULL for the entire texture
1253 * \param dstrect the destination SDL_Rect structure or NULL for the entire
1254 * rendering target
1255 * \param angle an angle in degrees that indicates the rotation that will be
1256 * applied to dstrect, rotating it in a clockwise direction
1257 * \param center a pointer to a point indicating the point around which
1258 * dstrect will be rotated (if NULL, rotation will be done
1259 * around `dstrect.w / 2`, `dstrect.h / 2`)
1260 * \param flip a SDL_RendererFlip value stating which flipping actions should
1261 * be performed on the texture
1262 * \returns 0 on success or a negative error code on failure; call
1263 * SDL_GetError() for more information.
1264 *
1265 * \sa SDL_RenderCopy
1266 * \sa SDL_SetTextureAlphaMod
1267 * \sa SDL_SetTextureBlendMode
1268 * \sa SDL_SetTextureColorMod
1269 */
1270extern DECLSPEC int SDLCALL SDL_RenderCopyEx(SDL_Renderer * renderer,
1271 SDL_Texture * texture,
1272 const SDL_Rect * srcrect,
1273 const SDL_Rect * dstrect,
1274 const double angle,
1275 const SDL_Point *center,
1276 const SDL_RendererFlip flip);
1277
1278
1279/**
1280 * Draw a point on the current rendering target at subpixel precision.
1281 *
1282 * \param renderer The renderer which should draw a point.
1283 * \param x The x coordinate of the point.
1284 * \param y The y coordinate of the point.
1285 * \return 0 on success, or -1 on error
1286 */
1287extern DECLSPEC int SDLCALL SDL_RenderDrawPointF(SDL_Renderer * renderer,
1288 float x, float y);
1289
1290/**
1291 * Draw multiple points on the current rendering target at subpixel precision.
1292 *
1293 * \param renderer The renderer which should draw multiple points.
1294 * \param points The points to draw
1295 * \param count The number of points to draw
1296 * \return 0 on success, or -1 on error
1297 */
1298extern DECLSPEC int SDLCALL SDL_RenderDrawPointsF(SDL_Renderer * renderer,
1299 const SDL_FPoint * points,
1300 int count);
1301
1302/**
1303 * Draw a line on the current rendering target at subpixel precision.
1304 *
1305 * \param renderer The renderer which should draw a line.
1306 * \param x1 The x coordinate of the start point.
1307 * \param y1 The y coordinate of the start point.
1308 * \param x2 The x coordinate of the end point.
1309 * \param y2 The y coordinate of the end point.
1310 * \return 0 on success, or -1 on error
1311 */
1312extern DECLSPEC int SDLCALL SDL_RenderDrawLineF(SDL_Renderer * renderer,
1313 float x1, float y1, float x2, float y2);
1314
1315/**
1316 * Draw a series of connected lines on the current rendering target at
1317 * subpixel precision.
1318 *
1319 * \param renderer The renderer which should draw multiple lines.
1320 * \param points The points along the lines
1321 * \param count The number of points, drawing count-1 lines
1322 * \return 0 on success, or -1 on error
1323 */
1324extern DECLSPEC int SDLCALL SDL_RenderDrawLinesF(SDL_Renderer * renderer,
1325 const SDL_FPoint * points,
1326 int count);
1327
1328/**
1329 * Draw a rectangle on the current rendering target at subpixel precision.
1330 *
1331 * \param renderer The renderer which should draw a rectangle.
1332 * \param rect A pointer to the destination rectangle, or NULL to outline the entire rendering target.
1333 * \return 0 on success, or -1 on error
1334 */
1335extern DECLSPEC int SDLCALL SDL_RenderDrawRectF(SDL_Renderer * renderer,
1336 const SDL_FRect * rect);
1337
1338/**
1339 * Draw some number of rectangles on the current rendering target at subpixel
1340 * precision.
1341 *
1342 * \param renderer The renderer which should draw multiple rectangles.
1343 * \param rects A pointer to an array of destination rectangles.
1344 * \param count The number of rectangles.
1345 * \return 0 on success, or -1 on error
1346 */
1347extern DECLSPEC int SDLCALL SDL_RenderDrawRectsF(SDL_Renderer * renderer,
1348 const SDL_FRect * rects,
1349 int count);
1350
1351/**
1352 * Fill a rectangle on the current rendering target with the drawing color
1353 * at subpixel precision.
1354 *
1355 * \param renderer The renderer which should fill a rectangle.
1356 * \param rect A pointer to the destination rectangle, or NULL for the entire
1357 * rendering target.
1358 * \return 0 on success, or -1 on error
1359 */
1360extern DECLSPEC int SDLCALL SDL_RenderFillRectF(SDL_Renderer * renderer,
1361 const SDL_FRect * rect);
1362
1363/**
1364 * Fill some number of rectangles on the current rendering target with the
1365 * drawing color at subpixel precision.
1366 *
1367 * \param renderer The renderer which should fill multiple rectangles.
1368 * \param rects A pointer to an array of destination rectangles.
1369 * \param count The number of rectangles.
1370 * \return 0 on success, or -1 on error
1371 */
1372extern DECLSPEC int SDLCALL SDL_RenderFillRectsF(SDL_Renderer * renderer,
1373 const SDL_FRect * rects,
1374 int count);
1375
1376/**
1377 * Copy a portion of the texture to the current rendering target at subpixel
1378 * precision.
1379 *
1380 * \param renderer The renderer which should copy parts of a texture.
1381 * \param texture The source texture.
1382 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1383 * texture.
1384 * \param dstrect A pointer to the destination rectangle, or NULL for the
1385 * entire rendering target.
1386 * \return 0 on success, or -1 on error
1387 */
1388extern DECLSPEC int SDLCALL SDL_RenderCopyF(SDL_Renderer * renderer,
1389 SDL_Texture * texture,
1390 const SDL_Rect * srcrect,
1391 const SDL_FRect * dstrect);
1392
1393/**
1394 * Copy a portion of the source texture to the current rendering target,
1395 * with rotation and flipping, at subpixel precision.
1396 *
1397 * \param renderer The renderer which should copy parts of a texture.
1398 * \param texture The source texture.
1399 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1400 * texture.
1401 * \param dstrect A pointer to the destination rectangle, or NULL for the
1402 * entire rendering target.
1403 * \param angle An angle in degrees that indicates the rotation that will be applied to dstrect, rotating it in a clockwise direction
1404 * \param center A pointer to a point indicating the point around which dstrect will be rotated (if NULL, rotation will be done around dstrect.w/2, dstrect.h/2).
1405 * \param flip An SDL_RendererFlip value stating which flipping actions should be performed on the texture
1406 *
1407 * \return 0 on success, or -1 on error
1408 */
1409extern DECLSPEC int SDLCALL SDL_RenderCopyExF(SDL_Renderer * renderer,
1410 SDL_Texture * texture,
1411 const SDL_Rect * srcrect,
1412 const SDL_FRect * dstrect,
1413 const double angle,
1414 const SDL_FPoint *center,
1415 const SDL_RendererFlip flip);
1416
1417/**
1418 * Read pixels from the current rendering target to an array of pixels.
1419 *
1420 * **WARNING**: This is a very slow operation, and should not be used
1421 * frequently.
1422 *
1423 * `pitch` specifies the number of bytes between rows in the destination
1424 * `pixels data. This allows you to write to a subrectangle or have padded
1425 * rows in the destination. Generally, `pitch` should equal the number of
1426 * pixels per row in the `pixels` data times the number of bytes per pixel,
1427 * but it might contain additional padding (for example, 24bit RGB Windows
1428 * Bitmap data pads all rows to multiples of 4 bytes).
1429 *
1430 * \param renderer the rendering context
1431 * \param rect an SDL_Rect structure representing the area to read, or NULL
1432 * for the entire render target
1433 * \param format an SDL_PixelFormatEnum value of the desired format of the
1434 * pixel data, or 0 to use the format of the rendering target
1435 * \param pixels a pointer to the pixel data to copy into
1436 * \param pitch the pitch of the `pixels` parameter
1437 * \returns 0 on success or a negative error code on failure; call
1438 * SDL_GetError() for more information.
1439 */
1440extern DECLSPEC int SDLCALL SDL_RenderReadPixels(SDL_Renderer * renderer,
1441 const SDL_Rect * rect,
1442 Uint32 format,
1443 void *pixels, int pitch);
1444
1445/**
1446 * Update the screen with any rendering performed since
1447 * the previous call.
1448 *
1449 * SDL's rendering functions operate on a backbuffer; that is, calling a
1450 * rendering function such as SDL_RenderDrawLine() does not directly put a
1451 * line on the screen, but rather updates the backbuffer. As such, you compose
1452 * your entire scene and *present* the composed backbuffer to the screen as a
1453 * complete picture.
1454 *
1455 * Therefore, when using SDL's rendering API, one does all drawing intended
1456 * for the frame, and then calls this function once per frame to present the
1457 * final drawing to the user.
1458 *
1459 * The backbuffer should be considered invalidated after each present; do not
1460 * assume that previous contents will exist between frames. You are strongly
1461 * encouraged to call SDL_RenderClear() to initialize the backbuffer before
1462 * starting each new frame's drawing, even if you plan to overwrite every
1463 * pixel.
1464 *
1465 * \param renderer the rendering context
1466 *
1467 * \sa SDL_RenderClear
1468 * \sa SDL_RenderDrawLine
1469 * \sa SDL_RenderDrawLines
1470 * \sa SDL_RenderDrawPoint
1471 * \sa SDL_RenderDrawPoints
1472 * \sa SDL_RenderDrawRect
1473 * \sa SDL_RenderDrawRects
1474 * \sa SDL_RenderFillRect
1475 * \sa SDL_RenderFillRects
1476 * \sa SDL_SetRenderDrawBlendMode
1477 * \sa SDL_SetRenderDrawColor
1478 */
1479extern DECLSPEC void SDLCALL SDL_RenderPresent(SDL_Renderer * renderer);
1480
1481/**
1482 * Destroy the specified texture.
1483 *
1484 * Passing NULL or an otherwise invalid texture will set the SDL error message
1485 * to "Invalid texture".
1486 *
1487 * \param texture the texture to destroy
1488 *
1489 * \sa SDL_CreateTexture
1490 * \sa SDL_CreateTextureFromSurface
1491 */
1492extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture * texture);
1493
1494/**
1495 * Destroy the rendering context for a window and free associated textures.
1496 *
1497 * \param renderer the rendering context
1498 *
1499 * \sa SDL_CreateRenderer
1500 */
1501extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer * renderer);
1502
1503/**
1504 * Force the rendering context to flush any pending commands to the underlying
1505 * rendering API.
1506 *
1507 * You do not need to (and in fact, shouldn't) call this function unless
1508 * you are planning to call into OpenGL/Direct3D/Metal/whatever directly
1509 * in addition to using an SDL_Renderer.
1510 *
1511 * This is for a very-specific case: if you are using SDL's render API, you
1512 * asked for a specific renderer backend (OpenGL, Direct3D, etc), you set
1513 * SDL_HINT_RENDER_BATCHING to "1", and you plan to make OpenGL/D3D/whatever
1514 * calls in addition to SDL render API calls. If all of this applies, you
1515 * should call SDL_RenderFlush() between calls to SDL's render API and the
1516 * low-level API you're using in cooperation.
1517 *
1518 * In all other cases, you can ignore this function. This is only here to get
1519 * maximum performance out of a specific situation. In all other cases, SDL
1520 * will do the right thing, perhaps at a performance loss.
1521 *
1522 * This function is first available in SDL 2.0.10, and is not needed in
1523 * 2.0.9 and earlier, as earlier versions did not queue rendering commands
1524 * at all, instead flushing them to the OS immediately.
1525 *
1526 * \param renderer the rendering context
1527 * \returns 0 on success or a negative error code on failure; call
1528 * SDL_GetError() for more information.
1529 *
1530 * \since This function is available since SDL 2.0.10.
1531 */
1532extern DECLSPEC int SDLCALL SDL_RenderFlush(SDL_Renderer * renderer);
1533
1534
1535/**
1536 * Bind an OpenGL/ES/ES2 texture to the current context.
1537 *
1538 * This is for use with OpenGL instructions when rendering OpenGL primitives
1539 * directly.
1540 *
1541 * If not NULL, `texw` and `texh` will be filled with the width and height
1542 * values suitable for the provided texture. In most cases, both will be 1.0,
1543 * however, on systems that support the GL_ARB_texture_rectangle extension,
1544 * these values will actually be the pixel width and height used to create the
1545 * texture, so this factor needs to be taken into account when providing
1546 * texture coordinates to OpenGL.
1547 *
1548 * You need a renderer to create an SDL_Texture, therefore you can only use
1549 * this function with an implicit OpenGL context from SDL_CreateRenderer(),
1550 * not with your own OpenGL context. If you need control over your OpenGL
1551 * context, you need to write your own texture-loading methods.
1552 *
1553 * Also note that SDL may upload RGB textures as BGR (or vice-versa), and
1554 * re-order the color channels in the shaders phase, so the uploaded texture
1555 * may have swapped color channels.
1556 *
1557 * \param texture the texture to bind to the current OpenGL/ES/ES2 context
1558 * \param texw a pointer to a float value which will be filled with the
1559 * texture width or NULL if you don't need that value
1560 * \param texh a pointer to a float value which will be filled with the
1561 * texture height or NULL if you don't need that value
1562 * \returns 0 on success, or -1 if the operation is not supported; call
1563 * SDL_GetError() for more information.
1564 *
1565 * \since This function is available since SDL 2.0.0.
1566 *
1567 * \sa SDL_GL_MakeCurrent
1568 * \sa SDL_GL_UnbindTexture
1569 */
1570extern DECLSPEC int SDLCALL SDL_GL_BindTexture(SDL_Texture *texture, float *texw, float *texh);
1571
1572/**
1573 * Unbind an OpenGL/ES/ES2 texture from the current context.
1574 *
1575 * See SDL_GL_BindTexture() for examples on how to use these functions
1576 *
1577 * \param texture the texture to unbind from the current OpenGL/ES/ES2 context
1578 * \returns 0 on success, or -1 if the operation is not supported
1579 *
1580 * \sa SDL_GL_BindTexture
1581 * \sa SDL_GL_MakeCurrent
1582 */
1583extern DECLSPEC int SDLCALL SDL_GL_UnbindTexture(SDL_Texture *texture);
1584
1585/**
1586 * Get the CAMetalLayer associated with the given Metal renderer.
1587 *
1588 * This function returns `void *`, so SDL doesn't have to include Metal's
1589 * headers, but it can be safely cast to a `CAMetalLayer *`.
1590 *
1591 * \param renderer The renderer to query
1592 * \returns CAMetalLayer* on success, or NULL if the renderer isn't a Metal
1593 * renderer
1594 *
1595 * \sa SDL_RenderGetMetalCommandEncoder()
1596 */
1597extern DECLSPEC void *SDLCALL SDL_RenderGetMetalLayer(SDL_Renderer * renderer);
1598
1599/**
1600 * Get the Metal command encoder for the current frame
1601 *
1602 * This function returns `void *`, so SDL doesn't have to include Metal's
1603 * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
1604 *
1605 * \param renderer The renderer to query
1606 * \returns `id<MTLRenderCommandEncoder>` on success, or NULL if the renderer
1607 * isn't a Metal renderer.
1608 *
1609 * \sa SDL_RenderGetMetalLayer()
1610 */
1611extern DECLSPEC void *SDLCALL SDL_RenderGetMetalCommandEncoder(SDL_Renderer * renderer);
1612
1613/* Ends C function definitions when using C++ */
1614#ifdef __cplusplus
1615}
1616#endif
1617#include "close_code.h"
1618
1619#endif /* SDL_render_h_ */
1620
1621/* vi: set ts=4 sw=4 expandtab: */
1622