SDL 3.0
SDL_render.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2024 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: https://github.com/libsdl-org/SDL/issues/986
46 */
47
48#ifndef SDL_render_h_
49#define SDL_render_h_
50
51#include <SDL3/SDL_stdinc.h>
52#include <SDL3/SDL_error.h>
53#include <SDL3/SDL_events.h>
54#include <SDL3/SDL_properties.h>
55#include <SDL3/SDL_rect.h>
56#include <SDL3/SDL_video.h>
57
58#include <SDL3/SDL_begin_code.h>
59/* Set up for C function definitions, even when using C++ */
60#ifdef __cplusplus
61extern "C" {
62#endif
63
64/**
65 * The name of the software renderer.
66 *
67 * \since This macro is available since SDL 3.0.0.
68 */
69#define SDL_SOFTWARE_RENDERER "software"
70
71/**
72 * Flags used when creating a rendering context.
73 *
74 * \since This enum is available since SDL 3.0.0.
75 */
77{
78 SDL_RENDERER_PRESENTVSYNC = 0x00000004 /**< Present is synchronized with the refresh rate */
80
81/**
82 * Information on the capabilities of a render driver or context.
83 *
84 * \since This struct is available since SDL 3.0.0.
85 */
86typedef struct SDL_RendererInfo
87{
88 const char *name; /**< The name of the renderer */
89 Uint32 flags; /**< Supported ::SDL_RendererFlags */
90 int num_texture_formats; /**< The number of available texture formats */
91 SDL_PixelFormatEnum texture_formats[16]; /**< The available texture formats */
92 int max_texture_width; /**< The maximum texture width */
93 int max_texture_height; /**< The maximum texture height */
95
96/**
97 * Vertex structure.
98 *
99 * \since This struct is available since SDL 3.0.0.
100 */
101typedef struct SDL_Vertex
102{
103 SDL_FPoint position; /**< Vertex position, in SDL_Renderer coordinates */
104 SDL_FColor color; /**< Vertex color */
105 SDL_FPoint tex_coord; /**< Normalized texture coordinates, if needed */
106} SDL_Vertex;
107
108/**
109 * The access pattern allowed for a texture.
110 *
111 * \since This enum is available since SDL 3.0.0.
112 */
114{
115 SDL_TEXTUREACCESS_STATIC, /**< Changes rarely, not lockable */
116 SDL_TEXTUREACCESS_STREAMING, /**< Changes frequently, lockable */
117 SDL_TEXTUREACCESS_TARGET /**< Texture can be used as a render target */
119
120/**
121 * How the logical size is mapped to the output.
122 *
123 * \since This enum is available since SDL 3.0.0.
124 */
126{
127 SDL_LOGICAL_PRESENTATION_DISABLED, /**< There is no logical size in effect */
128 SDL_LOGICAL_PRESENTATION_STRETCH, /**< The rendered content is stretched to the output resolution */
129 SDL_LOGICAL_PRESENTATION_LETTERBOX, /**< The rendered content is fit to the largest dimension and the other dimension is letterboxed with black bars */
130 SDL_LOGICAL_PRESENTATION_OVERSCAN, /**< The rendered content is fit to the smallest dimension and the other dimension extends beyond the output bounds */
131 SDL_LOGICAL_PRESENTATION_INTEGER_SCALE /**< The rendered content is scaled up by integer multiples to fit the output resolution */
133
134/**
135 * A structure representing rendering state
136 *
137 * \since This struct is available since SDL 3.0.0.
138 */
139struct SDL_Renderer;
141
142/**
143 * An efficient driver-specific representation of pixel data
144 *
145 * \since This struct is available since SDL 3.0.0.
146 */
147struct SDL_Texture;
149
150/* Function prototypes */
151
152/**
153 * Get the number of 2D rendering drivers available for the current display.
154 *
155 * A render driver is a set of code that handles rendering and texture
156 * management on a particular display. Normally there is only one, but some
157 * drivers may have several available with different capabilities.
158 *
159 * There may be none if SDL was compiled without render support.
160 *
161 * \returns a number >= 0 on success or a negative error code on failure; call
162 * SDL_GetError() for more information.
163 *
164 * \since This function is available since SDL 3.0.0.
165 *
166 * \sa SDL_CreateRenderer
167 * \sa SDL_GetRenderDriver
168 */
169extern DECLSPEC int SDLCALL SDL_GetNumRenderDrivers(void);
170
171/**
172 * Use this function to get the name of a built in 2D rendering driver.
173 *
174 * The list of rendering drivers is given in the order that they are normally
175 * initialized by default; the drivers that seem more reasonable to choose
176 * first (as far as the SDL developers believe) are earlier in the list.
177 *
178 * The names of drivers are all simple, low-ASCII identifiers, like "opengl",
179 * "direct3d12" or "metal". These never have Unicode characters, and are not
180 * meant to be proper names.
181 *
182 * The returned value points to a static, read-only string; do not modify or
183 * free it!
184 *
185 * \param index the index of the rendering driver; the value ranges from 0 to
186 * SDL_GetNumRenderDrivers() - 1
187 * \returns the name of the rendering driver at the requested index, or NULL
188 * if an invalid index was specified.
189 *
190 * \since This function is available since SDL 3.0.0.
191 *
192 * \sa SDL_GetNumRenderDrivers
193 */
194extern DECLSPEC const char *SDLCALL SDL_GetRenderDriver(int index);
195
196/**
197 * Create a window and default renderer.
198 *
199 * \param title the title of the window, in UTF-8 encoding
200 * \param width the width of the window
201 * \param height the height of the window
202 * \param window_flags the flags used to create the window (see
203 * SDL_CreateWindow())
204 * \param window a pointer filled with the window, or NULL on error
205 * \param renderer a pointer filled with the renderer, or NULL on error
206 * \returns 0 on success or a negative error code on failure; call
207 * SDL_GetError() for more information.
208 *
209 * \since This function is available since SDL 3.0.0.
210 *
211 * \sa SDL_CreateRenderer
212 * \sa SDL_CreateWindow
213 */
214extern DECLSPEC int SDLCALL SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer);
215
216/**
217 * Create a 2D rendering context for a window.
218 *
219 * If you want a specific renderer, you can specify its name here. A list of
220 * available renderers can be obtained by calling SDL_GetRenderDriver multiple
221 * times, with indices from 0 to SDL_GetNumRenderDrivers()-1. If you don't
222 * need a specific renderer, specify NULL and SDL will attempt to choose the
223 * best option for you, based on what is available on the user's system.
224 *
225 * By default the rendering size matches the window size in pixels, but you
226 * can call SDL_SetRenderLogicalPresentation() to change the content size and
227 * scaling options.
228 *
229 * \param window the window where rendering is displayed
230 * \param name the name of the rendering driver to initialize, or NULL to
231 * initialize the first one supporting the requested flags
232 * \param flags 0, or one or more SDL_RendererFlags OR'd together
233 * \returns a valid rendering context or NULL if there was an error; call
234 * SDL_GetError() for more information.
235 *
236 * \since This function is available since SDL 3.0.0.
237 *
238 * \sa SDL_CreateRendererWithProperties
239 * \sa SDL_CreateSoftwareRenderer
240 * \sa SDL_DestroyRenderer
241 * \sa SDL_GetNumRenderDrivers
242 * \sa SDL_GetRenderDriver
243 * \sa SDL_GetRendererInfo
244 */
245extern DECLSPEC SDL_Renderer * SDLCALL SDL_CreateRenderer(SDL_Window *window, const char *name, Uint32 flags);
246
247/**
248 * Create a 2D rendering context for a window, with the specified properties.
249 *
250 * These are the supported properties:
251 *
252 * - `SDL_PROP_RENDERER_CREATE_NAME_STRING`: the name of the rendering driver
253 * to use, if a specific one is desired
254 * - `SDL_PROP_RENDERER_CREATE_WINDOW_POINTER`: the window where rendering is
255 * displayed, required if this isn't a software renderer using a surface
256 * - `SDL_PROP_RENDERER_CREATE_SURFACE_POINTER`: the surface where rendering
257 * is displayed, if you want a software renderer without a window
258 * - `SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace
259 * value describing the colorspace for output to the display, defaults to
260 * SDL_COLORSPACE_SRGB. The direct3d11, direct3d12, and metal renderers
261 * support SDL_COLORSPACE_SRGB_LINEAR, which is a linear color space and
262 * supports HDR output. If you select SDL_COLORSPACE_SRGB_LINEAR, drawing
263 * still uses the sRGB colorspace, but values can go beyond 1.0 and float
264 * (linear) format textures can be used for HDR content.
265 * - `SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_BOOLEAN`: true if you want
266 * present synchronized with the refresh rate
267 *
268 * With the vulkan renderer:
269 *
270 * - `SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER`: the VkInstance to use
271 * with the renderer, optional.
272 * - `SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER`: the VkSurfaceKHR to use
273 * with the renderer, optional.
274 * - `SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER`: the
275 * VkPhysicalDevice to use with the renderer, optional.
276 * - `SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER`: the VkDevice to use
277 * with the renderer, optional.
278 * - `SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER`: the
279 * queue family index used for rendering.
280 * - `SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the
281 * queue family index used for presentation.
282 *
283 * \param props the properties to use
284 * \returns a valid rendering context or NULL if there was an error; call
285 * SDL_GetError() for more information.
286 *
287 * \since This function is available since SDL 3.0.0.
288 *
289 * \sa SDL_CreateProperties
290 * \sa SDL_CreateRenderer
291 * \sa SDL_CreateSoftwareRenderer
292 * \sa SDL_DestroyRenderer
293 * \sa SDL_GetRendererInfo
294 */
296
297#define SDL_PROP_RENDERER_CREATE_NAME_STRING "name"
298#define SDL_PROP_RENDERER_CREATE_WINDOW_POINTER "window"
299#define SDL_PROP_RENDERER_CREATE_SURFACE_POINTER "surface"
300#define SDL_PROP_RENDERER_CREATE_OUTPUT_COLORSPACE_NUMBER "output_colorspace"
301#define SDL_PROP_RENDERER_CREATE_PRESENT_VSYNC_BOOLEAN "present_vsync"
302#define SDL_PROP_RENDERER_CREATE_VULKAN_INSTANCE_POINTER "vulkan.instance"
303#define SDL_PROP_RENDERER_CREATE_VULKAN_SURFACE_NUMBER "vulkan.surface"
304#define SDL_PROP_RENDERER_CREATE_VULKAN_PHYSICAL_DEVICE_POINTER "vulkan.physical_device"
305#define SDL_PROP_RENDERER_CREATE_VULKAN_DEVICE_POINTER "vulkan.device"
306#define SDL_PROP_RENDERER_CREATE_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "vulkan.graphics_queue_family_index"
307#define SDL_PROP_RENDERER_CREATE_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "vulkan.present_queue_family_index"
308
309/**
310 * Create a 2D software rendering context for a surface.
311 *
312 * Two other API which can be used to create SDL_Renderer:
313 * SDL_CreateRenderer() and SDL_CreateWindowAndRenderer(). These can _also_
314 * create a software renderer, but they are intended to be used with an
315 * SDL_Window as the final destination and not an SDL_Surface.
316 *
317 * \param surface the SDL_Surface structure representing the surface where
318 * rendering is done
319 * \returns a valid rendering context or NULL if there was an error; call
320 * SDL_GetError() for more information.
321 *
322 * \since This function is available since SDL 3.0.0.
323 *
324 * \sa SDL_DestroyRenderer
325 */
326extern DECLSPEC SDL_Renderer *SDLCALL SDL_CreateSoftwareRenderer(SDL_Surface *surface);
327
328/**
329 * Get the renderer associated with a window.
330 *
331 * \param window the window to query
332 * \returns the rendering context on success or NULL on failure; call
333 * SDL_GetError() for more information.
334 *
335 * \since This function is available since SDL 3.0.0.
336 */
337extern DECLSPEC SDL_Renderer *SDLCALL SDL_GetRenderer(SDL_Window *window);
338
339/**
340 * Get the window associated with a renderer.
341 *
342 * \param renderer the renderer to query
343 * \returns the window on success or NULL on failure; call SDL_GetError() for
344 * more information.
345 *
346 * \since This function is available since SDL 3.0.0.
347 */
348extern DECLSPEC SDL_Window *SDLCALL SDL_GetRenderWindow(SDL_Renderer *renderer);
349
350/**
351 * Get information about a rendering context.
352 *
353 * \param renderer the rendering context
354 * \param info an SDL_RendererInfo structure filled with information about the
355 * current renderer
356 * \returns 0 on success or a negative error code on failure; call
357 * SDL_GetError() for more information.
358 *
359 * \since This function is available since SDL 3.0.0.
360 *
361 * \sa SDL_CreateRenderer
362 * \sa SDL_CreateRendererWithProperties
363 */
364extern DECLSPEC int SDLCALL SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_RendererInfo *info);
365
366/**
367 * Get the properties associated with a renderer.
368 *
369 * The following read-only properties are provided by SDL:
370 *
371 * - `SDL_PROP_RENDERER_NAME_STRING`: the name of the rendering driver
372 * - `SDL_PROP_RENDERER_WINDOW_POINTER`: the window where rendering is
373 * displayed, if any
374 * - `SDL_PROP_RENDERER_SURFACE_POINTER`: the surface where rendering is
375 * displayed, if this is a software renderer without a window
376 * - `SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER`: an SDL_ColorSpace value
377 * describing the colorspace for output to the display, defaults to
378 * SDL_COLORSPACE_SRGB.
379 * - `SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN`: true if the output colorspace is
380 * SDL_COLORSPACE_SRGB_LINEAR and the renderer is showing on a display with
381 * HDR enabled. This property can change dynamically when
382 * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
383 * - `SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT`: the value of SDR white in the
384 * SDL_COLORSPACE_SRGB_LINEAR colorspace. When HDR is enabled, this value is
385 * automatically multiplied into the color scale. This property can change
386 * dynamically when SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
387 * - `SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT`: the additional high dynamic range
388 * that can be displayed, in terms of the SDR white point. When HDR is not
389 * enabled, this will be 1.0. This property can change dynamically when
390 * SDL_EVENT_DISPLAY_HDR_STATE_CHANGED is sent.
391 *
392 * With the direct3d renderer:
393 *
394 * - `SDL_PROP_RENDERER_D3D9_DEVICE_POINTER`: the IDirect3DDevice9 associated
395 * with the renderer
396 *
397 * With the direct3d11 renderer:
398 *
399 * - `SDL_PROP_RENDERER_D3D11_DEVICE_POINTER`: the ID3D11Device associated
400 * with the renderer
401 *
402 * With the direct3d12 renderer:
403 *
404 * - `SDL_PROP_RENDERER_D3D12_DEVICE_POINTER`: the ID3D12Device associated
405 * with the renderer
406 * - `SDL_PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER`: the ID3D12CommandQueue
407 * associated with the renderer
408 *
409 * With the vulkan renderer:
410 *
411 * - `SDL_PROP_RENDERER_VULKAN_INSTANCE_POINTER`: the VkInstance associated
412 * with the renderer
413 * - `SDL_PROP_RENDERER_VULKAN_SURFACE_NUMBER`: the VkSurfaceKHR associated
414 * with the renderer
415 * - `SDL_PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER`: the VkPhysicalDevice
416 * associated with the renderer
417 * - `SDL_PROP_RENDERER_VULKAN_DEVICE_POINTER`: the VkDevice associated with
418 * the renderer
419 * - `SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER`: the queue
420 * family index used for rendering
421 * - `SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER`: the queue
422 * family index used for presentation
423 * - `SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER`: the number of
424 * swapchain images, or potential frames in flight, used by the Vulkan
425 * renderer
426 *
427 * \param renderer the rendering context
428 * \returns a valid property ID on success or 0 on failure; call
429 * SDL_GetError() for more information.
430 *
431 * \since This function is available since SDL 3.0.0.
432 *
433 * \sa SDL_GetProperty
434 * \sa SDL_SetProperty
435 */
436extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetRendererProperties(SDL_Renderer *renderer);
437
438#define SDL_PROP_RENDERER_NAME_STRING "SDL.renderer.name"
439#define SDL_PROP_RENDERER_WINDOW_POINTER "SDL.renderer.window"
440#define SDL_PROP_RENDERER_SURFACE_POINTER "SDL.renderer.surface"
441#define SDL_PROP_RENDERER_OUTPUT_COLORSPACE_NUMBER "SDL.renderer.output_colorspace"
442#define SDL_PROP_RENDERER_HDR_ENABLED_BOOLEAN "SDL.renderer.HDR_enabled"
443#define SDL_PROP_RENDERER_SDR_WHITE_POINT_FLOAT "SDL.renderer.SDR_white_point"
444#define SDL_PROP_RENDERER_HDR_HEADROOM_FLOAT "SDL.renderer.HDR_headroom"
445#define SDL_PROP_RENDERER_D3D9_DEVICE_POINTER "SDL.renderer.d3d9.device"
446#define SDL_PROP_RENDERER_D3D11_DEVICE_POINTER "SDL.renderer.d3d11.device"
447#define SDL_PROP_RENDERER_D3D12_DEVICE_POINTER "SDL.renderer.d3d12.device"
448#define SDL_PROP_RENDERER_D3D12_COMMAND_QUEUE_POINTER "SDL.renderer.d3d12.command_queue"
449#define SDL_PROP_RENDERER_VULKAN_INSTANCE_POINTER "SDL.renderer.vulkan.instance"
450#define SDL_PROP_RENDERER_VULKAN_SURFACE_NUMBER "SDL.renderer.vulkan.surface"
451#define SDL_PROP_RENDERER_VULKAN_PHYSICAL_DEVICE_POINTER "SDL.renderer.vulkan.physical_device"
452#define SDL_PROP_RENDERER_VULKAN_DEVICE_POINTER "SDL.renderer.vulkan.device"
453#define SDL_PROP_RENDERER_VULKAN_GRAPHICS_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.graphics_queue_family_index"
454#define SDL_PROP_RENDERER_VULKAN_PRESENT_QUEUE_FAMILY_INDEX_NUMBER "SDL.renderer.vulkan.present_queue_family_index"
455#define SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER "SDL.renderer.vulkan.swapchain_image_count"
456
457/**
458 * Get the output size in pixels of a rendering context.
459 *
460 * This returns the true output size in pixels, ignoring any render targets or
461 * logical size and presentation.
462 *
463 * \param renderer the rendering context
464 * \param w a pointer filled in with the width in pixels
465 * \param h a pointer filled in with the height in pixels
466 * \returns 0 on success or a negative error code on failure; call
467 * SDL_GetError() for more information.
468 *
469 * \since This function is available since SDL 3.0.0.
470 *
471 * \sa SDL_GetCurrentRenderOutputSize
472 */
473extern DECLSPEC int SDLCALL SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h);
474
475/**
476 * Get the current output size in pixels of a rendering context.
477 *
478 * If a rendering target is active, this will return the size of the rendering
479 * target in pixels, otherwise if a logical size is set, it will return the
480 * logical size, otherwise it will return the value of
481 * SDL_GetRenderOutputSize().
482 *
483 * \param renderer the rendering context
484 * \param w a pointer filled in with the current width
485 * \param h a pointer filled in with the current height
486 * \returns 0 on success or a negative error code on failure; call
487 * SDL_GetError() for more information.
488 *
489 * \since This function is available since SDL 3.0.0.
490 *
491 * \sa SDL_GetRenderOutputSize
492 */
493extern DECLSPEC int SDLCALL SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h);
494
495/**
496 * Create a texture for a rendering context.
497 *
498 * \param renderer the rendering context
499 * \param format one of the enumerated values in SDL_PixelFormatEnum
500 * \param access one of the enumerated values in SDL_TextureAccess
501 * \param w the width of the texture in pixels
502 * \param h the height of the texture in pixels
503 * \returns a pointer to the created texture or NULL if no rendering context
504 * was active, the format was unsupported, or the width or height
505 * were out of range; call SDL_GetError() for more information.
506 *
507 * \since This function is available since SDL 3.0.0.
508 *
509 * \sa SDL_CreateTextureFromSurface
510 * \sa SDL_CreateTextureWithProperties
511 * \sa SDL_DestroyTexture
512 * \sa SDL_QueryTexture
513 * \sa SDL_UpdateTexture
514 */
515extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTexture(SDL_Renderer *renderer, SDL_PixelFormatEnum format, int access, int w, int h);
516
517/**
518 * Create a texture from an existing surface.
519 *
520 * The surface is not modified or freed by this function.
521 *
522 * The SDL_TextureAccess hint for the created texture is
523 * `SDL_TEXTUREACCESS_STATIC`.
524 *
525 * The pixel format of the created texture may be different from the pixel
526 * format of the surface. Use SDL_QueryTexture() to query the pixel format of
527 * the texture.
528 *
529 * \param renderer the rendering context
530 * \param surface the SDL_Surface structure containing pixel data used to fill
531 * the texture
532 * \returns the created texture or NULL on failure; call SDL_GetError() for
533 * more information.
534 *
535 * \since This function is available since SDL 3.0.0.
536 *
537 * \sa SDL_CreateTexture
538 * \sa SDL_CreateTextureWithProperties
539 * \sa SDL_DestroyTexture
540 * \sa SDL_QueryTexture
541 */
542extern DECLSPEC SDL_Texture *SDLCALL SDL_CreateTextureFromSurface(SDL_Renderer *renderer, SDL_Surface *surface);
543
544/**
545 * Create a texture for a rendering context with the specified properties.
546 *
547 * These are the supported properties:
548 *
549 * - `SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER`: an SDL_ColorSpace value
550 * describing the texture colorspace, defaults to SDL_COLORSPACE_SRGB_LINEAR
551 * for floating point textures, SDL_COLORSPACE_HDR10 for 10-bit textures,
552 * SDL_COLORSPACE_SRGB for other RGB textures and SDL_COLORSPACE_JPEG for
553 * YUV textures.
554 * - `SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER`: one of the enumerated values in
555 * SDL_PixelFormatEnum, defaults to the best RGBA format for the renderer
556 * - `SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER`: one of the enumerated values in
557 * SDL_TextureAccess, defaults to SDL_TEXTUREACCESS_STATIC
558 * - `SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER`: the width of the texture in
559 * pixels, required
560 * - `SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER`: the height of the texture in
561 * pixels, required
562 * - `SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating
563 * point textures, this defines the value of 100% diffuse white, with higher
564 * values being displayed in the High Dynamic Range headroom. This defaults
565 * to 100 for HDR10 textures and 1.0 for floating point textures.
566 * - `SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT`: for HDR10 and floating
567 * point textures, this defines the maximum dynamic range used by the
568 * content, in terms of the SDR white point. This would be equivalent to
569 * maxCLL / SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT for HDR10 content.
570 * If this is defined, any values outside the range supported by the display
571 * will be scaled into the available HDR headroom, otherwise they are
572 * clipped.
573 *
574 * With the direct3d11 renderer:
575 *
576 * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D
577 * associated with the texture, if you want to wrap an existing texture.
578 * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D
579 * associated with the U plane of a YUV texture, if you want to wrap an
580 * existing texture.
581 * - `SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D
582 * associated with the V plane of a YUV texture, if you want to wrap an
583 * existing texture.
584 *
585 * With the direct3d12 renderer:
586 *
587 * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER`: the ID3D12Resource
588 * associated with the texture, if you want to wrap an existing texture.
589 * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource
590 * associated with the U plane of a YUV texture, if you want to wrap an
591 * existing texture.
592 * - `SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource
593 * associated with the V plane of a YUV texture, if you want to wrap an
594 * existing texture.
595 *
596 * With the metal renderer:
597 *
598 * - `SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER`: the CVPixelBufferRef
599 * associated with the texture, if you want to create a texture from an
600 * existing pixel buffer.
601 *
602 * With the opengl renderer:
603 *
604 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER`: the GLuint texture
605 * associated with the texture, if you want to wrap an existing texture.
606 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture
607 * associated with the UV plane of an NV12 texture, if you want to wrap an
608 * existing texture.
609 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture
610 * associated with the U plane of a YUV texture, if you want to wrap an
611 * existing texture.
612 * - `SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture
613 * associated with the V plane of a YUV texture, if you want to wrap an
614 * existing texture.
615 *
616 * With the opengles2 renderer:
617 *
618 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
619 * associated with the texture, if you want to wrap an existing texture.
620 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
621 * associated with the texture, if you want to wrap an existing texture.
622 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture
623 * associated with the UV plane of an NV12 texture, if you want to wrap an
624 * existing texture.
625 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture
626 * associated with the U plane of a YUV texture, if you want to wrap an
627 * existing texture.
628 * - `SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture
629 * associated with the V plane of a YUV texture, if you want to wrap an
630 * existing texture.
631 *
632 * With the vulkan renderer:
633 *
634 * - `SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER`: the VkImage with layout
635 * VK_IMAGE_LAYOUT_SHADER_READ_ONLY_OPTIMAL associated with the texture, if
636 * you want to wrap an existing texture.
637 *
638 * \param renderer the rendering context
639 * \param props the properties to use
640 * \returns a pointer to the created texture or NULL if no rendering context
641 * was active, the format was unsupported, or the width or height
642 * were out of range; call SDL_GetError() for more information.
643 *
644 * \since This function is available since SDL 3.0.0.
645 *
646 * \sa SDL_CreateProperties
647 * \sa SDL_CreateTexture
648 * \sa SDL_CreateTextureFromSurface
649 * \sa SDL_DestroyTexture
650 * \sa SDL_QueryTexture
651 * \sa SDL_UpdateTexture
652 */
654
655#define SDL_PROP_TEXTURE_CREATE_COLORSPACE_NUMBER "colorspace"
656#define SDL_PROP_TEXTURE_CREATE_FORMAT_NUMBER "format"
657#define SDL_PROP_TEXTURE_CREATE_ACCESS_NUMBER "access"
658#define SDL_PROP_TEXTURE_CREATE_WIDTH_NUMBER "width"
659#define SDL_PROP_TEXTURE_CREATE_HEIGHT_NUMBER "height"
660#define SDL_PROP_TEXTURE_CREATE_SDR_WHITE_POINT_FLOAT "SDR_white_point"
661#define SDL_PROP_TEXTURE_CREATE_HDR_HEADROOM_FLOAT "HDR_headroom"
662#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_POINTER "d3d11.texture"
663#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_U_POINTER "d3d11.texture_u"
664#define SDL_PROP_TEXTURE_CREATE_D3D11_TEXTURE_V_POINTER "d3d11.texture_v"
665#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_POINTER "d3d12.texture"
666#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_U_POINTER "d3d12.texture_u"
667#define SDL_PROP_TEXTURE_CREATE_D3D12_TEXTURE_V_POINTER "d3d12.texture_v"
668#define SDL_PROP_TEXTURE_CREATE_METAL_PIXELBUFFER_POINTER "metal.pixelbuffer"
669#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_NUMBER "opengl.texture"
670#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_UV_NUMBER "opengl.texture_uv"
671#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_U_NUMBER "opengl.texture_u"
672#define SDL_PROP_TEXTURE_CREATE_OPENGL_TEXTURE_V_NUMBER "opengl.texture_v"
673#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_NUMBER "opengles2.texture"
674#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_UV_NUMBER "opengles2.texture_uv"
675#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_U_NUMBER "opengles2.texture_u"
676#define SDL_PROP_TEXTURE_CREATE_OPENGLES2_TEXTURE_V_NUMBER "opengles2.texture_v"
677#define SDL_PROP_TEXTURE_CREATE_VULKAN_TEXTURE_NUMBER "vulkan.texture"
678
679/**
680 * Get the properties associated with a texture.
681 *
682 * The following read-only properties are provided by SDL:
683 *
684 * - `SDL_PROP_TEXTURE_COLORSPACE_NUMBER`: an SDL_ColorSpace value describing
685 * the colorspace used by the texture
686 * - `SDL_PROP_TEXTURE_SDR_WHITE_POINT_FLOAT`: for HDR10 and floating point
687 * textures, this defines the value of 100% diffuse white, with higher
688 * values being displayed in the High Dynamic Range headroom. This defaults
689 * to 100 for HDR10 textures and 1.0 for other textures.
690 * - `SDL_PROP_TEXTURE_HDR_HEADROOM_FLOAT`: for HDR10 and floating point
691 * textures, this defines the maximum dynamic range used by the content, in
692 * terms of the SDR white point. If this is defined, any values outside the
693 * range supported by the display will be scaled into the available HDR
694 * headroom, otherwise they are clipped. This defaults to 1.0 for SDR
695 * textures, 4.0 for HDR10 textures, and no default for floating point
696 * textures.
697 *
698 * With the direct3d11 renderer:
699 *
700 * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_POINTER`: the ID3D11Texture2D associated
701 * with the texture
702 * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_U_POINTER`: the ID3D11Texture2D
703 * associated with the U plane of a YUV texture
704 * - `SDL_PROP_TEXTURE_D3D11_TEXTURE_V_POINTER`: the ID3D11Texture2D
705 * associated with the V plane of a YUV texture
706 *
707 * With the direct3d12 renderer:
708 *
709 * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_POINTER`: the ID3D12Resource associated
710 * with the texture
711 * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_U_POINTER`: the ID3D12Resource associated
712 * with the U plane of a YUV texture
713 * - `SDL_PROP_TEXTURE_D3D12_TEXTURE_V_POINTER`: the ID3D12Resource associated
714 * with the V plane of a YUV texture
715 *
716 * With the vulkan renderer:
717 *
718 * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_POINTER`: the VkImage associated with
719 * the texture
720 * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_U_POINTER`: the VkImage associated with
721 * the U plane of a YUV texture
722 * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_V_POINTER`: the VkImage associated with
723 * the V plane of a YUV texture
724 * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_UV_POINTER`: the VkImage associated with
725 * the UV plane of a NV12/NV21 texture
726 *
727 * With the opengl renderer:
728 *
729 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_NUMBER`: the GLuint texture associated
730 * with the texture
731 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER`: the GLuint texture
732 * associated with the UV plane of an NV12 texture
733 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER`: the GLuint texture associated
734 * with the U plane of a YUV texture
735 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER`: the GLuint texture associated
736 * with the V plane of a YUV texture
737 * - `SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER`: the GLenum for the
738 * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_RECTANGLE_ARB`, etc)
739 * - `SDL_PROP_TEXTURE_OPENGL_TEX_W_FLOAT`: the texture coordinate width of
740 * the texture (0.0 - 1.0)
741 * - `SDL_PROP_TEXTURE_OPENGL_TEX_H_FLOAT`: the texture coordinate height of
742 * the texture (0.0 - 1.0)
743 *
744 * With the opengles2 renderer:
745 *
746 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER`: the GLuint texture
747 * associated with the texture
748 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER`: the GLuint texture
749 * associated with the UV plane of an NV12 texture
750 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER`: the GLuint texture
751 * associated with the U plane of a YUV texture
752 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER`: the GLuint texture
753 * associated with the V plane of a YUV texture
754 * - `SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER`: the GLenum for the
755 * texture target (`GL_TEXTURE_2D`, `GL_TEXTURE_EXTERNAL_OES`, etc)
756 *
757 * With the vulkan renderer:
758 *
759 * - `SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER`: the VkImage associated with the
760 * texture
761 *
762 * \param texture the texture to query
763 * \returns a valid property ID on success or 0 on failure; call
764 * SDL_GetError() for more information.
765 *
766 * \since This function is available since SDL 3.0.0.
767 *
768 * \sa SDL_GetProperty
769 * \sa SDL_SetProperty
770 */
771extern DECLSPEC SDL_PropertiesID SDLCALL SDL_GetTextureProperties(SDL_Texture *texture);
772
773#define SDL_PROP_TEXTURE_COLORSPACE_NUMBER "SDL.texture.colorspace"
774#define SDL_PROP_TEXTURE_SDR_WHITE_POINT_FLOAT "SDL.texture.SDR_white_point"
775#define SDL_PROP_TEXTURE_HDR_HEADROOM_FLOAT "SDL.texture.HDR_headroom"
776#define SDL_PROP_TEXTURE_D3D11_TEXTURE_POINTER "SDL.texture.d3d11.texture"
777#define SDL_PROP_TEXTURE_D3D11_TEXTURE_U_POINTER "SDL.texture.d3d11.texture_u"
778#define SDL_PROP_TEXTURE_D3D11_TEXTURE_V_POINTER "SDL.texture.d3d11.texture_v"
779#define SDL_PROP_TEXTURE_D3D12_TEXTURE_POINTER "SDL.texture.d3d12.texture"
780#define SDL_PROP_TEXTURE_D3D12_TEXTURE_U_POINTER "SDL.texture.d3d12.texture_u"
781#define SDL_PROP_TEXTURE_D3D12_TEXTURE_V_POINTER "SDL.texture.d3d12.texture_v"
782#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_NUMBER "SDL.texture.opengl.texture"
783#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_UV_NUMBER "SDL.texture.opengl.texture_uv"
784#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_U_NUMBER "SDL.texture.opengl.texture_u"
785#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_V_NUMBER "SDL.texture.opengl.texture_v"
786#define SDL_PROP_TEXTURE_OPENGL_TEXTURE_TARGET_NUMBER "SDL.texture.opengl.target"
787#define SDL_PROP_TEXTURE_OPENGL_TEX_W_FLOAT "SDL.texture.opengl.tex_w"
788#define SDL_PROP_TEXTURE_OPENGL_TEX_H_FLOAT "SDL.texture.opengl.tex_h"
789#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_NUMBER "SDL.texture.opengles2.texture"
790#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_UV_NUMBER "SDL.texture.opengles2.texture_uv"
791#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_U_NUMBER "SDL.texture.opengles2.texture_u"
792#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_V_NUMBER "SDL.texture.opengles2.texture_v"
793#define SDL_PROP_TEXTURE_OPENGLES2_TEXTURE_TARGET_NUMBER "SDL.texture.opengles2.target"
794#define SDL_PROP_TEXTURE_VULKAN_TEXTURE_NUMBER "SDL.texture.vulkan.texture"
795
796/**
797 * Get the renderer that created an SDL_Texture.
798 *
799 * \param texture the texture to query
800 * \returns a pointer to the SDL_Renderer that created the texture, or NULL on
801 * failure; call SDL_GetError() for more information.
802 *
803 * \threadsafety It is safe to call this function from any thread.
804 *
805 * \since This function is available since SDL 3.0.0.
806 */
807extern DECLSPEC SDL_Renderer *SDLCALL SDL_GetRendererFromTexture(SDL_Texture *texture);
808
809/**
810 * Query the attributes of a texture.
811 *
812 * \param texture the texture to query
813 * \param format a pointer filled in with the raw format of the texture; the
814 * actual format may differ, but pixel transfers will use this
815 * format (one of the SDL_PixelFormatEnum values). This argument
816 * can be NULL if you don't need this information.
817 * \param access a pointer filled in with the actual access to the texture
818 * (one of the SDL_TextureAccess values). This argument can be
819 * NULL if you don't need this information.
820 * \param w a pointer filled in with the width of the texture in pixels. This
821 * argument can be NULL if you don't need this information.
822 * \param h a pointer filled in with the height of the texture in pixels. This
823 * argument can be NULL if you don't need this information.
824 * \returns 0 on success or a negative error code on failure; call
825 * SDL_GetError() for more information.
826 *
827 * \since This function is available since SDL 3.0.0.
828 */
829extern DECLSPEC int SDLCALL SDL_QueryTexture(SDL_Texture *texture, SDL_PixelFormatEnum *format, int *access, int *w, int *h);
830
831/**
832 * Set an additional color value multiplied into render copy operations.
833 *
834 * When this texture is rendered, during the copy operation each source color
835 * channel is modulated by the appropriate color value according to the
836 * following formula:
837 *
838 * `srcC = srcC * (color / 255)`
839 *
840 * Color modulation is not always supported by the renderer; it will return -1
841 * if color modulation is not supported.
842 *
843 * \param texture the texture to update
844 * \param r the red color value multiplied into copy operations
845 * \param g the green color value multiplied into copy operations
846 * \param b the blue color value multiplied into copy operations
847 * \returns 0 on success or a negative error code on failure; call
848 * SDL_GetError() for more information.
849 *
850 * \since This function is available since SDL 3.0.0.
851 *
852 * \sa SDL_GetTextureColorMod
853 * \sa SDL_SetTextureAlphaMod
854 * \sa SDL_SetTextureColorModFloat
855 */
856extern DECLSPEC int SDLCALL SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b);
857
858
859/**
860 * Set an additional color value multiplied into render copy operations.
861 *
862 * When this texture is rendered, during the copy operation each source color
863 * channel is modulated by the appropriate color value according to the
864 * following formula:
865 *
866 * `srcC = srcC * color`
867 *
868 * Color modulation is not always supported by the renderer; it will return -1
869 * if color modulation is not supported.
870 *
871 * \param texture the texture to update
872 * \param r the red color value multiplied into copy operations
873 * \param g the green color value multiplied into copy operations
874 * \param b the blue color value multiplied into copy operations
875 * \returns 0 on success or a negative error code on failure; call
876 * SDL_GetError() for more information.
877 *
878 * \since This function is available since SDL 3.0.0.
879 *
880 * \sa SDL_GetTextureColorModFloat
881 * \sa SDL_SetTextureAlphaModFloat
882 * \sa SDL_SetTextureColorMod
883 */
884extern DECLSPEC int SDLCALL SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b);
885
886
887/**
888 * Get the additional color value multiplied into render copy operations.
889 *
890 * \param texture the texture to query
891 * \param r a pointer filled in with the current red color value
892 * \param g a pointer filled in with the current green color value
893 * \param b a pointer filled in with the current blue color value
894 * \returns 0 on success or a negative error code on failure; call
895 * SDL_GetError() for more information.
896 *
897 * \since This function is available since SDL 3.0.0.
898 *
899 * \sa SDL_GetTextureAlphaMod
900 * \sa SDL_GetTextureColorModFloat
901 * \sa SDL_SetTextureColorMod
902 */
903extern DECLSPEC int SDLCALL SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b);
904
905/**
906 * Get the additional color value multiplied into render copy operations.
907 *
908 * \param texture the texture to query
909 * \param r a pointer filled in with the current red color value
910 * \param g a pointer filled in with the current green color value
911 * \param b a pointer filled in with the current blue color value
912 * \returns 0 on success or a negative error code on failure; call
913 * SDL_GetError() for more information.
914 *
915 * \since This function is available since SDL 3.0.0.
916 *
917 * \sa SDL_GetTextureAlphaModFloat
918 * \sa SDL_GetTextureColorMod
919 * \sa SDL_SetTextureColorModFloat
920 */
921extern DECLSPEC int SDLCALL SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b);
922
923/**
924 * Set an additional alpha value multiplied into render copy operations.
925 *
926 * When this texture is rendered, during the copy operation the source alpha
927 * value is modulated by this alpha value according to the following formula:
928 *
929 * `srcA = srcA * (alpha / 255)`
930 *
931 * Alpha modulation is not always supported by the renderer; it will return -1
932 * if alpha modulation is not supported.
933 *
934 * \param texture the texture to update
935 * \param alpha the source alpha value multiplied into copy operations
936 * \returns 0 on success or a negative error code on failure; call
937 * SDL_GetError() for more information.
938 *
939 * \since This function is available since SDL 3.0.0.
940 *
941 * \sa SDL_GetTextureAlphaMod
942 * \sa SDL_SetTextureAlphaModFloat
943 * \sa SDL_SetTextureColorMod
944 */
945extern DECLSPEC int SDLCALL SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha);
946
947/**
948 * Set an additional alpha value multiplied into render copy operations.
949 *
950 * When this texture is rendered, during the copy operation the source alpha
951 * value is modulated by this alpha value according to the following formula:
952 *
953 * `srcA = srcA * alpha`
954 *
955 * Alpha modulation is not always supported by the renderer; it will return -1
956 * if alpha modulation is not supported.
957 *
958 * \param texture the texture to update
959 * \param alpha the source alpha value multiplied into copy operations
960 * \returns 0 on success or a negative error code on failure; call
961 * SDL_GetError() for more information.
962 *
963 * \since This function is available since SDL 3.0.0.
964 *
965 * \sa SDL_GetTextureAlphaModFloat
966 * \sa SDL_SetTextureAlphaMod
967 * \sa SDL_SetTextureColorModFloat
968 */
969extern DECLSPEC int SDLCALL SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha);
970
971/**
972 * Get the additional alpha value multiplied into render copy operations.
973 *
974 * \param texture the texture to query
975 * \param alpha a pointer filled in with the current alpha value
976 * \returns 0 on success or a negative error code on failure; call
977 * SDL_GetError() for more information.
978 *
979 * \since This function is available since SDL 3.0.0.
980 *
981 * \sa SDL_GetTextureAlphaModFloat
982 * \sa SDL_GetTextureColorMod
983 * \sa SDL_SetTextureAlphaMod
984 */
985extern DECLSPEC int SDLCALL SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha);
986
987/**
988 * Get the additional alpha value multiplied into render copy operations.
989 *
990 * \param texture the texture to query
991 * \param alpha a pointer filled in with the current alpha value
992 * \returns 0 on success or a negative error code on failure; call
993 * SDL_GetError() for more information.
994 *
995 * \since This function is available since SDL 3.0.0.
996 *
997 * \sa SDL_GetTextureAlphaMod
998 * \sa SDL_GetTextureColorModFloat
999 * \sa SDL_SetTextureAlphaModFloat
1000 */
1001extern DECLSPEC int SDLCALL SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha);
1002
1003/**
1004 * Set the blend mode for a texture, used by SDL_RenderTexture().
1005 *
1006 * If the blend mode is not supported, the closest supported mode is chosen
1007 * and this function returns -1.
1008 *
1009 * \param texture the texture to update
1010 * \param blendMode the SDL_BlendMode to use for texture blending
1011 * \returns 0 on success or a negative error code on failure; call
1012 * SDL_GetError() for more information.
1013 *
1014 * \since This function is available since SDL 3.0.0.
1015 *
1016 * \sa SDL_GetTextureBlendMode
1017 */
1018extern DECLSPEC int SDLCALL SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode);
1019
1020/**
1021 * Get the blend mode used for texture copy operations.
1022 *
1023 * \param texture the texture to query
1024 * \param blendMode a pointer filled in with the current SDL_BlendMode
1025 * \returns 0 on success or a negative error code on failure; call
1026 * SDL_GetError() for more information.
1027 *
1028 * \since This function is available since SDL 3.0.0.
1029 *
1030 * \sa SDL_SetTextureBlendMode
1031 */
1032extern DECLSPEC int SDLCALL SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode);
1033
1034/**
1035 * Set the scale mode used for texture scale operations.
1036 *
1037 * The default texture scale mode is SDL_SCALEMODE_LINEAR.
1038 *
1039 * If the scale mode is not supported, the closest supported mode is chosen.
1040 *
1041 * \param texture The texture to update.
1042 * \param scaleMode the SDL_ScaleMode to use for texture scaling.
1043 * \returns 0 on success or a negative error code on failure; call
1044 * SDL_GetError() for more information.
1045 *
1046 * \since This function is available since SDL 3.0.0.
1047 *
1048 * \sa SDL_GetTextureScaleMode
1049 */
1050extern DECLSPEC int SDLCALL SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode);
1051
1052/**
1053 * Get the scale mode used for texture scale operations.
1054 *
1055 * \param texture the texture to query.
1056 * \param scaleMode a pointer filled in with the current scale mode.
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 3.0.0.
1061 *
1062 * \sa SDL_SetTextureScaleMode
1063 */
1064extern DECLSPEC int SDLCALL SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode);
1065
1066/**
1067 * Update the given texture rectangle with new pixel data.
1068 *
1069 * The pixel data must be in the pixel format of the texture. Use
1070 * SDL_QueryTexture() to query the pixel format of the texture.
1071 *
1072 * This is a fairly slow function, intended for use with static textures that
1073 * do not change often.
1074 *
1075 * If the texture is intended to be updated often, it is preferred to create
1076 * the texture as streaming and use the locking functions referenced below.
1077 * While this function will work with streaming textures, for optimization
1078 * reasons you may not get the pixels back if you lock the texture afterward.
1079 *
1080 * \param texture the texture to update
1081 * \param rect an SDL_Rect structure representing the area to update, or NULL
1082 * to update the entire texture
1083 * \param pixels the raw pixel data in the format of the texture
1084 * \param pitch the number of bytes in a row of pixel data, including padding
1085 * between lines
1086 * \returns 0 on success or a negative error code on failure; call
1087 * SDL_GetError() for more information.
1088 *
1089 * \since This function is available since SDL 3.0.0.
1090 *
1091 * \sa SDL_LockTexture
1092 * \sa SDL_UnlockTexture
1093 * \sa SDL_UpdateNVTexture
1094 * \sa SDL_UpdateYUVTexture
1095 */
1096extern DECLSPEC int SDLCALL SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch);
1097
1098/**
1099 * Update a rectangle within a planar YV12 or IYUV texture with new pixel
1100 * data.
1101 *
1102 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
1103 * block of Y and U/V planes in the proper order, but this function is
1104 * available if your pixel data is not contiguous.
1105 *
1106 * \param texture the texture to update
1107 * \param rect a pointer to the rectangle of pixels to update, or NULL to
1108 * update the entire texture
1109 * \param Yplane the raw pixel data for the Y plane
1110 * \param Ypitch the number of bytes between rows of pixel data for the Y
1111 * plane
1112 * \param Uplane the raw pixel data for the U plane
1113 * \param Upitch the number of bytes between rows of pixel data for the U
1114 * plane
1115 * \param Vplane the raw pixel data for the V plane
1116 * \param Vpitch the number of bytes between rows of pixel data for the V
1117 * plane
1118 * \returns 0 on success or a negative error code on failure; call
1119 * SDL_GetError() for more information.
1120 *
1121 * \since This function is available since SDL 3.0.0.
1122 *
1123 * \sa SDL_UpdateNVTexture
1124 * \sa SDL_UpdateTexture
1125 */
1126extern DECLSPEC int SDLCALL SDL_UpdateYUVTexture(SDL_Texture *texture,
1127 const SDL_Rect *rect,
1128 const Uint8 *Yplane, int Ypitch,
1129 const Uint8 *Uplane, int Upitch,
1130 const Uint8 *Vplane, int Vpitch);
1131
1132/**
1133 * Update a rectangle within a planar NV12 or NV21 texture with new pixels.
1134 *
1135 * You can use SDL_UpdateTexture() as long as your pixel data is a contiguous
1136 * block of NV12/21 planes in the proper order, but this function is available
1137 * if your pixel data is not contiguous.
1138 *
1139 * \param texture the texture to update
1140 * \param rect a pointer to the rectangle of pixels to update, or NULL to
1141 * update the entire texture.
1142 * \param Yplane the raw pixel data for the Y plane.
1143 * \param Ypitch the number of bytes between rows of pixel data for the Y
1144 * plane.
1145 * \param UVplane the raw pixel data for the UV plane.
1146 * \param UVpitch the number of bytes between rows of pixel data for the UV
1147 * plane.
1148 * \returns 0 on success or a negative error code on failure; call
1149 * SDL_GetError() for more information.
1150 *
1151 * \since This function is available since SDL 3.0.0.
1152 *
1153 * \sa SDL_UpdateTexture
1154 * \sa SDL_UpdateYUVTexture
1155 */
1156extern DECLSPEC int SDLCALL SDL_UpdateNVTexture(SDL_Texture *texture,
1157 const SDL_Rect *rect,
1158 const Uint8 *Yplane, int Ypitch,
1159 const Uint8 *UVplane, int UVpitch);
1160
1161/**
1162 * Lock a portion of the texture for **write-only** pixel access.
1163 *
1164 * As an optimization, the pixels made available for editing don't necessarily
1165 * contain the old texture data. This is a write-only operation, and if you
1166 * need to keep a copy of the texture data you should do that at the
1167 * application level.
1168 *
1169 * You must use SDL_UnlockTexture() to unlock the pixels and apply any
1170 * changes.
1171 *
1172 * \param texture the texture to lock for access, which was created with
1173 * `SDL_TEXTUREACCESS_STREAMING`
1174 * \param rect an SDL_Rect structure representing the area to lock for access;
1175 * NULL to lock the entire texture
1176 * \param pixels this is filled in with a pointer to the locked pixels,
1177 * appropriately offset by the locked area
1178 * \param pitch this is filled in with the pitch of the locked pixels; the
1179 * pitch is the length of one row in bytes
1180 * \returns 0 on success or a negative error code if the texture is not valid
1181 * or was not created with `SDL_TEXTUREACCESS_STREAMING`; call
1182 * SDL_GetError() for more information.
1183 *
1184 * \since This function is available since SDL 3.0.0.
1185 *
1186 * \sa SDL_LockTextureToSurface
1187 * \sa SDL_UnlockTexture
1188 */
1189extern DECLSPEC int SDLCALL SDL_LockTexture(SDL_Texture *texture,
1190 const SDL_Rect *rect,
1191 void **pixels, int *pitch);
1192
1193/**
1194 * Lock a portion of the texture for **write-only** pixel access, and expose
1195 * it as a SDL surface.
1196 *
1197 * Besides providing an SDL_Surface instead of raw pixel data, this function
1198 * operates like SDL_LockTexture.
1199 *
1200 * As an optimization, the pixels made available for editing don't necessarily
1201 * contain the old texture data. This is a write-only operation, and if you
1202 * need to keep a copy of the texture data you should do that at the
1203 * application level.
1204 *
1205 * You must use SDL_UnlockTexture() to unlock the pixels and apply any
1206 * changes.
1207 *
1208 * The returned surface is freed internally after calling SDL_UnlockTexture()
1209 * or SDL_DestroyTexture(). The caller should not free it.
1210 *
1211 * \param texture the texture to lock for access, which must be created with
1212 * `SDL_TEXTUREACCESS_STREAMING`
1213 * \param rect a pointer to the rectangle to lock for access. If the rect is
1214 * NULL, the entire texture will be locked
1215 * \param surface this is filled in with an SDL surface representing the
1216 * locked area
1217 * \returns 0 on success or a negative error code on failure; call
1218 * SDL_GetError() for more information.
1219 *
1220 * \since This function is available since SDL 3.0.0.
1221 *
1222 * \sa SDL_LockTexture
1223 * \sa SDL_UnlockTexture
1224 */
1225extern DECLSPEC int SDLCALL SDL_LockTextureToSurface(SDL_Texture *texture,
1226 const SDL_Rect *rect,
1227 SDL_Surface **surface);
1228
1229/**
1230 * Unlock a texture, uploading the changes to video memory, if needed.
1231 *
1232 * **Warning**: Please note that SDL_LockTexture() is intended to be
1233 * write-only; it will not guarantee the previous contents of the texture will
1234 * be provided. You must fully initialize any area of a texture that you lock
1235 * before unlocking it, as the pixels might otherwise be uninitialized memory.
1236 *
1237 * Which is to say: locking and immediately unlocking a texture can result in
1238 * corrupted textures, depending on the renderer in use.
1239 *
1240 * \param texture a texture locked by SDL_LockTexture()
1241 *
1242 * \since This function is available since SDL 3.0.0.
1243 *
1244 * \sa SDL_LockTexture
1245 */
1246extern DECLSPEC void SDLCALL SDL_UnlockTexture(SDL_Texture *texture);
1247
1248/**
1249 * Set a texture as the current rendering target.
1250 *
1251 * The default render target is the window for which the renderer was created.
1252 * To stop rendering to a texture and render to the window again, call this
1253 * function with a NULL `texture`.
1254 *
1255 * \param renderer the rendering context
1256 * \param texture the targeted texture, which must be created with the
1257 * `SDL_TEXTUREACCESS_TARGET` flag, or NULL to render to the
1258 * window instead of a texture.
1259 * \returns 0 on success or a negative error code on failure; call
1260 * SDL_GetError() for more information.
1261 *
1262 * \since This function is available since SDL 3.0.0.
1263 *
1264 * \sa SDL_GetRenderTarget
1265 */
1266extern DECLSPEC int SDLCALL SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture);
1267
1268/**
1269 * Get the current render target.
1270 *
1271 * The default render target is the window for which the renderer was created,
1272 * and is reported a NULL here.
1273 *
1274 * \param renderer the rendering context
1275 * \returns the current render target or NULL for the default render target.
1276 *
1277 * \since This function is available since SDL 3.0.0.
1278 *
1279 * \sa SDL_SetRenderTarget
1280 */
1281extern DECLSPEC SDL_Texture *SDLCALL SDL_GetRenderTarget(SDL_Renderer *renderer);
1282
1283/**
1284 * Set a device independent resolution and presentation mode for rendering.
1285 *
1286 * This function sets the width and height of the logical rendering output. A
1287 * render target is created at the specified size and used for rendering and
1288 * then copied to the output during presentation.
1289 *
1290 * You can disable logical coordinates by setting the mode to
1291 * SDL_LOGICAL_PRESENTATION_DISABLED, and in that case you get the full pixel
1292 * resolution of the output window.
1293 *
1294 * You can convert coordinates in an event into rendering coordinates using
1295 * SDL_ConvertEventToRenderCoordinates().
1296 *
1297 * \param renderer the rendering context
1298 * \param w the width of the logical resolution
1299 * \param h the height of the logical resolution
1300 * \param mode the presentation mode used
1301 * \param scale_mode the scale mode used
1302 * \returns 0 on success or a negative error code on failure; call
1303 * SDL_GetError() for more information.
1304 *
1305 * \since This function is available since SDL 3.0.0.
1306 *
1307 * \sa SDL_ConvertEventToRenderCoordinates
1308 * \sa SDL_GetRenderLogicalPresentation
1309 */
1310extern DECLSPEC int SDLCALL SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode);
1311
1312/**
1313 * Get device independent resolution and presentation mode for rendering.
1314 *
1315 * This function gets the width and height of the logical rendering output, or
1316 * the output size in pixels if a logical resolution is not enabled.
1317 *
1318 * \param renderer the rendering context
1319 * \param w an int to be filled with the width
1320 * \param h an int to be filled with the height
1321 * \param mode a pointer filled in with the presentation mode
1322 * \param scale_mode a pointer filled in with the scale mode
1323 * \returns 0 on success or a negative error code on failure; call
1324 * SDL_GetError() for more information.
1325 *
1326 * \since This function is available since SDL 3.0.0.
1327 *
1328 * \sa SDL_SetRenderLogicalPresentation
1329 */
1330extern DECLSPEC int SDLCALL SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode);
1331
1332/**
1333 * Get a point in render coordinates when given a point in window coordinates.
1334 *
1335 * \param renderer the rendering context
1336 * \param window_x the x coordinate in window coordinates
1337 * \param window_y the y coordinate in window coordinates
1338 * \param x a pointer filled with the x coordinate in render coordinates
1339 * \param y a pointer filled with the y coordinate in render coordinates
1340 * \returns 0 on success or a negative error code on failure; call
1341 * SDL_GetError() for more information.
1342 *
1343 * \since This function is available since SDL 3.0.0.
1344 *
1345 * \sa SDL_SetRenderLogicalPresentation
1346 * \sa SDL_SetRenderScale
1347 */
1348extern DECLSPEC int SDLCALL SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y);
1349
1350/**
1351 * Get a point in window coordinates when given a point in render coordinates.
1352 *
1353 * \param renderer the rendering context
1354 * \param x the x coordinate in render coordinates
1355 * \param y the y coordinate in render coordinates
1356 * \param window_x a pointer filled with the x coordinate in window
1357 * coordinates
1358 * \param window_y a pointer filled with the y coordinate in window
1359 * coordinates
1360 * \returns 0 on success or a negative error code on failure; call
1361 * SDL_GetError() for more information.
1362 *
1363 * \since This function is available since SDL 3.0.0.
1364 *
1365 * \sa SDL_SetRenderLogicalPresentation
1366 * \sa SDL_SetRenderScale
1367 */
1368extern DECLSPEC int SDLCALL SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y);
1369
1370/**
1371 * Convert the coordinates in an event to render coordinates.
1372 *
1373 * Touch coordinates are converted from normalized coordinates in the window
1374 * to non-normalized rendering coordinates.
1375 *
1376 * Once converted, the coordinates may be outside the rendering area.
1377 *
1378 * \param renderer the rendering context
1379 * \param event the event to modify
1380 * \returns 0 on success or a negative error code on failure; call
1381 * SDL_GetError() for more information.
1382 *
1383 * \since This function is available since SDL 3.0.0.
1384 *
1385 * \sa SDL_GetRenderCoordinatesFromWindowCoordinates
1386 */
1387extern DECLSPEC int SDLCALL SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event);
1388
1389/**
1390 * Set the drawing area for rendering on the current target.
1391 *
1392 * \param renderer the rendering context
1393 * \param rect the SDL_Rect structure representing the drawing area, or NULL
1394 * to set the viewport to the entire target
1395 * \returns 0 on success or a negative error code on failure; call
1396 * SDL_GetError() for more information.
1397 *
1398 * \since This function is available since SDL 3.0.0.
1399 *
1400 * \sa SDL_GetRenderViewport
1401 * \sa SDL_RenderViewportSet
1402 */
1403extern DECLSPEC int SDLCALL SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect);
1404
1405/**
1406 * Get the drawing area for the current target.
1407 *
1408 * \param renderer the rendering context
1409 * \param rect an SDL_Rect structure filled in with the current drawing area
1410 * \returns 0 on success or a negative error code on failure; call
1411 * SDL_GetError() for more information.
1412 *
1413 * \since This function is available since SDL 3.0.0.
1414 *
1415 * \sa SDL_RenderViewportSet
1416 * \sa SDL_SetRenderViewport
1417 */
1418extern DECLSPEC int SDLCALL SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect);
1419
1420/**
1421 * Return whether an explicit rectangle was set as the viewport.
1422 *
1423 * This is useful if you're saving and restoring the viewport and want to know
1424 * whether you should restore a specific rectangle or NULL. Note that the
1425 * viewport is always reset when changing rendering targets.
1426 *
1427 * \param renderer the rendering context
1428 * \returns SDL_TRUE if the viewport was set to a specific rectangle, or
1429 * SDL_FALSE if it was set to NULL (the entire target)
1430 *
1431 * \since This function is available since SDL 3.0.0.
1432 *
1433 * \sa SDL_GetRenderViewport
1434 * \sa SDL_SetRenderViewport
1435 */
1436extern DECLSPEC SDL_bool SDLCALL SDL_RenderViewportSet(SDL_Renderer *renderer);
1437
1438/**
1439 * Set the clip rectangle for rendering on the specified target.
1440 *
1441 * \param renderer the rendering context
1442 * \param rect an SDL_Rect structure representing the clip area, relative to
1443 * the viewport, or NULL to disable clipping
1444 * \returns 0 on success or a negative error code on failure; call
1445 * SDL_GetError() for more information.
1446 *
1447 * \since This function is available since SDL 3.0.0.
1448 *
1449 * \sa SDL_GetRenderClipRect
1450 * \sa SDL_RenderClipEnabled
1451 */
1452extern DECLSPEC int SDLCALL SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect);
1453
1454/**
1455 * Get the clip rectangle for the current target.
1456 *
1457 * \param renderer the rendering context
1458 * \param rect an SDL_Rect structure filled in with the current clipping area
1459 * or an empty rectangle if clipping is disabled
1460 * \returns 0 on success or a negative error code on failure; call
1461 * SDL_GetError() for more information.
1462 *
1463 * \since This function is available since SDL 3.0.0.
1464 *
1465 * \sa SDL_RenderClipEnabled
1466 * \sa SDL_SetRenderClipRect
1467 */
1468extern DECLSPEC int SDLCALL SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect);
1469
1470/**
1471 * Get whether clipping is enabled on the given renderer.
1472 *
1473 * \param renderer the rendering context
1474 * \returns SDL_TRUE if clipping is enabled or SDL_FALSE if not; call
1475 * SDL_GetError() for more information.
1476 *
1477 * \since This function is available since SDL 3.0.0.
1478 *
1479 * \sa SDL_GetRenderClipRect
1480 * \sa SDL_SetRenderClipRect
1481 */
1482extern DECLSPEC SDL_bool SDLCALL SDL_RenderClipEnabled(SDL_Renderer *renderer);
1483
1484/**
1485 * Set the drawing scale for rendering on the current target.
1486 *
1487 * The drawing coordinates are scaled by the x/y scaling factors before they
1488 * are used by the renderer. This allows resolution independent drawing with a
1489 * single coordinate system.
1490 *
1491 * If this results in scaling or subpixel drawing by the rendering backend, it
1492 * will be handled using the appropriate quality hints. For best results use
1493 * integer scaling factors.
1494 *
1495 * \param renderer the rendering context
1496 * \param scaleX the horizontal scaling factor
1497 * \param scaleY the vertical scaling factor
1498 * \returns 0 on success or a negative error code on failure; call
1499 * SDL_GetError() for more information.
1500 *
1501 * \since This function is available since SDL 3.0.0.
1502 *
1503 * \sa SDL_GetRenderScale
1504 */
1505extern DECLSPEC int SDLCALL SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY);
1506
1507/**
1508 * Get the drawing scale for the current target.
1509 *
1510 * \param renderer the rendering context
1511 * \param scaleX a pointer filled in with the horizontal scaling factor
1512 * \param scaleY a pointer filled in with the vertical scaling factor
1513 * \returns 0 on success or a negative error code on failure; call
1514 * SDL_GetError() for more information.
1515 *
1516 * \since This function is available since SDL 3.0.0.
1517 *
1518 * \sa SDL_SetRenderScale
1519 */
1520extern DECLSPEC int SDLCALL SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY);
1521
1522/**
1523 * Set the color used for drawing operations.
1524 *
1525 * Set the color for drawing or filling rectangles, lines, and points, and for
1526 * SDL_RenderClear().
1527 *
1528 * \param renderer the rendering context
1529 * \param r the red value used to draw on the rendering target
1530 * \param g the green value used to draw on the rendering target
1531 * \param b the blue value used to draw on the rendering target
1532 * \param a the alpha value used to draw on the rendering target; usually
1533 * `SDL_ALPHA_OPAQUE` (255). Use SDL_SetRenderDrawBlendMode to
1534 * specify how the alpha channel is used
1535 * \returns 0 on success or a negative error code on failure; call
1536 * SDL_GetError() for more information.
1537 *
1538 * \since This function is available since SDL 3.0.0.
1539 *
1540 * \sa SDL_GetRenderDrawColor
1541 * \sa SDL_SetRenderDrawColorFloat
1542 */
1543extern DECLSPEC int SDLCALL SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a);
1544
1545/**
1546 * Set the color used for drawing operations (Rect, Line and Clear).
1547 *
1548 * Set the color for drawing or filling rectangles, lines, and points, and for
1549 * SDL_RenderClear().
1550 *
1551 * \param renderer the rendering context
1552 * \param r the red value used to draw on the rendering target
1553 * \param g the green value used to draw on the rendering target
1554 * \param b the blue value used to draw on the rendering target
1555 * \param a the alpha value used to draw on the rendering target. Use
1556 * SDL_SetRenderDrawBlendMode to specify how the alpha channel is
1557 * used
1558 * \returns 0 on success or a negative error code on failure; call
1559 * SDL_GetError() for more information.
1560 *
1561 * \since This function is available since SDL 3.0.0.
1562 *
1563 * \sa SDL_GetRenderDrawColorFloat
1564 * \sa SDL_SetRenderDrawColor
1565 */
1566extern DECLSPEC int SDLCALL SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a);
1567
1568/**
1569 * Get the color used for drawing operations (Rect, Line and Clear).
1570 *
1571 * \param renderer the rendering context
1572 * \param r a pointer filled in with the red value used to draw on the
1573 * rendering target
1574 * \param g a pointer filled in with the green value used to draw on the
1575 * rendering target
1576 * \param b a pointer filled in with the blue value used to draw on the
1577 * rendering target
1578 * \param a a pointer filled in with the alpha value used to draw on the
1579 * rendering target; usually `SDL_ALPHA_OPAQUE` (255)
1580 * \returns 0 on success or a negative error code on failure; call
1581 * SDL_GetError() for more information.
1582 *
1583 * \since This function is available since SDL 3.0.0.
1584 *
1585 * \sa SDL_GetRenderDrawColorFloat
1586 * \sa SDL_SetRenderDrawColor
1587 */
1588extern DECLSPEC int SDLCALL SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a);
1589
1590/**
1591 * Get the color used for drawing operations (Rect, Line and Clear).
1592 *
1593 * \param renderer the rendering context
1594 * \param r a pointer filled in with the red value used to draw on the
1595 * rendering target
1596 * \param g a pointer filled in with the green value used to draw on the
1597 * rendering target
1598 * \param b a pointer filled in with the blue value used to draw on the
1599 * rendering target
1600 * \param a a pointer filled in with the alpha value used to draw on the
1601 * rendering target
1602 * \returns 0 on success or a negative error code on failure; call
1603 * SDL_GetError() for more information.
1604 *
1605 * \since This function is available since SDL 3.0.0.
1606 *
1607 * \sa SDL_SetRenderDrawColorFloat
1608 * \sa SDL_GetRenderDrawColor
1609 */
1610extern DECLSPEC int SDLCALL SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a);
1611
1612/**
1613 * Set the color scale used for render operations.
1614 *
1615 * The color scale is an additional scale multiplied into the pixel color
1616 * value while rendering. This can be used to adjust the brightness of colors
1617 * during HDR rendering, or changing HDR video brightness when playing on an
1618 * SDR display.
1619 *
1620 * The color scale does not affect the alpha channel, only the color
1621 * brightness.
1622 *
1623 * \param renderer the rendering context
1624 * \param scale the color scale value
1625 * \returns 0 on success or a negative error code on failure; call
1626 * SDL_GetError() for more information.
1627 *
1628 * \since This function is available since SDL 3.0.0.
1629 *
1630 * \sa SDL_GetRenderColorScale
1631 */
1632extern DECLSPEC int SDLCALL SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale);
1633
1634/**
1635 * Get the color scale used for render operations.
1636 *
1637 * \param renderer the rendering context
1638 * \param scale a pointer filled in with the current color scale value
1639 * \returns 0 on success or a negative error code on failure; call
1640 * SDL_GetError() for more information.
1641 *
1642 * \since This function is available since SDL 3.0.0.
1643 *
1644 * \sa SDL_SetRenderColorScale
1645 */
1646extern DECLSPEC int SDLCALL SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale);
1647
1648/**
1649 * Set the blend mode used for drawing operations (Fill and Line).
1650 *
1651 * If the blend mode is not supported, the closest supported mode is chosen.
1652 *
1653 * \param renderer the rendering context
1654 * \param blendMode the SDL_BlendMode to use for blending
1655 * \returns 0 on success or a negative error code on failure; call
1656 * SDL_GetError() for more information.
1657 *
1658 * \since This function is available since SDL 3.0.0.
1659 *
1660 * \sa SDL_GetRenderDrawBlendMode
1661 */
1662extern DECLSPEC int SDLCALL SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode);
1663
1664/**
1665 * Get the blend mode used for drawing operations.
1666 *
1667 * \param renderer the rendering context
1668 * \param blendMode a pointer filled in with the current SDL_BlendMode
1669 * \returns 0 on success or a negative error code on failure; call
1670 * SDL_GetError() for more information.
1671 *
1672 * \since This function is available since SDL 3.0.0.
1673 *
1674 * \sa SDL_SetRenderDrawBlendMode
1675 */
1676extern DECLSPEC int SDLCALL SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode);
1677
1678/**
1679 * Clear the current rendering target with the drawing color.
1680 *
1681 * This function clears the entire rendering target, ignoring the viewport and
1682 * the clip rectangle.
1683 *
1684 * \param renderer the rendering context
1685 * \returns 0 on success or a negative error code on failure; call
1686 * SDL_GetError() for more information.
1687 *
1688 * \since This function is available since SDL 3.0.0.
1689 *
1690 * \sa SDL_SetRenderDrawColor
1691 */
1692extern DECLSPEC int SDLCALL SDL_RenderClear(SDL_Renderer *renderer);
1693
1694/**
1695 * Draw a point on the current rendering target at subpixel precision.
1696 *
1697 * \param renderer The renderer which should draw a point.
1698 * \param x The x coordinate of the point.
1699 * \param y The y coordinate of the point.
1700 * \returns 0 on success, or -1 on error
1701 *
1702 * \since This function is available since SDL 3.0.0.
1703 *
1704 * \sa SDL_RenderPoints
1705 */
1706extern DECLSPEC int SDLCALL SDL_RenderPoint(SDL_Renderer *renderer, float x, float y);
1707
1708/**
1709 * Draw multiple points on the current rendering target at subpixel precision.
1710 *
1711 * \param renderer The renderer which should draw multiple points.
1712 * \param points The points to draw
1713 * \param count The number of points to draw
1714 * \returns 0 on success or a negative error code on failure; call
1715 * SDL_GetError() for more information.
1716 *
1717 * \since This function is available since SDL 3.0.0.
1718 *
1719 * \sa SDL_RenderPoint
1720 */
1721extern DECLSPEC int SDLCALL SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count);
1722
1723/**
1724 * Draw a line on the current rendering target at subpixel precision.
1725 *
1726 * \param renderer The renderer which should draw a line.
1727 * \param x1 The x coordinate of the start point.
1728 * \param y1 The y coordinate of the start point.
1729 * \param x2 The x coordinate of the end point.
1730 * \param y2 The y coordinate of the end point.
1731 * \returns 0 on success, or -1 on error
1732 *
1733 * \since This function is available since SDL 3.0.0.
1734 *
1735 * \sa SDL_RenderLines
1736 */
1737extern DECLSPEC int SDLCALL SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2);
1738
1739/**
1740 * Draw a series of connected lines on the current rendering target at
1741 * subpixel precision.
1742 *
1743 * \param renderer The renderer which should draw multiple lines.
1744 * \param points The points along the lines
1745 * \param count The number of points, drawing count-1 lines
1746 * \returns 0 on success or a negative error code on failure; call
1747 * SDL_GetError() for more information.
1748 *
1749 * \since This function is available since SDL 3.0.0.
1750 *
1751 * \sa SDL_RenderLine
1752 */
1753extern DECLSPEC int SDLCALL SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count);
1754
1755/**
1756 * Draw a rectangle on the current rendering target at subpixel precision.
1757 *
1758 * \param renderer The renderer which should draw a rectangle.
1759 * \param rect A pointer to the destination rectangle, or NULL to outline the
1760 * entire rendering target.
1761 * \returns 0 on success, or -1 on error
1762 *
1763 * \since This function is available since SDL 3.0.0.
1764 *
1765 * \sa SDL_RenderRects
1766 */
1767extern DECLSPEC int SDLCALL SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect);
1768
1769/**
1770 * Draw some number of rectangles on the current rendering target at subpixel
1771 * precision.
1772 *
1773 * \param renderer The renderer which should draw multiple rectangles.
1774 * \param rects A pointer to an array of destination rectangles.
1775 * \param count The number of rectangles.
1776 * \returns 0 on success or a negative error code on failure; call
1777 * SDL_GetError() for more information.
1778 *
1779 * \since This function is available since SDL 3.0.0.
1780 *
1781 * \sa SDL_RenderRect
1782 */
1783extern DECLSPEC int SDLCALL SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count);
1784
1785/**
1786 * Fill a rectangle on the current rendering target with the drawing color at
1787 * subpixel precision.
1788 *
1789 * \param renderer The renderer which should fill a rectangle.
1790 * \param rect A pointer to the destination rectangle, or NULL for the entire
1791 * rendering target.
1792 * \returns 0 on success, or -1 on error
1793 *
1794 * \since This function is available since SDL 3.0.0.
1795 *
1796 * \sa SDL_RenderFillRects
1797 */
1798extern DECLSPEC int SDLCALL SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect);
1799
1800/**
1801 * Fill some number of rectangles on the current rendering target with the
1802 * drawing color at subpixel precision.
1803 *
1804 * \param renderer The renderer which should fill multiple rectangles.
1805 * \param rects A pointer to an array of destination rectangles.
1806 * \param count The number of rectangles.
1807 * \returns 0 on success or a negative error code on failure; call
1808 * SDL_GetError() for more information.
1809 *
1810 * \since This function is available since SDL 3.0.0.
1811 *
1812 * \sa SDL_RenderFillRect
1813 */
1814extern DECLSPEC int SDLCALL SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count);
1815
1816/**
1817 * Copy a portion of the texture to the current rendering target at subpixel
1818 * precision.
1819 *
1820 * \param renderer The renderer which should copy parts of a texture.
1821 * \param texture The source texture.
1822 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1823 * texture.
1824 * \param dstrect A pointer to the destination rectangle, or NULL for the
1825 * entire rendering target.
1826 * \returns 0 on success, or -1 on error
1827 *
1828 * \since This function is available since SDL 3.0.0.
1829 *
1830 * \sa SDL_RenderTextureRotated
1831 */
1832extern DECLSPEC int SDLCALL SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect);
1833
1834/**
1835 * Copy a portion of the source texture to the current rendering target, with
1836 * rotation and flipping, at subpixel precision.
1837 *
1838 * \param renderer The renderer which should copy parts of a texture.
1839 * \param texture The source texture.
1840 * \param srcrect A pointer to the source rectangle, or NULL for the entire
1841 * texture.
1842 * \param dstrect A pointer to the destination rectangle, or NULL for the
1843 * entire rendering target.
1844 * \param angle An angle in degrees that indicates the rotation that will be
1845 * applied to dstrect, rotating it in a clockwise direction
1846 * \param center A pointer to a point indicating the point around which
1847 * dstrect will be rotated (if NULL, rotation will be done
1848 * around dstrect.w/2, dstrect.h/2).
1849 * \param flip An SDL_FlipMode value stating which flipping actions should be
1850 * performed on the texture
1851 * \returns 0 on success or a negative error code on failure; call
1852 * SDL_GetError() for more information.
1853 *
1854 * \since This function is available since SDL 3.0.0.
1855 *
1856 * \sa SDL_RenderTexture
1857 */
1858extern DECLSPEC int SDLCALL SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture,
1859 const SDL_FRect *srcrect, const SDL_FRect *dstrect,
1860 const double angle, const SDL_FPoint *center,
1861 const SDL_FlipMode flip);
1862
1863/**
1864 * Render a list of triangles, optionally using a texture and indices into the
1865 * vertex array Color and alpha modulation is done per vertex
1866 * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1867 *
1868 * \param renderer The rendering context.
1869 * \param texture (optional) The SDL texture to use.
1870 * \param vertices Vertices.
1871 * \param num_vertices Number of vertices.
1872 * \param indices (optional) An array of integer indices into the 'vertices'
1873 * array, if NULL all vertices will be rendered in sequential
1874 * order.
1875 * \param num_indices Number of indices.
1876 * \returns 0 on success, or -1 if the operation is not supported
1877 *
1878 * \since This function is available since SDL 3.0.0.
1879 *
1880 * \sa SDL_RenderGeometryRaw
1881 */
1882extern DECLSPEC int SDLCALL SDL_RenderGeometry(SDL_Renderer *renderer,
1883 SDL_Texture *texture,
1884 const SDL_Vertex *vertices, int num_vertices,
1885 const int *indices, int num_indices);
1886
1887/**
1888 * Render a list of triangles, optionally using a texture and indices into the
1889 * vertex arrays Color and alpha modulation is done per vertex
1890 * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1891 *
1892 * \param renderer The rendering context.
1893 * \param texture (optional) The SDL texture to use.
1894 * \param xy Vertex positions
1895 * \param xy_stride Byte size to move from one element to the next element
1896 * \param color Vertex colors (as SDL_Color)
1897 * \param color_stride Byte size to move from one element to the next element
1898 * \param uv Vertex normalized texture coordinates
1899 * \param uv_stride Byte size to move from one element to the next element
1900 * \param num_vertices Number of vertices.
1901 * \param indices (optional) An array of indices into the 'vertices' arrays,
1902 * if NULL all vertices will be rendered in sequential order.
1903 * \param num_indices Number of indices.
1904 * \param size_indices Index size: 1 (byte), 2 (short), 4 (int)
1905 * \returns 0 on success or a negative error code on failure; call
1906 * SDL_GetError() for more information.
1907 *
1908 * \since This function is available since SDL 3.0.0.
1909 *
1910 * \sa SDL_RenderGeometry
1911 */
1912extern DECLSPEC int SDLCALL SDL_RenderGeometryRaw(SDL_Renderer *renderer,
1913 SDL_Texture *texture,
1914 const float *xy, int xy_stride,
1915 const SDL_Color *color, int color_stride,
1916 const float *uv, int uv_stride,
1917 int num_vertices,
1918 const void *indices, int num_indices, int size_indices);
1919
1920/**
1921 * Render a list of triangles, optionally using a texture and indices into the
1922 * vertex arrays Color and alpha modulation is done per vertex
1923 * (SDL_SetTextureColorMod and SDL_SetTextureAlphaMod are ignored).
1924 *
1925 * \param renderer The rendering context.
1926 * \param texture (optional) The SDL texture to use.
1927 * \param xy Vertex positions
1928 * \param xy_stride Byte size to move from one element to the next element
1929 * \param color Vertex colors (as SDL_FColor)
1930 * \param color_stride Byte size to move from one element to the next element
1931 * \param uv Vertex normalized texture coordinates
1932 * \param uv_stride Byte size to move from one element to the next element
1933 * \param num_vertices Number of vertices.
1934 * \param indices (optional) An array of indices into the 'vertices' arrays,
1935 * if NULL all vertices will be rendered in sequential order.
1936 * \param num_indices Number of indices.
1937 * \param size_indices Index size: 1 (byte), 2 (short), 4 (int)
1938 * \returns 0 on success or a negative error code on failure; call
1939 * SDL_GetError() for more information.
1940 *
1941 * \since This function is available since SDL 3.0.0.
1942 *
1943 * \sa SDL_RenderGeometry
1944 * \sa SDL_RenderGeometryRaw
1945 */
1946extern DECLSPEC int SDLCALL SDL_RenderGeometryRawFloat(SDL_Renderer *renderer,
1947 SDL_Texture *texture,
1948 const float *xy, int xy_stride,
1949 const SDL_FColor *color, int color_stride,
1950 const float *uv, int uv_stride,
1951 int num_vertices,
1952 const void *indices, int num_indices, int size_indices);
1953
1954/**
1955 * Read pixels from the current rendering target.
1956 *
1957 * The returned surface should be freed with SDL_DestroySurface()
1958 *
1959 * **WARNING**: This is a very slow operation, and should not be used
1960 * frequently. If you're using this on the main rendering target, it should be
1961 * called after rendering and before SDL_RenderPresent().
1962 *
1963 * \param renderer the rendering context
1964 * \param rect an SDL_Rect structure representing the area in pixels relative
1965 * to the to current viewport, or NULL for the entire viewport
1966 * \returns a new SDL_Surface on success or NULL on failure; call
1967 * SDL_GetError() for more information.
1968 *
1969 * \since This function is available since SDL 3.0.0.
1970 */
1971extern DECLSPEC SDL_Surface * SDLCALL SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect);
1972
1973/**
1974 * Update the screen with any rendering performed since the previous call.
1975 *
1976 * SDL's rendering functions operate on a backbuffer; that is, calling a
1977 * rendering function such as SDL_RenderLine() does not directly put a line on
1978 * the screen, but rather updates the backbuffer. As such, you compose your
1979 * entire scene and *present* the composed backbuffer to the screen as a
1980 * complete picture.
1981 *
1982 * Therefore, when using SDL's rendering API, one does all drawing intended
1983 * for the frame, and then calls this function once per frame to present the
1984 * final drawing to the user.
1985 *
1986 * The backbuffer should be considered invalidated after each present; do not
1987 * assume that previous contents will exist between frames. You are strongly
1988 * encouraged to call SDL_RenderClear() to initialize the backbuffer before
1989 * starting each new frame's drawing, even if you plan to overwrite every
1990 * pixel.
1991 *
1992 * \param renderer the rendering context
1993 * \returns 0 on success or a negative error code on failure; call
1994 * SDL_GetError() for more information.
1995 *
1996 * \threadsafety You may only call this function on the main thread.
1997 *
1998 * \since This function is available since SDL 3.0.0.
1999 *
2000 * \sa SDL_RenderClear
2001 * \sa SDL_RenderLine
2002 * \sa SDL_RenderLines
2003 * \sa SDL_RenderPoint
2004 * \sa SDL_RenderPoints
2005 * \sa SDL_RenderRect
2006 * \sa SDL_RenderRects
2007 * \sa SDL_RenderFillRect
2008 * \sa SDL_RenderFillRects
2009 * \sa SDL_SetRenderDrawBlendMode
2010 * \sa SDL_SetRenderDrawColor
2011 */
2012extern DECLSPEC int SDLCALL SDL_RenderPresent(SDL_Renderer *renderer);
2013
2014/**
2015 * Destroy the specified texture.
2016 *
2017 * Passing NULL or an otherwise invalid texture will set the SDL error message
2018 * to "Invalid texture".
2019 *
2020 * \param texture the texture to destroy
2021 *
2022 * \since This function is available since SDL 3.0.0.
2023 *
2024 * \sa SDL_CreateTexture
2025 * \sa SDL_CreateTextureFromSurface
2026 */
2027extern DECLSPEC void SDLCALL SDL_DestroyTexture(SDL_Texture *texture);
2028
2029/**
2030 * Destroy the rendering context for a window and free associated textures.
2031 *
2032 * If `renderer` is NULL, this function will return immediately after setting
2033 * the SDL error message to "Invalid renderer". See SDL_GetError().
2034 *
2035 * \param renderer the rendering context
2036 *
2037 * \since This function is available since SDL 3.0.0.
2038 *
2039 * \sa SDL_CreateRenderer
2040 */
2041extern DECLSPEC void SDLCALL SDL_DestroyRenderer(SDL_Renderer *renderer);
2042
2043/**
2044 * Force the rendering context to flush any pending commands and state.
2045 *
2046 * You do not need to (and in fact, shouldn't) call this function unless you
2047 * are planning to call into OpenGL/Direct3D/Metal/whatever directly, in
2048 * addition to using an SDL_Renderer.
2049 *
2050 * This is for a very-specific case: if you are using SDL's render API, and
2051 * you plan to make OpenGL/D3D/whatever calls in addition to SDL render API
2052 * calls. If this applies, you should call this function between calls to
2053 * SDL's render API and the low-level API you're using in cooperation.
2054 *
2055 * In all other cases, you can ignore this function.
2056 *
2057 * This call makes SDL flush any pending rendering work it was queueing up to
2058 * do later in a single batch, and marks any internal cached state as invalid,
2059 * so it'll prepare all its state again later, from scratch.
2060 *
2061 * This means you do not need to save state in your rendering code to protect
2062 * the SDL renderer. However, there lots of arbitrary pieces of Direct3D and
2063 * OpenGL state that can confuse things; you should use your best judgement
2064 * and be prepared to make changes if specific state needs to be protected.
2065 *
2066 * \param renderer the rendering context
2067 * \returns 0 on success or a negative error code on failure; call
2068 * SDL_GetError() for more information.
2069 *
2070 * \since This function is available since SDL 3.0.0.
2071 */
2072extern DECLSPEC int SDLCALL SDL_FlushRenderer(SDL_Renderer *renderer);
2073
2074/**
2075 * Get the CAMetalLayer associated with the given Metal renderer.
2076 *
2077 * This function returns `void *`, so SDL doesn't have to include Metal's
2078 * headers, but it can be safely cast to a `CAMetalLayer *`.
2079 *
2080 * \param renderer The renderer to query
2081 * \returns a `CAMetalLayer *` on success, or NULL if the renderer isn't a
2082 * Metal renderer
2083 *
2084 * \since This function is available since SDL 3.0.0.
2085 *
2086 * \sa SDL_GetRenderMetalCommandEncoder
2087 */
2088extern DECLSPEC void *SDLCALL SDL_GetRenderMetalLayer(SDL_Renderer *renderer);
2089
2090/**
2091 * Get the Metal command encoder for the current frame.
2092 *
2093 * This function returns `void *`, so SDL doesn't have to include Metal's
2094 * headers, but it can be safely cast to an `id<MTLRenderCommandEncoder>`.
2095 *
2096 * This will return NULL if Metal refuses to give SDL a drawable to render to,
2097 * which might happen if the window is hidden/minimized/offscreen. This
2098 * doesn't apply to command encoders for render targets, just the window's
2099 * backbuffer. Check your return values!
2100 *
2101 * \param renderer The renderer to query
2102 * \returns an `id<MTLRenderCommandEncoder>` on success, or NULL if the
2103 * renderer isn't a Metal renderer or there was an error.
2104 *
2105 * \since This function is available since SDL 3.0.0.
2106 *
2107 * \sa SDL_GetRenderMetalLayer
2108 */
2109extern DECLSPEC void *SDLCALL SDL_GetRenderMetalCommandEncoder(SDL_Renderer *renderer);
2110
2111
2112/**
2113 * Add a set of synchronization semaphores for the current frame.
2114 *
2115 * The Vulkan renderer will wait for `wait_semaphore` before submitting
2116 * rendering commands and signal `signal_semaphore` after rendering commands
2117 * are complete for this frame.
2118 *
2119 * This should be called each frame that you want semaphore synchronization.
2120 * The Vulkan renderer may have multiple frames in flight on the GPU, so you
2121 * should have multiple semaphores that are used for synchronization. Querying
2122 * SDL_PROP_RENDERER_VULKAN_SWAPCHAIN_IMAGE_COUNT_NUMBER will give you the
2123 * maximum number of semaphores you'll need.
2124 *
2125 * \param renderer the rendering context
2126 * \param wait_stage_mask the VkPipelineStageFlags for the wait
2127 * \param wait_semaphore a VkSempahore to wait on before rendering the current
2128 * frame, or 0 if not needed
2129 * \param signal_semaphore a VkSempahore that SDL will signal when rendering
2130 * for the current frame is complete, or 0 if not
2131 * needed
2132 * \returns 0 on success or a negative error code on failure; call
2133 * SDL_GetError() for more information.
2134 *
2135 * \since This function is available since SDL 3.0.0.
2136 */
2137extern DECLSPEC int SDLCALL SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore);
2138
2139/**
2140 * Toggle VSync of the given renderer.
2141 *
2142 * \param renderer The renderer to toggle
2143 * \param vsync 1 for on, 0 for off. All other values are reserved
2144 * \returns 0 on success or a negative error code on failure; call
2145 * SDL_GetError() for more information.
2146 *
2147 * \since This function is available since SDL 3.0.0.
2148 *
2149 * \sa SDL_GetRenderVSync
2150 */
2151extern DECLSPEC int SDLCALL SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync);
2152
2153/**
2154 * Get VSync of the given renderer.
2155 *
2156 * \param renderer The renderer to toggle
2157 * \param vsync an int filled with 1 for on, 0 for off. All other values are
2158 * reserved
2159 * \returns 0 on success or a negative error code on failure; call
2160 * SDL_GetError() for more information.
2161 *
2162 * \since This function is available since SDL 3.0.0.
2163 *
2164 * \sa SDL_SetRenderVSync
2165 */
2166extern DECLSPEC int SDLCALL SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync);
2167
2168/* Ends C function definitions when using C++ */
2169#ifdef __cplusplus
2170}
2171#endif
2172#include <SDL3/SDL_close_code.h>
2173
2174#endif /* SDL_render_h_ */
SDL_BlendMode
SDL_PixelFormatEnum
Definition SDL_pixels.h:216
Uint32 SDL_PropertiesID
void SDL_DestroyTexture(SDL_Texture *texture)
int SDL_GetRenderScale(SDL_Renderer *renderer, float *scaleX, float *scaleY)
int SDL_SetRenderTarget(SDL_Renderer *renderer, SDL_Texture *texture)
int SDL_GetRenderLogicalPresentation(SDL_Renderer *renderer, int *w, int *h, SDL_RendererLogicalPresentation *mode, SDL_ScaleMode *scale_mode)
int SDL_SetRenderScale(SDL_Renderer *renderer, float scaleX, float scaleY)
SDL_Texture * SDL_CreateTextureWithProperties(SDL_Renderer *renderer, SDL_PropertiesID props)
struct SDL_Texture SDL_Texture
Definition SDL_render.h:148
int SDL_CreateWindowAndRenderer(const char *title, int width, int height, SDL_WindowFlags window_flags, SDL_Window **window, SDL_Renderer **renderer)
int SDL_RenderClear(SDL_Renderer *renderer)
int SDL_RenderGeometryRaw(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_Color *color, int color_stride, const float *uv, int uv_stride, int num_vertices, const void *indices, int num_indices, int size_indices)
int SDL_RenderGeometryRawFloat(SDL_Renderer *renderer, SDL_Texture *texture, const float *xy, int xy_stride, const SDL_FColor *color, int color_stride, const float *uv, int uv_stride, int num_vertices, const void *indices, int num_indices, int size_indices)
int SDL_SetRenderVSync(SDL_Renderer *renderer, int vsync)
int SDL_RenderRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count)
SDL_Window * SDL_GetRenderWindow(SDL_Renderer *renderer)
int SDL_RenderTextureRotated(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect, const double angle, const SDL_FPoint *center, const SDL_FlipMode flip)
int SDL_UpdateYUVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *Uplane, int Upitch, const Uint8 *Vplane, int Vpitch)
int SDL_SetRenderDrawColor(SDL_Renderer *renderer, Uint8 r, Uint8 g, Uint8 b, Uint8 a)
int SDL_FlushRenderer(SDL_Renderer *renderer)
void SDL_DestroyRenderer(SDL_Renderer *renderer)
void SDL_UnlockTexture(SDL_Texture *texture)
int SDL_GetTextureColorModFloat(SDL_Texture *texture, float *r, float *g, float *b)
SDL_Surface * SDL_RenderReadPixels(SDL_Renderer *renderer, const SDL_Rect *rect)
int SDL_GetNumRenderDrivers(void)
int SDL_GetRenderClipRect(SDL_Renderer *renderer, SDL_Rect *rect)
SDL_bool SDL_RenderViewportSet(SDL_Renderer *renderer)
SDL_RendererFlags
Definition SDL_render.h:77
@ SDL_RENDERER_PRESENTVSYNC
Definition SDL_render.h:78
int SDL_SetRenderDrawColorFloat(SDL_Renderer *renderer, float r, float g, float b, float a)
SDL_Renderer * SDL_CreateRendererWithProperties(SDL_PropertiesID props)
int SDL_GetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode *blendMode)
int SDL_GetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode *scaleMode)
int SDL_SetRenderColorScale(SDL_Renderer *renderer, float scale)
int SDL_GetTextureColorMod(SDL_Texture *texture, Uint8 *r, Uint8 *g, Uint8 *b)
int SDL_GetRenderVSync(SDL_Renderer *renderer, int *vsync)
int SDL_GetRenderColorScale(SDL_Renderer *renderer, float *scale)
int SDL_SetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode blendMode)
int SDL_GetRenderViewport(SDL_Renderer *renderer, SDL_Rect *rect)
SDL_Texture * SDL_CreateTextureFromSurface(SDL_Renderer *renderer, SDL_Surface *surface)
SDL_Renderer * SDL_GetRendererFromTexture(SDL_Texture *texture)
SDL_TextureAccess
Definition SDL_render.h:114
@ SDL_TEXTUREACCESS_STATIC
Definition SDL_render.h:115
@ SDL_TEXTUREACCESS_STREAMING
Definition SDL_render.h:116
@ SDL_TEXTUREACCESS_TARGET
Definition SDL_render.h:117
int SDL_GetRendererInfo(SDL_Renderer *renderer, SDL_RendererInfo *info)
int SDL_GetRenderOutputSize(SDL_Renderer *renderer, int *w, int *h)
SDL_Renderer * SDL_CreateSoftwareRenderer(SDL_Surface *surface)
int SDL_RenderLines(SDL_Renderer *renderer, const SDL_FPoint *points, int count)
int SDL_SetTextureAlphaMod(SDL_Texture *texture, Uint8 alpha)
SDL_bool SDL_RenderClipEnabled(SDL_Renderer *renderer)
int SDL_RenderCoordinatesToWindow(SDL_Renderer *renderer, float x, float y, float *window_x, float *window_y)
void * SDL_GetRenderMetalLayer(SDL_Renderer *renderer)
int SDL_ConvertEventToRenderCoordinates(SDL_Renderer *renderer, SDL_Event *event)
int SDL_RenderGeometry(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_Vertex *vertices, int num_vertices, const int *indices, int num_indices)
int SDL_RenderFillRect(SDL_Renderer *renderer, const SDL_FRect *rect)
int SDL_SetRenderClipRect(SDL_Renderer *renderer, const SDL_Rect *rect)
int SDL_SetTextureScaleMode(SDL_Texture *texture, SDL_ScaleMode scaleMode)
SDL_RendererLogicalPresentation
Definition SDL_render.h:126
@ SDL_LOGICAL_PRESENTATION_LETTERBOX
Definition SDL_render.h:129
@ SDL_LOGICAL_PRESENTATION_DISABLED
Definition SDL_render.h:127
@ SDL_LOGICAL_PRESENTATION_OVERSCAN
Definition SDL_render.h:130
@ SDL_LOGICAL_PRESENTATION_STRETCH
Definition SDL_render.h:128
@ SDL_LOGICAL_PRESENTATION_INTEGER_SCALE
Definition SDL_render.h:131
int SDL_GetRenderDrawColorFloat(SDL_Renderer *renderer, float *r, float *g, float *b, float *a)
int SDL_GetTextureAlphaModFloat(SDL_Texture *texture, float *alpha)
int SDL_RenderPoint(SDL_Renderer *renderer, float x, float y)
int SDL_RenderCoordinatesFromWindow(SDL_Renderer *renderer, float window_x, float window_y, float *x, float *y)
SDL_PropertiesID SDL_GetTextureProperties(SDL_Texture *texture)
int SDL_SetTextureColorMod(SDL_Texture *texture, Uint8 r, Uint8 g, Uint8 b)
SDL_Renderer * SDL_GetRenderer(SDL_Window *window)
const char * SDL_GetRenderDriver(int index)
void * SDL_GetRenderMetalCommandEncoder(SDL_Renderer *renderer)
int SDL_SetTextureColorModFloat(SDL_Texture *texture, float r, float g, float b)
int SDL_GetRenderDrawColor(SDL_Renderer *renderer, Uint8 *r, Uint8 *g, Uint8 *b, Uint8 *a)
int SDL_GetRenderDrawBlendMode(SDL_Renderer *renderer, SDL_BlendMode *blendMode)
struct SDL_Renderer SDL_Renderer
Definition SDL_render.h:140
int SDL_UpdateTexture(SDL_Texture *texture, const SDL_Rect *rect, const void *pixels, int pitch)
int SDL_RenderLine(SDL_Renderer *renderer, float x1, float y1, float x2, float y2)
int SDL_UpdateNVTexture(SDL_Texture *texture, const SDL_Rect *rect, const Uint8 *Yplane, int Ypitch, const Uint8 *UVplane, int UVpitch)
int SDL_LockTextureToSurface(SDL_Texture *texture, const SDL_Rect *rect, SDL_Surface **surface)
SDL_PropertiesID SDL_GetRendererProperties(SDL_Renderer *renderer)
SDL_Renderer * SDL_CreateRenderer(SDL_Window *window, const char *name, Uint32 flags)
SDL_Texture * SDL_GetRenderTarget(SDL_Renderer *renderer)
int SDL_SetRenderLogicalPresentation(SDL_Renderer *renderer, int w, int h, SDL_RendererLogicalPresentation mode, SDL_ScaleMode scale_mode)
int SDL_RenderTexture(SDL_Renderer *renderer, SDL_Texture *texture, const SDL_FRect *srcrect, const SDL_FRect *dstrect)
int SDL_SetTextureAlphaModFloat(SDL_Texture *texture, float alpha)
int SDL_RenderRect(SDL_Renderer *renderer, const SDL_FRect *rect)
int SDL_GetTextureAlphaMod(SDL_Texture *texture, Uint8 *alpha)
int SDL_RenderFillRects(SDL_Renderer *renderer, const SDL_FRect *rects, int count)
int SDL_SetTextureBlendMode(SDL_Texture *texture, SDL_BlendMode blendMode)
int SDL_AddVulkanRenderSemaphores(SDL_Renderer *renderer, Uint32 wait_stage_mask, Sint64 wait_semaphore, Sint64 signal_semaphore)
int SDL_SetRenderViewport(SDL_Renderer *renderer, const SDL_Rect *rect)
int SDL_QueryTexture(SDL_Texture *texture, SDL_PixelFormatEnum *format, int *access, int *w, int *h)
SDL_Texture * SDL_CreateTexture(SDL_Renderer *renderer, SDL_PixelFormatEnum format, int access, int w, int h)
int SDL_GetCurrentRenderOutputSize(SDL_Renderer *renderer, int *w, int *h)
int SDL_RenderPoints(SDL_Renderer *renderer, const SDL_FPoint *points, int count)
int SDL_LockTexture(SDL_Texture *texture, const SDL_Rect *rect, void **pixels, int *pitch)
int SDL_RenderPresent(SDL_Renderer *renderer)
uint8_t Uint8
Definition SDL_stdinc.h:188
int64_t Sint64
Definition SDL_stdinc.h:233
int SDL_bool
Definition SDL_stdinc.h:170
uint32_t Uint32
Definition SDL_stdinc.h:224
SDL_ScaleMode
Definition SDL_surface.h:77
SDL_FlipMode
Definition SDL_surface.h:89
struct SDL_Window SDL_Window
Definition SDL_video.h:119
Uint32 SDL_WindowFlags
Definition SDL_video.h:133
SDL_PixelFormatEnum texture_formats[16]
Definition SDL_render.h:91
const char * name
Definition SDL_render.h:88
SDL_FPoint tex_coord
Definition SDL_render.h:105
SDL_FPoint position
Definition SDL_render.h:103
SDL_FColor color
Definition SDL_render.h:104